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.
124 lines
5.0 KiB
Markdown
124 lines
5.0 KiB
Markdown
# 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.
|
|
|
|
### 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:
|
|
|
|
```css
|
|
/* 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.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.
|