@pilotspace/add 1.1.0 → 1.3.0

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

@@ -23,8 +23,8 @@ Reject:
   - 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 amount/rounding model changes and this contract is wrong
+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
 ```
 

package/docs/appendix-e-checklists.md

@@ -18,7 +18,8 @@ Every exit check in the book, collected for quick use. Print this page.
 - [ ] Every required behavior stated explicitly.
 - [ ] Every rejection has a named error code.
 - [ ] Success state-change described.
-- [ ] Assumptions ranked least-sure first; the 1–2 most-likely-wrong ⚠-flagged with why + cost (or an honest "none material" that still names the single biggest risk).
+- [ ] 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
 
@@ -40,6 +41,9 @@ Every exit check in the book, collected for quick use. Print this page.
 - [ ] 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
 
@@ -55,7 +59,10 @@ Every exit check in the book, collected for quick use. Print this page.
 - [ ] Concurrency/timing of the risky operation is safe.
 - [ ] No exposed secrets, injection, or unexpected dependencies.
 - [ ] Layering and dependencies follow `CONVENTIONS.md`.
-- [ ] A person reviewed and approved.
+- [ ] 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
@@ -70,11 +77,16 @@ Every exit check in the book, collected for quick use. Print this page.
 
 A feature is shippable only when all are true:
 
-- [ ] Spec complete: behavior stated, rejections named, assumptions ranked least-sure first with the biggest risk flagged.
+- [ ] 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.
+- [ ] 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

@@ -10,11 +10,11 @@ This appendix maps every AIDD document to a three-level project hierarchy, so th
 
 | Level | What it is | AIDD meaning | Spans |
 |-------|-----------|--------------|-------|
-| **Project** | the whole product or engagement | the survivor layer — documents created once and kept for the life of the product | all milestones |
+| **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 survivor-layer documents 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.
+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
 
@@ -53,12 +53,12 @@ Which document lives at which level, who is accountable for it, and how long it
 | `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 | survivor (promoted to project) | Architect / Lead |
+| `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 survivor layer — other tasks depend on it. That promotion is why a contract change is a project-level change request, not a task-local edit.
+> 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.
 
 ---
 
@@ -93,13 +93,13 @@ Every task, regardless of milestone, produces this artifact chain. The depth var
 
 | Step | Required document | Exit gate (the proof) | Detail |
 |------|-------------------|------------------------|--------|
-| 1 Specify | `SPEC.md` | rules + named rejections, assumptions ranked least-sure first (biggest risk ⚠-flagged) | [03](./03-step-1-specify.md) |
+| 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 + competency deltas captured | [09](./09-the-loop.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).
 
@@ -136,13 +136,13 @@ The tests are the source of truth; this table is their index. If a row here is e
 
 ## Worked example — the hierarchy filled in
 
-- **Project:** *Mobile Banking App.* Survivor-layer documents: `CONVENTIONS.md`, `GLOSSARY.md` (defines *account*, *balance*, *transfer*), `MODEL_REGISTRY.md`, `dependencies.allowlist`, `playbook/`.
+- **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 survivor artifact the next milestone builds on.
+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.
 
 ---
 

package/docs/appendix-g-references.md

@@ -0,0 +1,106 @@
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "ADD (AI-Driven Development) — a minimal, state-tracked Claude Code skill that drives every feature through Specify → Scenarios → Contract → Tests → Build → Verify → Observe. Ships the AIDD book as its trust layer.",
   "bin": {
     "add": "bin/cli.js"

package/skill/add/SKILL.md

@@ -20,7 +20,7 @@ You are the orchestrator. ADD keeps the AI fast *and* safe by fixing direction
 the result through passing evidence rather than a plausible-looking diff.
 
 **One file = one task.** Each feature lives in a single `.add/tasks/<slug>/TASK.md`
-with seven sections. You fill them top to bottom; the Python tool tracks where
+with a §0 ground preamble and seven step sections. You fill them top to bottom; the Python tool tracks where
 you are so context never rots across sessions.
 
 ## Always start here (orient — do not skip)
@@ -34,7 +34,7 @@ python3 .add/tooling/add.py status
 - **No `.add/state.json` yet** (a fresh install drops tooling + docs but does *not* init — so `status` says
   `no .add/ project found`) → enter **autonomous setup**: YOU run init yourself —
   `add.py init --name "<inferred>" --stage <picked> --await-lock` (don't tell the human to) — then read
-  `phases/0-setup.md` and draft the foundation + first scope + first contract through to the human lock-down.
+  `phases/0-setup.md` and draft the foundation + first scope + first contract through to the human baseline approval.
 - **A task is active** → open `.add/tasks/<active>/TASK.md`, look at its `phase:`
   marker, and read the matching `phases/<n>-<phase>.md`. Work *only* that phase.
 - **No active task** → first SIZE the request (see Intake below), then create the
@@ -45,8 +45,9 @@ python3 .add/tooling/add.py status
 When the user brings a raw request, classify it BEFORE making a milestone or task:
 read `intake.md` and place it in exactly one bucket — `new-major` · `sub-milestone`
 · `task` · `change-request` — then propose `{ bucket, rationale, command }` and let
-the human confirm. This is the intake altitude (request → versioned scope); see
-`intake.md` for the rubric, the tie-break order, and worked examples.
+the human confirm. This is the intake level (request → versioned scope); see
+`intake.md` for the rubric, the tie-break order, and worked examples. A question or
+unsharp intent? **Interview before you size** — explore and suggest first (`intake.md`).
 
 Once a request is classified `new-major`/`sub-milestone`, drafting the actual
 `MILESTONE.md` (goal · scope · exit criteria · breadth-first tasks) is the second
@@ -59,57 +60,56 @@ Load the phase guide **only for the phase you are in** (progressive disclosure):
 
 | Phase | Guide | Produces (TASK.md section) | Who leads |
 |-------|-------|----------------------------|-----------|
-| setup | `phases/0-setup.md` | `.add/` + survivors + first §1–§3 + `SETUP-REVIEW.md` | AI drafts → **human locks** (the lock-down) |
-| specify | `phases/1-specify.md` | §1 rules + ranked least-sure flag | AI drafts (co-specify)† |
+| setup | `phases/0-setup.md` | `.add/` + living docs + first §1–§3 + `SETUP-REVIEW.md` | AI drafts → **human locks** (the baseline approval) |
+| ground | `phases/0-ground.md` | §0 GROUND map (real files · symbols · the anchors §3 cites) | **AI** (the §0 preamble — no new gate) |
+| specify | `phases/1-specify.md` | §1 rules + ranked lowest-confidence flag | AI drafts (co-specify)† |
 | scenarios | `phases/2-scenarios.md` | §2 Given/When/Then | AI drafts† |
-| contract | `phases/3-contract.md` | §3 frozen shape | AI drafts → **human approves once** (the seam)† |
+| contract | `phases/3-contract.md` | §3 frozen shape | AI drafts → **human approves once** (the decision point)† |
 | tests | `phases/4-tests.md` | §4 + red suite in `tests/` | AI drafts† |
 | build | `phases/5-build.md` | code in `src/`, tests green | **AI** |
 | verify | `phases/6-verify.md` | §6 checks + gate record | **AI auto-gates on evidence**; human on residue/security‡ |
 | observe | `phases/7-observe.md` | §7 spec delta | human + AI |
 
-† **One-approval front (v7).** §1–§4 are drafted by the AI as a single bundle and frozen
-together; the human gives **one approval, at the contract freeze** (the autonomy seam) — not
-three separate sign-offs. The AI presents the bundle least-sure-first. See `run.md`.
-‡ **Verify auto-gate (v6–v7).** Under `autonomy: auto` (the default) a run may auto-PASS once
-the evidence is complete (all tests green · loops dry · no residue) — recorded as *auto-resolved*,
-an explicit PASS, not a skip. **Security always escalates** (HARD-STOP), as do concurrency /
-architecture residue and `conservative` autonomy. See `run.md`.
+† **The specification bundle (v7).** §1–§4 are one bundle; the human gives **one approval at the
+contract freeze** (the decision point), presented lowest-confidence-first. See `run.md`.
+‡ **Verify auto-gate (v6–v7).** Under `autonomy: auto` (the default) a run may auto-PASS on
+complete evidence — recorded as *auto-resolved*, an explicit PASS, not a skip. **Security always
+escalates** (HARD-STOP); so do concurrency / architecture residue and a lowered autonomy level (`conservative` / `manual`).
+See `run.md`.
 
-Whenever you present a seam to the human in chat (intake · front approval · gate ·
-milestone close), follow `report-template.md` — SUMMARY → DECISION → ⚠ FLAGS →
-EVIDENCE → NEXT, engine-sourced facts, show-before-ask, never pre-stamp a seam.
+Whenever you present a decision point to the human in chat (intake · bundle approval · gate ·
+milestone close), follow `report-template.md` — open with the ARC (goal · done · plan,
+engine-sourced), then SUMMARY → DECISION → ⚠ FLAGS → EVIDENCE → NEXT, show-before-ask, never
+pre-stamp a decision point — and the question is a summary, never the artifact.
 
-In **observe**, also emit **competency deltas** — learnings tagged by which of the five
+In **observe**, also emit **lessons learned** — learnings tagged by which of the five
 (`DDD · SDD · UDD · TDD · ADD`) they improve — so the foundation self-improves across loops.
-You write them as `open`; the human folds them into `PROJECT.md`. Read `deltas.md` for the
-grammar and the status lifecycle. At milestone close (or on demand), run the fold ritual that
+You write them as `open`; the human consolidates them into `PROJECT.md`. Read `deltas.md` for the
+grammar and the status lifecycle. At milestone close (or on demand), run the retrospective consolidation that
 gathers confirmed deltas into a versioned foundation — read `fold.md`.
 
-## The dynamic run (v6–v7)
+## Beyond the bundle — load on demand
 
-Once **§3 CONTRACT is FROZEN**, the build→verify half runs as a dynamic, auto-gated run —
-fan-out + in-run convergence — instead of a manual build (`autonomy: auto` is the default; lower
-to `conservative` to keep a human at the gate). Read `run.md` for the trigger, the touch-boundary,
-the evidence auto-gate, and the autonomy dial. The human-led front still owns *direction*, but v7
-compresses it to a **single approval at the contract seam**; the run never edits a frozen contract
-and never auto-passes a security finding.
+Once **§3 CONTRACT is FROZEN**, the build→verify half is a dynamic, auto-gated run
+(`autonomy: auto` default, lowered to `conservative` or `manual` for a human gate) — read `run.md`. To
+pipeline several ready tasks behind their own frozen contracts, read `streams.md`.
 
-## Parallel streams — pipelining independent tasks (opt-in)
+When a milestone's tasks are all done but its **goal** (the `MILESTONE.md` exit criteria) is not
+yet met, `milestone-done` holds the milestone open — read `loop.md` for the dynamic loop that turns
+open deltas + extras into the next tasks, proposed by you and confirmed by the human, until the goal is met.
 
-The default is one task at a time. When a milestone has several tasks whose `deps=` are
-already `PASS` and a human is ready to review, you MAY run them concurrently: read
-`streams.md`. It changes no `add.py` code — you compute a READY-QUEUE from `status`,
-spawn one worker per ready task (each in a worktree, building behind its own frozen
-contract), and keep the human seams (front approval · escalated Verify) on one serial
-REVIEW-QUEUE. The honest gain is pipelining (the reviewer never waits on a build), not
-N× speed; the autonomy dial sets how much actually overlaps.
+When `add.py status` prints **`MVP covered → propose graduation`** (every milestone done AND the
+stage-goal-criteria all `[x]`), the project is ready to graduate its stage — read `graduate.md` for the
+orchestration: gather `graduation-report` analytics → co-specify interview → draft ≥1 production
+milestone → human confirm → then (and only then) `stage production`. The flip is guarded
+(`stage_no_roadmap`) and is the FINAL step — never a bare label change.
 
 ## Non-negotiable rules (from the method)
 
+<constraints>
 1. **Direction before speed.** Never start Build until §1–§4 exist and tests are red.
 2. **Trust evidence, not inspection.** A feature is trusted because its tests pass
-   and the blind-spots (concurrency, security, architecture) were checked — not
+   and the non-functional risks (concurrency, security, architecture) were checked — not
    because the code reads plausibly.
 3. **Never weaken a test or edit a frozen contract to make the build pass.** That
    inverts the method. A real change is a *change request* back to Specify.
@@ -117,6 +117,7 @@ N× speed; the autonomy dial sets how much actually overlaps.
    `PASS`, `RISK-ACCEPTED` (signed, non-security only), or `HARD-STOP`. A security
    finding is always `HARD-STOP`.
 5. **Ask, don't guess.** If a requirement is unclear, stop and ask the user.
+</constraints>
 
 ## Advancing
 
@@ -136,9 +137,11 @@ The steps never change; their depth does. Read the stage from `add.py status`:
 - **prototype** — run light; code is throwaway; design/experience is the point.
 - **poc** — run contract/tests/build deeply on the single riskiest slice only.
 - **mvp** — full flow, narrow scope, light observation.
-- **production** — every step at full rigor + the observe loop.
+- **production** — every step at full rigor + the observe loop. Reach it via the graduation
+  orchestration (`graduate.md`) when status shows `MVP covered → propose graduation`, never a bare
+  `stage production` flip — the transition is guarded behind a human-confirmed roadmap.
 
-## The trust layer
+## The method rationale
 
 The full method (the *why* behind every rule) is the AIDD book in `.add/docs/`.
 When a phase decision is genuinely unclear, read the linked chapter — each phase

package/skill/add/adopt.md

@@ -3,8 +3,8 @@
 When ADD is pointed at a repo that already has code, onboarding is **silent**: the code
 answers the questions a greenfield interview would ask, so you read it rather than ask.
 This is the **brownfield path** of setup (the greenfield path keeps the 4-lens interview —
-see `phases/0-setup.md`). You fill the survivor files from evidence, then stop at the one
-human gate: the **lock-down** (`add.py lock`).
+see `phases/0-setup.md`). You fill the living-documentation files from evidence, then stop at the one
+human gate: the **baseline approval** (`add.py lock`).
 
 ## The signal — and arming the gate
 
@@ -14,7 +14,7 @@ Enter a brownfield repo with `--await-lock`:
 python3 .add/tooling/add.py init --await-lock
 ```
 
-`--await-lock` does two things. It seeds an **unlocked** setup, which *arms the lock-down gate*
+`--await-lock` does two things. It seeds an **unlocked** setup, which *arms the baseline-approval gate*
 — the engine then refuses a second task, crossing into build, and recording a gate until you
 `lock`. And init, being brownfield-aware, prints a line that begins:
 
@@ -29,9 +29,9 @@ code (a mechanical fact); it never reads or fills it — interpreting it is your
 
 ## The silent mapping
 
-Fill each survivor file in `.add/` from what the code actually shows — **ask nothing**:
+Fill each living-doc file in `.add/` from what the code actually shows — **ask nothing**:
 
-| Survivor | Read it from |
+| Living doc | Read it from |
 |----------|--------------|
 | `PROJECT.md` (foundation) | the domain nouns, entry points, the README, the first milestone the code implies |
 | `CONVENTIONS.md` | the languages, folder layout, naming, lint config, error style already in the tree |
@@ -41,19 +41,21 @@ Fill each survivor file in `.add/` from what the code actually shows — **ask n
 
 Two rules that never bend:
 
-1. **Never clobber a survivor.** `init` already skips any survivor that exists; if a human
+<constraints>
+1. **Never clobber a living doc.** `init` already skips any living-doc file that exists; if a human
    already wrote `PROJECT.md`, you READ it, you do not overwrite it. Add, never replace.
 2. **Tag every drafted decision `evidence-grounded` vs `guessed`.** A line you read from the
    code is *evidence-grounded* (cite the file). A line you inferred because the code was silent
-   is *guessed*. The human's single lock-down is only honest if they can see which is which —
+   is *guessed*. The human's single baseline approval is only honest if they can see which is which —
    the guesses are what they actually need to check. (The tags feed `SETUP-REVIEW.md`.)
+</constraints>
 
-## Where it ends — the lock-down
+## Where it ends — the baseline approval
 
 Brownfield onboarding draws no per-step approvals. You map the foundation, then draft the
-first milestone's scope and the first task's candidate front exactly as greenfield does, and
-present it all at **one** human gate. The human reviews the decisions (least-sure / `guessed`
-first) and signs:
+first milestone's scope and the first task's candidate specification bundle exactly as greenfield does, and
+present it all at **one** human gate. The human reviews the decisions (lowest-confidence / `guessed`
+first) and confirms in conversation; you run the lock with their name:
 
 ```bash
 python3 .add/tooling/add.py lock --by "<name>"

package/skill/add/deltas.md

@@ -1,12 +1,12 @@
-# Competency deltas — how each loop sharpens the foundation
+# Lessons learned — how each loop sharpens the foundation
 
-A **competency delta** is a single learning a task produces, tagged by which of ADD's five
+A **lesson learned** is a single learning a task produces, tagged by which of ADD's five
 competencies it improves. You write deltas in a task's **OBSERVE** phase; later, the
-`foundation-update-loop` gathers the confirmed ones and folds them into a versioned `PROJECT.md`.
+`foundation-update-loop` gathers the confirmed ones and consolidates them into a versioned `PROJECT.md`.
 This is how `DDD · SDD · UDD · TDD · ADD` stop being write-once and start converging.
 
 You (the AI) **emit** deltas as `open`. Only the **human** moves a delta to `folded` or `rejected`
-(folding into the foundation is judgment — see the verify/observe seam). You never self-fold.
+(consolidating into the foundation is judgment — see the verify/observe decision point). You never self-approve a consolidation.
 
 ## The grammar (frozen)
 
@@ -50,7 +50,7 @@ That is its home. Split genuinely separate learnings into separate deltas; never
 ```
 emit (OBSERVE)        human review (foundation-update-loop)
    open  ───────────▶  folded     (the learning is merged into PROJECT.md; version bumps)
-         └──────────▶  rejected   (considered and deliberately NOT folded — the trail is kept)
+         └──────────▶  rejected   (considered and deliberately NOT consolidated — the trail is kept)
 ```
 
 An `open` delta is a pending signal. `folded` and `rejected` are both human decisions; a `rejected`
@@ -60,9 +60,11 @@ delta is left in place (not deleted) so "we saw this and chose not to act" stays
 
 There is no engine validator yet, so before you record a delta, self-check it:
 
+<reject_codes>
 - `unknown_competency` — the tag is missing or not one of `DDD · SDD · UDD · TDD · ADD`. Fix the tag.
 - `no_evidence` — the `(evidence: …)` pointer is missing or empty. Add the proof, or drop the line.
 - `unknown_status` — the status is not `open | folded | rejected`. A fresh delta is `open`.
+</reject_codes>
 
 ## Worked example
 
@@ -75,5 +77,5 @@ A task that built a tenancy feature finished its OBSERVE phase with:
 ```
 
 Three learnings, three competencies, each with a pointer. At the next foundation update the human
-folded the DDD and TDD deltas into `PROJECT.md` (→ `folded`) and rejected the ADD one as a one-off
+consolidated the DDD and TDD deltas into `PROJECT.md` (→ `folded`) and rejected the ADD one as a one-off
 (→ `rejected`). The foundation got sharper; nothing was silently lost.

package/skill/add/fold.md

@@ -1,29 +1,29 @@
-# Folding deltas — how the foundation self-improves
+# Consolidating deltas — how the foundation self-improves
 
-This **closes the loop**. `deltas.md` lets a task EMIT learnings (`open` competency deltas in its
-OBSERVE phase); folding gathers the confirmed ones and writes them into a **versioned foundation**,
+This **closes the loop**. `deltas.md` lets a task EMIT learnings (`open` lessons learned in its
+OBSERVE phase); the retrospective consolidation gathers the confirmed ones and writes them into a **versioned foundation**,
 so `DDD · SDD · UDD · TDD · ADD` sharpen across milestones instead of drifting.
 
-You (the AI) **gather and propose**; the **human confirms**; you then write the **append-only** fold.
-You never self-fold — folding is judgment (see the verify/observe seam).
+You (the AI) **gather and propose**; the **human confirms**; you then write the **append-only** consolidation.
+You never self-approve a consolidation — consolidating is judgment (see the verify/observe decision point).
 
-## When to fold
+## When to consolidate
 
 At **milestone close** (the natural "version bump to the foundation"), or **on demand** when open
-deltas have piled up. This is a convention, not a command — there is no `add.py fold`; the ritual
+deltas have piled up. This is a convention, not a command — there is no `add.py fold`; the consolidation
 lives here so the engine stays judgment-free.
 
 ## The ritual
 
-1. **Gather** — scan every task's OBSERVE `### Competency deltas` block for lines still `open`.
+1. **Gather** — scan every task's §7 OBSERVE block for lesson-learned lines still `open` (`add.py deltas` reads them by the machine heading).
 2. **Group** — bucket them by competency (`DDD · SDD · UDD · TDD · ADD`).
 3. **Propose** — for each, draft the exact foundation edit (see routing) and show the human.
 4. **Confirm** — the human accepts or declines each delta. No write happens without this.
 5. **Write** — append the accepted edits, flip each delta's status, and bump the version.
 
-## Fold routing (every competency has a home)
+## Consolidation routing (every competency has a home)
 
-| competency | folds into | how |
+| competency | consolidates into | how |
 |------------|-----------|-----|
 | `DDD` | `PROJECT.md` §Domain (DDD) | refine/append a model bullet |
 | `SDD` | `PROJECT.md` §Spec / Living Document (SDD) | refine/append a settled-vs-open line |
@@ -31,7 +31,7 @@ lives here so the engine stays judgment-free.
 | `TDD` | `CONVENTIONS.md` | append a testing convention (no PROJECT.md section — it is the engine) |
 | `ADD` | `CONVENTIONS.md` | append a build/harness convention (likewise the engine) |
 
-**Every** fold — whatever the competency — ALSO appends one row to `PROJECT.md` **§Key Decisions**
+**Every** consolidation — whatever the competency — ALSO appends one row to `PROJECT.md` **§Key Decisions**
 (date · decision · why · outcome): the universal, auditable trail of what the foundation learned.
 
 ## Status transitions & version
@@ -39,16 +39,18 @@ lives here so the engine stays judgment-free.
 - on **confirm**: the delta moves `open` → `folded` (and its edit is appended to the routed target).
 - on **decline**: the delta moves `open` → `rejected` and is **left in place** — never deleted —
   so "we considered this and chose not to act" stays auditable.
-- a fold is **append-only**: it adds bullets/rows; it never silently rewrites existing foundation text.
-- each fold session **bumps** the `foundation-version:` marker in `PROJECT.md` by one (monotonic int).
+- a consolidation is **append-only**: it adds bullets/rows; it never silently rewrites existing foundation text.
+- each consolidation session **bumps** the `foundation-version:` marker in `PROJECT.md` by one (monotonic int).
 
 ## Reject codes (the AI is first check, the human the backstop)
 
+<reject_codes>
 - `no_open_deltas` — nothing is `open` anywhere. The ritual is a no-op; do **not** bump the version.
 - `unconfirmed_fold` — a write was attempted without recorded human confirmation. The AI proposes;
-  it never self-folds. Stop and get confirmation.
-- `unroutable_delta` — a delta's competency is not one of the five, so it has no fold target. Fix the
-  delta (it is malformed per `deltas.md`) before folding.
+  it never self-approves one. Stop and get confirmation.
+- `unroutable_delta` — a delta's competency is not one of the five, so it has no consolidation target. Fix the
+  delta (it is malformed per `deltas.md`) before consolidating.
+</reject_codes>
 
 ## Worked example (from this repo's own history)
 
@@ -60,7 +62,7 @@ which have no PROJECT.md section:
 - [TDD · open] structural tests guard canonical artifacts but not their dogfood twins (evidence: scope-loop note + this build)
 ```
 
-At the next fold the human confirms both. Routing sends each to `CONVENTIONS.md` (a "sync the dogfood
+At the next consolidation the human confirms both. Routing sends each to `CONVENTIONS.md` (a "sync the dogfood
 tree + assert md5 parity" convention), appends a §Key Decisions row for each, flips them to `folded`,
 and bumps `foundation-version` 1 → 2. The two competencies the foundation never tracked before now
 have a home — which is exactly why v5 routes TDD/ADD to `CONVENTIONS.md`.