@pilotspace/add 1.16.1 → 2.0.0

package/docs/appendix-d-worked-example.md

@@ -1,231 +0,0 @@
-# Appendix D · The worked example, end to end
-
-[← Appendix C Glossary](./appendix-c-glossary.md) · [Contents](./README.md) · Next: [Appendix E Checklists →](./appendix-e-checklists.md)
-
-The running example, assembled in one place so you can see a complete pass through the flow without flipping between chapters. The feature: **transfer money between a user's own accounts.**
-
----
-
-## Step 1 — Specify → `SPEC.md`
-
-```
-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 — lowest-confidence first:
-  ⚠ same currency only (no FX) in v1 — lowest confidence because the ticket never said; if wrong: the amount/rounding model changes and this contract is wrong
-  - [x] no daily limit in v1 — confirmed: out of scope for v1
-```
-
-The product owner read the flagged assumption first — the single-currency choice, the one most likely to be wrong and most expensive if it were — and confirmed it: v1 is single-currency with no daily limit.
-
-## Step 2 — Scenarios → `features/transfer.feature`
-
-```
-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: amount must be positive
-  Given A has 100, mine
-  When I transfer 0 from A to B
-  Then it is rejected "amount_invalid"
-  And no balance changes
-
-Scenario: same account
-  Given A has 100, mine
-  When I transfer 10 from A to A
-  Then it is rejected "same_account"
-  And no balance changes
-
-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"
-```
-
-Five scenarios for four rejections plus the happy path — every rule from the spec is covered.
-
-## Step 3 — Contract → `contracts/transfer.md`
-
-```
-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
-```
-
-Frozen at v1. The schema note flags the atomicity requirement the verification step will check.
-
-## Step 4 — Tests → `tests/transfer_test.py` (run first; all fail)
-
-```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_amount_must_be_positive():
-    a = account(balance=100, owner=me); b = account(balance=0, owner=me)
-    r = transfer(a.id, b.id, 0)
-    assert r.status == 400 and r.error == "amount_invalid"
-    assert a.balance == 100 and b.balance == 0
-
-def test_same_account():
-    a = account(balance=100, owner=me)
-    r = transfer(a.id, a.id, 10)
-    assert r.status == 400 and r.error == "same_account"
-    assert a.balance == 100
-
-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
-
-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 now, with no implementation: all five fail. That is the honest baseline.
-
-## Step 5 — Build → the prompt given to the AI
-
-```
-Read SPEC.md, contracts/transfer.md, and tests/transfer_test.py.
-Implement POST /transfers so that EVERY test passes.
-Constraints:
-  - Do NOT change any test.
-  - Do NOT change the contract.
-  - Make the balance update atomic: debit and credit in a single transaction,
-    and re-check the balance inside the transaction.
-  - Stop and ask if any requirement is unclear — do not guess.
-  - Use only packages in dependencies.allowlist.
-Report which tests pass and exactly what you changed.
-```
-
-The AI implements, runs the suite, iterates, and reports all five green, listing the files it changed.
-
-## Step 6 — Verify → the human checks
-
-- **Evidence:** all five tests pass; coverage held; no test or contract was altered. ✓
-- **Concurrency (the key check):** two simultaneous transfers from account A must not both pass the balance check and overdraw it. The reviewer confirms the balance re-check happens *inside* the transaction and that the row is locked for the update — so a race cannot double-spend. ✓
-- **Security:** no hardcoded secrets; inputs validated; no new dependency added. ✓
-- **Architecture:** the change respects the layering in `CONVENTIONS.md`. ✓
-- **Outcome recorded:** `PASS`, reviewed by the senior engineer.
-
-## The loop — observe
-
-Released behind a feature flag to 5% of users. Monitored:
-
-- transfer error rate (target: well under 0.1% of attempts);
-- the rate of each rejection — a spike in `insufficient_funds` would suggest a UX problem (users not seeing their balance) rather than a code defect;
-- latency of the atomic update under load.
-
-A week later, telemetry shows an unexpectedly high `forbidden` rate. The `6_observe` prompt clusters it: users are trying to transfer *into* a shared account they can see but do not own. That observation becomes a `SPEC.md` delta — "support transfers into accounts I am authorized on, not only accounts I own" — and the flow returns to Step 1 for the next cycle.
-
----
-
-This is the whole method in one feature: four artifacts written in order, an AI build bounded by them, a verification grounded in evidence plus the one check tests miss, and a loop that turns production reality into the next specification.
-
----
-
-## Multi-component, end to end
-
-The example above is a single codebase with one green bar. Real slices often cross components — a backend endpoint and the frontend that calls it. ADD ships that slice *inside one milestone* using the component pillar (chapter 17). Here is the same flow, now spanning two components: a `gateway` backend that **produces** an `orders` contract, and a `web` frontend that **consumes** it.
-
-### Declare the components
-
-The two parts and the boundary between them are declared in `.add/components.toml` — never inferred:
-
-```toml
-[component.gateway]
-root      = "apps/gateway"
-green_bar = "pytest + pyright"
-verify    = "pytest -q apps/gateway"
-
-[component.web]
-root      = "apps/web"
-green_bar = "vitest + a11y"
-verify    = "pnpm -C apps/web test"
-
-[contract.orders]
-producer  = "gateway"
-consumers = ["web"]
-```
-
-One milestone, **list-orders slice**, holds two tasks: `orders-api` (the BE, `produces: orders`) and `orders-list` (the FE, `consumes: orders`).
-
-### The backend freezes first → an immutable snapshot
-
-`orders-api` carries a `component: gateway` and a `produces: orders` header. It runs the normal flow — specify, scenarios, contract — and the human freezes its §3:
-
-```
-GET /orders?status=  ->  200 { orders: [{ id, status, total, placedAt }], nextCursor }
-                          400 { error: "bad_status" }
-Status: FROZEN @ v1 — approved by the tech lead
-```
-
-The moment that contract freezes and the task crosses contract→tests, the engine writes an immutable snapshot — `.add/contracts/orders.json` — recording the id, producer, version, frozen date, and a hash over the frozen §3 shape. That file *is* the published interface.
-
-### The frontend is held until the backend freezes
-
-`orders-list` (`component: web`, `consumes: orders`) was started in the same milestone, but it must not commit to a shape the backend has not frozen. When it tries to advance scenarios→contract before the snapshot exists, the engine refuses:
-
-```
-$ python3 .add/tooling/add.py advance
-add: error: producer_contract_unfrozen: orders-list consumes 'orders' but no frozen producer snapshot exists yet — the FE is held until gateway freezes
-```
-
-Once `orders.json` exists, the same `advance` succeeds: the FE writes its §3 against the frozen shape and **pins that snapshot's hash**. The slice is ordered by the contract, not by splitting BE and FE across two milestones.
-
-If the backend later *re-opens* its §3 to change the shape, the engine holds the consumer `producer_contract_stale` rather than letting it pin a shape that is mid-change — and `add.py check` separately surfaces `contract_producer_stale` / `contract_snapshot_hashless` as never-red warnings. Freeze-recency, not just existence.
-
-### Each task verifies against its own green bar
-
-At the gate, the engine holds each task to *its* component. `orders-api` must cite `pytest + pyright` in its §6 evidence; `orders-list` must cite `vitest + a11y` — cite the wrong bar (or none) and the gate refuses `component_green_bar_uncited`. The engine never runs either suite; it **surfaces** the component's `verify` command so the operator sees exactly what to run:
-
-```
-$ python3 .add/tooling/add.py gate PASS
-task 'orders-api' gate -> PASS
-component: gateway · expected green-bar: pytest + pyright · verify: pytest -q apps/gateway   # run this suite — the engine does not (NO-EXEC)
-```
-
-Two tasks, one milestone, two green bars — each held to its own, each suite run by you.
-
-### Across repositories — federation
-
-When `gateway` and `web` live in *separate* repos, only the snapshot transport changes. The `web` repo declares where the producer publishes:
-
-```toml
-[federation.orders]
-source = "../gateway/.add/contracts/orders.json"
-pin    = "v1"
-```
-
-`add.py federate pull orders` validates the producer repo's published snapshot (valid JSON, matching id, a hash, matching version) and lands a byte-for-byte copy locally — from there the FE holds and pins exactly as in a monorepo. The pull is fail-loud: an unknown id, an unreadable source, a `source` that escapes the repo's allowlist (`federation_source_escapes`), an invalid snapshot, or a version mismatch each HARD-STOPS and lands nothing. Federation never builds the FE against a guessed, out-of-tree, or stale endpoint.
-
-That is the component pillar in one slice: declare the parts, freeze the boundary, hold the consumer behind the producer, verify each part on its own bar, and carry the frozen contract across repos — all within the same six-step flow and its single contract-freeze approval.

package/docs/appendix-e-checklists.md

@@ -1,92 +0,0 @@
-# Appendix E · Checklists
-
-[← Appendix D Worked example](./appendix-d-worked-example.md) · [Contents](./README.md) · Next: [Appendix F Requirements matrix →](./appendix-f-requirements-matrix.md)
-
-Every exit check in the book, collected for quick use. Print this page.
-
----
-
-## Setup (once per project)
-
-- [ ] Pipeline runs and is green on the empty skeleton.
-- [ ] AI model pinned in `MODEL_REGISTRY.md`.
-- [ ] Dependency allow-list exists; pipeline fails on anything outside it.
-- [ ] `playbook/` contains the six prompts.
-
-## Step 1 — Specify
-
-- [ ] Every required behavior stated explicitly.
-- [ ] Every rejection has a named error code.
-- [ ] Success state-change described.
-- [ ] Assumptions ranked lowest-confidence first; the 1–2 most-likely-wrong ⚠-flagged with why + cost (or an honest "none material" that still names the single biggest risk).
-- [ ] "Existing behavior" assumptions carry grep/line citations; wiring claims name the production caller chain.
-
-## Step 2 — Scenarios
-
-- [ ] Every "Must" rule has a scenario.
-- [ ] Every "Reject" rule has a scenario.
-- [ ] Each result is a specific, observable fact.
-- [ ] Rejections assert what must stay unchanged.
-
-## Step 3 — Contract
-
-- [ ] Contract versioned and `FROZEN`.
-- [ ] Contract tests pass against the mock.
-- [ ] Names match the glossary.
-- [ ] Every spec rejection has a contracted response.
-
-## Step 4 — Tests
-
-- [ ] One test per scenario.
-- [ ] Suite runs in the pipeline and is red for the right reason.
-- [ ] Tests assert behavior, not internals.
-- [ ] Coverage target recorded.
-- [ ] No `should_panic` lying reds — unimplemented paths use `todo!()` so they fail.
-- [ ] Collateral tests for globally-enumerated things listed by exact name.
-- [ ] Arithmetic checked: fixtures can reach green against frozen constants.
-
-## Step 5 — Build
-
-- [ ] All tests pass.
-- [ ] Coverage did not decrease.
-- [ ] No test or contract modified by the AI.
-- [ ] No package outside the allow-list added.
-- [ ] Change is small enough to review in full.
-
-## Step 6 — Verify
-
-- [ ] All tests pass (the evidence).
-- [ ] Concurrency/timing of the risky operation is safe.
-- [ ] No exposed secrets, injection, or unexpected dependencies.
-- [ ] Layering and dependencies follow `CONVENTIONS.md`.
-- [ ] Deep check: wiring trace recorded (every new symbol reachable from production entry point) and no dead code introduced.
-- [ ] Was the green earned? Adversarial refute-read on the unchanged suite (no overfit, no vacuous asserts, no stubbed logic).
-- [ ] Full-suite rerun by orchestrator (not only the agent's scoped run).
-- [ ] A person reviewed and approved, **or** auto-resolved by the run (under `autonomy: auto`, no residue).
-- [ ] Outcome recorded (`PASS` / `RISK-ACCEPTED` / `HARD-STOP`).
-
-## The loop
-
-- [ ] Released behind a flag or gradual rollout.
-- [ ] Scenarios reused as production monitors.
-- [ ] Learnings written back as a `SPEC.md` delta.
-
----
-
-## Master shippable checklist
-
-A feature is shippable only when all are true:
-
-- [ ] Spec complete: behavior stated, rejections named, assumptions ranked lowest-confidence first with the biggest risk flagged.
-- [ ] Wiring and "existing behavior" assumptions carry grep/line citations; wiring claims name the production caller chain.
-- [ ] Every rule has a scenario.
-- [ ] Contract frozen; contract tests green.
-- [ ] A test per scenario; suite was red before the build (no `should_panic` lying reds).
-- [ ] Collateral tests listed by exact name; arithmetic checked against frozen constants.
-- [ ] All tests green; coverage held; tests and contract untouched by the AI.
-- [ ] Wiring trace recorded: every new symbol reachable from production entry point.
-- [ ] Adversarial refute-read confirms the green was earned (no overfit, no vacuous asserts, no stubbed logic).
-- [ ] Full-suite rerun by orchestrator; not just the agent's scoped run.
-- [ ] Concurrency, security, and architecture checked by a person.
-- [ ] Gate outcome recorded with an accountable owner.
-- [ ] Released behind a flag, with monitors in place.

package/docs/appendix-f-requirements-matrix.md

@@ -1,171 +0,0 @@
-# Appendix F · Document requirements matrix (Project → Milestone → Task)
-
-[← Appendix E Checklists](./appendix-e-checklists.md) · [Contents](./README.md)
-
-This appendix maps every AIDD document to a three-level project hierarchy, so that at any level a team can answer three questions: **which documents must exist, who owns them, and what proves the level is complete.** It is the traceability backbone of the method — read it alongside the stage-depth matrix in [10 Setup and stages](./10-setup-and-stages.md), which covers *step* depth; this appendix covers *document* requirements.
-
----
-
-## The three levels
-
-| Level | What it is | AIDD meaning | Spans |
-|-------|-----------|--------------|-------|
-| **Project** | the whole product or engagement | the living documentation — documents created once and kept for the life of the product | all milestones |
-| **Milestone** | a stage or release | one pass of the flow at a chosen depth: Prototype, POC, MVP, or Production-Ready; groups many tasks | many tasks |
-| **Task** | one feature through the flow | a single pass of Specify → … → Verify → Observe; the smallest unit with its own gate records | the seven steps |
-
-A **project** sets up the living documentation once. A **milestone** is a depth-bounded goal that groups tasks and has its own entry and exit document gates. A **task** is one feature, and it produces the per-feature artifacts.
-
-## How the hierarchy decomposes
-
-```mermaid
-flowchart TD
-  P["PROJECT — the product<br/>PROJECT.md (foundation) · CONVENTIONS · GLOSSARY · MODEL_REGISTRY · allowlist · playbook"]
-  P --> M1["MILESTONE · Prototype"]
-  P --> M2["MILESTONE · POC"]
-  P --> M3["MILESTONE · MVP"]
-  P --> M4["MILESTONE · Production-Ready"]
-  M3 --> T1["TASK · Transfer between accounts<br/>SPEC · feature · contract · tests · code · gate records"]
-  M3 --> T2["TASK · View balance"]
-  M3 --> T3["TASK · Transaction history"]
-  classDef p fill:#F1EFE8,stroke:#5F5E5A,color:#2C2C2A;
-  classDef m fill:#FAEEDA,stroke:#BA7517,color:#633806;
-  classDef t fill:#E6F1FB,stroke:#185FA5,color:#042C53;
-  class P p; class M1,M2,M3,M4 m; class T1,T2,T3 t;
-```
-
----
-
-## Matrix 1 — Documents by level (ownership and lifespan)
-
-Which document lives at which level, who is accountable for it, and how long it lasts.
-
-| Document | Level | Created | Lifespan | Accountable owner |
-|----------|:-----:|---------|----------|-------------------|
-| `PROJECT.md` (foundation: domain · spec · UI/UX) | Project | setup, grows | whole project | Product / Architect |
-| `CONVENTIONS.md` | Project | setup | whole project | Architect / Lead |
-| `GLOSSARY.md` | Project | setup, grows | whole project | Product / Domain |
-| `MODEL_REGISTRY.md` | Project | setup | whole project | Architect / Lead |
-| `dependencies.allowlist` | Project | setup | whole project | Security |
-| `playbook/*.md` (prompts) | Project | setup, versioned | whole project | Eng Lead |
-| Stage plan / roadmap | Milestone | per milestone | the milestone | EM / Delivery |
-| Milestone exit report | Milestone | milestone end | the milestone | EM / Delivery |
-| `SLO.md` (objectives) | Milestone (MVP+) | from MVP | from MVP onward | DevOps / SRE |
-| `SPEC.md` | Task | per feature | living | Product / Domain |
-| `features/*.feature` | Task | per feature | living | QA / Test |
-| `contracts/*.md` | Task → **Project** | per feature, then frozen | living doc (promoted to project) | Architect / Lead |
-| `tests/*` | Task | per feature | living | QA / Engineer |
-| Source code | Task | per feature | **disposable** | Engineer |
-| Gate outcome records | Task | per step | kept for audit | the reviewer |
-
-> Note the one promotion: a **contract** is authored at task level but, once frozen, becomes part of the project's living documentation — other tasks depend on it. That promotion is why a contract change is a project-level change request, not a task-local edit.
-
----
-
-## Matrix 2 — Documents required by milestone
-
-Which documents must exist, and at what depth, to **exit** each milestone. Depth: **Deep** · **Core** · **Light** · **—** (not required).
-
-| Document | Prototype | POC | MVP | Production-Ready |
-|----------|:---------:|:---:|:---:|:----------------:|
-| `CONVENTIONS.md` | Light | Core | Required | Required |
-| `GLOSSARY.md` | seed | Core | Required | Required |
-| `MODEL_REGISTRY.md` | Required | Required | Required | Required |
-| `dependencies.allowlist` | optional | Required | Required | Required |
-| `playbook/*.md` | Required | Required | Required | Required |
-| `SPEC.md` | Light | Deep (risky slice) | Required (full) | Required (full) |
-| Design: flows + screen states | **Deep** | Light | Core | Deep |
-| `features/*.feature` | — | Core | Required | Exhaustive |
-| `contracts/*.md` (frozen) | — | Core (risky slice) | Required (frozen) | Required (versioned) |
-| `tests/*` | — | Core | Core | Full coverage |
-| `SLO.md` | — | — | Light | Required |
-| Gate outcome records | — | Core | Required | Required (all `HARD-STOP`) |
-| Operate / observe report | — | — | Light | Required |
-| Milestone exit report | Light | Core | Required | Required |
-
-**Reading it:** a Prototype exits on a deep design and little else; a POC adds a deep spec, core scenarios/contract/tests on the risky slice; an MVP requires the full per-feature document set plus light operations; Production requires everything at full depth with operations and audit-grade gate records.
-
----
-
-## Matrix 3 — Documents required per task (the seven steps)
-
-Every task, regardless of milestone, produces this artifact chain. The depth varies by milestone (Matrix 2); the *sequence and exit gate* do not.
-
-| Step | Required document | Exit gate (the proof) | Detail |
-|------|-------------------|------------------------|--------|
-| 1 Specify | `SPEC.md` | rules + named rejections, assumptions ranked lowest-confidence first (biggest risk ⚠-flagged) | [03](./03-step-1-specify.md) |
-| 2 Scenarios | `features/<task>.feature` | one scenario per rule | [04](./04-step-2-scenarios.md) |
-| 3 Contract | `contracts/<task>.md` | frozen + contract tests green | [05](./05-step-3-contract.md) |
-| 4 Tests | `tests/<task>_*` | one test per scenario, red first | [06](./06-step-4-tests.md) |
-| 5 Build | source code + evidence bundle | all tests green, nothing weakened | [07](./07-step-5-build.md) |
-| 6 Verify | gate outcome record | `PASS` / `RISK-ACCEPTED` / `HARD-STOP` (auto-resolved on evidence under `autonomy: auto`; security always escalates) | [08](./08-step-6-verify.md) |
-| 7 Observe | `TASK.md` §7 OBSERVE block | released behind a flag; scenario-monitors live; spec delta + lessons learned captured | [09](./09-the-loop.md) |
-
-A task is **done** when the build's documents exist and the Verify record reads `PASS` (or a signed `RISK-ACCEPTED`); the seventh step — **Observe** (§7) — then runs in production and feeds the next loop's Specify. See the master shippable checklist in [Appendix E](./appendix-e-checklists.md).
-
----
-
-## Matrix 4 — Executable proofs (the claims the engine enforces)
-
-The rows above are the method's *promises*. A promise a tool quietly breaks is worse than none — so the `add` engine ships a proof-harness: each invariant below is pinned by an automated test that fails loudly if the **Story** (this book) and the **State** (the engine) drift apart. This table is the coverage *so far*, not a completeness claim — but the minimalism-and-coverage audit has now run once over Matrices 1–3 (see **Sweep findings** below); what it could cheaply prove, it added; what it deliberately left unenforced, it recorded.
-
-| Claim (where it lives) | The engine enforces | Proof test |
-|------------------------|---------------------|------------|
-| No silent skips (principle 7) · "done only when Verify reads `PASS`" (Matrix 3) | `gate PASS` is **refused** unless the task has reached `verify` | `test_gate_pass_refused_before_verify` |
-| A passed task is genuinely done | `gate PASS` at `verify` advances to `done` | `test_gate_pass_at_verify_reaches_done` |
-| Deliberate ≠ silent | the explicit `phase` command is a logged escape hatch the guardrail does not block | `test_phase_override_escape_hatch` |
-| "A security finding is ALWAYS `HARD-STOP`" | `HARD-STOP` is recordable from any phase and never forces `done` | `test_hardstop_recordable_mid_build` |
-| "done … or a signed `RISK-ACCEPTED`" (Matrix 3) | `gate RISK-ACCEPTED` at `verify` advances to `done` (same guard as `PASS`) | `test_risk_accepted_complete_reaches_done` |
-| A waived task **can complete its milestone** (the point of the waiver) | the completeness predicate counts a signed `RISK-ACCEPTED` as done, so `milestone-done` / `ready` / `check` / `archive` accept it — it does not silently block | `test_milestone_done_accepts_a_waived_task` · `test_check_tolerates_a_recorded_waiver` |
-| A waiver is **signed** (owner · ticket · expiry) | `gate RISK-ACCEPTED` is refused without all three; they are stored in state | `test_risk_accepted_requires_waiver` · `test_risk_accepted_partial_waiver_refused` |
-| A waiver can **expire** — a lapsed one is caught, not trusted forever | `check` **FAILS** a `RISK-ACCEPTED` task whose stored `expires` is before today; fail-closed on a missing/unparseable date (`waiver_expired`) | `test_check_flags_expired_waiver` · `test_check_passes_unexpired_waiver` · `test_check_failclosed_on_unparseable_expires` |
-| **The Story is never auto-loaded** (principle 9, the *Minimal* pillar) | **no** command reads a `docs/` chapter at runtime — and the spy runs *every* subcommand the parser exposes, so "no command" is universal, not a subset; a project with **no** `docs/` runs the whole lifecycle | `test_full_lifecycle_runs_with_no_story` · `test_no_command_reads_a_docs_chapter` · `test_every_subcommand_is_covered` |
-| The book's gate outcomes are the engine's | `PASS` · `RISK-ACCEPTED` · `HARD-STOP` exist in both prose and `GATES` | `test_book_gate_outcomes_match_engine` |
-
-The tests are the source of truth; this table is their index. If a row here is ever unproven, that is a gap in the method, not a detail — the proof-harness exists to make such gaps fail loudly. (Tests: `add-method/tooling/test_proof_harness.py`, `test_waiver.py`.)
-
-**Now closed:** an earlier version of this table flagged a `RISK-ACCEPTED` gap — the engine advanced only `PASS` to `done`, so a waived task could not complete its milestone, and the waiver fields were uncaptured. The `RISK-ACCEPTED` rows above close it: a signed waiver (owner · ticket · expiry) now completes a verify-phase task and is stored in state for a later `check` to expire. Closing it took *two* edits, not one — advancing the gate to `done` was necessary but not sufficient, because the shared completeness predicate (`milestone-done` / `ready` / `check` / `archive` all read it) still counted only `PASS`; a waived task reached `done` yet silently blocked its milestone until that predicate was taught to count a signed `RISK-ACCEPTED` too. The end-to-end row above is what catches that class of half-fix — proving the *task* completes is not proving the *milestone* can. The pattern that found it — book-claim → engine-enforces → named test — is the standing way to audit the remaining rows.
-
-**Sweep findings (minimalism-and-coverage audit, v2):** the audit walked Matrices 1–3 for claims the engine *could* enforce but did not yet prove.
-
-- **Proved and added** (rows above): the *Minimal* pillar's headline — "the Story is never auto-loaded" (principle 9) — was written but unproven; it is now pinned behaviorally (the engine runs the whole lifecycle with no `docs/` present, and a read-spy over *every* subcommand confirms none reads a chapter at runtime). And waiver **expiry**, which Matrix 4 already promised the state captured "for a later `check` to expire," is now enforced.
-- **Recorded, deliberately *not* enforced:** Matrix 3 says a task is done only when "all six documents exist." The engine checks that `TASK.md` *exists* and that its phase marker matches state — it does **not** parse the file to confirm each of the seven sections is filled. Teaching it to grade section completeness would push the engine toward reading and judging the Story it is supposed to keep off the runtime path — an anti-minimal move. The reviewer owns section completeness at the Verify gate (the human-led half of the method); the engine owns the cheap structural invariants. This is a chosen boundary, not an oversight.
-- **Lean check:** the audit confirmed `state.json` carries no redundant per-task fields — `title`, `phase`, `gate`, `milestone`, `depends_on`, the two timestamps, and a `waiver` only once one is signed; nothing to trim. A clean bill is a finding too.
-
----
-
-## Worked example — the hierarchy filled in
-
-- **Project:** *Mobile Banking App.* Living documentation: `CONVENTIONS.md`, `GLOSSARY.md` (defines *account*, *balance*, *transfer*), `MODEL_REGISTRY.md`, `dependencies.allowlist`, `playbook/`.
-- **Milestone:** *MVP — core money movement.* Exit requires the full per-feature document set for each task below, plus a light `SLO.md` and a milestone exit report.
-  - **Task:** *Transfer between own accounts* → `SPEC.md`, `features/transfer.feature`, `contracts/transfer.md` (frozen at v1), `tests/transfer_test.py`, code, and a `PASS` gate record. (The full set is in [Appendix D](./appendix-d-worked-example.md).)
-  - **Task:** *View balance* → its own SPEC, feature, contract, tests, code, record.
-  - **Task:** *Transaction history* → its own set.
-
-When all three tasks read `PASS` and the milestone documents exist, the MVP milestone exits — and the frozen `transfer` contract is now a project-level living-documentation artifact the next milestone builds on.
-
----
-
-## Traceability chain
-
-The hierarchy gives a clean line of evidence from a business goal down to a passing test — which is what makes an AIDD project auditable:
-
-```
-PROJECT goal           "let customers move their own money safely"
-  └─ MILESTONE (MVP)    "core money movement"
-       └─ TASK          "transfer between own accounts"
-            └─ SPEC rule        "source must have enough balance"
-                 └─ SCENARIO    "insufficient funds -> rejected, no change"
-                      └─ TEST   test_insufficient_funds (was red, now green)
-                           └─ VERIFY record   PASS (atomicity checked)
-```
-
-Every level points down to the evidence beneath it and up to the goal above it. To audit any claim — "we handle insufficient funds correctly" — you follow the chain to a specific test and a specific gate record. Nothing rests on assertion.
-
----
-
-*This matrix is the requirements view of the method. The flow ([Part II](./02-the-flow.md)) tells you the order; the stages ([10](./10-setup-and-stages.md)) tell you the depth; this appendix tells you, at each level of the project, exactly which documents must exist and who owns them.*
-
----
-
-*End of book. AIDD is one repeatable loop — Specify → Scenarios → Contract → Tests → Build → Verify → observe, then repeat. People own direction and verification; the AI owns the build; the artifacts are the asset and the code is disposable.*

package/docs/appendix-g-references.md

@@ -1,106 +0,0 @@
-# Appendix G — References & Lineage
-
-ADD did not appear from nowhere. It sits at the meeting point of three currents:
-the **recursive self-improvement** thesis (AI that helps build the next AI), the
-**spec-driven development** movement (the specification, not the code, is the
-source of truth), and a decade of **agentic + tests-first** research showing that
-a generate→check→refine loop, constrained by executable tests, turns fluent model
-output into trustworthy software. This appendix is the curated, verified grounding
-for that lineage — every source below is reachable and annotated with a `↔ ADD:`
-line saying exactly how it relates to the method.
-
-**The frame — "closing the loop."** Anthropic's recursive-self-improvement picture
-runs from autonomous agents delegating to workers *today* toward a future where
-Claude improves Claude. ADD is a deliberately **human-gated, evidence-trusted**
-instance of that loop: the AI drives spec→build→verify→observe, but a human owns the
-frozen contract and the verify gate, and trust comes from passing tests and
-re-resolved evidence — never from a plausible-looking diff. The sources here are
-the shoulders that posture stands on.
-
-The four sections below are the four currents. The comparison table places ADD next
-to its two closest peers — GitHub's **spec-kit** and **GSD (Get Shit Done)** — and
-names where ADD diverges. Read "How to cite" first; the rest of the book cites into
-the keys defined here.
-
-## How to cite
-
-The book uses one inline citation form — **author-year** — and every entry's lead
-`(Author Year)` *is* its cite-key. Resolve any inline `[…]` to the matching entry below.
-
-| Authors | Inline form | Example |
-|---|---|---|
-| one author | `[Surname Year]` | `[Schmidhuber 2003]` |
-| two authors | `[Surname & Surname Year]` | `[Mathews & Nagappan 2024]` |
-| three or more | `[Surname et al. Year]` | `[Zelikman et al. 2023]` |
-| an organisation | `[Org Year]` | `[Anthropic 2026a]` · `[GitHub 2025]` |
-| several at once | joined by `; ` | `[Schmidhuber 2003; Zelikman et al. 2023]` |
-| same author, same year | add a `Year`-letter suffix | `[Anthropic 2025a]` / `[Anthropic 2025b]` |
-
-The 3+-author rule becomes **et al.**; an organisation stands in as the author
-when no individual is credited; and when two org-authored sources collide on a year
-(several Anthropic 2025/2026 items do, below) a trailing letter disambiguates them.
-There is exactly one entry per cite-key.
-
-## spec-kit ↔ ADD (and GSD)
-
-ADD shares the spec-first DNA of GitHub's **spec-kit** and the Claude-Code,
-context-rot-fighting niche of **GSD**. The phase models line up closely:
-
-| ADD phase | spec-kit command | GSD phase |
-|---|---|---|
-| foundation · principles | `/speckit.constitution` → `constitution.md` | (project setup / `CLAUDE.md`-level) |
-| §1 specify (what / why) | `/speckit.specify` → `spec.md` | **discuss** — capture decisions before planning |
-| §3 contract (how, frozen) | `/speckit.plan` → `plan.md`, `contracts/` | **plan** — research, decompose, fit fresh context |
-| milestone tasks / waves | `/speckit.tasks` → `tasks.md` | (phases → parallel waves) |
-| §5 build | `/speckit.implement` | **execute** — parallel waves, fresh 200k-token context each |
-| §6 verify | `/speckit.analyze` + `/speckit.checklist` | **verify** — walk what was built, fix before declaring done |
-
-**Where ADD diverges.** spec-kit stops at `implement`; GSD ends at verify (GSD Core
-adds a fifth *ship* phase). ADD closes the loop past both by adding three things
-neither has as a first-class gate: a **failing-tests-first** gate (§4 — no build
-starts until the tests are red for the right reason), an **observe→`fold`**
-self-improvement step (§7 — confirmed learnings consolidate into a versioned foundation),
-and an engine-tracked **dynamic goal-loop** that will hold a milestone open and
-reopen tasks until its exit criteria are met. ADD also deliberately targets **less
-doc-time than GSD** — a lean foundation and one human approval per task, rather than
-a document per phase. The shared lineage is real; the tests-first gate, the `fold`,
-and the goal-loop are ADD's contribution.
-
-## 1. Recursive self-improvement
-
-- **When AI builds itself** (Favaro & Clark 2026) — https://www.anthropic.com/institute/recursive-self-improvement — essay. The RSI thesis: by 2026 >80% of code merged at Anthropic was Claude-authored and the 50%-task time-horizon keeps doubling; recursive self-improvement would shift humans from builders to validators. ↔ ADD: the seed source — ADD is the human-gated, evidence-trusted way to run a spec→build→verify→observe loop while the human stays the validator.
-- **Automated Alignment Researchers** (Anthropic 2026a) — https://www.anthropic.com/research/automated-alignment-researchers — research. Nine parallel Claude agents recovered ~97% of the human-expert gap on an alignment task in 5 days versus 7 for the human team. ↔ ADD: the strongest evidence the recursive loop is not speculative — parallel agents under review are exactly ADD's wave-plus-verify shape.
-- **Machines of Loving Grace** (Amodei 2024) — https://www.darioamodei.com/essay/machines-of-loving-grace — essay. A "country of geniuses in a datacenter," argued with a measured, bounded position on recursive self-improvement. ↔ ADD: the intent framing behind milestoning — bound the loop with human direction rather than let it run open.
-- **Gödel Machines: Self-Referential Universal Problem Solvers** (Schmidhuber 2003) — https://arxiv.org/abs/cs/0309048 — paper. A provably-optimal self-modifying agent that rewrites itself only when it can prove the rewrite helps. ↔ ADD: the mathematical anchor of the lineage — and a precedent for "only change on proof," which ADD enforces socially via the never-weaken-a-test rule.
-- **STOP: Self-Taught Optimizer** (Zelikman et al. 2023) — https://arxiv.org/abs/2310.02304 — paper. A scaffolding program recursively improves the code that improves code. ↔ ADD: the algorithmic kin of the `fold` step — consolidate confirmed learnings back into the method that produced them.
-- **Self-Refine: Iterative Refinement with Self-Feedback** (Madaan et al. 2023) — https://arxiv.org/abs/2303.17651 — paper. Generate→critique→refine with the same model lifts quality ~20% with no extra training. ↔ ADD: the micro-loop inside build→verify — produce, check against the contract, refine.
-- **Self-Rewarding Language Models** (Yuan et al. 2024) — https://arxiv.org/abs/2401.10020 — paper. A model acts as its own reward judge to improve across iterations. ↔ ADD: the risk ADD answers — a self-judging loop needs an external gate; ADD makes tests and a human the reward signal, not the model's own opinion.
-- **Reflexion: Language Agents with Verbal Reinforcement Learning** (Shinn et al. 2023) — https://arxiv.org/abs/2303.11366 — paper. Agents keep verbal reflections in episodic memory and retry, reaching 91% on HumanEval. ↔ ADD: the principle behind "reopen the task if criteria are unmet" — a failed check becomes feedback for the next attempt, not a dead end.
-- **Voyager: An Open-Ended Embodied Agent with LLMs** (Wang et al. 2023) — https://arxiv.org/abs/2305.16291 — paper. An auto-curriculum agent that grows a reusable skill library over time. ↔ ADD: the growing foundation — each milestone's consolidated deltas are ADD's accumulating skill library.
-- **AlphaEvolve: A Coding Agent for Scientific and Algorithmic Discovery** (Novikov et al. 2025) — https://arxiv.org/abs/2506.13131 — paper. An evolutionary coding agent that beat a long-standing matrix-multiplication record and shipped a production scheduler improvement. ↔ ADD: the end-state evidence — a generate-and-verify loop can exceed human baselines when every candidate is checked.
-
-## 2. Autonomous & agentic workflows
-
-- **Building Effective Agents** (Schluntz & Zhang 2024) — https://www.anthropic.com/research/building-effective-agents — blog. The canonical taxonomy: prompt-chaining, routing, orchestrator-workers, and the evaluator-optimizer loop. ↔ ADD: the architecture cite — evaluator-optimizer is build→verify→refine; orchestrator-workers is ADD's wave parallelism.
-- **Enabling Claude Code to work more autonomously** (Anthropic 2025a) — https://www.anthropic.com/news/enabling-claude-code-to-work-more-autonomously — news. Checkpoints, subagents, hooks, background tasks, and `/rewind` rollback. ↔ ADD: checkpoint/rewind is the rollback strategy behind phase gates; hooks are where the engine enforces them.
-- **How we built our multi-agent research system** (Anthropic 2025b) — https://www.anthropic.com/engineering/multi-agent-research-system — blog. An Opus lead orchestrating Sonnet subagents, with an LLM acting as judge, lifting task performance ~90%. ↔ ADD: the lead-plus-subagents-plus-judge pattern is exactly ADD's wave execution under a verify gate.
-- **ReAct: Synergizing Reasoning and Acting in Language Models** (Yao et al. 2022) — https://arxiv.org/abs/2210.03629 — paper. Interleaving think→act→observe turns a model into an agent. ↔ ADD: the base loop every ADD phase runs on.
-- **Toolformer: Language Models Can Teach Themselves to Use Tools** (Schick et al. 2023) — https://arxiv.org/abs/2302.04761 — paper. Self-supervised learning of when and how to call external tools. ↔ ADD: the capability that lets an agent run its own tests, linters, and builds — the evidence ADD trusts.
-- **SWE-agent: Agent–Computer Interfaces Enable Automated Software Engineering** (Yang et al. 2024) — https://arxiv.org/abs/2405.15793 — paper. A designed agent–computer interface materially improves autonomous issue resolution. ↔ ADD: the structured agent↔environment contract — ADD's `add.py` engine is that interface for the method.
-- **The AI Scientist: Towards Fully Automated Open-Ended Scientific Discovery** (Lu et al. 2024) — https://arxiv.org/abs/2408.06292 — paper. A full idea→experiment→write→review research loop at ~$15 per paper. ↔ ADD: the research analog of ADD's loop — and a reminder that an automated reviewer is the weak link a human gate protects.
-
-## 3. Spec-driven development & spec-kit
-
-- **GitHub Spec Kit** (GitHub 2025) — https://github.com/github/spec-kit — repo. The reference SDD toolkit: the phase model is `constitution` → `specify` → `plan` → `tasks` → `implement`, with the spec as the executable source of truth. ↔ ADD: the closest spec-first sibling — ADD's specify and contract phases map onto specify and plan; see the comparison table for the divergence.
-- **Spec-driven development with AI: get started with a new open-source toolkit** (Delimarsky 2025) — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/ — blog. The spec-kit launch post; frames `tasks` as "TDD for your AI agent." ↔ ADD: independent articulation of why decomposing a spec into checkable units beats one big prompt.
-- **Spec-driven development: using Markdown as a programming language when building with AI** (Vesely 2025) — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-using-markdown-as-a-programming-language-when-building-with-ai/ — blog. Spec-as-source, with context-rot named as the failure SDD exists to solve. ↔ ADD: the rationale for the frozen contract — a stable written spec is what survives when the model's context degrades.
-- **Get Shit Done (GSD)** (GSD 2025) — https://github.com/open-gsd/gsd-core — repo. A meta-prompting, context-engineering, spec-driven system for Claude Code; its `discuss` → `plan` → `execute` → `verify` cycle runs each phase in a fresh subagent context to fight context-rot (originally `gsd-build/get-shit-done`, now continued as GSD Core). ↔ ADD: ADD's closest peer — same Claude-Code, context-rot niche; ADD diverges with the tests-first gate, the observe→`fold` step, and the dynamic goal-loop, and aims for less doc-time than GSD.
-- **Beyond Vibe Coding: Amazon Introduces Kiro, the Spec-Driven Agentic IDE** (InfoQ 2025) — https://www.infoq.com/news/2025/08/aws-kiro-spec-driven-agent/ — blog. Kiro structures work as requirements→design→tasks with execution hooks. ↔ ADD: cross-vendor confirmation that spec-first is converging across the industry, not a single-tool idea.
-- **Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants** (Piskala 2026) — https://arxiv.org/abs/2602.00180 — paper. A taxonomy of SDD rigor — Spec-First, Spec-Anchored, Spec-as-Source — reporting human-refined specs can cut LLM code errors substantially, with BDD as SDD's ancestor. ↔ ADD: places ADD as "Spec-Anchored" and gives the academic vocabulary for the contract-freeze decision.
-
-## 4. Tests-first & verification
-
-- **Test-Driven Development for Code Generation** (Mathews & Nagappan 2024) — https://arxiv.org/abs/2402.13521 — paper. Supplying tests alongside the prompt measurably lifts pass rates on MBPP and HumanEval. ↔ ADD: the empirical backbone of the failing-tests-first gate — tests as the constraint that makes generation verifiable.
-- **SWE-bench: Can Language Models Resolve Real-World GitHub Issues?** (Jimenez et al. 2023) — https://arxiv.org/abs/2310.06770 — paper. 2,294 real issues judged by whether the project's own tests pass; <2% solved at release. ↔ ADD: the yardstick that proves the point — "done" means the tests pass, which is exactly how ADD gates a feature.
-- **Our framework for developing safe and trustworthy agents** (Anthropic 2025c) — https://www.anthropic.com/news/our-framework-for-developing-safe-and-trustworthy-agents — news. Five principles: human control, transparency, alignment, privacy, and security. ↔ ADD: the frozen-contract gate and never-weaken-a-test rule are human control and transparency made concrete; the security HARD-STOP is the security principle.
-- **Responsible Scaling Policy v3.0** (Anthropic 2026b) — https://www.anthropic.com/news/responsible-scaling-policy-v3 — policy. The AI Safety Level framework; ASL-3 governs autonomous R&D capability. ↔ ADD: the governance ceiling that makes ADD's discipline necessary — as the loop gets more capable, the gates and the human-owned verify matter more, not less.