docs/GLOSSARY.md code pointers drifted from the lines they cite (16 of 25)
- Dominant language
- Python
- Stars
- 28
- Forks
- 51
- Avg merge
- 14h 11m
- Merged PRs (30d)
- 443
Description
## Summary
`docs/GLOSSARY.md` pins each definition to a `src/.../file.py:LINE` pointer, and 16 of the 25 pointers no longer land on the code the entry describes. The `models.py` cluster is the worst: `models.py:1060` is cited for `RecoveryContract` but holds `class EnvResource`, `models.py:1133` is cited for `StateCheckpoint` but holds a field assignment, `models.py:172` is cited for `Origin` but holds `class ApprovalStatus`, and the `EnvironmentSnapshot` and `EnvResource` pointers at 1024 and 1014 are off by 48 and 46 lines respectively. `RecoveryLedger` is cited at `recovery/ledger.py:205`, which now holds `_UNSAFE_FILENAME_CHARS`.
This is a recurrence of #731, which fixed the same class of drift and asked for a full audit rather than a spot check. The audit is what found these.
## Affected component
Documentation
## Severity
Minor, but it defeats the file's purpose. The glossary's promise is that every definition is verifiable in the code, not inferred; a reader who follows a pointer to an unrelated line stops trusting the ones that are right.
## Evidence
Each row: what the entry claims, what the cited line actually contains, and where the symbol really is.
| GLOSSARY line | Cited pointer | Actually at that line | Real location |
|---|---|---|---|
| 6 | `recovery/ledger.py:88` | `run_id: str` | `anchor: bool` at `:95` |
| 9 | `recovery/ledger.py:208` | filename-sanitising comment | `RecoveryLedger.__init__` at `:284`, `lock` at `:286` |
| 12 | `models.py:1060` | `class EnvResource(BaseModel):` | `RecoveryContract` at `models.py:1114` |
| 12 | `recovery/contract.py:83` | `mode="json", exclude={...}` | `def build_contract` at `:88` |
| 15 | `models.py:172` | `class ApprovalStatus(StrEnum):` | `class Origin` at `models.py:192` |
| 15 | `models.py:94` | `FAILED = "failed"` (an enum member) | `class StateStatus` at `models.py:97` |
| 18 | `models.py:1133` | `evidence: list[str] = Field(...)` | `class StateCheckpoint` at `models.py:1188` |
| 18 | `checkpoint/manager.py:168` | comment on replay scope | `def checkpoint(` at `:174` |
| 21 | `models.py:1024` | `raise ValueError("caused_by ...")` | `class EnvironmentSnapshot` at `models.py:1072` |
| 21 | `models.py:1014` | comment on caps | `class EnvResource` at `models.py:1060` |
| 24 | `state/validator.py:218` | `lines.append(f"Reason: ...")` | `class StateValidator` at `:222` |
| 24 | `recovery/impact.py:47` | blank line | `class DependencyGraph` at `:48` |
| 27 | `recovery/ledger.py:205` | `_UNSAFE_FILENAME_CHARS = ...` | `class RecoveryLedger` at `:281` |
| 30 | `recovery/planner.py:111` | blank line | `class RepairPlan` at `:112` |
| 42 | `recovery/engine.py:320` | `)` | `check_admissibility(...)` call at `:324` |
| 48 | `reconcilers.py:289` | blank line | `def probe_authority_verdict` at `:291` |
Still correct and left alone: `checkpoint/policy.py:62` and `:52`, `recovery/cleanup.py:20`, `concurrency/lease.py:58`, `security/provenance.py:19`, `provenance_map.py:60`, `adapters/actions.py:24` and `:53`, `models.py:227`.
## Command or code to reproduce
python - <<'EOF'
import re
from pathlib import Path
text = Path("docs/GLOSSARY.md").read_text(encoding="utf-8")
for path, line in sorted(set(re.findall(r"(src/continuum/[\w./]+\.py):(\d+)", text))):
src = Path(path).read_text(encoding="utf-8").splitlines()
n = int(line)
print(f"{path}:{line} :: {src[n-1].strip()[:70] if 0 < n <= len(src) else ''}")
EOF
Compare each printed line against what the surrounding glossary prose claims it points to.
## Expected behaviour
Every `path:line` pointer in the glossary resolves to the code the entry describes. Targets that moved get corrected line numbers; targets that no longer exist get re-anchored to the right symbol.
## Suggested fix shape
Re-anchor the 16 drifted pointers using the table above, then add a small test that resolves every pointer in `docs/GLOSSARY.md` and asserts each lands within a few lines of the symbol named in its entry's backticks. Pointers have now drifted twice (#731 and here), so a mechanical check is what stops a third round.
## System information
- OS: macOS 15.2 (Darwin 25.2.0)
- Python: 3.14.5
- continuum-agent: from source at HEAD `14f8a84`
- Installed via: `uv pip install -e ".[dev]"`
Contributor guide
Research direction
Start with docs/GLOSSARY.md and run the provided Python pointer-resolution script to compare each cited line with the glossary entry and evidence table. Re-anchor the 16 drifted pointers, then add the suggested mechanical test that resolves every pointer and checks it lands near the named symbol. Done means every path:line reference identifies the code described by its entry.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- Half a day
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 86/100