# QUALITY_GATES.md — executable frontend gates The single command that runs **every** gate, locally and in CI: ```bash 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 merge-base of `GOVERNANCE_BASE` (merge_group: each first-parent commit) | `governance` + CI | Deployable app files vs `terraform/` (live: PR, merge_group, local) | ## 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, or `.env*`). 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`](.github/workflows/ci.yaml)):** this repository owns every job. `static` (`format:check` + `lint`), `build` (`tsc -b && vite build`), `unit` (`vitest run` in four shards), `visual` (Playwright visual), `browser-smoke` (`npm run test:e2e`), and `governance` (`npm run governance`, with Terraform 1.16.0) run in parallel. `ci-complete` fails unless all of those jobs succeeded and is the required merge-queue check. Live G13 runs on `pull_request` (merge-base range), `merge_group` (each queued PR as a first-parent commit), and locally. It skips `push`. A Terraform-only PR stacked with an app-only PR still passes; a mixed change set still fails. Terraform fmt/validate and the related unit tests run inside `governance` on every event. ## 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`.