Add librarian Stage 1 citation checker with ignore list

scripts/librarian_check_citations.py extracts file:line references from
inline-code spans across docs/**/*.md and verifies each path exists
(and, if cited with a line number, is within range). Skips
docs/archive/ and docs/plans/archive/ which are read-only by policy.

Caught one real drift in docs/research/optimization_sequencing.md: the
note pointed at docs/plans/amp_trainer.md, which had moved into
docs/plans/archive/.

scripts/librarian-ignore.txt holds fnmatch globs for citations that are
intentionally future-tense (planned files described in the plan docs
themselves). Used sparingly so the checker stays useful as a drift
signal.

Updates docs/plans/librarian.md Progress + Next Step. Next concrete
step is a thin scripts/librarian.sh orchestrator over both checkers.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-07 23:22:34 +09:00
co-authored by Claude Opus 4.7
parent 09bbe7ccf7
commit a899af4d7e
4 changed files with 209 additions and 7 deletions
+24 -6
View File
@@ -121,12 +121,30 @@ operator applies the patch.
- ✅ Prompt moved: `.claude/agents/librarian.md`
`scripts/librarian-prompt.md`. Claude-specific subagent registration
removed.
- ✅ Stage 1, piece 1: `scripts/librarian_check_links.py` (lychee
wrapper). Caught one stale README link on first run (commit
`b9bbb4f`).
- ✅ Stage 1, piece 2: `scripts/librarian_check_citations.py` (custom
`file:line` citation checker over inline-code spans). Skips
`docs/archive/` and `docs/plans/archive/`. Ignore list at
`scripts/librarian-ignore.txt` for intentional future-tense
references. Caught one real drift in
`docs/research/optimization_sequencing.md` (path moved into
`docs/plans/archive/`).
## Stage 1 Remaining Checks
- Stale plans (mtime + git-log staleness heuristic).
- Promotable archive entries (deferred to Stage 2 — heuristic vs LLM
judgment is the open question).
- MEMORY.md drift (index lines vs target file `description:` frontmatter).
- Duplicate prose (high-overlap pairs across archive vs research).
- Oversize files (>500-line soft cap from AGENTS.md).
## Next Concrete Step
Build a minimum viable Stage 1: port coolrl's `check_doc_links.py`
into `scripts/` as `librarian_check_links.py` (one-file lychee wrapper),
verified to run against `docs/**`. No JSON aggregation yet — just exit
code 0/non-zero. This proves the deterministic-lint layer works on this
repo before adding the custom checks (code citations, stale plans,
etc.).
Build `scripts/librarian.sh` as a thin orchestrator that runs every
existing Stage 1 check in order and aggregates the exit code. Two
checks today, more land incrementally. This gives a single entry
point so users (and future cron) can run `scripts/librarian.sh`
instead of remembering each individual checker.