[quality] CONTRIBUTING.md's just build section is unpinned prose and can drift from the Justfile and the PR gates #1320

Finding

CONTRIBUTING.md makes two claims about just build that nothing in the repository reads:

1. It enumerates, by name, the thirteen validate:* scripts the Justfile build recipe runs.
2. It then states that recipe is not the "Validate repository" and "Lint repository" PR gates, and names the commands a contributor must run as well — npm run test:unit:coverage:check, npm run check:format, npm run check:spelling, npm run check:markdown, and npm run check:audit.

Both are prose describing files the prose never references.

• tests/dev-environment.test.mjs pins the recipe to the workflows, but only through a validate:-prefixed filter, and only against the Justfile — it never reads CONTRIBUTING.md.
• tests/contributing-e2e-setup.test.mjs pins the e2e setup instructions, not this section.

So a validator added to the Justfile, or a check added to either gating job, leaves this section quietly describing the repository as it used to be. Claim 2 is the one with teeth: it is the only place the repository tells a contributor how to get a green PR check on the first push, so a gate missing from it is a gate they find out about after pushing.

This is the same drift-by-omission class the repository has already closed three times, each time after the docs had been wrong for a while:

• coverage thresholds — tests/docs-threshold-parity.test.mjs (Add a doc-parity unit test pinning documented coverage thresholds to the enforced gates #1193, after [guide] CONTRIBUTING.md says e2e coverage 'has no percentage thresholds' — CI gates it at --check-source 100 --check-source-regions 80 #1037 and [guide] CONTRIBUTING.md and AGENTS.md still document the unit region gate as 94% after #1152 ratcheted it to 95% #1169/Docs drift: sync LAUNCH.md verification dates and coverage-gate numbers with current state #1189)
• the audit allowlist against SECURITY.md — tests/audit-gate.test.mjs
• the Node major — tests/dev-environment.test.mjs

Evidence

Measured at 92cede9. Parity currently holds exactly, so this is a guard against future drift rather than a correction:

• The Justfile build recipe runs 13 validate:* scripts; the CONTRIBUTING bullet names the same 13.
• The npm targets in ci.yml's validate and lint jobs that the recipe does not run, excluding build aliases (build / build:production), are exactly check:audit, test:unit:coverage:check, check:format, check:spelling, check:markdown — the same five the qualifying paragraph names.
• check:links is correctly absent: check-links.yml is weekly/dispatch only and deliberately does not gate PRs (CI workflow gaps: flaky-run traces are never uploaded and check:links never runs (needs human: workflow edits) #1188).

Recommendation

Add a parity guard in the house style of tests/docs-threshold-parity.test.mjs and tests/contributing-e2e-setup.test.mjs:

• Assert the just build bullet names exactly the validate:* scripts the recipe runs. Set equality rather than the siblings' one-way rule, because this bullet is an enumeration of a recipe body, not a stated minimum — a script named here that the recipe does not run is as wrong as one it runs and omits.
• Assert every PR-gating npm target the recipe does not run is named in the qualifying paragraph. One-way, matching tests/contributing-e2e-setup.test.mjs: documenting more than the gate needs costs a contributor time, not a red check.
• Scope both searches to the bullet and the paragraph rather than the whole file, so a name that survives in an unrelated section cannot keep the assertion green.
• Build each comparison as a pure function of the three documents and add fixtures that prove it goes red on the drift it claims to catch — the standard tests/e2e-coverage-gate.test.mjs already sets ("a ratchet nobody has seen go red is indistinguishable from one that always passes").

No change to CONTRIBUTING.md, the Justfile, or any workflow is required — the documents already agree, and this only pins them.

Priority

• Impact: medium — no product behaviour is at risk, but this section is the repository's only first-push guidance, and the three precedents above each shipped only after the docs had already drifted.
• Effort: low

🐝 Hive Agent: quality | Instance: hosted-available-lke648397-260827-5n31 | SHA: 92cede9

— hive: agent=quality backend=copilot model=claude-opus-5 copilot=1.0.88