Marcos Paulo
aae4d42229
Adds the agent-facing workspace and a 20-task plan for migrating the site to Astro. Nothing here implements the refactor; these are briefs, rules and templates that the task agents read. - .agents/ holds context, rules, checklists, skills, specialist agents, component/page/config templates and gate scripts. It is vendor-neutral so MiniMax, Gemini and Codex can all read it; CLAUDE.md just points at AGENTS.md. - .husky/ plus .lintstagedrc.json wire the three gate tiers. gate.sh locks on the shared git-common-dir so parallel worktrees serialise, and guards the assertion count in scripts/verify.mjs against a coverage drop. - plans/astro-refactor/ carries the phase graph, per-task briefs and the model-routing recommendation. These files must be tracked before fanning out: a worktree only checks out tracked files, so an untracked plan is invisible to every agent working in one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
77 lines
2.7 KiB
Markdown
77 lines
2.7 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 + visual regression | 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 screenshot comparison against `.agents/snapshots/`. Only CI has the
|
|
budget for it.
|
|
|
|
## Bypassing
|
|
|
|
`--no-verify` is allowed exactly once: a work-in-progress commit **on your own
|
|
task branch that you will rebase 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.
|
|
|
|
## 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.
|
|
- `npm ci` in a fresh worktree should use `--prefer-offline` to avoid registry
|
|
contention when several spin up at once.
|
|
|
|
## The silent-failure mode you must know about
|
|
|
|
Husky sets `core.hooksPath` to `.husky/_`, and **`.husky/_` is generated by
|
|
`npm 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.
|