ai-for-dummies/.agents/rules/gates.md

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:

.agents/scripts/verify-hooks.sh

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