[guide] Coverage gate undocumented: CI runs test:unit:coverage:check (97%/99% thresholds) but docs tell contributors to run test:unit

[hivecommons-hive]

Documentation Gap

The required Validate repository CI check (.github/workflows/ci.yml, job validate) runs:

npm run test:unit:coverage:check

which is node tests/tools/coverage-report.mjs --check 97 --check-source 99 — it fails the PR if unit-test coverage drops below 97% (lines) / 99% (source).

But every contributor-facing doc names the wrong command and never mentions the coverage gate:

• CONTRIBUTING.md (Making changes, step 3): "Run npm run test:unit — the required 'Validate repository' check runs this on every PR." — CI does not run test:unit; it runs test:unit:coverage:check.
• AGENTS.md (Build & Test): "Unit Tests: npm run test:unit — required 'Validate repository' CI check on every PR." — same inaccuracy.
• grep for coverage across README.md, CONTRIBUTING.md, AGENTS.md, docs/skills/*.md, and Justfile returns zero matches — the gate is documented nowhere.

Impact

A contributor (human or agent) can follow the docs exactly, get a green npm run test:unit locally, open a PR, and then hit a CI failure on coverage thresholds they had no way to discover before pushing. This is exactly the contributor-experience trap the Making-changes checklist exists to prevent.

Recommendation

1. In CONTRIBUTING.md step 3 and AGENTS.md Build & Test, state that the required check runs npm run test:unit:coverage:check (coverage thresholds 97% lines / 99% source) and tell contributors to run that exact command locally before opening a PR.
2. Optionally note that npm run test:unit alone (tests without the coverage gate) is not sufficient for a green PR check.

---

Filed by guide agent (ACMM L4 — issues-only mode)

🐝 Hive Agent: guide | Instance: hosted-available-lke648397-260827-5n31 | SHA: unknown

— hive: agent=guide backend=copilot model=kimi-k3 copilot=1.0.88

[mrbobbytables]

Expanding scope to absorb #720: both findings are the same defect — CONTRIBUTING.md is out of date about the repository's actual gates. One doc pass should (1) document the coverage gate (CI runs test:unit:coverage:check with 97%/99% thresholds, not plain test:unit) and (2) fix the 'just build' validator list to include validate:button-contrast (10 validators, not 9). Note the list will need validate:projects-born too once #753 merges.

[hivecommons-hive]

Status update for whoever picks this up — two things landed since the scope note:

1. ci: gate region coverage alongside line coverage #674 merged (26946ba): the coverage gate is now npm run test:unit:coverage:check = coverage-report.mjs --check 97 --check-source 99 --check-regions 93 --check-source-regions 97. The doc pass should cite all four thresholds, not just 97/99.

2. fix(security): consolidated hardening of data validators and URL gates #753 merged (10e70b5): scripts/validate-projects-born.mjs now exists and CI gates on it (ci.yml step 'Validate projects-born data'). Beyond the just build list, two more CONTRIBUTING spots are now stale:

   • The data table row (CONTRIBUTING.md:68): 'ProjectsBorn (/practitioners) | data/projects-born.json | manual edit, no validation script' — a validator now exists.
   • CONTRIBUTING.md:102: 'data/projects-born.json has no generator; edit it directly…' — should tell contributors to run npm run validate:projects-born before pushing.
   • Note: just build (Justfile) runs 10 validators and does not include validate:projects-born, while ci.yml does — so a green local just build can still fail CI. Either the recipe or the doc description of it needs to change as part of the same pass.

Verified against main @ 26946ba.

🐝 Hive Agent: guide | Instance: hosted-available-lke648397-260827-5n31 | SHA: unknown

— hive: agent=guide backend=copilot model=kimi-k3 copilot=1.0.88