# Rule: quality gates

Three tiers. Each is scoped so that **many agents committing in parallel
worktrees stay fast** — the whole point is that a gate you are tempted to skip
is not a gate.

| Tier | Hook               | Scope                                 | Budget  | Runs                 |
| ---- | ------------------ | ------------------------------------- | ------- | -------------------- |
| 1    | `pre-commit`       | **staged files only** (lint-staged)   | < 3s    | every commit         |
| 2    | `pre-push`         | whole project: build + verify + audit | < 90s   | every push           |
| 3    | CI (Gitea Actions) | tier 2 + lint, on a clean install     | minutes | every push to `main` |

Tier 1 must stay under a few seconds. If it creeps, move the check to tier 2. An
agent that waits 40s per commit will start passing `--no-verify`, and then you
have no gate at all.

## Tier 1 — pre-commit (lint-staged)

Formats and lints **only what you staged**. Scoped by construction, so ten
parallel worktrees do ten small jobs, not ten full-project sweeps.

- Prettier + ESLint on `*.{js,mjs,ts,astro}`
- Prettier + Stylelint on `*.css`
- `check-tokens.mjs` on changed `.astro`/`.css` — catches raw hex before it
  lands
- Prettier on `*.{json,md}`

## Tier 2 — pre-push

The real gate:

```
astro check        types
astro build        it compiles
verify.mjs         42 content assertions — count must not fall
audit-ui.mjs       no external runtime dependencies
check-tokens.mjs   full sweep
```

## Tier 3 — CI

Tier 2 plus `pnpm run lint`, run against a clean
`pnpm install --frozen-lockfile` — which is the part a local worktree cannot
prove.

Screenshot comparison against `.agents/snapshots/` is **not** wired in yet.
`visual-regression.mjs` can only capture baselines, not diff them, so running it
in CI would overwrite the baselines and pass unconditionally. It also needs
Playwright, which is not a project dependency. Add the step back when the script
grows a compare mode.

## Bypassing

`--no-verify` is allowed exactly once: a work-in-progress commit **on your own
task branch that you will amend or squash away**. It is never allowed on a
commit you intend to merge, and the pre-push gate has no bypass.

If a gate is wrong, fix the gate in its own commit. Do not route around it.

## Never restructure code to slip past a checker

A checker is a proxy for a rule. Passing the proxy while breaking the rule is
worse than failing, because failure is visible and this is not.

`check-tokens.mjs` matches `font-size: Npx`. Writing the same value as the
`font:` shorthand passes it. Task 07 did exactly that, in **two** components,
with a comment saying so. Both hardcoded values survived into a "green" branch.

When a token you need does not exist:

1. Stop. Do not invent a value, and do not reshape the syntax to hide one.
2. Write the gap in your task report: the selector, the legacy value(s) it comes
   from, and which file owns the token.
3. If your task cannot proceed without it, say so and stop. A blocked task is a
   finding. A silently-passing one is a defect that ships.

`tokens.css` has a single owner (`design-system-keeper`) precisely so that "add
a token" is a decision, not a side effect.

## Parallelism

- Hooks are **per-worktree**. Git's `index.lock` is per-worktree, so parallel
  commits do not contend.
- The heavy tier-2 gate takes a **lock** (`.git/af-gate.lock`, shared across
  worktrees) so ten agents pushing at once do not run ten concurrent builds and
  thrash the machine. Waiters queue; they do not fail.
- `pnpm install --frozen-lockfile` in a fresh worktree is cheap: pnpm hardlinks
  from the shared content-addressable store, so a second worktree costs seconds
  and almost no disk instead of another 225 MB. No `--prefer-offline` needed.

## The silent-failure mode you must know about

Husky sets `core.hooksPath` to `.husky/_`, and **`.husky/_` is generated by
`pnpm install`, not committed**. A fresh `git worktree add` therefore has hooks
configured but the directory missing — so **hooks silently do not run**. Every
commit passes. Nothing is checked.

`.agents/scripts/worktree.sh start` runs the install and then verifies. Check
manually any time you did not use it:

```bash
.agents/scripts/verify-hooks.sh
```

Run this first in any worktree you did not create with the script.