Entity: doc_scan

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]

How it works

  1. Docs: tracked *.md / *.markdown files, minus vendored and build dirs, generated pages under ouro/wiki/, symlinked aliases (CLAUDE.md -> AGENTS.md), and (by default) the skill's own directory.
  2. 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.
  3. 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 like poiAccess.ts whose suffix appears among tracked files is treated as a path. Spans with spaces, globs, placeholders (<name>) or URLs are ignored.
  4. 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 -lwF outside Markdown. Only identifiers that look like code count (snake_case, camelCase, or PascalCase with 2+ capitals), so Surface or true are 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.
  5. 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.
  6. Moved: for each cited file (directories are only checked for existence), the git log --no-merges commits with a committer time later than the paragraph's newest git blame line. Committer time is used on both sides so rebases don't reorder them.
  7. 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.
  8. 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/ or adrs/, because ADRs are historical records.
    • 4 per provisional phrase, up to 2.
  9. 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):

Tuning that came out of this run (each change was checked against the two known positives):

Dogfood: ourobor-os (2026-10-25)

--include-skill: 36 docs, 70 candidates.

Note: Run as a script, main() goes through runlog.run() (runlog).

Next