@pilotspace/add 1.0.0 → 1.2.0

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.0.0",
+  "version": "1.2.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"
@@ -9,7 +9,8 @@
     "access": "public"
   },
   "scripts": {
-    "test": "python3 -m unittest discover -s tooling -p 'test_*.py'"
+    "test": "python3 -m unittest discover -s tooling -p 'test_*.py'",
+    "prepublishOnly": "python3 -m unittest discover -s tooling -p 'test_packaging.py'"
   },
   "files": [
     "bin/",
@@ -18,7 +19,8 @@
     "tooling/templates/",
     "docs/",
     "README.md",
-    "GETTING-STARTED.md"
+    "GETTING-STARTED.md",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "ai-driven-development",

package/skill/add/SKILL.md

@@ -31,7 +31,10 @@ Run the tool to find the resume point instead of re-reading the repo:
 python3 .add/tooling/add.py status
 ```
 
-- **No `.add/` yet** → go to **phase 0 (setup)**: read `phases/0-setup.md`.
+- **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 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
@@ -42,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
@@ -56,34 +60,55 @@ 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/` + survivor files | human |
-| specify | `phases/1-specify.md` | §1 rules + ranked least-sure flag | human + AI (co-specify) |
-| scenarios | `phases/2-scenarios.md` | §2 Given/When/Then | human |
-| contract | `phases/3-contract.md` | §3 frozen shape | human + AI |
-| tests | `phases/4-tests.md` | §4 + red suite in `tests/` | human sets, AI writes |
+| setup | `phases/0-setup.md` | `.add/` + living docs + first §1–§3 + `SETUP-REVIEW.md` | AI drafts → **human locks** (the baseline approval) |
+| 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 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 | **human** |
+| 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 |
 
-In **observe**, also emit **competency deltas** — learnings tagged by which of the five
+† **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 `conservative` autonomy.
+See `run.md`.
+
+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 **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)
+## Beyond the bundle — load on demand
+
+Once **§3 CONTRACT is FROZEN**, the build→verify half is a dynamic, auto-gated run
+(`autonomy: auto` default, lowered to `conservative` for a human gate) — read `run.md`. To
+pipeline several ready tasks behind their own frozen contracts, read `streams.md`.
+
+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.
 
-Once **§3 CONTRACT is FROZEN**, the build→verify half MAY run as a dynamic, auto-gated run —
-fan-out + in-run convergence — instead of a manual build. Read `run.md` for the trigger, the
-touch-boundary, the evidence auto-gate, and the autonomy dial. The human-led front
-(specify·scenarios·contract) is unchanged; the run never edits a frozen contract and never
-auto-passes a security finding.
+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.
@@ -91,6 +116,7 @@ auto-passes a security finding.
    `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
 
@@ -100,6 +126,7 @@ inside TASK.md):
 ```bash
 python3 .add/tooling/add.py advance            # next phase of the active task
 python3 .add/tooling/add.py gate PASS          # at verify: records PASS, marks done
+python3 .add/tooling/add.py use <slug>         # switch the active task (e.g. across parallel streams)
 ```
 
 ## Depth by stage
@@ -109,9 +136,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

@@ -0,0 +1,67 @@
+# Adopt — map an existing repo into the foundation (silent)
+
+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 living-documentation files from evidence, then stop at the one
+human gate: the **baseline approval** (`add.py lock`).
+
+## The signal — and arming the gate
+
+Enter a brownfield repo with `--await-lock`:
+
+```bash
+python3 .add/tooling/add.py init --await-lock
+```
+
+`--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:
+
+```
+brownfield: existing code detected — the `add` skill maps it into your foundation …
+```
+
+That line is your cue to run this guide. **Always use `--await-lock` for brownfield onboarding**:
+a plain `init` writes no setup and is grandfathered-locked, so its gate never arms *and* the
+closing `lock` below would refuse with `already_locked`. The engine only *detects* the existing
+code (a mechanical fact); it never reads or fills it — interpreting it is your job.
+
+## The silent mapping
+
+Fill each living-doc file in `.add/` from what the code actually shows — **ask nothing**:
+
+| 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 |
+| `GLOSSARY.md` | the recurring names in modules, models, and public APIs (one name per concept) |
+| `MODEL_REGISTRY.md` | leave the active model record; note any AI-authored code you can detect |
+| `dependencies.allowlist` | the manifests already in the repo (package.json, pyproject, go.mod, …) |
+
+Two rules that never bend:
+
+<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 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 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 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>"
+```
+
+`lock` freezes the foundation + scope + first contract in one atomic write and opens the build.
+Until it is run, the engine refuses a second task, crossing into build, and recording a gate —
+so nothing is built on an unreviewed map. That gate is the only thing brownfield onboarding asks
+of a human; everything before it, you did from the code.

package/skill/add/deltas.md

@@ -1,16 +1,16 @@
-# 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)
 
-Each delta is ONE line, exactly:
+Each delta begins on its own **tag line**; the learning may wrap onto continuation lines:
 
 ```
 - [<COMPETENCY> · <status>] <learning> (evidence: <pointer>)
@@ -18,10 +18,20 @@ Each delta is ONE line, exactly:
 
 - `<COMPETENCY>` — exactly one of the five (below).
 - `<status>` — `open` | `folded` | `rejected`. A **newly emitted delta is `open`**.
-- `<learning>` — the insight, in one phrase ("the domain model missed multi-tenancy").
+- `<learning>` — the insight ("the domain model missed multi-tenancy"). It may run past one line;
+  the `- [COMPETENCY · status]` tag line must come **first**, and the `(evidence: …)` clause must
+  **close** the delta (on its last line).
 - `(evidence: …)` — **required**, non-empty: a failing scenario, a production signal, a review
   note. No evidence → it is an opinion, not a delta.
 
+A long learning may wrap — the lint (`add.py check`) joins continuation lines, so this is **one**
+delta, not two:
+
+```
+- [SDD · open] the export endpoint must reject a tenant-scoped token used cross-tenant,
+  returning `forbidden` (not `not_found`) (evidence: scenario_cross_tenant_export failed)
+```
+
 ## The five competencies (pick exactly one per delta)
 
 | tag | competency | a delta here means you learned something about… |
@@ -40,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`
@@ -50,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
 
@@ -65,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`.

package/skill/add/graduate.md

@@ -0,0 +1,74 @@
+# Stage graduation — propose the move to production as a roadmap, never a flip
+
+A project does not become "production" because someone typed a new label. It graduates when
+the MVP is genuinely covered AND a human-confirmed roadmap of production work exists. This guide
+is the **4th scope level** — after setup (`phases/0-setup.md`), intake (`intake.md` / `scope.md`),
+and the milestone loop (`loop.md`). It turns the bare `add.py stage` flip into the **final step** of
+an analytics-driven, interview-led orchestration.
+
+You (the AI) **gather and propose**; the **human confirms and judges**; the engine only counts
+tallies and enforces the floor. The engine never decides that the project is "ready" — that is
+judgment, and it belongs to the interview.
+
+## The cue (what starts this)
+
+When every milestone is `done` AND the human's stage-goal-criteria in `PROJECT.md` are all `[x]`,
+`add.py status` prints:
+
+```
+  → MVP covered → propose graduation
+```
+
+That line is the trigger. Before both tallies complete, status is silent and nothing here applies
+(a project with no stage-goal-criteria block behaves exactly as today — grandfathered, zero change).
+
+## The flow
+
+1. **Gather the analytics** — run `add.py graduation-report` (add `--json` to branch on it). It
+   clusters the whole MVP loop's evidence into five labeled record-sets: open deltas by competency ·
+   open RISK-ACCEPTED waivers by expiry · RETRO records · verify residue · observe-loop coverage gaps.
+   It **gathers, never judges** — there is no readiness verdict to read; the records are what you
+   reason from.
+2. **Co-specify interview** — synthesize *"what production means HERE"* WITH the human, using the
+   gathered records as the agenda (the residue to harden, the coverage gaps to monitor, the open
+   deltas to consolidate). This synthesis is the judgment the engine refuses to make. Interview to real confidence —
+   do not guess what "production-ready" means for this project.
+3. **Draft the roadmap** — for each production outcome the interview surfaces, draft a production
+   milestone with the EXISTING command and goal-gate criteria:
+   `add.py new-milestone <slug> --stage production --goal "…"`, then write its exit criteria. The
+   roadmap is **≥1** milestone — the hardening work itself (SLOs, rollback tests, incident runbooks)
+   is what these milestones *contain*; this guide proposes them, it does not do them.
+4. **Human confirms** — present the roadmap via `report-template.md`, opening with the ARC
+   (goal · done · plan): the stage-graduation goal, the MVP coverage that earns the move, and the
+   plan the production milestones lay out. The human accepts, edits, or declines each drafted
+   milestone. No milestone is created without this; nothing advances on a draft the human has not confirmed.
+5. **Flip — the final step** — only now run `add.py stage production`. Because ≥1 production milestone
+   now exists, the guard passes and the transition is recorded. This is the orchestration's last act.
+
+## The floor (what the engine enforces)
+
+`add.py stage production` is **guarded**: it refuses with `stage_no_roadmap` (non-zero exit, state
+byte-unchanged) when zero milestones have `stage: production`. The check is a **tally** — "does a
+production-roadmap record exist?" — never a readiness judgment (gather-not-judge at stage level;
+it mirrors the milestone goal-gate's `milestone_goal_unmet`). `--force` overrides it, preserving human
+authority for grandfathered/edge cases; use it deliberately, not as the normal path.
+
+Scope: the guard is on the `→production` **transition** only. Flips to prototype/poc/mvp are the
+existing bare flip, unchanged. `add.py init --stage production` is an explicit at-creation declaration
+(the same authority as `--force`), not a transition — it is out of scope of the guard by design.
+
+## Invariants (never break these)
+
+- **The flip is the final step**, never called outside this confirmed-roadmap path. A bare flip with
+  no roadmap is the symptom this scope level removes.
+- **The engine never auto-flips.** Every step here is human-confirmed; the engine gathers, counts, and
+  enforces the floor — it does not advance the stage on its own.
+- **The flow is continuous, not cue-reentrant.** The moment you draft the first production milestone,
+  `status` stops printing the cue (the "every milestone done" tally breaks). That is expected — do NOT
+  re-await the cue after drafting; carry the flow straight through to confirm and flip.
+
+## Depth and reuse
+
+The same orchestration serves prototype→poc and poc→mvp; **mvp→production** is the rigorous proof
+case (every step at full depth + the observe loop). At lower stages, run it light — the shape is the
+same, the depth is less.

package/skill/add/intake.md

@@ -1,10 +1,19 @@
 # Intake — size a request into versioned scope
 
 Before a task exists, ADD turns a raw request into correctly-sized, versioned scope.
-This is the **intake altitude**: the per-task flow is phases 0–7; intake is the step
+This is the **intake level**: the per-task flow is phases 0–7; intake is the step
 *before* a task — request → milestone or task. You (the AI) **propose**; the human
 **confirms**. Never create scope without a confirmed proposal.
 
+## Interview before you size
+
+When the request arrives as a question, or its intent is not yet sharp enough to
+place in one bucket: explore it WITH the user before classifying. Reflect the
+intent you heard, name what seems in and out of scope, and offer 2–3 sized options
+with your own recommendation. Only then emit `{ bucket, rationale, command }`.
+`ask_human` stays the floor: when interviewing cannot sharpen the request,
+reject — never guess a bucket.
+
 ## The four buckets
 
 Classify every request into exactly ONE bucket:
@@ -24,17 +33,23 @@ First ask "does this change already-frozen scope?" → if yes, it is a `change-r
 
 ## What you emit (the proposal)
 
+Present the proposal to the human via `report-template.md` — open with the ARC (goal · done ·
+plan): the goal this request serves, what is already covered, and the plan the chosen bucket sets up.
+
 For every request, emit ONE of:
 
 - **a classification** — `{ bucket, rationale, command }` — where `rationale` names WHY
   (the theme, the slice, the fit, or the frozen scope touched) and `command` is the exact
   `add.py …` from the table. The human confirms or overrides before you run it.
-- **a rejection** — `{ reject, rationale }` — and you create nothing:
-  - `ask_human` — too ambiguous/underspecified to size. Ask the human; never guess a bucket.
-  - `frozen_scope` — it changes frozen scope; route it as a `change-request` back to
-    SPECIFY/CONTRACT of the affected task — never spawn a parallel milestone that forks the truth.
-  - `split_required` — it spans more than one bucket; propose the SMALLEST set of correctly-sized
-    items, each with its own rationale; never force it into one milestone.
+- **a rejection** — `{ reject, rationale }` — and you create nothing, emitting one of the closed set:
+
+<reject_codes>
+- `ask_human` — too ambiguous/underspecified to size. Ask the human; never guess a bucket.
+- `frozen_scope` — it changes frozen scope; route it as a `change-request` back to
+  SPECIFY/CONTRACT of the affected task — never spawn a parallel milestone that forks the truth.
+- `split_required` — it spans more than one bucket; propose the SMALLEST set of correctly-sized
+  items, each with its own rationale; never force it into one milestone.
+</reject_codes>
 
 When confirmed, record the `rationale` in the artifact you create or affect — the new
 MILESTONE.md goal/body, the new TASK.md, or a note in the affected TASK.md — never in state.json.