@pilotspace/add 1.0.0

package/docs/02-the-flow.md

@@ -0,0 +1,93 @@
+# 02 · The flow, and what is disposable
+
+[← 01 Core principles](./01-principles.md) · [Contents](./README.md) · Next: [03 Step 1 Specify →](./03-step-1-specify.md)
+
+---
+
+## The flow
+
+AIDD is one repeatable flow of six steps, followed by an observation loop. People perform the first four steps (with AI assistance), the AI performs the fifth (under direction), and people perform the sixth.
+
+![The ADD flow — a solid forward spine Specify→Scenarios→Contract→Tests→Build→Verify→Observe, with dashed backward-correction arrows (any phase may return to an earlier one), a Tests⇄Build red/green engine, and Observe looping back to the next Specify](./add-flow.png)
+
+```mermaid
+flowchart LR
+  S1["1 Specify<br/>the rules"] --> S2["2 Scenarios<br/>pass/fail cases"]
+  S2 --> S3["3 Contract<br/>freeze the shape"]
+  S3 --> S4["4 Tests<br/>safety net (red)"]
+  S4 --> S5["5 Build<br/>AI writes code"]
+  S5 --> S6["6 Verify<br/>evidence + checks"]
+  S6 --> OBS["Observe<br/>in production"]
+  S5 -. "red / green engine" .-> S4
+  S6 -. "evidence fails → back to Build" .-> S5
+  S5 -. "a missing rule → back to Specify" .-> S1
+  OBS -. "what you learn becomes the next spec" .-> S1
+  classDef human fill:#FAEEDA,stroke:#BA7517,color:#633806;
+  classDef seam fill:#E1F5EE,stroke:#0F6E56,color:#04342C;
+  classDef machine fill:#E6F1FB,stroke:#185FA5,color:#042C53;
+  class S1,S2 human;
+  class S3,S4 seam;
+  class S5,S6 machine;
+```
+
+> **Solid arrows are the forward spine** — you never start a phase before its input exists (forward-skip forbidden). **Dashed arrows are backward correction** — any phase may return to an earlier one to repair its artifact (the long loop, Observe → Specify, is the same rule at milestone scale). The tight Tests ⇄ Build cycle is the per-feature red/green engine.
+
+```text
+  human-led ─────────────────►│◄─────────── machine-led ──► human verify
+  1 Specify → 2 Scenarios → 3 Contract → 4 Tests ⇄ 5 Build → 6 Verify
+       ▲                        (freeze)   └red/green┘  (AI)     (people)
+       ╎                                                            │
+       ╎╴╴ backward correction (dashed): any phase may return to ╴╴╴┤
+       ╎    an earlier one — e.g. Build exposes a missing rule      │
+       │                                                            │
+       │                  observe in production  ◄──────────────────┘
+       │                         │
+       └─────────────────────────┘  becomes the next Specify
+```
+
+The shape is deliberate: the human-led steps establish direction, a frozen contract forms the seam in the middle, and the AI-led build runs fast and safely on the far side because everything it needs is already fixed.
+
+## Why the order is the order
+
+Each step produces exactly one artifact, and each artifact is the input to the next step. The order is not a preference; it is a dependency chain.
+
+| Step | Produces | Which is needed by |
+|------|----------|--------------------|
+| 1 Specify | the rules | scenarios, and everything after |
+| 2 Scenarios | pass/fail cases | the tests |
+| 3 Contract | the fixed shape | the tests and the build |
+| 4 Tests | the failing safety net | the build and the verification |
+| 5 Build | the code | the verification |
+| 6 Verify | a trusted, releasable change | the release and the next loop |
+
+The single rule of discipline follows directly: **do not begin a step until the previous artifact exists.** Skipping forward means the AI builds against a guess.
+
+The flow runs in two directions under two rules that never conflict. **Backward correction is always allowed:** any phase may send you back to an earlier one to repair its artifact — a failing Build that exposes a missing rule sends you back to Specify, and that is the loop working ([principle 4](./01-principles.md)), not a failure. **Forward-skipping is forbidden:** you never start a phase before its input artifact exists. Correct backward freely; never skip forward.
+
+## Who does what
+
+| Step | Person's job | AI's job |
+|------|--------------|----------|
+| 1 Specify | decide and confirm the rules | draft; list assumptions to confirm |
+| 2 Scenarios | decide what "correct" looks like | draft scenarios |
+| 3 Contract | approve and freeze the shape | generate the contract and mocks |
+| 4 Tests | set the targets | generate failing tests |
+| 5 Build | direct in small batches | implement until tests pass |
+| 6 Verify | confirm via evidence + judgment | (none — this is the human check) |
+
+## What survives, and what is disposable
+
+This is the idea that most distinguishes AIDD from older practice.
+
+**The artifacts are the durable asset.** The specification, the scenarios, the contract, and the tests capture decisions and meaning. They are what you protect, version, and carry forward.
+
+**The code is disposable.** It is one implementation that satisfies the artifacts. If a better approach appears, or the AI model improves, the code can be regenerated against the same artifacts without loss.
+
+A practical test of whether a team has absorbed this: ask what they would be upset to lose. If the answer is "the code," they are still working the old way. If the answer is "the contracts and the tests," they are working in AIDD.
+
+> **Do:** invest in clear, stable specs, contracts, and tests.
+> **Don't:** measure progress by how much code was generated or reused — that counts the cheap, disposable thing.
+
+## How the rest of Part II is organized
+
+Each of the next seven chapters takes one step (and then the loop) and gives it the same treatment: its purpose, who does it, the artifact it produces, the AI prompt that drives it, the exit check that says it is done, and what to do when that check fails. The running example continues throughout.

package/docs/03-step-1-specify.md

@@ -0,0 +1,117 @@
+# 03 · Step 1 — Specify
+
+[← 02 The flow](./02-the-flow.md) · [Contents](./README.md) · Next: [04 Step 2 Scenarios →](./04-step-2-scenarios.md)
+
+> **Purpose:** state, in plain language, what the feature must do and what it must reject, with no ambiguity left for the AI to resolve by guessing.
+> **Produces:** `SPEC.md` for the feature.
+> **How it works — co-specification:** AI and human **brainstorm the shape together**; the AI drafts; the **human validates, with the AI's advice.** The decisive advice is a *least-sure flag* — the AI names the one or two things most likely to be wrong, so the human's attention lands where it matters. The human owns the decision; the AI owns surfacing what it does not yet know.
+
+---
+
+## Why this step is first
+
+The specification is the description the AI will build from. Every other artifact descends from it. Anything vague here does not stay vague — it becomes a concrete wrong guess in the code, discovered late. The cheapest moment to remove an ambiguity is now, in a sentence, before anything depends on it.
+
+There is also a diagnostic value: **if you cannot write the spec, you do not yet understand the feature well enough to build it.** The inability to specify is information, not an obstacle to push past.
+
+## Co-specification — how the spec gets made
+
+A specification is not dictated by one side. It is made in three moves:
+
+1. **Diverge — brainstorm by both.** Before drafting, the AI surfaces the *decision space*: the two or three genuine ways to frame the feature, and the open questions it would otherwise resolve by guessing. You react — add, kill, redirect. This is the brainstorm, and it lives in the conversation, not in a new document.
+2. **Converge — the AI drafts, and ranks its own uncertainty.** The AI writes the spec below, then ranks what it is least sure about. It does not hand you a flat wall of equal-looking assumptions to nod through; it tells you *where it is most likely wrong, and what that would cost.*
+3. **Validate — you decide, with the AI's advice.** You read the ranked uncertainty first, then confirm, correct, or send it back. Your approval is real because your attention was aimed.
+
+The brainstorm leaves a *light trace, not a document.* What you chose becomes a rule; what you weighed and dropped becomes a one-line **`Framings weighed:`** note; what stayed genuinely uncertain becomes a **least-sure flag**. Nothing new to maintain — the residue lands in the spec you were writing anyway.
+
+## What a good specification contains
+
+Four parts, kept short:
+
+1. **Must** — the behaviors the feature is required to perform.
+2. **Reject** — the inputs or situations it must refuse, each paired with a named error.
+3. **After** — the state that is true once it succeeds (what changed).
+4. **Assumptions — least-sure first** — the things you are taking for granted, **ranked so the most-likely-wrong come first.** The top one or two carry a `⚠` flag with *why it is uncertain* and *what it costs if wrong*; the rest are the low-stakes tail. A spec with genuinely nothing uncertain still names its single biggest risk, however small — the AI never claims a blank mind.
+
+Naming the errors matters. "Reject bad amounts" is an instruction to guess; `amount <= 0 -> "amount_invalid"` is a rule that produces a testable scenario and a defined contract response.
+
+## Template
+
+```
+# SPEC.md
+Feature: <name>
+Framings weighed: <chosen> (chosen) · <alternative> · <alternative>
+Must:
+  - <required behavior>
+Reject:
+  - <bad input / situation> -> "<error_code>"
+After:
+  - <what is true once it succeeds>
+Assumptions — least-sure first:
+  ⚠ <most-likely-wrong assumption> — least sure because <why>; if wrong: <cost>
+  - [x] <confirmed / low-stakes assumption> — <one line>
+```
+
+## ▶ Example
+
+```
+Feature: Transfer money between my own accounts
+Framings weighed: synchronous single-currency transfer (chosen) · queued transfer · multi-currency with FX
+Must:
+  - move an amount from one of my accounts to another of mine
+  - amount > 0
+  - source and destination are different accounts
+  - source has enough balance
+After:
+  - source balance -= amount, destination balance += amount
+Reject:
+  - amount <= 0           -> "amount_invalid"
+  - source == destination -> "same_account"
+  - balance < amount      -> "insufficient_funds"
+  - account not mine      -> "forbidden"
+Assumptions — least-sure first:
+  ⚠ same currency only (no FX) in v1 — least sure because the ticket never said; if wrong: the whole amount/rounding model changes and this contract is wrong
+  - [x] no daily limit in v1 — confirmed: out of scope for v1
+```
+
+The `Framings weighed:` line shows what was considered and dropped, so the chosen shape is a *decision*, not a default. The `⚠` line is the one the stakeholder reads first: the assumption most likely to be wrong and most expensive to get wrong. The flat `[x]` line is real but low-stakes. A reviewer can now spend their attention where it pays.
+
+## The AI's role here
+
+Use the AI to **open the space and then narrow it honestly.** First it brainstorms the genuine framings with you (diverge). Then it drafts the spec from whatever raw material you have — a ticket, an interview, a contract document — listing every assumption it had to make, **ranked least-sure first**, and flagging the one or two it is least confident in with *why* and *what it costs if wrong*. Its instinct is to fill gaps silently and present a confident wall; the method forces those gaps into the open, and forces the confident wall to declare its own soft spots. See `playbook/1_specify.md` in [Appendix B](./appendix-b-prompts.md).
+
+The defining instruction: *if a requirement is unclear, ask — do not resolve it by guessing — and of the things you must assume, say plainly which you are least sure about.*
+
+## Common mistakes
+
+- **Stating only the happy path.** The "Reject" list is where most real complexity lives; an empty one usually means it has not been thought through.
+- **Free-text errors.** Errors must be named codes, not sentences, so they can become scenarios and contract responses.
+- **Hidden assumptions.** If an assumption is not written down, it is not confirmed — it is a future bug with a delay timer.
+- **A flat wall of "confirmed" assumptions.** Eight equal-looking ticks invite a reflex approval. Rank them; flag the one or two that are load-bearing. An unranked list hides the risk inside the noise.
+
+## Exit check
+
+A spec is done when:
+
+- [ ] Every required behavior is stated explicitly.
+- [ ] Every rejection has a named error code.
+- [ ] The success state-change is described.
+- [ ] The assumptions are ordered least-sure first, and the one or two `⚠` flags carry *why* + *cost* — or, for genuinely trivial scope, an honest "none material" that still names the single biggest risk.
+
+The shift from older practice: you no longer pre-confirm every assumption to advance. You confirm that the AI has *ranked* its uncertainty and that you have *engaged the top of the rank.* Stated honestly: the flag makes a genuine review cheap and a lazy one visibly negligent — it cannot force the read. That is the most a lightweight check can buy.
+
+## If the check fails
+
+If you cannot state a rule clearly, the feature is not ready to build. Stop, take the question to whoever owns the requirement, and resolve it. Do not let the AI proceed on an unresolved point — that is the exact failure the whole method exists to prevent.
+
+---
+
+## The one approval, and where the flag really lands
+
+In the one-approval front, you do not approve the spec alone — you approve the whole frozen bundle (spec, scenarios, contract, tests) once, at the contract freeze. So the least-sure flag is **bundle-wide**: at that single seam the AI leads with *"of everything I'm asking you to freeze, these one or two points are most likely wrong"* — and a flag may point at an uncovered scenario or the contract shape, not only a spec assumption. The ranking you do here in Specify is the first feeder into that one gate. See [05 Contract](./05-step-3-contract.md) and the `add` skill's `run.md`.
+
+---
+
+## When the feature has a user interface
+
+For anything with a UI, extend this step with a quick design: the **user flows** (the happy path and the main alternatives) and **every screen state** — loading, empty, error, and success. Correct logic behind a confusing or incomplete interface is still a poor product, and undesigned states are exactly where an AI will improvise something ugly. In the early **Prototype** stage, this design work is the main event and the code is throwaway (see [10 Stages](./10-setup-and-stages.md)).

package/docs/04-step-2-scenarios.md

@@ -0,0 +1,78 @@
+# 04 · Step 2 — Scenarios
+
+[← 03 Step 1 Specify](./03-step-1-specify.md) · [Contents](./README.md) · Next: [05 Step 3 Contract →](./05-step-3-contract.md)
+
+> **Purpose:** rewrite each rule from the spec as a concrete, pass-or-fail scenario.
+> **Produces:** `features/<name>.feature`.
+> **Person's job:** decide what "correct" looks like in concrete situations. **AI's job:** draft the scenarios.
+
+---
+
+## Why turn rules into scenarios
+
+A plain rule is still open to interpretation. "Source must have enough balance" leaves open: enough for what, exactly? What happens to the balances when it is *not* enough? A scenario removes the interpretation by pinning a specific situation to a specific expected result.
+
+Scenarios occupy a unique position: they are **readable by people and checkable by machines at the same time.** A product owner can confirm a scenario is what they meant; a test can be generated directly from it. This makes them the bridge between the human-led front of the flow and the machine-led back. They are the single most leverage-bearing artifact in the method, because everything downstream — the tests, and through them the build's definition of success — is generated from them.
+
+## The form
+
+Each scenario has three parts:
+
+- **Given** — the starting situation.
+- **When** — the action taken.
+- **Then** — the result that must follow.
+
+Where a rule also constrains what must *not* change, add an **And** clause to state it. Unwanted side effects are caught by what you assert stays the same, not only by what you assert changes.
+
+## Template
+
+```
+Scenario: <short name>
+  Given <starting situation>
+  When <action>
+  Then <expected result>
+  And <what must remain unchanged>   # when relevant
+```
+
+## ▶ Example
+
+```
+Scenario: successful transfer
+  Given A has 100 and B has 0, both mine
+  When I transfer 30 from A to B
+  Then A has 70 and B has 30
+
+Scenario: insufficient funds
+  Given A has 20, mine
+  When I transfer 50 from A to B
+  Then it is rejected "insufficient_funds"
+  And no balance changes
+
+Scenario: not my account
+  Given account C is not mine
+  When I transfer 10 from C to B
+  Then it is rejected "forbidden"
+```
+
+The `And no balance changes` line is doing real work: it specifies that a rejected transfer must leave the world untouched — a property the AI could easily violate by deducting before checking.
+
+## The AI's role here
+
+Hand the AI the spec and have it draft a scenario for each rule, including the rejection rules. Then read them as the person who owns the requirement: do they describe what you actually meant? Correct any that drift. See `playbook/2_scenarios.md` in [Appendix B](./appendix-b-prompts.md).
+
+## Common mistakes
+
+- **Only happy-path scenarios.** Every "Reject" rule in the spec needs its own scenario, or that rule will never be verified.
+- **Vague results.** "Then it works" is not checkable. The result must be a specific, observable fact ("A has 70").
+- **Forgetting the unchanged state.** For any rejection, assert that nothing changed; otherwise a partial, corrupting failure can pass.
+
+## Exit check
+
+- [ ] Every "Must" rule has at least one scenario.
+- [ ] Every "Reject" rule has at least one scenario.
+- [ ] Each scenario's result is a specific, observable fact.
+- [ ] Rejections assert what must stay unchanged.
+
+## If the check fails
+
+A rule with no scenario will never be tested, and therefore will never be verified — it is a rule in name only. Either write the missing scenario or remove the rule from the spec. Do not carry an unscenarioed rule into the contract.

package/docs/05-step-3-contract.md

@@ -0,0 +1,78 @@
+# 05 · Step 3 — Contract
+
+[← 04 Step 2 Scenarios](./04-step-2-scenarios.md) · [Contents](./README.md) · Next: [06 Step 4 Tests →](./06-step-4-tests.md)
+
+> **Purpose:** fix the external shape of the feature — interfaces, data structures, names, and error cases — and freeze it.
+> **Produces:** `contracts/<name>.md` (plus a mock and contract tests).
+> **Person's job:** approve and freeze the shape. **AI's job:** generate the first draft, the mock, and the contract tests.
+
+---
+
+## The seam of the whole method
+
+This step is the seam between the human-led and machine-led halves of the flow, and it is what makes everything after it safe.
+
+The reasoning is simple. The AI is allowed to write and rewrite code quickly. That is only safe if there is a stable surface that the rest of the system depends on and that the AI is not allowed to disturb. The frozen contract is that surface. Below it, the code is disposable and can be regenerated freely; above it, nothing breaks, because the shape it depends on does not move.
+
+Freezing the contract is therefore not bureaucracy — it is the precondition for granting the AI real autonomy in the build step. Without it, every regeneration risks silently changing an interface that another part of the system relies on.
+
+## What the contract contains
+
+- **Interfaces** — the endpoints, functions, or messages, with their inputs and outputs.
+- **Data structures** — the request and response shapes, and the persistent schema.
+- **Names** — drawn from the project glossary, so the same concept has the same name everywhere.
+- **Error cases** — the defined failures, using the error codes from the spec.
+
+## Template
+
+```
+# contracts/<name>.md
+<METHOD> <path>   body: { <fields> }
+  200 -> { <success fields> }
+  4xx -> { error: "<code>" | "<code>" }
+Schema: <tables/fields touched, and access pattern>
+Status: FROZEN @ v<n>
+```
+
+## ▶ Example
+
+```
+POST /transfers   body: { fromAccountId, toAccountId, amount }
+  200 -> { transferId, fromBalance, toBalance }
+  400 -> { error: "amount_invalid" | "same_account" | "insufficient_funds" }
+  403 -> { error: "forbidden" }
+Schema: accounts.balance (read + write, must be transactional)
+Status: FROZEN @ v1
+```
+
+Every error code traces back to a rejection rule in the spec, and the schema note (`must be transactional`) flags the one place where correctness depends on more than shape — a hint the verification step will follow up.
+
+## The AI's role here
+
+The AI generates the contract from the spec and design, and additionally produces two things that make the contract enforceable: a **mock server** that returns the contracted shapes, and **contract tests** that pin those shapes. With the mock in place, work that depends on this feature can proceed before the real code exists. See `playbook/3_contract.md` in [Appendix B](./appendix-b-prompts.md).
+
+## The change-request rule
+
+Once frozen, a contract does not change casually. A needed change is a **change request**: you return to [Step 1](./03-step-1-specify.md), adjust the spec, re-freeze at a new version, and come forward again. The AI never alters a frozen contract on its own initiative.
+
+This rule is what keeps the contract trustworthy as a foundation. If it could drift, nothing built on it would be safe.
+
+> **Do:** version and freeze the contract before any implementation.
+> **Don't:** let the build step quietly change an interface to make code easier — that breaks everything depending on it.
+
+## Common mistakes
+
+- **Inconsistent names.** If the contract calls it `fromAccountId` and the schema calls it `src_acct`, the AI will produce subtle mismatches. Use the glossary everywhere.
+- **Undefined errors.** Every failure the spec rejects must have a contracted response, or callers cannot handle it.
+- **Freezing too early or too late.** Freeze once the spec and design are stable — not before they are agreed, and not after code has already been written against an unfrozen shape.
+
+## Exit check
+
+- [ ] Contract is versioned and marked `FROZEN`.
+- [ ] Contract tests pass against the mock.
+- [ ] Every name matches the project glossary.
+- [ ] Every spec rejection has a contracted error response.
+
+## If the check fails
+
+If the contract is not yet stable enough to freeze, the upstream artifacts are not settled — return to the spec or scenarios and resolve what is still open. If a frozen contract later needs to change, treat it as a change request rather than an edit; the discipline is the point.

package/docs/06-step-4-tests.md

@@ -0,0 +1,71 @@
+# 06 · Step 4 — Tests
+
+[← 05 Step 3 Contract](./05-step-3-contract.md) · [Contents](./README.md) · Next: [07 Step 5 Build →](./07-step-5-build.md)
+
+> **Purpose:** turn the scenarios and contract into automated tests, and confirm they fail before any code exists.
+> **Produces:** a failing (red) automated test suite.
+> **Person's job:** set the targets and coverage. **AI's job:** generate the tests.
+
+---
+
+## Why tests come before code
+
+This is the step that operationalizes the second principle — *trust through evidence, not inspection.* The tests written here are how you will judge the AI's code in [Step 5](./07-step-5-build.md). For that judgment to be honest, the tests must exist *before* the code.
+
+The reason is mechanical. If code is written first and tests after, the tests are unconsciously shaped to match whatever the code happens to do — including its mistakes. Tests written first, from the scenarios, are shaped only by the agreed definition of correct. They are an independent standard the code must rise to meet, not a description of what the code already does.
+
+## The must-fail principle
+
+After generating the tests, you run them — and they must **fail**, because no implementation exists yet. This sounds trivial and is not. A test that passes before any code is written is testing nothing; it is a false reassurance that will later wave bad code through. Confirming the suite is "red for the right reason" (a missing implementation, not a broken test) is what makes it a genuine safety net.
+
+## What to test
+
+- **One test per scenario** — every scenario from [Step 2](./04-step-2-scenarios.md) becomes an executable test.
+- **Contract conformance** — tests that pin the shapes and error responses from [Step 3](./05-step-3-contract.md).
+- **Edge cases from the spec** — the boundary values implied by the "Reject" rules.
+- **Behavior, not internals** — tests assert what the feature does (the observable result), never how it is implemented, so the code can be regenerated freely beneath them.
+
+## ▶ Example
+
+```python
+def test_successful_transfer():
+    a = account(balance=100, owner=me); b = account(balance=0, owner=me)
+    r = transfer(a.id, b.id, 30)
+    assert r.status == 200
+    assert a.balance == 70 and b.balance == 30
+
+def test_insufficient_funds():
+    a = account(balance=20, owner=me); b = account(balance=0, owner=me)
+    r = transfer(a.id, b.id, 50)
+    assert r.status == 400 and r.error == "insufficient_funds"
+    assert a.balance == 20    # unchanged — the side-effect assertion
+
+def test_not_my_account():
+    c = account(balance=100, owner=someone_else); b = account(balance=0, owner=me)
+    r = transfer(c.id, b.id, 10)
+    assert r.status == 403 and r.error == "forbidden"
+```
+
+Run this now, with no implementation: all three fail. That is the correct, honest starting point for the build.
+
+## The AI's role here
+
+The AI generates the test suite from the scenarios and contract. Your job is to confirm two things it cannot judge for itself: that each test asserts *behavior* rather than internal detail, and that none of them pass by accident before code exists. See `playbook/4_tests.md` in [Appendix B](./appendix-b-prompts.md).
+
+## Common mistakes
+
+- **Tests that test the implementation.** Asserting on private internals couples the test to one version of the code and defeats disposability.
+- **A green suite before the build.** Means the tests are not actually exercising the missing feature — fix them now.
+- **Skipping the side-effect assertions.** Without `assert a.balance == 20` on the rejection path, a corrupting partial failure passes silently.
+- **No coverage target.** Without a recorded target, coverage can quietly erode during the build.
+
+## Exit check
+
+- [ ] One test exists per scenario.
+- [ ] The suite runs in the pipeline and is **red for the right reason**.
+- [ ] Tests assert observable behavior, not internals.
+- [ ] A coverage target is recorded.
+
+## If the check fails
+
+If a test passes before any implementation, it is a fake test — repair it before continuing, because it is your only independent check on the AI. If the suite is red for the wrong reason (a syntax or harness error), fix the harness first; a build cannot be judged against a broken net.

package/docs/07-step-5-build.md

@@ -0,0 +1,80 @@
+# 07 · Step 5 — Build
+
+[← 06 Step 4 Tests](./06-step-4-tests.md) · [Contents](./README.md) · Next: [08 Step 6 Verify →](./08-step-6-verify.md)
+
+> **Purpose:** have the AI implement the feature so that every failing test passes.
+> **Produces:** working code, plus the evidence that the tests now pass.
+> **Person's job:** direct, in small batches. **AI's job:** implement.
+
+---
+
+## The only step the AI leads
+
+This is the step the AI is genuinely good at, and the only one where it should be doing the heavy lifting. It works precisely because the previous four steps removed all the ambiguity: the AI is no longer guessing what to build: it has a spec, a set of scenarios, a frozen contract, and a suite of failing tests that define "done" exactly. Its task is narrow and checkable — turn the suite green.
+
+This is the difference between AIDD and vague-prompt coding. The same agent that produces confident nonsense from "build me a transfer feature" produces correct, bounded code from "make these specific failing tests pass without changing them." The agent did not change; the direction did.
+
+## The build prompt
+
+The instruction is explicit about constraints, because the constraints are what keep the speed safe.
+
+```
+Read SPEC.md, contracts/<name>.md, and tests/<name>_test.py.
+Implement the feature so that EVERY test passes.
+Constraints:
+  - Do NOT change any test.
+  - Do NOT change the contract.
+  - <feature-specific safety rule>.
+  - Stop and ask if any requirement is unclear — do not guess.
+  - Use only packages listed in dependencies.allowlist.
+Report which tests pass and exactly what you changed.
+```
+
+For the running example, the feature-specific safety rule is *"make the balance update atomic — debit and credit occur in a single transaction."* This is the one correctness property the tests alone may not force, so it is named directly to the builder.
+
+See `playbook/5_build.md` in [Appendix B](./appendix-b-prompts.md).
+
+## Work in small batches
+
+Direct the AI one task at a time, and keep each task small enough that its result can be reviewed in full. This is a direct application of the principle *you cannot move faster than you can verify.* A single enormous change that turns the whole suite green at once is not a triumph — it is an unreviewable blob. Small batches keep the verification step (next chapter) tractable and keep a human genuinely in the loop.
+
+## The iteration loop
+
+```
+AI writes code → pipeline runs the tests → some still fail
+   → AI iterates → ... → all green → hand to Verify
+```
+
+The loop is tight and largely autonomous within a task: the AI runs the tests, sees what fails, and adjusts. Your attention is needed at the boundaries — defining the task going in, and reviewing the result coming out — not on each internal iteration.
+
+## The cardinal rule: never change the test to pass
+
+An AI under pressure to make a suite green has an available shortcut: weaken or delete the failing test. This must be forbidden explicitly and caught reliably. A test changed to fit the code inverts the entire method — the code is now judging itself. If you find a test was altered during the build, reject the change outright and re-prompt with the constraint restated.
+
+The same applies to the contract: the build implements *against* the frozen contract and may not edit it. A genuine need to change either is a change request that returns to an earlier step.
+
+## How much autonomy
+
+The autonomy granted in this step should match the evidence and your review capacity (see [11 Governance](./11-governance.md)):
+
+- Where the area is new or risky, the AI proposes and a person reviews every change.
+- Where the contract and tests are solid, the AI generates freely and a person reviews each batch.
+- Only in narrow, well-tested areas, with a full evidence bundle attached, may the AI integrate its own work.
+
+## Common mistakes
+
+- **Batches too large to review.** Shrinks verification to rubber-stamping.
+- **Letting the AI add unknown dependencies.** The allow-list check in the pipeline should block this automatically; if it does not, the supply-chain risk is real (an AI may invent a plausible package name that an attacker has registered).
+- **Accepting "all tests pass" without reading the change.** Passing tests are necessary, not sufficient — the next step exists for exactly this reason.
+
+## Exit check
+
+- [ ] All tests pass.
+- [ ] Test coverage did not decrease.
+- [ ] No test and no contract was modified by the AI.
+- [ ] No dependency outside the allow-list was added.
+- [ ] The change is small enough to review in full.
+
+## If the check fails
+
+If the AI weakened a test, reject and re-prompt. If it added an out-of-allow-list package, the pipeline blocks it; have the AI find an approved alternative or raise the package for human approval. If the batch is too large to review, ask the AI to split the work and resubmit. Only once the exit check passes does the change proceed to verification.

package/docs/08-step-6-verify.md

@@ -0,0 +1,63 @@
+# 08 · Step 6 — Verify
+
+[← 07 Step 5 Build](./07-step-5-build.md) · [Contents](./README.md) · Next: [09 The loop →](./09-the-loop.md)
+
+> **Purpose:** confirm the result is correct and safe to release.
+> **Produces:** a reviewed change with a recorded outcome, ready to release.
+> **Person's job:** this entire step. There is no AI role here — it is the human check.
+
+---
+
+## Where trust is actually established
+
+The build produced passing tests. That is necessary but not sufficient. Verification is where a person establishes trust — and the principle governing it is *trust through evidence, not inspection.*
+
+This needs care, because it is easy to misread. "Not by inspection" does not mean "do not look at the code." It means the *basis* of trust is the passing evidence plus a deliberate check of the specific things tests cannot easily catch — not a general impression that the code reads plausibly. Plausibility is exactly the trap: AI code is frequently plausible and wrong. So verification has two parts: confirm the evidence, then check the known blind spots.
+
+## Part one — confirm the evidence
+
+- [ ] All tests pass.
+- [ ] Coverage did not decrease.
+- [ ] No test or contract was altered during the build.
+
+If any of these is false, stop here and return to the build; there is nothing to verify yet.
+
+## Part two — check what tests miss
+
+Automated tests are excellent at behavior on defined inputs and poor at a few specific things. Check those by hand, every time:
+
+- **Concurrency and timing.** Is the operation correct when two of them happen at once? Tests usually run serially and miss races.
+  - ▶ *Example: the balance update must be one atomic transaction. Confirm that two simultaneous transfers from the same account cannot both pass the balance check and overdraw it.* This is the single most important check for this feature, and it is the reason the build prompt named atomicity explicitly.
+- **Security.** Are there exposed secrets, injection openings, or unexpected dependencies? AI-generated code is known to hardcode secrets and to pull in packages by plausible-but-wrong names.
+- **Architecture conformance.** Does the change respect the layering and dependency rules in `CONVENTIONS.md`? Speed with no architectural check produces a fast-growing tangle that becomes unmaintainable within months.
+
+## Recording the outcome
+
+Every verification ends with exactly one recorded outcome, with an accountable owner — never a silent pass:
+
+| Outcome | Meaning | Allowed when |
+|---------|---------|--------------|
+| `PASS` | all checks met | the normal path |
+| `RISK-ACCEPTED` | proceed with a signed waiver: named owner, linked ticket, expiry date | a non-security gap only |
+| `HARD-STOP` | cannot proceed | any failing test or any security finding |
+
+A security finding is always a `HARD-STOP`; it is never waved through with a waiver. A `RISK-ACCEPTED` outcome is a deliberate, documented decision to ship a known, non-security limitation — not a way to skip the check.
+
+## The verification checklist
+
+- [ ] All tests pass (the evidence).
+- [ ] Concurrency/timing of the risky operation is safe.
+- [ ] No exposed secrets, injection openings, or unexpected dependencies.
+- [ ] Layering and dependencies follow `CONVENTIONS.md`.
+- [ ] A person has reviewed and approved the change.
+- [ ] An outcome is recorded (`PASS` / `RISK-ACCEPTED` / `HARD-STOP`).
+
+## Common mistakes
+
+- **Shipping on plausibility.** Reading the diff, finding it reasonable, and approving — without the evidence and the blind-spot checks — is the precise failure the method exists to prevent.
+- **Treating a security gap as acceptable risk.** It is a `HARD-STOP`, not a waiver.
+- **Skipping the concurrency check** because the tests are green. Tests rarely exercise simultaneity; this is a manual check by design.
+
+## If the check fails
+
+A failing test or a security finding returns the change to the build step ([Step 5](./07-step-5-build.md)). A non-security limitation may proceed only with a signed `RISK-ACCEPTED` record carrying an owner and an expiry — so the team can find and close it later. Nothing proceeds on an unrecorded decision.

package/docs/09-the-loop.md

@@ -0,0 +1,43 @@
+# 09 · The loop — observe and learn
+
+[← 08 Step 6 Verify](./08-step-6-verify.md) · [Contents](./README.md) · Next: [10 Setup and stages →](./10-setup-and-stages.md)
+
+> **Purpose:** release the verified change, watch how it behaves in reality, and turn what you learn into the next specification.
+> **Produces:** a running feature, observations, and the next `SPEC.md` delta.
+
+---
+
+## The flow is a loop, not a line
+
+Older mental models end at "ship." That framing is the source of a common pathology: teams treat release as a finish line, and so they hide defects to protect the line rather than manage them in the open. In AIDD, release is not the end of the flow — it is the point where the most reliable information about the feature finally becomes available: how it behaves with real users, real data, and real load.
+
+That information is the input to the next cycle. What you learn in production becomes the next specification, and the flow returns to [Step 1](./03-step-1-specify.md). The cycle is continuous.
+
+## Release deliberately
+
+Release behind a mechanism that limits the blast radius of a mistake — a feature flag, a gradual rollout, or both. The verification step established that the feature is correct against everything you anticipated; a controlled release is your protection against what you did not anticipate. If something is wrong, you want to affect a few users and roll back, not affect everyone and scramble.
+
+## Reuse the scenarios as monitors
+
+The scenarios from [Step 2](./04-step-2-scenarios.md) have a second life here. They described the behavior you expected; in production they become the behavior you monitor. The same definition of "correct" that drove the tests now drives the alerts.
+
+**What to watch (▶ example):**
+
+- the overall transfer error rate;
+- the rate of each individual rejection (`amount_invalid`, `same_account`, `insufficient_funds`, `forbidden`) — a sudden spike in one is a signal, not noise;
+- latency, especially of the atomic balance update under load.
+
+## Turn observation into the next spec
+
+Every defect, surprise, or new need is written up as a change to the specification — a delta that re-enters the flow at [Step 1](./03-step-1-specify.md). An error rate that is too high, a rejection that fires more than expected, a user behavior nobody designed for: each becomes a concrete, specified next step rather than a vague intention.
+
+This is also where the AI returns to a useful role: summarizing telemetry, clustering errors into themes, and drafting the proposed spec delta for a person to review. But the production decisions — what to roll back, what to prioritize — remain human.
+
+## Re-entrancy: the loop is the whole point
+
+Two principles converge here. *The flow is re-entrant* — any step can send you back to an earlier one — and *the flow is a loop* — production feeds the next specification. Together they mean the artifacts you built are never "finished"; they are living documents that the next cycle refines.
+
+A team operating this way does not experience requirements changing as a failure of planning. It experiences it as the system working: reality is teaching the specification, and the specification is teaching the next build.
+
+> **Do:** release small, watch the scenarios, and feed every learning back into the spec.
+> **Don't:** treat shipping as the end. The most valuable information about a feature arrives *after* it ships.