# Frontend CI Gate v1 (MC #106089)

# Frontend CI Gate v1

**Source spec:** `~/system/docs/published/alai-frontend-engineering-spec-v1-106089.md`  
**MC:** #106089  
**Principle:** `tsc` is not a build. Browser-visible changes require browser-visible evidence.

**Scope:** Gates below apply to the code a PR/promote actually exercises. A pre-existing gap
tracked in the source spec's Appendix B (Known Deviations) does not block an unrelated PR —
see that appendix and the source spec §9 for the full scope rule.

## Minimum PR gate

Every product may use its own script names, but the pipeline must cover these classes:

```bash
# dependency discipline
npm ci || pnpm install --frozen-lockfile

# static gates
npm run typecheck
npm run lint
npm run test:unit

# framework build gate — mandatory for Next.js/App Router
npm run build

# browser smoke on built artifact or deployed preview
npm run test:e2e:smoke
```

## Required stage/promote gate

```bash
# public URL verification
curl -sI "$PUBLIC_WEB_URL"
# Build-identity check — use whichever mechanism the product implements (source spec §2.1):
# (a) structured JSON endpoint (e.g. build-meta.json), or
# (b) response header comparison (e.g. `curl -sI "$PUBLIC_WEB_URL" | grep -i x-build-id`).
# Bilko currently uses (b); do not assume build-meta.json exists for every product.
curl -s "$PUBLIC_WEB_URL/build-meta.json"  # only if product implements mechanism (a)
npm run test:e2e:auth-critical
npm run test:e2e:core-flows
npm run test:e2e:headers
```

## Gate semantics

| Gate | Failure blocks merge? | Failure blocks promote? | Notes |
| --- | --- | --- | --- |
| Frozen lockfile install | Yes | Yes | No floating framework behavior in CI/deploy. |
| Typecheck | Yes | Yes | Static TS only. Not sufficient by itself. |
| Lint | Yes | Yes | Include App Router export, no mock production imports, i18n rules where applicable. |
| Unit/component tests | Yes | Yes | State machines, typed vendor wrappers, retry behavior. |
| `next build` / production build | Yes | Yes | Catches framework-only build failures. |
| Playwright smoke | Yes | Yes | Must click/assert at least navigation and one core action. |
| Auth critical E2E | Auth products: Yes | Auth products: Yes | Public/custom domain, hard-navigation protected route, logout. |
| Header/cache/CSP | No for non-deploy PR unless changed | Yes | Public URL checks for no-store HTML, immutable chunks, no-store build metadata, security headers. |
| Console/network gate | Yes for affected pages | Yes | Unexpected app console errors or 4xx/5xx fail. |

## Required evidence files

For every user-facing frontend task, save under the task evidence directory:

- command output for install/typecheck/lint/unit/build,
- Playwright report, trace, or screenshot,
- console error summary,
- network failure summary,
- public URL and build/deployment ID when deployed.