Brief: Read-only, stdlib-only Phase 1 scan that shortlists Markdown doc sections the code may have outgrown: broken references, and cited code that changed after the citing paragraph was last edited. --wiki merges the shortlist into ouro/wiki/maps/doc-drift.md for the agent to confirm or dismiss.
Overview
ouro/scripts/doc_scan.py is the deterministic half of Phase 1 (ADR-011, ADR-013). It never calls an LLM. It only produces a ranked shortlist. The agent decides what is real by reading the code, following onboarding step 5 in SKILL.md. The page format and the merge rules live in drift_page.
Usage
python <path-to-skill>/scripts/doc_scan.py [repo_path] [--json] [--limit N] [--wiki] [--include-skill]
--limit(default 10): how many candidates are printed, and how many unconfirmed entries are raised on the page.--wiki: merges intoouro/wiki/maps/doc-drift.mdin the scanned project. It exits with an error ifouro/wiki/doesn't exist. Never pass it in this repo (ADR-001).--include-skill: also scans the skill's own docs (for developing Ourobor OS).
How it works
- Docs: tracked
*.md/*.markdownfiles, minus vendored and build dirs, generated pages underouro/wiki/, symlinked aliases (CLAUDE.md -> AGENTS.md), and (by default) the skill's own directory. - Sections and paragraphs: ATX headings split a doc into sections; fenced code is skipped. Within a section, each prose block, list item or table row is a paragraph, the unit a statement is dated by.
- References per line: backticked spans and relative Markdown links. A span is a path if it contains
/or a dotted name that isn't an identifier; otherwise a symbol. A bare file name likepoiAccess.tswhose suffix appears among tracked files is treated as a path. Spans with spaces, globs, placeholders (<name>) or URLs are ignored. - Resolution:
- Paths resolve relative to the doc, then to the repo root, then as a unique path suffix (
world/physics.ts→src/world/physics.ts). More than 3 matches is too ambiguous to use. - Symbols are searched with
git grep -lwFoutside Markdown. Only identifiers that look like code count (snake_case, camelCase, or PascalCase with 2+ capitals), soSurfaceortrueare ignored. Call arguments are stripped (beginFrame(dt)→beginFrame), and for dotted names the last code-like part is searched (PICKUP_ACCESS.kerbHighways→kerbHighways). When the section also cites a file the symbol appears in, only that file dates it.
- Paths resolve relative to the doc, then to the repo root, then as a unique path suffix (
- Broken: a link or a rooted path (first segment is a tracked top-level entry) that resolves to nothing and isn't gitignored, or a symbol with no hits. Bare names (
credentials.json) and non-paths (feat/doc-scan,text/html) are never broken. - Moved: for each cited file (directories are only checked for existence), the
git log --no-mergescommits with a committer time later than the paragraph's newestgit blameline. Committer time is used on both sides so rebases don't reorder them. - Wording: in a paragraph that has a broken or moved reference, provisional phrases (
stopgap,workaround,for now,not yet,nothing [currently] imports,proper fix,will be,another change, ...) are recorded, and the claim line moves to the first such sentence. - Score per section:
- 5 per broken path or link, plus 2 per broken symbol.
- The commit count of the most-changed cited file (capped at 10), plus the number of moved files (capped at 5). This moved score is halved for docs under
decisions/,adr/oradrs/, because ADRs are historical records. - 4 per provisional phrase, up to 2.
- Code state: the short SHA of the newest commit touching any cited file. drift_page uses it to decide when a dismissed entry should come back.
@snippet moved-check
later = {sha for sha, ts in history if ts > para_time}
Field test: dabao-dasher (2026-10-25)
Run on a clone of dabao-dasher (17 docs, 326 tracked files, about 3 s):
- Known positives (the two drifts the agent found by hand on 2026-09-30), at
99d5c22^, the commit before the AUDIO fix:docs/ENGINE.md § Why pickups move to the kerbranks #1 ("proper fix", "stopgap";poiAccess.tschanged since) anddocs/AUDIO.md § Audio (AUD-1)ranks #5 ("nothing currently imports";src/app.tschanged since). - At HEAD the AUDIO entry is gone, because the doc was fixed. The kerb entry is still #1, because it is still unfixed.
- New finding at #2:
docs/MAPGEN.md § Stageslists 15 of the 37tools/mapgen/*.tsmodules. The missing ones includepoiDoors.ts, which does the kerb fix, and the hawker and void-deck modules. - Clear false positive at #3:
docs/GRAPHICS.md § Plancites files that are planned in a parked roadmap. - The rest of the top 10 has not been labelled yet. That review is part of the dabao-dasher re-run (roadmap Next Steps) and decides the ≥50% precision criterion.
Tuning that came out of this run (each change was checked against the two known positives):
- Directories don't date code.
src/andtests/changed after every doc edit and filled the top 10 with rules fromAGENTS.md. - Each table row and list item is dated on its own. Before this, one 40-row module table scored 55.
- The moved score is driven by the most-changed file, not the commit total.
- Symlinked aliases are skipped, gitignored directories (
public/tiles/) are never broken, and call arguments are stripped from symbols. - Bare
untilwas dropped from the wording list (descriptive use, "until the player has moved"), and the wording weight was raised from 3 to 4.
Dogfood: ourobor-os (2026-10-25)
--include-skill: 36 docs, 70 candidates.
- #1,
wiki/entities/bootstrap.md § bootstrap(), was partly real: its "Existing docs" paragraph didn't mention thedoc_scanline this change added to the protocol, and it was fixed. Its broken references (docs/adr,docs/adrs) are example names, so they are false positives. - #2–#4 are field-test notes that quote dabao-dasher paths (
docs/AUDIO.md), which are broken here by design. This kind of false positive is expected in docs that describe other repos.
Next
- Label the full top 10 on dabao-dasher and on a Python repo.
- Possible signal suggested by the MAPGEN case: tracked files added to a directory a section enumerates, but not named in it.
- Comment claims from claim_scan feeding the same page.
- The agent feed through hooks, and
--vault.