tools: ADR allocator (new-adr) + doc-ref drift lint (check-doc-refs)#5
Merged
Merged
Conversation
What: two anti-hallucination tools from the agentic-flow guardrail discussion,
replacing "deduce a value and trust the model" with "allocate / verify via a tool":
- `make new-adr TITLE="..."` allocates the next ADR number from the actual
docs/adr/*.md files (max + 1) and scaffolds the file, so the number is never
eyeballed (the failure that nearly produced a duplicate ADR-036). The
duplicate-number guard already lives in check-adrs.py; this removes the manual
step that fed it.
- `make check-doc-refs` verifies source line-refs in docs resolve to live code:
every [path#LNN] link must point at an existing file with >= NN lines, and an
ASSUMPTIONS.md row naming a backtick `SYMBOL` must have that symbol within +-1
of the cited line. Catches the HD-01 class (a ref drifting off its const). On
first run it found 46 genuinely-stale source-line refs in ASSUMPTIONS.md (e.g.
MAX_TASKS cited :157, actually :214) -- baselined per the don't-grow idiom; the
bulk re-sync is a follow-up the tool will verify.
- Makefile: new-adr / check-doc-refs / update-doc-refs-baseline targets + .PHONY.
Why: CI is an oracle for "does it build / test / prove", not "is this prose claim
true". The hands-off doc lane (auto-merged; CI cannot read prose) is exactly where
a hallucinated number or citation could land unreviewed. check-doc-refs is the
machine check that closes that for source-line refs.
Out of scope (follow-ups): wiring check-doc-refs into ci.yml as a blocking gate
(.github/, separate change); the 46-ref ASSUMPTIONS.md bulk re-sync; the
adversarial-verify harness stage (non-repo workflow change).
Verification: make check-doc-refs clean (46 baseline, 0 new); make new-adr
allocates the next number + guards empty TITLE; make check-adrs OK (no duplicate);
Makefile parses (targets resolve). No kernel code touched; CI runs the tri-arch
gate on the PR.
Staged files:
Makefile
tools/check-doc-refs-baseline.txt
tools/check-doc-refs.py
tools/new-adr.py
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Anti-hallucination tooling from the agentic-flow guardrail discussion: replace "deduce a value and trust the model" with "allocate / verify via a tool." Built + committed from an isolated git worktree (the parallel-session contention lesson, applied).
make new-adr TITLE="..."- allocates the next ADR number from the actualdocs/adr/*.mdfiles (max + 1) and scaffolds the file, so the number is never eyeballed. (This is the failure mode that nearly produced a duplicate ADR-036 in a workflow output.) The duplicate-number guard already exists incheck-adrs.py; this removes the manual step that fed it.make check-doc-refs- verifies doc source-line refs resolve to live code: every[path#LNN]link must hit an existing file with >= NN lines, and anASSUMPTIONS.mdrow naming a backtickSYMBOLmust have that symbol within +-1 of the cited line. Catches the HD-01 class (a ref drifting off its const). On first run it found 46 genuinely-stale source-line refs inASSUMPTIONS.md(e.g.MAX_TASKScited:157, actually:214) - baselined per the don't-grow idiom; the bulk re-sync is a queued follow-up the tool will verify.Why: CI proves code builds/tests; it does not read prose. The hands-off doc lane (auto-merged) is exactly where a hallucinated number or citation could land unreviewed.
check-doc-refsis the machine check that closes that gap.Out of scope (follow-ups): wiring
check-doc-refsintoci.yml; the 46-ref bulk re-sync; the adversarial-verify harness stage.Touches
tools/+Makefile(owned) -> needs your code-owner review.🤖 Generated with Claude Code