Skip to content

test: pin CONTRIBUTING.md's just build section to the recipe and the PR gates - #1321

Open
hivecommons-hive[bot] wants to merge 1 commit into
mainfrom
quality/contributing-just-build-parity
Open

hivecommons-hive[bot] wants to merge 1 commit into
mainfrom
quality/contributing-just-build-parity

Conversation

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Test Improvement

Adds tests/contributing-just-build-parity.test.mjs, pinning the just build section of CONTRIBUTING.md to the two things it describes and never references.

CONTRIBUTING.md makes two claims nothing in the repository reads:

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

tests/dev-environment.test.mjs pins the recipe to the workflows, but only through a validate:-prefixed filter and only against the Justfile; 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 describing the repository as it used to be — and claim 2 is the only place the repository tells a contributor how to get a green check on the first push.

This is the drift-by-omission class already closed three times here: #1193 for the coverage thresholds (after #1037 and #1169/#1189), tests/audit-gate.test.mjs for the SECURITY.md allowlist, and tests/dev-environment.test.mjs for the Node major.

Design notes

  • The validator list is set equality, not one-way. The siblings' rule — "documenting more than CI runs is never the bug" — fits a doc stating a minimum. This bullet is an enumeration of a recipe body, so a script named here that the recipe does not run is as wrong as one it runs and omits. The gate list stays one-way, matching tests/contributing-e2e-setup.test.mjs.
  • Both searches are scoped to the bullet and the qualifying paragraph rather than the whole file. Several of these names also appear elsewhere in CONTRIBUTING.md, so a file-wide search would pass on a name that survived in an unrelated section after this one dropped it. This was not hypothetical — a file-wide draft passed while test:unit:coverage:check was unnamed.
  • check:links is correctly out of scope: 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). Build aliases (build / build:production) are excluded too, since the recipe ends in the build step under its own alias.

The guard is shown to go red

Every comparison is a pure function of the three documents, so the fixtures can prove it fails on the drift it claims to catch — the standard tests/e2e-coverage-gate.test.mjs sets ("a ratchet nobody has seen go red is indistinguishable from one that always passes"). Four fixtures cover the drift itself:

fixture caught as
validator added to the recipe alone undocumented: ['validate:newly-added']
validator removed from the recipe alone phantom: ['validate:awards']
gating check dropped from the paragraph test:unit:coverage:check (run by the "validate" job)
check added to a gating job and nowhere else check:newly-added (run by the "lint" job)

The remaining fixtures drive the "update this test" paths, so a restructured document is reported rather than crashed on three frames down.

Verification

  • 15 tests in the new file pass; full unit suite green — 2388 passed, 0 failed.
  • npm run test:unit:coverage:check passes; npx prettier --check clean.
  • The new file measures 100.00% lines / 100.00% regions, taking the all-files region ratio from 96.17% to 96.20% — it adds margin to the aggregate gate rather than spending it.
  • Parity holds exactly at 92cede9, so CONTRIBUTING.md, the Justfile and every workflow are untouched. This PR adds one file and changes nothing else.

Related Issue

Closes #1320


Filed by quality agent (hold-gated mode). Human review required.

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

…e PR gates

CONTRIBUTING.md makes two claims about `just build` that nothing reads:
it enumerates the thirteen validate:* scripts the Justfile build recipe
runs, and it states the recipe is not the "Validate repository" and
"Lint repository" PR gates, naming the five commands a contributor must
run as well. 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;
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 the section describing the repository as it
used to be -- and the second claim is the only place the repository
tells a contributor how to get a green check on the first push.

This is the drift-by-omission class already closed three times here:
#1193 for the coverage thresholds (after #1037 and #1169/#1189),
tests/audit-gate.test.mjs for the SECURITY.md allowlist, and
tests/dev-environment.test.mjs for the Node major.

The validator list is asserted as set equality rather than one-way. The
siblings' rule -- documenting more than CI runs is never the bug -- fits
a doc stating a minimum; this bullet is an enumeration of a recipe body,
so a script named but not run is as wrong as one run but omitted. The
gate list stays one-way. Both searches are scoped to the bullet and the
paragraph rather than the whole file, so a name surviving in an
unrelated section cannot hold an assertion green.

Every comparison is a pure function of the three documents, and eleven
fixtures drive them: four prove the guard goes red on the drift it
claims to catch, and the rest drive the "update this test" paths so a
restructured document is reported rather than crashed on.

Parity holds exactly at this commit, so nothing in CONTRIBUTING.md, the
Justfile or any workflow changes -- this only pins them. Verified:
15 tests pass, the full unit suite is green (2388 passed, 0 failed),
prettier is clean, and the new file measures 100.00% lines / 100.00%
regions, taking the all-files region ratio from 96.17% to 96.20%.

Signed-off-by: quality <quality@hive.kubestellar.io>
@hivecommons-hive

Copy link
Copy Markdown
Contributor Author

Important

Held for human review by the hive's ACMM level gate.

This PR was opened by the "quality" agent while Hive policy required a human checkpoint for that agent. Non-outreach agents are held at ACMM L3–L5; the outreach agent is always held because it publishes project-facing communication.

Hive will keep the hold label until a human removes it. Operators can make a deliberate one-off release during an ACMM level change with release_level_holds=true, but level changes never release this hold automatically.

@hivecommons-hive

Copy link
Copy Markdown
Contributor Author

Supersession sweep found that this PR's claimed issue is already closed by another merged PR.

  • Claimed issue: endusers#1193
  • Closing PR: #1198

this PR also claims another issue that is still open. A human should decide whether to close this PR.

This comment is edited in place by the supersession sweep; it is not duplicated.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

0 participants