Marcos Paulo
723abeafb5
Companion to da790de. The previous wording said 'report the gap and
stop', which agents read as 'report the gap and substitute'. Name the
near-miss substitution explicitly and point at the marker instead.
5.0 KiB
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.mjson 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.
Do not substitute a near-miss token either
The second way to break this is subtler, and both tasks 10 and 11 did it: keep
the gate happy by pointing a legacy value at the closest token that already
exists. #e5eeeb became var(--paper). Diff-added green became
var(--accent) — purple. 12px and 14px both became var(--step-1), 15px.
That is a silent redesign, and it is worse than leaving the raw value in, because a raw hex is at least honest about being unresolved.
What to do instead: mark the gap
tokens.css has one owner (design-system-keeper) so that "add a token" is a
decision, not a side effect. You may not add one. You can keep the true
value and stay green — mark it:
/* token-gap: no --step-* covers 12px; owner design-system-keeper */
font-size: 12px;
The marker waives that one finding. It needs a real reason after the colon; a
bare token-gap: is rejected. Every marked value is listed on each run, so the
debt stays visible rather than disappearing.
Write it in your task report as well: selector, legacy value, owning file. Marking a gap is not resolving it — it keeps the site truthful until whoever owns the token layer decides.
Parallelism
- Hooks are per-worktree. Git's
index.lockis 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-lockfilein 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-offlineneeded.
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.