shoc-frontend-new/QUALITY_GATES.md

QUALITY_GATES.md — executable frontend gates

The single command that runs every gate, locally and in CI:

npm run verify

verify chains: format:check → lint → build (tsc -b && vite build) → test (vitest run) → governance. Governance also runs the repository gates: Terraform import-plan checker, Terraform formatting and validation, the HCP run guard, CloudFront verify, workflow shell checks, and G13 (app/Terraform isolation). A task is not done until this is green.

Gate matrix

Gate	Command / rule source	Enforced by	Scope
Formatting	npm run format:check (Prettier)	verify + lint-staged	Whole repo
Lint, zero warnings	npm run lint → eslint . --max-warnings=0	verify + CI	Governed TS/TSX (eslint.config.js)
Type-check + production build	npm run build → tsc -b && vite build	verify + CI	Whole app
Unit tests	npm test → vitest run	verify + CI	src/test/**, config/**/*.test.ts
Conditional rendering (no : null)	no-restricted-syntax in eslint.config.js	lint	Governed TSX
Boolean-only JSX &&	seahaven/no-non-boolean-jsx-and (type-aware) in eslint-rules/	lint	Governed TSX
Shared Text typography	no-restricted-syntax (raw p/h1–h6) + seahaven/no-vp-error-outside-text	lint	Governed TSX
Hooks correctness	eslint-plugin-react-hooks recommended (incl. exhaustive-deps) under zero-warnings	lint	Governed TS/TSX
Godfile ratchet (file length)	scripts/governance-check.mjs + scripts/governance-baseline.json	governance	src/**, config/** (non-test)
Changed-file maintainability	scripts/governance-check.mjs → ESLint (complexity, max-lines-per-function, max-params, max-depth)	governance	Changed TS/TSX vs base ref
Terraform import-plan contract	npm run test:terraform-import-plan → scripts/test-terraform-import-plan-check.py	governance + CI	Synthetic plan JSON + canonical maps
Terraform formatting/validation	npm run test:terraform → scripts/terraform-validate.mjs	governance + CI	terraform/live/dev, terraform/live/staging
HCP run guard	npm run test:hcp-run-guard → scripts/test-hcp-run-guard.py	governance + CI	Workspace invariants + apply reconcile
CloudFront release verify	npm run test:cloudfront-release-verify → scripts/test-verify-cloudfront-release.sh	governance + CI	Stubbed aws/curl
GitHub workflow shell	npm run test:github-workflows → scripts/check-github-workflows.sh	governance + CI	bash -n + actionlint
G13 App/Terraform isolation	python3 scripts/check_app_terraform_isolation.py vs GOVERNANCE_BASE	governance + CI	Deployable app files vs terraform/

No-false-pass guarantees

• --max-warnings=0 — a warning is a failure. There is no "warning-only" backlog; rules ship green (see AGENTS.md → How to add a convention).
• Type-aware rules fail closed — seahaven/no-non-boolean-jsx-and reports when type services are unavailable rather than silently claiming safety.
• Godfile ratchet is monotonic — any new file over the cap, new baseline entry, global cap increase, per-file cap increase, or growth beyond a frozen legacy cap fails. Only cap reductions and entry removals are allowed.
• Changed-file maintainability fails closed without a valid base — in CI the base ref is derived from GITHUB_BASE_REF (PR) or github.event.before (push). An absent or unresolvable base is a failure, not a pass.
• Terraform gates never touch live state — terraform init -backend=false -lockfile=readonly and validate run offline; the plan checker is tested against synthetic plan JSON. Real import and controlled-update plans from HCP are migration evidence reviewed by a human before an approved apply (terraform/README.md). G13 fails a diff that contains both terraform/ and deployable application files (src/, public/, pages/, config/, index.html, Vite/tsconfig, .env*, or scripts/deploy-web.sh). Workflow, docs, and gate-script changes may travel with either side. Runtime isolation stays: deploy-web.yaml ignores terraform/**, and app-only tags skip HCP when workspace trigger patterns miss.

Where the gates run

• Locally: npm run verify. lint-staged (via Husky) re-runs ESLint + Prettier on staged files at commit; commitlint enforces Conventional Commits.
• CI (.github/workflows/ci.yaml): the org reusable workflow (ci-typescript-frontend.yaml, Node 24) runs format/lint/build/tests, and a repo-owned governance job runs npm run verify (with Terraform 1.16.0 installed) so the maintainability ratchets and repository gates are guaranteed from this repository regardless of the reusable workflow.
• Terraform CI (.github/workflows/ci-terraform.yaml): fmt, init -backend=false, validate, import-plan unit tests, and G13 classifier unit tests on terraform/** changes for PRs to main or dev.

Toolchain pin

Node ≥ 22.22.1 (CI uses Node 24); npm 11.16.0 via packageManager (use corepack npm … if your default npm is older). The lockfile is package-lock.json v3; install with npm ci. Governance also needs terraform (CI: 1.16.0; versions.tf accepts >= 1.14.0, < 2.0.0) and python3 (3.10+) on PATH.