Why this exists
test-doc-consistency.sh carried a guard asserting that README's "how to read
Setup A precisely" pointer linked to AI_SETUP_LANES.md. It was deleted under
the #530 rule — a guard whose review cost exceeds what it guards is routed to a
follow-up rather than patched again.
The cost evidence
Four consecutive P1 rounds from the cross-model reviewer on PR #670, on one
guard protecting one sentence:
| Round |
Defect |
| 1 |
Two facts asserted separately, never bound. README contains AI_SETUP_LANES.md 4x for unrelated reasons, so the grep could never fail |
| 2 |
Same-paragraph binding still vacuous — the paragraph's billing-anchor link satisfied the pattern alone |
| 3 |
WRONG_SHAPE. Restricting to anchorless links was a fourth region-based pattern; a sibling anchorless link defeats it |
| 4 |
WRONG_SHAPE. Phrase-as-link closed the region class, but the match ended before the file boundary, so AI_SETUP_LANES.md.bak passed 137/0 |
Rounds 1-3 were the same defect at narrowing scope: assert a link exists in a
REGION. Round 4 changed the principle to check the CONSTRUCT and closed
that class — then opened a new one, because the destination was still
pattern-matched rather than resolved.
What to build instead
A generic check over shipped markdown: for every relative link target, assert
the file exists. Structural, not bespoke — it catches .bak, renames, moves,
and typos across every doc at once, which is what the deleted guard was
reaching for with a one-sentence regex.
Scope note, carried from the evidence-exception test's threat model and
accepted by the reviewer there: this guards accidental rot, not an
adversarial retarget to a live wrong file. A committer who retargets a link on
purpose can equally delete the guard. Review is that control.
Not in scope
Anchor validity (whether #section resolves). Different guard, different cost.
Also correct while here
The surviving pass message in test_setup_a_escalation_and_advisor_fallback_explicit
still reads "explicit in README and AI_SETUP_LANES". After the pointer guard was
deleted, that function asserts nothing about README, so the message overclaims.
Found by the reviewer as a P2 on PR #670 (VOLUNTEERED, disposition FILE) and
routed here rather than fixed in that PR — the guard's whole region gets
rewritten when this issue lands, and correcting one string there would have
invalidated a certified merge SHA to buy another review round.
Why this exists
test-doc-consistency.shcarried a guard asserting that README's "how to readSetup A precisely" pointer linked to
AI_SETUP_LANES.md. It was deleted underthe #530 rule — a guard whose review cost exceeds what it guards is routed to a
follow-up rather than patched again.
The cost evidence
Four consecutive P1 rounds from the cross-model reviewer on PR #670, on one
guard protecting one sentence:
AI_SETUP_LANES.md4x for unrelated reasons, so the grep could never failAI_SETUP_LANES.md.bakpassed 137/0Rounds 1-3 were the same defect at narrowing scope: assert a link exists in a
REGION. Round 4 changed the principle to check the CONSTRUCT and closed
that class — then opened a new one, because the destination was still
pattern-matched rather than resolved.
What to build instead
A generic check over shipped markdown: for every relative link target, assert
the file exists. Structural, not bespoke — it catches
.bak, renames, moves,and typos across every doc at once, which is what the deleted guard was
reaching for with a one-sentence regex.
Scope note, carried from the evidence-exception test's threat model and
accepted by the reviewer there: this guards accidental rot, not an
adversarial retarget to a live wrong file. A committer who retargets a link on
purpose can equally delete the guard. Review is that control.
Not in scope
Anchor validity (whether
#sectionresolves). Different guard, different cost.Also correct while here
The surviving
passmessage intest_setup_a_escalation_and_advisor_fallback_explicitstill reads "explicit in README and AI_SETUP_LANES". After the pointer guard was
deleted, that function asserts nothing about README, so the message overclaims.
Found by the reviewer as a P2 on PR #670 (VOLUNTEERED, disposition FILE) and
routed here rather than fixed in that PR — the guard's whole region gets
rewritten when this issue lands, and correcting one string there would have
invalidated a certified merge SHA to buy another review round.