shoc-frontend-new/QUALITY_GATES.md

# 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`.