fix(prior-art): the CI hint and CONTRIBUTING catch up with the referent grammar (#1597 ledger K-5 follow-up) - #1655
Merged
Merged
Conversation
added 7 commits
September 6, 2026 12:46
…quiring a resolvable referent (#1597 ledger L-1/B-3, K-5) Two ways the capability gate disagreed with the definition it claims to mirror. L-1 / B-3 — the LOC triggers counted test material. CLAUDE.md's capability definition has always closed with «test additions for existing capabilities … NOT capability commits», and its section header declares the prose a mirror of this detector. Measured over the last 250 first-parent commits on staging, the >=80-LOC arm fired on 27 commits and 18 of them added ONLY test files; the trailers it forced cited SSOT rows the commit never touched. Test material — *.test.* / *.spec.*, and anything under test(s)/, __tests__/ or *fixtures/ — is now carved out of both LOC arms. A commit adding test material alongside a qualifying production file still trips on the production file, and files directly in packages/core/principles/ are excluded from the carve-out: a principle IS the enforcement capability, and all 9 that fired in the same window carried substantive on-topic citations. Both halves match the other enforcement channel of the same invariant, which has held this semantic since it shipped — principle 11 builds its capability set from non-test files only (packages/core/principles/11-build-first-reuse-default.test.ts:192) while requiring principle tests to carry «a dedicated SSOT entry with verbatim path OR a Prior-art trailer» (:525). 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 trailer must now name something a reader can open: an SSOT row (prior-art-evaluations.md#N), a concrete artefact path, or an issue/PR reference. The grammar is deliberately wider than the strict reading of the documented form: over the post-cutoff first-parent history 145 capability commits carry a positive trailer, 23 of them (16%) reference in-repo precedent or a research patch rather than a register row. Under this grammar the same corpus fails 2 (1.4%), both from before 2026-07-19 — hence an error, not a transitional window. Stacked lines still work: a referent-free line is skipped so a later valid line can carry the commit. CLAUDE.md moves with the hook in this commit — the LOC-trigger carve-out paragraph now names three carve-outs, and the trailer-syntax section enumerates the three referent forms. Prior-art: prior-art-evaluations.md#56 (§7 Prior-art trailer parser, verdict BUILD — this is that row's own module; the change is a semantics fix inside it, no new capability).
… detector change Three cells move in each of the eight npm baselines — packages/core/hooks/checks/prior-art.ts, packages/core/hooks/pre-push.ts, and the .ai-factory/refresh-baseline.json that records their shipped hashes. The cargo / python / go baselines are untouched. Prior-art: skipped — generated-artefact recapture after a code change, no new capability and no design decision to consult prior art about
…nce-ad630c # Conflicts: # packages/getff/MANIFEST.sha256 # tests/install-sh/baselines/react-native/brownfield.fingerprint # tests/install-sh/baselines/react-native/greenfield.fingerprint # tests/install-sh/baselines/react-next/brownfield.fingerprint # tests/install-sh/baselines/react-next/greenfield.fingerprint # tests/install-sh/baselines/react-spa/brownfield.fingerprint # tests/install-sh/baselines/react-spa/greenfield.fingerprint # tests/install-sh/baselines/ts-server/brownfield.fingerprint # tests/install-sh/baselines/ts-server/greenfield.fingerprint
…ust the SSOT row (#1597 ledger K-5 follow-up) PR #1652 widened the positive-trailer grammar from «cite prior-art-evaluations.md#N» to «name a resolvable referent» — an SSOT row, a concrete artefact path, or an issue/PR reference — because 23 of 145 capability commits in the post-cutoff first-parent history rest on in-repo precedent or a research patch rather than a register row. The stderr hint an author actually reads when the PR-body gate fires still said «cite an SSOT entry instead», so the one channel that teaches the grammar was teaching the pre-fix version of it, and an author with a legitimate in-repo consult was being told to invent a register row. The hint now enumerates all three forms with a worked example each. A sync arm reads the bin from disk and fails if any form stops being named, or if the «only way is the SSOT» phrasing comes back; it ships with a paired negative built from the pre-fix hint text. Scope note: the pre-push substance-arm messages (packages/core/hooks/pre-push.ts:415, :426) are deliberately unchanged — they fire on `Prior-art: skipped` taken on a capability commit, where citing the register IS the right advice; they are not the «which forms are accepted» hint. Prior-art: prior-art-evaluations.md#56 (§7 Prior-art trailer parser, verdict BUILD — this is that row's own CI entrypoint; a diagnostic-text fix inside it, no new capability and no new dependency).
…ferent grammar and the test-material carve-out Found by this PR's own backward check, which swept every surface that teaches an author what a `Prior-art:` line may look like. CONTRIBUTING.md:3 declares itself authoritative for «capability-commit definition + Prior-art trailer convention», so it is a teaching surface for both halves of #1652 — and it was stale on both: its syntax block still carried «narrative referencing prior-art-evaluations.md#<ID>, or escape hatch», and its trigger table listed the two LOC thresholds with none of the detector's carve-outs. Both are now stated: the three accepted referent forms with a worked example each, and the three LOC carve-outs including test material with its packages/core/principles/ exception. A sync arm reads the file from disk and fails if either enumeration stops being named. Prior-art: prior-art-evaluations.md#56 (§7 Prior-art trailer parser, verdict BUILD — the contributor-facing documentation of that row's own convention; a doc-parity fix, no new capability and no new dependency).
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.
Summary
Follow-up to #1652 (ledger #1597 K-5), same concern, coordinator-ACKed. That PR widened the positive-trailer grammar from «cite
prior-art-evaluations.md#N» to «name a resolvable referent» — an SSOT row, a concrete artefact path, or an issue/PR reference — on the measurement that 23 of 145 capability commits in the post-cutoff first-parent history rest on in-repo precedent or a research patch rather than a register row. Two teaching surfaces were left describing the pre-fix version of that grammar: the stderr hint the PR-body gate prints, and the CONTRIBUTING.md section that declares itself authoritative for the convention.The second one was not in the ACKed scope — it was found by this PR's own backward check, which swept every surface that tells an author what a
Prior-art:line may look like. Aligning it here rather than deferring it: it is the same concern (a teaching surface contradicting the gate), it is in the same doc family as theCLAUDE.mdparagraph #1652 already moved, and shipping a fix for one stale twin while knowingly leaving the other is the drift this campaign exists to close.Changes
packages/core/hooks/checks/pr-body-prior-art-bin.ts:44-:47. It keeps the escape-hatch warning and the pointer at the CLAUDE.md section that owns the grammar.CONTRIBUTING.md:207) now states the three referent forms with an example each and names the referent-free assertion the hook rejects; its capability-commit section (CONTRIBUTING.md:175) now states the detector's three LOC carve-outs — docs, byte-identical relocations, and test material with itspackages/core/principles/exception — where before it listed the two thresholds with no carve-out at all.packages/core/hooks/checks/pr-body-prior-art.test.ts:190reads the bin from disk,:210reads CONTRIBUTING.md, and each fails if an enumeration stops being named or if the «cite an SSOT entry instead» phrasing returns. Paired negative built from the pre-fix hint text.Scope note (deliberate non-change): the pre-push substance-arm messages at
packages/core/hooks/pre-push.ts:415andpackages/core/hooks/pre-push.ts:425stay as they are. They fire when an author tookPrior-art: skippedon a capability commit, where citing the register IS the right advice — they are not the «which forms are accepted» hint, so widening them would blur two different diagnostics.Review findings
Prior-art: REUSE — setup.d/lib.sh:359 (the copy_safe idiom this reuses)fails some other check, the author re-reads the prior-art gate's hint while fixing, and «cite an SSOT entry instead» tells them their valid trailer is wrong — pushing a spurious append todocs/meta-factory/prior-art-evaluations.md, which is an append-only register per its §3. The sync arm is RED against the pre-fix hint (2 failed | 15 passed, quoted under Test plan) and green after.CONTRIBUTING.md:3claims authority over «capability-commit definition + Prior-art trailer convention» while both of its enumerations were stale. Failure-scenario: a contributor follows the documented path — reads CONTRIBUTING, writesPrior-art: <narrative referencing prior-art-evaluations.md#<ID>>for a commit whose only new packages/ file is a 90-line*.test.ts, and is told by the doc to consult prior art the gate no longer asks for; conversely a reader of its trigger table concludes a new test file IS a capability commit, which the shipped detector contradicts. The CONTRIBUTING sync arm is RED against the pre-fix file (1 failed | 17 passed) and green after.§1.7 Forward-check applied
No new channel: this is the diagnostic text of an existing CI gate (
.github/workflows/pr-body-prior-art.yml→packages/core/hooks/checks/pr-body-prior-art-bin.ts:23) plus the contributor doc that mirrors it. What is new is that neither is maintained by attention any more —packages/core/hooks/checks/pr-body-prior-art.test.ts:190and:210read both files and assert each accepted form is still named, the same mechanised-parity shape #1652 applied to the CLAUDE.md prose, and the counter to#warning-nobody-readsin.claude/rules/attention-is-not-a-mechanism.md:29. Each arm ships with a paired negative so it cannot pass vacuously.§1.7 Backward-check applied
Swept every surface that tells an author what a
Prior-art:line may look like — five exist.CLAUDE.md:50(the ratified grammar) and the pre-push §7 failure message (packages/core/hooks/pre-push.ts:383) were updated in #1652. The pre-push substance-arm messages (packages/core/hooks/pre-push.ts:415,packages/core/hooks/pre-push.ts:425) are deliberately unchanged — see the scope note. This PR closes the remaining two: the CI bin hint andCONTRIBUTING.md:207/:175..github/pull_request_template.md:11was checked and carries no enumeration — it links to CONTRIBUTING rather than restating the forms, so it inherits the fix instead of drifting. The grammar itself is untouched:REFERENT_REatpackages/core/hooks/checks/prior-art.ts:74remains the single definition, and this PR changes no gate behaviour — only what the gate prints and what the docs claim.The first draft of this section asserted CONTRIBUTING.md carried no enumeration; running the grep instead of trusting the recollection is what surfaced it.
Fidelity verdict
FIDELITY: skipped — no kickoff or spec substrate; this is the coordinator-ACKed diagnostic-text half of the K-5 fix landed in #1652, plus the stale contributor-doc twin its backward check surfaced, each verified by a sync arm RED against the pre-fix file.
Test plan
npx vitest run hooks/checks/pr-body-prior-art(inpackages/core) — 18 passed after the change.git show HEAD:packages/core/hooks/checks/pr-body-prior-art-bin.tsrestored in place) — 2 failed | 15 passed, the failures being exactly «the hint names all three accepted referent forms» and «the hint no longer claims the SSOT row is the only way».CONTRIBUTING.md— 1 failed | 17 passed, the failure being exactly the new CONTRIBUTING arm.npx vitest run hooks/checks/(inpackages/core) — 415 passed.npx tsc --noEmit -p packages/core— clean.bash scripts/build-getff-dist.sh --check— «in sync with the repo root (1066 files)»; MANIFEST regenerated in the same commit as the files it pins.SNAPSHOT_MODE=capture bash tests/install-sh/snapshot.sh— no baseline moved. Expected: the bin is a CI entrypoint and CONTRIBUTING.md is not part of the consumer-shipped payload, so neither appears in an install fingerprint.wc -l CONTRIBUTING.md— 273, well under the 600-line markdown gate.Prior-art consult
Prior-art: prior-art-evaluations.md#56 (§7 Prior-art trailer parser — capability-commit detection + trailer validation, verdict BUILD; this changes that row's own CI diagnostic text and the contributor documentation of its convention, no new capability and no new dependency).
Not a capability change: all four touched paths are modifications — no new file under
packages/, no new explicit dependency.