Problem
The local npm run ci script does not run the per-file coverage gate, so it is not actually at parity with GitHub CI — despite AGENTS.md claiming it "runs the same steps as .github/workflows/main.yml". A push can pass every documented pre-push command locally and still fail CI on the coverage gate.
Evidence
Actual GitHub workflow (.github/workflows/main.yml) runs:
validate → coverage → smoke → test:storybook
Root npm run ci runs:
validate → ci:integration → smoke → ci:storybook
npm run ci is missing npm run coverage — the one gate that enforces the per-file ≥90% (lines/statements/functions/branches) threshold. This exact gap caused PR #1601 to fail CI on HistoryEntry.tsx (85.71% function coverage) after a local run that did not include coverage.
Contributing doc weaknesses (AGENTS.md)
- The pre-push guidance offers
npm run validate as an acceptable "minimum" before pushing — but validate runs test, not test:coverage, so it performs zero coverage gating.
- The coverage step is phrased as a soft add-on ("also run
npm run coverage"), reading as optional.
- AGENTS.md states
npm run ci mirrors the workflow, which is inaccurate re: the coverage gate.
Proposed fix
-
Tooling (durable): make the root ci script a true superset of GitHub CI so a single command reaches real parity:
"ci": "npm run validate && npm run coverage && npm run smoke && npm run ci:storybook"
(coverage:web already runs the integration project, superseding the current ci:integration step.)
-
Docs (framing): tighten the "Mandatory pre-push gate" section so the coverage gate is a hard, non-optional step — remove the "or at minimum npm run validate" loophole and the "also run" softening, and correct the parity claim.
Acceptance criteria
Problem
The local
npm run ciscript does not run the per-file coverage gate, so it is not actually at parity with GitHub CI — despite AGENTS.md claiming it "runs the same steps as.github/workflows/main.yml". A push can pass every documented pre-push command locally and still fail CI on the coverage gate.Evidence
Actual GitHub workflow (
.github/workflows/main.yml) runs:Root
npm run ciruns:npm run ciis missingnpm run coverage— the one gate that enforces the per-file ≥90% (lines/statements/functions/branches) threshold. This exact gap caused PR #1601 to fail CI onHistoryEntry.tsx(85.71% function coverage) after a local run that did not includecoverage.Contributing doc weaknesses (AGENTS.md)
npm run validateas an acceptable "minimum" before pushing — butvalidaterunstest, nottest:coverage, so it performs zero coverage gating.npm run coverage"), reading as optional.npm run cimirrors the workflow, which is inaccurate re: the coverage gate.Proposed fix
Tooling (durable): make the root
ciscript a true superset of GitHub CI so a single command reaches real parity:(
coverage:webalready runs the integration project, superseding the currentci:integrationstep.)Docs (framing): tighten the "Mandatory pre-push gate" section so the coverage gate is a hard, non-optional step — remove the "or at minimum
npm run validate" loophole and the "also run" softening, and correct the parity claim.Acceptance criteria
npm run ciruns the coverage gate (per-file ≥90% on all four dimensions) locally.npm run cidoes.