BL-10 — five dangling Learning #N citations, and the invariant mechanized

[rmsharp]

Five citations in two bin/_manifest.py-distributed files point at Learnings #28, #29, #30 and #34. The Learnings table ships rows 1–13. Those four are defined nowhere in this repository, so every adopter has been carrying pointers that resolve to nothing since v2.6.

starter-kit/RECOMMENDED_SKILLS.md:90      Learning #30
starter-kit/RECOMMENDED_SKILLS.md:94      Learning #34
starter-kit/RECOMMENDED_SKILLS.md:95      Learnings #28/#29
workstreams/DEVELOPMENT_WORKSTREAM.md:23  Learning #30
workstreams/DEVELOPMENT_WORKSTREAM.md:56  Learning #30

Where they came from

All five trace to docs/audits/2026-05-02-mattpocock-skills-evaluation.md (commits 151f743, 3a497b4), written in session S438 of a different methodology instance — one whose own Learnings table ran into the 30s. The numbers were correct there and meaningless here. This is the class Learning #13 was just added for, one level out: a citation resolvable only against a source the reader does not have.

Three of the five were worse than dangling

They asserted framework rules that do not exist, so stripping just the numbers would have left unattributed false claims — worse, because no checker can see those.

• RECOMMENDED_SKILLS.md:94 rejected /caveman because "the methodology's length discipline (≤150 lines for handoffs)" covered it. The only 150-as-handoff-length string in the entire distributed corpus was that line itself. There is no handoff length rule; failure mode Phase 2.5 naming: consider Phase 2B for consistency with Phase 1B precedent #15 names the thin handoff as the failure, so the corpus's pressure runs the other way.
• DEVELOPMENT_WORKSTREAM.md:23 routed the reader to ITERATIVE_METHODOLOGY.md §Knowledge Accumulation. That section does exist — so bin/check-links and every heading check pass — but it contains no numbered learnings and nothing about issues. The reader is sent to an absence, which is strictly harder to detect than a broken link.

What changed

Each site is re-grounded on something a reader of this corpus can open: the acceptance-criteria bar at DEVELOPMENT_WORKSTREAM.md §Issue Lifecycle transition rule 2; the six Minimum Handoff Requirements and failure mode #15; §Sub-Agent Dispatch Pattern in INHERITED_CODEBASE_FAMILIARIZATION_CAMPAIGN.md.

Dispositions are unchanged — every row in "Skills not recommended" stays a rejection. A bridge sentence at :83 notes the linked audit argues from another instance's numbers, so a reader following the index's own link does not land back in the defect. The audit keeps its original wording as a dated record (v2.7.1 precedent).

No Learnings row was added and none was edited — the table is append-only, and starter-kit/SESSION_RUNNER.md is untouched by this branch.

Mechanized, per Learning #12

The invariant is a relation between two enumerable sets, so it is an assertion rather than another review-time grep — a grep is a human step that silently stops happening, which is how these survived since v2.6.

New canonical-only bin/check-citations (not in bin/_manifest.py — adopters receive the corrected files, not the tool) plus Test 23 in bin/tests.sh. Suite 84 → 91.

• Compound-aware: Learnings #28/#29 is two citations. A naive Learning #\d+ grep drops the trailing member of every compound form — including the one in BL-10's own suggested command.
• Section-anchored, so Learning #27 cannot resolve against the Known Failure Modes table's row 27.
• Exit 1 = corpus defect, 2 = checker defect, so a guard trip is never misread as a finding.

Driven RED first, and the guards were driven RED too. Against the unpatched corpus the checker reported exactly 6 findings across the 5 sites. A corpus-independent self-test runs before every invocation, so a clean corpus cannot make the test vacuous; an injected Learning #99, a renamed registry heading, a broken extractor, and a hole in the table were each observed to trip.

Mutation-testing the fixture then caught a real defect in the checker itself: a missing registry file raised an uncaught OSError and exited 1, indistinguishable from a corpus finding. Fixed, and a fixture control now fails loudly rather than letting the guard assertions pass for the wrong reason.

Honest limits

• The checker proves referents, never truth. "There is no length rule here to trade against" carries no #N token. If a future release adds one, that claim silently becomes false and the suite stays green. Each such claim is therefore worded as a scope statement placed next to the rule that would have to change — but this is the campaign's own defect class surviving inside its fix, stated rather than papered over.
• It does not cover the table's shape. Your S5 receipt flagged that a duplicate row number and a malformed row both pass the suite. check-citations closes only the hole case (contiguity-from-1); duplicates and malformed rows still pass. The gap you identified is narrowed, not closed.
• Learnings only. Failure modes and principles are clean today, which is precisely why they cannot be driven RED — they belong to their own deliverable. Anti-patterns have no single registry and some citations deliberately point at an adopter's own list.

Verification

bin/tests.sh 91/91 · bin/check-citations OK (15 citations / 3 files / 13-row table) · bin/check-links OK (85 links / 21 files — 82 → 85 is the three new cross-references, a count change, not a regression) · no Learning #N above 13 anywhere in the distributed corpus · no brand token introduced into a brand-neutral file.

No principle, phase, gate, or workstream change. Failure-mode count stays 27; Learnings stay 1–13.

🤖 Generated with Claude Code

[rmsharp]

Closing — this PR was opened without the operator's authorization. The work stands and the branch is preserved on the fork; it will be re-proposed only if and when the operator decides to.