fix(prior-art): the detector stops taxing test material and starts requiring a resolvable referent (#1597 ledger L-1/B-3, K-5)

[artyhoo]

Summary

Two ways the capability gate disagreed with the definition it claims to mirror — ledger #1597 findings L-1 / B-3 (the wide half, == C13 addendum B-3) and K-5 (the real half). CLAUDE.md:30 declares the prose definition a mirror of packages/core/hooks/checks/prior-art.ts; both halves of the disagreement are closed here, in the same commit as the prose.

Changes

• L-1 / B-3 — the LOC triggers taxed test material. packages/core/hooks/checks/prior-art.ts:231 and :249 now skip test material in both LOC arms (isExemptTestMaterial, packages/core/hooks/checks/prior-art.ts:221): *.test.* / *.spec.* files and anything under test(s)/, __tests__/ or *fixtures/. The carve-out cannot hide a capability — a commit that adds test material alongside a qualifying production file still trips on the production file — and it stops at packages/core/principles/ (ENFORCEMENT_FILE_RE, packages/core/hooks/checks/prior-art.ts:190): a principle IS the enforcement capability, not a test for one.
• K-5 — a positive trailer needed no referent. checkTrailerBody accepted any ≥20-char payload that was not the skipped escape hatch, so Prior-art: consulted — no entry applies satisfied the gate on a capability commit. A positive line must now name something a reader can open (REFERENT_RE, packages/core/hooks/checks/prior-art.ts:74): an SSOT row (prior-art-evaluations.md#N), a concrete artefact path, or an issue/PR reference. Stacked lines keep working — a referent-free line is skipped so a later valid line can carry the commit.
• Prose parity in the same commit. CLAUDE.md:36 now names three carve-outs on the LOC triggers instead of two, and CLAUDE.md:50 enumerates the three referent forms. Three prose↔hook sync arms pin it (packages/core/hooks/checks/prior-art.test.ts:1462).
• Diagnostics. packages/core/hooks/pre-push.ts:383 names the three accepted referent forms in the failure message.

Measurement (why each side moved)

L-1 / B-3 — the detector is the drifted side. Over the last 250 first-parent commits on staging the ≥80-LOC arm fired on 27 commits; 18 of them added ONLY test files (9 under packages/core/principles/, 4 hook tests, 3 packages/runtime-bridge/test/, 2 skills, 1 synthesizer). The trailers it forced on the non-principle ones cited rows the commit never touched — #242/#20/#16 on a hook-test pair (the C15 case), #45 «unchanged by this» on a runtime-bridge pair. The 9 principle files, by contrast, each carried a substantive on-topic citation (#244 actionlint, #245 safe-settings, #246 Vitest test.include, #251 markdownlint, #19 lychee, #229, #230, #248) — which is why the carve-out stops there.

The split matches the other enforcement channel of the same invariant, which has held this exact semantic since it shipped: principle 11 (SSOT #48) builds its capability set from non-test files only (packages/core/principles/11-build-first-reuse-default.test.ts:192) while singling principle tests out as needing «a dedicated SSOT entry with verbatim path OR a Prior-art trailer» (packages/core/principles/11-build-first-reuse-default.test.ts:525). This PR brings the pre-push channel into parity with the CI one.

K-5 — error, not a transitional window, and a grammar wider than the strict reading. Measured over the post-cutoff (≥2026-05-12) first-parent history: 145 capability commits carry a positive Prior-art: trailer.

grammar	commits it would reject	rejects consulted — no entry applies?
strict #ID only (the literal documented form)	23 / 145 (16%)	yes
SSOT row | artefact path | issue/PR ref (shipped)	2 / 145 (1.4%)	yes

The 23 the strict reading would reject are legitimate consults naming in-repo precedent or a research patch (setup.d/lib.sh:359, research-patches/2026-05-23-guard-liveness-gate.md §2, PR #261), so the strict reading was rejected on evidence. The 2 that still fail under the shipped grammar are both from before 2026-07-19. No transitional window: the pre-push arm only inspects unpushed commits, so merged history is never re-checked, and the recent rate is 1 in the last 250 first-parent commits.

Review findings

• MAJOR: the ≥80-LOC / ≥50-LOC triggers classed new test files as capability commits, so two thirds of the gate's firings demanded a build-vs-reuse consult for work that adds no capability, and got rote citations back. Failure-scenario: a commit whose only new packages/ file is a 100-line packages/core/hooks/hook-emit-prelude.test.ts covering an existing prelude — detectCapabilityReason returned "new file ≥80 LOC under packages/" against the pre-fix module (probe output quoted under Test plan) and the real-git repro tests/hooks/prior-art-trailer-hook.test.sh sub-test 11 exited non-zero before the fix; both are clean after it, while sub-test 12 (a new principle file) stays non-zero on both sides.
• MAJOR: a positive Prior-art: trailer that named nothing satisfied the gate on a capability commit. Failure-scenario: a commit adding the explicit dependency some-new-dep: ^1.0.0 with the body line Prior-art: consulted — no entry applies — checkTrailerBody(...).code === 0 against the pre-fix module and the real-git repro sub-test 13 exited 0, so a genuinely new dependency merged with a trailer carrying no referent to any register row, artefact, or PR; the squash message then propagated it as the project's own precedent for what a consult looks like.

§1.7 Forward-check applied

Both fixes land on the channels the gate already owns — the pre-push §7 arm (packages/core/hooks/pre-push.ts:367 runs the same detector) and the PR-body arm (packages/core/hooks/checks/pr-body-prior-art-bin.ts:23) — with no new channel introduced, per the earliest-reachable-channel invariant. The prose↔hook obligation that CLAUDE.md:30 asserts is itself mechanised rather than left to attention: packages/core/hooks/checks/prior-art.test.ts:1462 reads CLAUDE.md from disk and fails if the capability definition stops naming the test-material carve-out or the packages/core/principles/ exception, and if the trailer-syntax section stops naming all three referent forms — the counter to #warning-nobody-reads in .claude/rules/attention-is-not-a-mechanism.md:29. Each sync arm ships with a paired negative (packages/core/hooks/checks/prior-art.test.ts:1476).

§1.7 Backward-check applied

Swept the sibling surfaces of both classes. The LOC arms had exactly two call sites, both converted (packages/core/hooks/checks/prior-art.ts:231, packages/core/hooks/checks/prior-art.ts:249); the third detector arm (isNewDepAdded) is path-independent and unaffected. The parallel enforcement channel for the same invariant was checked before choosing the carve-out shape and already excluded test files (packages/core/principles/11-build-first-reuse-default.test.ts:192), so this narrows a divergence rather than creating one. On the trailer side, the three existing tests that encoded the pre-K-5 grammar were found and updated in place rather than deleted — the two space-stripping mutation-killers keep their exact length arithmetic with #1271 standing in for filler (packages/core/hooks/checks/prior-art.test.ts:577, packages/core/hooks/checks/prior-art.test.ts:1051), and the C1 free-form case now asserts the honest post-fix semantic: a non-SSOT referent passes the existence arm because it has nothing to resolve (packages/core/hooks/checks/prior-art.test.ts:807). The two sibling PR-body gates (packages/core/hooks/checks/pr-body-fidelity.ts, packages/core/hooks/checks/pr-stale-revert.ts) parse their own trailers and share no code with this grammar. No static import was added from this shipped check to an unshipped util — the change is two module-local regexes.

Fidelity verdict

FIDELITY: skipped — no kickoff or spec substrate; this is a direct ledger-driven fix to the prior-art gate, verified by paired negatives that are RED against the pre-fix module and by a measurement over the repository's own first-parent history.

Test plan

• npx vitest run hooks/ (in packages/core) — 1399 passed / 73 files, including the 26 new arms in packages/core/hooks/checks/prior-art.test.ts (test-material carve-out across 9 path shapes, four paired negatives, the referent grammar with its vacuity probes and stacked-line cases, three prose↔hook sync arms).
• npx vitest run principles/ --no-file-parallelism (in packages/core) — 477 passed / 2 skipped / 47 files.
• bash tests/hooks/prior-art-trailer-hook.test.sh — 19 pass / 0 fail after the fix (4 new real-git sub-tests). Before it: 17 pass / 2 fail, the failures being exactly new sub-tests 11 and 13; sub-tests 12 and 14 (the paired negative and the paired positive) are green on both sides, so the carve-out is narrowed and the grammar widened only where intended.
• RED evidence against the pre-fix module (git show HEAD:packages/core/hooks/checks/prior-art.ts copy, run under tsx):
  • detectCapabilityReason(test-only commit) = "new file ≥80 LOC under packages/" → null after
  • detectCapabilityReason(principles/99-new.test.ts) = "new file ≥80 LOC under packages/" on both sides (control)
  • detectCapabilityReason(hooks/checks/newcheck.ts) = "new file ≥80 LOC under packages/" on both sides (control)
  • checkTrailerBody('Prior-art: consulted — no entry applies').code = 0 → 1 after
  • the SSOT-row, artefact-path and PR-reference trailers = 0 on both sides (controls)
• npx tsc --noEmit -p packages/core — clean.
• bash scripts/build-getff-dist.sh --check — «in sync with the repo root (1064 files)»; MANIFEST regenerated in the same commit as the files it pins, and re-verified after the merge-forward.
• SNAPSHOT_MODE=capture bash tests/install-sh/snapshot.sh — three cells move in each of the eight npm baselines (packages/core/hooks/checks/prior-art.ts, packages/core/hooks/pre-push.ts, .ai-factory/refresh-baseline.json); cargo / python / go untouched, no host-drift hunk to discard this time. Re-run after the merge-forward: no further change.
• Pre-push hook green on the pushed head.

Prior-art consult

Prior-art: prior-art-evaluations.md#56 (§7 Prior-art trailer parser — capability-commit detection + trailer validation, verdict BUILD; this change is a semantics fix inside that row's own module, no new capability and no new dependency).

Prior-art: prior-art-evaluations.md#23 (commitlint, verdict ADOPT VOCABULARY — «custom trailer enforcement via regex on raw commit body»; the referent grammar stays inside that adopted vocabulary, adding no dependency, and the row's revisit trigger «§9 hand-roll grows beyond 2 substance arms» is unchanged: this is the §7 arm, not §9).

Not a capability change: every touched path is a modification — no new file under packages/, no new explicit dependency.