ADD — direction · evidence · a durable bundle

You plan and build: fix direction first, trust only evidence you produced, leave a .add/ bundle.

Orient — every session, first, in one command

cat .add/PROJECT.md; grep -lE '^status: (direction|build|active)' .add/tasks/*.md .add/milestones/*.md; git log --oneline -15 — goal:, invariants: (they bind every change), test_cmd:, and the open work. Resume an open task at its status:; otherwise size the request. Read what the task touches, never the whole repo. No .add/ yet → create PROJECT.md and empty specs/ milestones/ tasks/ (references/format.md).

Turns — the real cost

Every turn re-reads the whole context: cost grows with turns, not words. Keep every step; cut round-trips:

• Direction = three turns. (1) One command reads what the task touches and finds how the tests run, installing what is missing in that same command. (2) The task file, its tests, and stubs that raise NotImplementedError (the first run fails on behavior, not imports), all as parallel writes in one message. (3) one command runs the checks and seals: <check> ; git add .add/tasks/<slug>.md <tests> && git commit -qm "freeze(<slug>): <goal>". Green, or red on an import error: fix it, refreeze.
• Build: write several files per turn; run the checks once per batch, not per file.
• Verify = two turns. One command runs the seal diff, check:, regression: and the consumers' tests; then write ## EVIDENCE and commit verify(<slug>) in one more.
• Subagents: at most one per beat, in the foreground — never pause the session to wait for one.

Size the work — you route and go

Floor: anything touching security · data · architecture, or that changes the shape of a surface other code consumes (signature, return, status, format), is at least a Task — never Quick. A fix that restores intended behavior without changing its shape is not. When in doubt, size up.

Quick: read the nearest tests and sibling code of what you change, and grep every other site that calls or emits it: the fix keeps their conventions (inputs not mutated, parallel paths consistent, the neighbours' pattern), so the fix the request literally suggests may be the wrong one. A change to behavior (a bug fix, a new case) gets a test: the request's own example and one case the most plausible wrong fix would pass (its falsifier; non-code: the check that fits); watch it fail, make it pass. No new behavior (a typo, a rename, a comment or docs, a config value, making an already-failing test pass) needs no new test. Either way run the suite, review your diff. No suite runs? Run the request's repro as written, else import every file you touched and trace its inputs through your edit. The last lines of your reply (and any commit body): lane: quick — <why> · intent: <convention → how the fix keeps it> · red→green: <test> or test: none — <what covers it> · suite: <cmd> → <result> (or suite: unavailable — <why> · ran: <what>). Floor touched, or a check to weaken? It is a Task now. A security issue you pass by stays out of the diff and leads the report: HARD-STOP.

The task loop — Direction → Build → Verify

1 · Direction — write the contract, watch it fail, seal it

Ground first: read the code the task touches, its nearest tests, and ## Decisions that bind in .add/specs/. Name the task's risks: — failure classes it could cause (authorization, data loss, migration, concurrency, compatibility, privacy …); they pick the persona, evidence and residue lenses. Write .add/tasks/<slug>.md:

---
type: Task
title: <title>
status: direction        # → build in the freeze commit · → done in the verify commit
risks: [<failure classes this change could cause>]   # [] when none
scope: [<paths you may touch>]
gives: [S1 <a surface other code will depend on>]
---
## CARD
goal: <one line> · why: <one line>
## RULES
- M1 <what it must do> (from: request | <file> | <spec> | derived: <why>)
- R:<CODE> <what it must refuse> (from: …)
## ASSUMPTIONS
- A1 [<dim>] <what is not said> → <reading taken> → <cost if wrong>
## PLAN
strategy: <how> · check: <this task's tests> · regression: <the full suite | affected: <cmd> — why>
## CHECKS
- C1 covers: M1 · acceptance · <test id> · falsifier: <the plausible wrong build it fails>
## EVIDENCE
<written once, at verify>

• RULES — what you were told or what code and specs require, with its source. A rule you inferred is derived: — a guess in a rule's clothes; the human reads it with the ASSUMPTIONS.
• ASSUMPTIONS — every real silence you had to fill, one per line; a dimension the request settles gets no line, and - none — <why> is valid. Sweep each public surface on six dims: who may act or see (silent → the least-privilege reading, only the owner: widening later is safe, narrowing breaks callers) · which cases are in · when (boundaries inclusive?) · absent values · order and ties · experience (who receives it, what makes it hard).
• CHECKS — at least one per Must and Reject: every RULES id appears on some covers: line. Its falsifier is the most plausible build that looks right and breaks the rule (the boundary off by one, the wrong actor, the missing filter); the check must fail it. Acceptance checks go through the public seam first, in their own files, and send inputs the way a real caller sends them, not the way your code expects: each value in every form the spec allows (a timestamp with and without an offset), and malformed or wrong-typed input refused, never a crash — the body itself (not JSON, null, a number, a list) as well as each field. A risks: rule gets a second, independent kind of evidence (references/evidence.md). Non-code work: anything that can fail is a check (references/format.md).

Second reader — every floor task, however small. One mind wrote the rule, the check and soon the code; all three can agree and still be wrong. Before sealing, the counter-lens (§ Personas) reads only the request and the task file and names the likeliest wrong readings of RULES and ASSUMPTIONS; fix what holds. Security work: one fresh subagent does it. Anything else: your own cold reread.

Seal: the checks must fail because the behavior is absent — a green proves nothing. Then set status: build, commit task file and checks as freeze(<slug>): <goal>; status: next changes at verify.

2 · Build — code to green, inside the lines

Write code until every check passes, never crossing these three lines:

1. Never edit a sealed check or the contract to get green. A hard check is telling you about the code.
2. Never move a gives: surface silently. Internals are free.
3. Stay inside scope:. Needing another path means the plan was wrong.

Contract wrong (a rule, a mis-aimed check, scope must grow, a new risk)? Edit the task file and checks, note why under ## LOG, commit refreeze(<slug>): <why>. Other tests are yours to change.

3 · Verify — trust evidence, not the diff

1. Seal intact: F=$(git log -1 --format=%H --grep='freeze(<slug>)'), then git diff $F HEAD -- .add/tasks/<slug>.md <check files> must print nothing.
2. Fresh green: on the clean committed tree, run check: and regression:. A check you cannot run is not green: record the Quick fallback; the verdict is at best RISK-ACCEPTED.
3. Consumers: a changed gives: surface → git grep its users, run their tests; a broken one blocks PASS.
4. Residue — what passing tests cannot show. Read the diff for security (authz, injection, secrets, unsafe input) · concurrency · architecture · each risks: lens (references/evidence.md).
5. Refute — Security work: the counter-lens (a fresh subagent) reads the task file before the diff and breaks your green with 1–3 executable probes from the frozen rules (new values · two rules composed · a boundary a rule implies); record each output. A probe that breaks it: back to Build, or refreeze the rule. Other tasks: probes: none — <why>, or the probes you chose to run.

6. Verdict — exactly one, in ## EVIDENCE with freeze sha, head sha, commands, exit codes, counts, consumers, residue, probes, and lens: (who looked, what they caught; or none — why):

   • PASS — seal intact, fresh green, consumers green, residue clean. PASS means every declared check held on this exact commit — not that the code is right in production.
   • RISK-ACCEPTED — a known non-security risk, with reason and owner.
   • HARD-STOP — a security finding, or a green you cannot honestly trust. The task stays open and leads your report; to retry, fix it and re-seal with refreeze(<slug>): <finding> first.

   Set status: done only on PASS or RISK-ACCEPTED. Commit verify(<slug>): <verdict>.

4 · Learn — close the loop

A lesson (a surprise, a wrong assumption) goes to .add/specs/<lens>.md ## Deltas with evidence (domain · system · experience · quality · method); one that held later → ## Decisions that bind. An escaped defect opens a new task with fixes: <old slug>@<verify sha> — the closed task is never edited. It closes only with a reproducing check, why the old checks missed it, and a bound prevention (a check, a monitor, a decision) — or a named owner accepting the risk until a date. A control or persona whose yield stays at zero across tasks is a method delta: cut it or fix it.

Milestones and release

A theme becomes .add/milestones/<slug>.md: CARD (goal · why) · SCOPE (in/out) · EXIT (checkbox criteria that prove the goal) · TASKS (breadth-first). Done when every EXIT box is checked with evidence — not when its tasks are. Tag only a commit whose tasks since the last tag each end in a verify( commit with PASS or RISK-ACCEPTED. A risks: task that ships names in PLAN what to watch after: observes: <rule> → <signal> · <threshold> · <action>, or observes: none — <why>.

Report — the human's review

End every session with a summary the human can act on: HARD-STOPs and open risks first, then per task — goal, verdict, freeze sha, evidence, and every ASSUMPTION and derived: rule you took, costliest if wrong first. Update PROJECT.md's CARD; open a PR when the repo uses them.

Personas — lenses that pick what must be proven

.add/personas/<name>.md holds expert lenses: flow: · covers-risks: · evidence: · counter-lens:. Lead = best fit on beat and risks:; one more only for a risk the lead leaves bare. None in the project → .add/personas-index/use-when.md; none fits → proceed. The second reader and the refuter load the lead's counter-lens:. A persona advises, never lowers a rule. Routing, lens: traces and upkeep: references/personas.md.

Non-negotiable rules