Cyrax321 / Cyrax321/CONTINUUM

docs/GLOSSARY.md code pointers drifted from the lines they cite (16 of 25)

Open Beginner friendly
#1,069 0 comments 0 reactions 0 assignees View on GitHub
bug documentation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.