Verified Autonomy
This project enforces completion mechanically. You are not being asked to be careful; a
hook checks.
Done
./bin/verify done exits 0. Nothing else counts. Not "tests look right", not "should work".
A Stop hook runs this. If any gate is red the hook exits 2, the turn does not end, and
stderr comes back to you as the reason. You cannot talk your way past it — deterministic
results are facts, and per the docs an exit-2 hook wins even over a JSON allow.
The rules
- Fix the code, never the gate. Never weaken, skip, or delete a test. Never add
|| true, raise a timeout, or add a retry to force green. A cheat scanner diffs for
exactly these.
- Never edit your own guardrails —
bin/verify, .claude/gates.json,
.claude/hooks/**, .github/workflows/**. A PreToolUse hook blocks it. If a gate is
wrong, say so and stop.
- Resolve unknowns, never infer them. Read the code or ask.
- Know the blast radius first —
./bin/verify blast <symbol>. Zero callers is a
hypothesis: DI and reflection are invisible to a static graph.
- Branch and PR only. Never push to main, never merge or approve your own PR.
The workflow
Each phase has a skill. Where a rule can be enforced by a machine, it is — the third
column is what makes this different from a skills library.
| Phase |
Skill |
Mechanically backed by |
| Understand |
brainstorming |
open assumptions block verify preflight |
| Design |
writing-plans |
— (judgment) |
| Isolate |
using-worktrees |
deny-list blocks pushes to main |
| Implement |
test-driven-development |
cheat scanner: skips, deleted assertions, || true, retries |
| Execute |
executing-plans |
ledger on disk survives compaction |
| Debug |
systematic-debugging |
flaky detection vs clean base commit |
| Delegate |
dispatching-agents |
— (judgment) |
| Verify |
gate |
Stop hook exit 2 while red |
| Impact |
blast |
graph query, fails loudly when no index |
| Review |
requesting-review |
reviewer cannot clear a red gate |
| Ship |
finishing-a-branch |
deny-list blocks self-merge; CI re-runs gates |
| Audit rules |
pressure-testing |
deterministic scoring, not an LLM judge |
Loop
./bin/verify preflight # graph health, open assumptions
./bin/verify blast <symbol> # before editing
./bin/verify fast # after each edit
./bin/verify done # exit 0 or you are not done
When blocked
Budget is 3 attempts per failing gate. On exhaustion, stop and report: the failing gate with
command and exit code, what you tried and why each attempt failed, the specific decision a
human must make, and a recommendation with trade-offs. A vague "I'm blocked" is just false
success wearing a different hat.
1---2name: verified-autonomy3description: Use when working in a repo that has .claude/gates.json — explains the mechanical gate contract, what "done" means, and why the Stop hook may refuse to let the turn end4---56# Verified Autonomy78This project enforces completion mechanically. You are not being asked to be careful; a9hook checks.1011## Done1213`./bin/verify done` exits 0. Nothing else counts. Not "tests look right", not "should work".1415A `Stop` hook runs this. If any gate is red the hook exits 2, the turn does not end, and16stderr comes back to you as the reason. You cannot talk your way past it — deterministic17results are facts, and per the docs an exit-2 hook wins even over a JSON `allow`.1819## The rules20211. **Fix the code, never the gate.** Never weaken, skip, or delete a test. Never add22 `|| true`, raise a timeout, or add a retry to force green. A cheat scanner diffs for23 exactly these.242. **Never edit your own guardrails** — `bin/verify`, `.claude/gates.json`,25 `.claude/hooks/**`, `.github/workflows/**`. A `PreToolUse` hook blocks it. If a gate is26 wrong, say so and stop.273. **Resolve unknowns, never infer them.** Read the code or ask.284. **Know the blast radius first** — `./bin/verify blast <symbol>`. Zero callers is a29 hypothesis: DI and reflection are invisible to a static graph.305. **Branch and PR only.** Never push to main, never merge or approve your own PR.3132## The workflow3334Each phase has a skill. **Where a rule can be enforced by a machine, it is** — the third35column is what makes this different from a skills library.3637| Phase | Skill | Mechanically backed by |38|---|---|---|39| Understand | `brainstorming` | open assumptions block `verify preflight` |40| Design | `writing-plans` | — (judgment) |41| Isolate | `using-worktrees` | deny-list blocks pushes to main |42| Implement | `test-driven-development` | cheat scanner: skips, deleted assertions, `\|\| true`, retries |43| Execute | `executing-plans` | ledger on disk survives compaction |44| Debug | `systematic-debugging` | flaky detection vs clean base commit |45| Delegate | `dispatching-agents` | — (judgment) |46| Verify | `gate` | **`Stop` hook exit 2 while red** |47| Impact | `blast` | graph query, fails loudly when no index |48| Review | `requesting-review` | reviewer cannot clear a red gate |49| Ship | `finishing-a-branch` | deny-list blocks self-merge; CI re-runs gates |50| Audit rules | `pressure-testing` | deterministic scoring, not an LLM judge |5152## Loop5354```bash55./bin/verify preflight # graph health, open assumptions56./bin/verify blast <symbol> # before editing57./bin/verify fast # after each edit58./bin/verify done # exit 0 or you are not done59```6061## When blocked6263Budget is 3 attempts per failing gate. On exhaustion, stop and report: the failing gate with64command and exit code, what you tried and why each attempt failed, the specific decision a65human must make, and a recommendation with trade-offs. A vague "I'm blocked" is just false66success wearing a different hat.
Giova445