@pilotspace/add 1.17.0 → 2.1.0

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.

package/skill/add/advisor.md

@@ -1,81 +0,0 @@
-# Advisor — spawning one subagent to follow your plan
-
-The **advisor** strategy: spawn a *single* subagent to execute one piece of your plan, then merge
-its verdict back. It is the single-subagent companion to `streams.md` (which pipelines *many* tasks
-in parallel worktrees) — you delegate *one* well-scoped piece and stay in the loop. The engine never
-spawns; this is your call per step.
-
-## When to spawn — and when not
-
-Spawn when the piece is **separable and worth the round-trip**: a broad sweep; an independent adversarial review (the `6-verify` refute-read — fresh context, not graded by the author); a well-scoped batch; or context-offload to a small verdict.
-
-Do **not** spawn for narrow, cheap work — pay the round-trip only when the piece is big or independent enough. When in doubt, do it in-context.
-
-**Prefer the named roster.** Check first whether the piece fits one of ADD's five phase specialists — `add-design` (setup–contract) · `add-build` (tests·build) · `add-verify` (verify·observe) · `add-persona` (fit-persona selection) · `add-advisor` (a consultative second opinion) — before an ad-hoc spawn; each already carries the worker contract below.
-
-## The 3-lens sequential checklist at verify
-
-At Verify, sweep security → concurrency → architecture in order. **Security HARD-STOP ends the checklist** (leave the rest blank). Each lens returns: **CLEAR** · **HARD-STOP** (security only) · **RESIDUE** (concurrency/architecture).
-
-Record it in §6 `### Advisor 3-lens verdict`: **Verdict** (PASS/HARD-STOP) · **Residue** (none or brief) · **Binding** (`yes` for `sensitivity: mechanical` — the engine reads it for `advisor-gate-relax`; `advisory` otherwise).
-
-**Persona for the refute-read.** When the piece is the earned-green refute-read, select a **Code-Reviewer** persona; its findings carry severity markers — 🔴 blocker · 🟡 concern · 💭 note. A persona is advisory: it never lowers a gate (a security finding still HARD-STOPs).
-
-## The plan-following prompt template
-
-Give the subagent the *piece it owns* and a fixed return shape. This reuses `streams.md`'s
-worker-contract tags — identical on any runner; only the spawn adapter (see `streams.md`) changes.
-The `<strategy>` block mirrors the task's §5 as the subagent's PREFERRED path — it self-improves on that plan and reports the strategy it actually used.
-
-```xml
-<objective>
-Execute THIS piece of the orchestrator's plan: {{PIECE}}. You own only this piece — not the
-surrounding decisions. Return a verdict; do not record state.
-</objective>
-
-<persona>
-SELECT the persona by frontmatter — flow: match first, then domain; read ONE body —
-and load `.add/personas/{{PERSONA_SLUG}}.md` —
-Identity→your stance · Critical Rules→constraints · Success Metrics→done-bar (streams.md's worker
-contract). No match → a {{DOMAIN}} engineer, correctness over speed; never blocks.
-Work step by step, following the plan:
-1. Load the context files + the persona; confirm you understand the piece you own.
-2. Do the work in small steps, honoring the orchestrator's plan and constraints.
-3. Self-score your result with confidence.md; if any dimension < 0.9, refine before returning.
-</persona>
-
-<strategy>
-The task's §5 plan — the Strategy (ordered batches) order and the Known-problem fixes — is
-your PREFERRED starting path, not a hard rule. Improve on it when a better strategy emerges
-as you build; on done, report the strategy you ACTUALLY used so the orchestrator can update
-§5 for the audit trail.
-</strategy>
-
-<context_files>
-the plan / task files the piece needs (read-only unless the piece says otherwise)
-</context_files>
-
-<return>
-End with a structured verdict the orchestrator parses and RECORDS:
-{ piece, persona, result, evidence, confidence: {per-dimension 0–1}, open_questions }.
-`persona` names the slug you adopted (or `generic`) — the orchestrator records which persona did the work.
-Do NOT run add.py or write any shared state — you propose, the orchestrator records.
-</return>
-```
-
-## Choosing the model — vendor-neutral tiers
-
-Pick the tier from `streams.md`: **mid** for an ordinary piece; **top** for a complex/ambiguous/
-cross-cutting one. The tier→model-id mapping + spawn adapter live there. A stronger model never buys
-back a gate: high-risk scope still escalates.
-
-## The hard rule — delegate, don't abdicate
-
-<constraints>
-The engine never spawns — it's the orchestrating agent's choice. And:
-- the subagent PROPOSES; the orchestrator RECORDS — a worker never runs add.py or writes shared state;
-- delegation never lowers a gate — a SECURITY finding still HARD-STOPs and high-risk scope still escalates, whoever did the work;
-- the subagent returns its confidence.md self-score; a low score means refine or re-spawn, never a pass.
-</constraints>
-
-> Used per step: each phase guide's Advisor hook points here (the per-step hooks).

package/skill/add/compact-foundation.md

@@ -1,40 +0,0 @@
-# Foundation compaction — collapse the stable tail
-
-`fold.md` PREPENDS new learnings (newest-first); foundation compaction COLLAPSES the stable tail of each foundation spec into a rolled-up settled line — keeping PROJECT.md, CONVENTIONS.md, GLOSSARY.md, and MODEL_REGISTRY.md to one screen as the project grows.
-
-You **gather and propose**; the **human confirms**; you then write the settled line. This is a **convention**, not a command — there is no `add.py compact-foundation`. It is DISTINCT from engine `add.py compact <slug>` (the archive recovery-bundle move).
-
-## When
-
-At **milestone close** (after `fold.md`) or **on demand** when a spec has grown past one screen. Always a SEPARATE step from `fold.md`.
-
-## Eligibility
-
-An entry is compaction-eligible **IFF** its milestone is **shipped** (done/archived) **AND** it carries **zero open residues**/deltas. Unshipped or open-residue entries are NOT eligible (`open-residue-version`).
-
-## The ritual
-
-1. **Gather** — collect the stable, shipped, zero-residue tail of the target spec.
-2. **Propose** — draft the per-spec rolled-up settled line and show the human.
-3. **Confirm** — no write happens without confirmation.
-4. **Write** — replace the collapsed tail with ONE settled line at the BOTTOM (newest-first: live records stay on top, settled line anchors at the tail), carrying a git/archive pointer.
-
-## Per-spec rolled-line shapes
-
-- **PROJECT.md §Spec** — `[folded fv N..M]` bullets → `settled fvN–fvM — <theme> (see git)`.
-- **PROJECT.md §Key-Decisions** — shipped rows → `| settled <dateA>–<dateB> | <N> decisions rolled | … | see git |` at the tail.
-- **CONVENTIONS.md** — `(TAG)` learnings → `- settled conventions <range> — <N> rules (see git)`.
-- **GLOSSARY.md** — verbose stable definition → terse canonical line + `(rationale: see git)`.
-- **MODEL_REGISTRY.md** — superseded model rows → `Prior models: <list> (see git)`.
-
-## Preservation
-
-- **Never delete** — summarize and point; a settled line is lossy on prose, lossless on traceability.
-- A git/archive pointer is mandatory (`trail-loss` if dropped).
-- OPEN residues stay live.
-
-## Reject codes
-
-- `open-residue-version` — entry is unshipped or has ≥1 open delta/residue; leave it live.
-- `trail-loss` — the collapse would drop the git/archive pointer or audit summary.
-- `wrong-order` — a record is not newest-first, or the settled line is not at the tail.

package/skill/add/components.md

@@ -1,52 +0,0 @@
-# Components — monorepo and multi-repo slices
-
-Opt-in pillar for a milestone spanning **more than one green bar** — a BE + its
-FE, a shared lib + two apps, services across repos. No components declared =
-byte-identical to a single-codebase project. Full narrative: `17-components.md`.
-
-## Declare (never inferred)
-
-`.add/components.toml`:
-
-```toml
-[component.gateway]
-root      = "apps/gateway"
-green_bar = "pytest + pyright"
-[component.dashboard]
-root      = "apps/web"
-green_bar = "vitest + a11y"
-```
-
-A task binds with a `component: <name>` header → that root joins its §5 Scope,
-and verify holds it to that component's green-bar.
-
-## The loop
-
-1. **Per-component verify.** A bound task must CITE its green-bar in §6 evidence
-   or the gate refuses `component_green_bar_uncited`. The engine never runs the
-   suite — it **surfaces** the component's `verify` command (and records it in §6);
-   you run it (NO-EXEC). The fast lane carries the same `component:` affordance.
-2. **Freeze a cross-component contract.** Declare `[contract.<id>]`
-   (producer + consumers). A task names its role `produces: <id>` / `consumes: <id>`.
-   The producer's freeze (contract→tests) writes the immutable snapshot
-   `.add/contracts/<id>.json`; the consumer pins its hash. A changed re-freeze
-   flags consumers `contract_consumer_stale`; a missing/malformed snapshot
-   HARD-STOPS — never build against an unfrozen shape.
-3. **One milestone, full slice.** A `consumes:` task is HELD from advancing
-   scenarios→contract (`producer_contract_unfrozen`) until the producer's snapshot
-   exists — and `producer_contract_stale` if a live producer re-opened/drifted its
-   §3 (freeze-recency). The FE stays downstream of the frozen BE, in one milestone.
-4. **Across repos — federate.** A consumer repo declares `[federation.<id>]`
-   (`source` + optional `pin`); `add.py federate pull <id>` validates and lands a
-   byte-for-byte copy of the producer's snapshot locally. Fail-loud:
-   unknown id / unreadable source / a `source` escaping the repo's allowlist
-   (`federation_source_escapes`, confined to a repo-root sibling) / invalid
-   snapshot / version mismatch each HARD-STOPS and lands nothing.
-
-## Hold the line
-
-- **Declared, not inferred** — no scanning `apps/*`.
-- **No central server / no shared mutable state** — federation copies an immutable
-  snapshot; each repo keeps its own `state.json`.
-- **No new approval** — engine-enforced gates on the six-step flow, not extra human
-  checkpoints. Per-component ownership/autonomy is the identity story (`streams.md`).

package/skill/add/confidence.md

@@ -1,32 +0,0 @@
-# Confidence — the self-score that aims attention
-
-The **confidence self-score** is an *advisory* check an agent runs on its own drafted artifact — a spec, a contract, a build, or a subagent verdict — *before* presenting it. It sharpens the draft and aims the reader's eye at the soft spots; it is never a gate.
-
-## The six dimensions
-
-Score each 0–1 honestly on the artifact you are about to hand over:
-
-- **Completeness** — did it cover every rule, scenario, and rejection the task asked for?
-- **Clarity** — would the next reader understand it without you in the room?
-- **Practicality** — is it feasible and implementable as written, against the real code?
-- **Optimization** — does it balance correctness, simplicity, and cost — no gold-plating, no corner cut?
-- **Edge cases** — did it name the failure modes, the concurrency, the empty/oversized inputs?
-- **Self-evaluation** — does it carry its own refine step — a way to catch its own mistakes?
-
-If **any** dimension scores **< 0.9**, refine the artifact before presenting, then re-score.
-
-## Where it plugs in
-
-- It **feeds the lowest-confidence flag** (run.md · 1-specify.md): the lowest-scoring dimension is what you surface ⚠-first at the contract freeze.
-- A persistently low score on a risky scope is a signal to **recommend** lowering the autonomy level (auto → conservative / manual; run.md) — the level stays the human's call.
-
-## The hard rule — advisory, never a gate
-
-<constraints>
-The confidence self-score is advisory only — never a gate. It never:
-- auto-pass a verify or block a run — the verify outcome rests on evidence (passing tests, the non-functional review), not a self-assigned number;
-- substitutes for evidence or for the human decision point;
-- is recorded as a score the human "agreed to" — a self-asserted score that gated would only move an unread approval one level up (run.md).
-
-What it MAY do: aim the lowest-confidence flag, trigger a refine pass, and recommend an autonomy adjustment. The gate itself stays evidence-based and human-owned.
-</constraints>