Add ratcheting coverage-floor gate to CI

[fpigeonjr]

Description

Adds a ratcheting coverage-floor gate to CI, mirroring the mechanism built for ngx-uswds (#237 → #259).

• coverage-floor.json (new) — records the four coverage floors (statements, branches, functions, lines), seeded to { statements: 53, branches: 39, functions: 50, lines: 52 }: the coverage measured against test-app's Vitest harness after the Karma→Vitest migration (Migrate test-app runner from Karma/Jasmine to Vitest (Analog) #626) landed, not the pre-migration Karma numbers, since coverage-measurement providers can differ slightly even when both are Istanbul-based.
• scripts/check-coverage.mjs (new) — reads floors from coverage-floor.json (not hardcoded) and fails with a clear per-metric message (✖ statements 40.00% (floor 53%)) if measured coverage — from test-app/coverage/coverage-summary.json — drops below any floor. --bump rewrites the floor file up to current measured coverage, ratchet-only (never lowers an existing floor); treats a missing/malformed floor as 0 so a corrupt file can never poison the ratchet with NaN.
• scripts/check-coverage.test.mjs (new) — 7 node --test cases (TDD'd incrementally) covering: pass at/above floor, per-metric failure naming, --bump raising floors, --bump never lowering (ratchet-only), malformed floor values, and a missing coverage summary.
• test-app/vitest.config.mts — added the json-summary reporter (alongside the existing text-summary/lcovonly) so coverage-summary.json actually exists for the gate to read; this was previously missing.
• package.json — added coverage:check and coverage:bump scripts.
• .github/workflows/ci.yml — wired coverage:check in as a required step immediately after the Vitest test run.
• AGENTS.md (new) — documents the ratchet policy for future contributors/agents: feature/spec-adding PRs must not edit coverage-floor.json — only coverage:bump should, landed as its own deliberate commit, so parallel coverage PRs don't collide on a shared file (the exact problem PR for filter pill changes #259 fixed on ngx-uswds).

Per the QASP "Tested" standard (ADR-0010), this floor is a working gate today; it closes out the epic (#576) once raised to the 80% new-code floor / 90% target. This issue only stands up the mechanism, not the final numbers.

Motivation and Context

Closes #627

Type of Change (Select One and Apply Label)

• Bug fix (non-breaking change which fixes an issue) → Apply bugfix label
• New feature (non-breaking change which adds functionality) → Apply enhancement label
• Breaking change (fix or feature that would cause existing functionality to change) → Apply breaking label
• Documentation / configuration update → Apply maintenance label

How to Test

1. npm ci && npm ci --prefix test-app
2. npm --prefix test-app test — runs the full spec suite via Vitest with coverage; now also emits test-app/coverage/coverage-summary.json.
3. npm run coverage:check — runs the gate against the seeded floors; should print ✓ Coverage gate passed.
4. node --test scripts/check-coverage.test.mjs — 7 unit tests for the gate script itself.
5. Regression check: temporarily lower a value in coverage-floor.json above current measured coverage (e.g. bump statements to 99), re-run npm run coverage:check — it should fail and name the metric with expected vs. actual percentages. Revert the temp change.
6. CI: confirm the CI workflow runs the new "Enforce coverage-floor gate" step after "Run test-app harness with coverage" and passes on this branch.

Expected result: Test Files 106 passed (106) / Tests 667 passed (667), coverage summary written, and the coverage gate passes at statements 53.56% / branches 39.77% / functions 50.31% / lines 52.84% against the seeded floors.

Screenshots (if appropriate)

N/A — CI/configuration change only.

Checklist

• Branch name follows convention (e.g. gh-<number>-<slug>)
• PR title starts with a verb in the imperative mood
• I have self-reviewed my own code
• format:check passes (npm run format:check)
• lint passes (npm run lint)
• build passes (cd test-app && npm run build)
• Tests pass and coverage is reported (cd test-app && npm test)
• If this change requires a documentation update, I have updated it accordingly (AGENTS.md)
• If there are dependent changes, they have been merged and published in downstream modules

[Copilot]

Pull request overview

Adds a CI coverage-floor gate and supporting ratchet tooling.

Changes:

• Generates JSON coverage summaries and enforces committed coverage floors.
• Adds ratchet bump tooling and unit tests.
• Documents and integrates the coverage policy into CI.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
.github/workflows/ci.yml	Runs the coverage gate in CI.
AGENTS.md	Documents coverage and lint ratchets.
coverage-floor.json	Defines initial coverage floors.
package.json	Adds coverage check and bump commands.
scripts/check-coverage.mjs	Implements coverage enforcement and floor bumping.
scripts/check-coverage.test.mjs	Tests the coverage gate CLI.
test-app/vitest.config.mts	Enables JSON summary reporting.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.