@pilotspace/add 1.1.0 → 1.3.0

package/docs/10-setup-and-stages.md

@@ -6,34 +6,34 @@ This chapter covers two operational matters: what you set up once per project, a
 
 ---
 
-## Setup: the AI drafts, you lock down
+## Setup: the AI drafts, you approve the baseline
 
-Before the first feature, the project needs a foundation — but standing it up is no longer your chore. Point ADD at the repo and **the AI does the drafting**: it runs `init` itself, reads what is there, and fills the foundation the whole project depends on. Your single act is the **lock-down** — the one human gate that freezes it.
+Before the first feature, the project needs a foundation — but standing it up is no longer your chore. Point ADD at the repo and **the AI does the drafting**: it runs `init` itself, reads what is there, and fills the foundation the whole project depends on. Your single act is the **baseline approval** — the one human gate that freezes it.
 
-**What the AI drafts.** From an existing codebase it works **silently** — the code answers the questions a setup interview would ask. On an empty repo it runs a short **four-lens interview** (domain · spec · users · decisions), then drafts. Either way it fills the survivor layer — the files that outlive all code — and drafts the first milestone's scope and the first task's candidate contract:
+**What the AI drafts.** From an existing codebase it works **silently** — the code answers the questions a setup interview would ask. On an empty repo it runs a short **four-lens interview** (domain · spec · users · decisions), then drafts. Either way it fills the living documentation — the files that outlive all code — and drafts the first milestone's scope and the first task's candidate contract:
 
 | Item | File | Purpose |
 |------|------|---------|
 | Foundation | `PROJECT.md` | domain · active spec · UI/UX · key decisions — the context every task reads first |
-| Conventions | `CONVENTIONS.md` | naming, layout, language, formatter — the survivor layer |
+| Conventions | `CONVENTIONS.md` | naming, layout, language, formatter — living documentation |
 | Model record | `MODEL_REGISTRY.md` | which AI model and version the project uses, for reproducibility and audit |
 | Dependency allow-list | `dependencies.allowlist` | the packages the AI may use; the pipeline rejects others |
 | Prompt playbook | `playbook/` | the six prompts from [Appendix B](./appendix-b-prompts.md) |
 | Repository + pipeline | — | runs the gates on every change |
 
-Every drafted decision is tagged **evidence-grounded** (read from the code) or **guessed** (thin or inferred) and listed least-sure-first in a `SETUP-REVIEW.md`, so the one signature you give is informed rather than a rubber stamp.
+Every drafted decision is tagged **evidence-grounded** (read from the code) or **guessed** (thin or inferred) and listed lowest-confidence-first in a `SETUP-REVIEW.md`, so the one signature you give is informed rather than given without reading.
 
-**The lock-down.** The AI presents `SETUP-REVIEW.md`; you check the `guessed` rows; you **lock** — once. That single act freezes the foundation, the first scope, and the first contract together. It is the setup-altitude analog of the [contract freeze](./05-step-3-contract.md), and it doubles as the first task's contract approval — so there is no separate sign-off. Before the lock the engine lets the AI draft but refuses to cross into build; after it, the build opens.
+**The baseline approval.** The AI presents `SETUP-REVIEW.md`; you check the `guessed` rows; you **lock** — once. That single act freezes the foundation, the first scope, and the first contract together. It is the setup-level analog of the [contract freeze](./05-step-3-contract.md), and it doubles as the first task's contract approval — so there is no separate sign-off. Before the lock the engine lets the AI draft but refuses to cross into build; after it, the build opens.
 
 **Setup exit check**
 
-- [ ] Foundation + survivors drafted (brownfield: from the code, evidence-tagged; greenfield: from the interview, gaps flagged `guessed`).
-- [ ] `SETUP-REVIEW.md` lists every drafted decision least-sure-first.
+- [ ] Foundation + living docs drafted (brownfield: from the code, evidence-tagged; greenfield: from the interview, gaps flagged `guessed`).
+- [ ] `SETUP-REVIEW.md` lists every drafted decision lowest-confidence-first.
 - [ ] The model is pinned; the allow-list exists and the pipeline fails on any package outside it.
 - [ ] The pipeline runs and is green on the empty skeleton.
 - [ ] The human **locked down** — and only then did the first feature's build open.
 
-Do not start a feature until the pipeline is green and the foundation is locked. The lock-down turns the AI's draft into committed direction; the pipeline enforces every later exit check without anyone having to remember to.
+Do not start a feature until the pipeline is green and the foundation is locked. The baseline approval turns the AI's draft into committed direction; the pipeline enforces every later exit check without anyone having to remember to.
 
 ---
 
@@ -80,7 +80,21 @@ The durable thing is never the code:
 | POC → MVP | the spike code | the validated approach + the risky-interface contract |
 | MVP → Production | nothing | everything; the code is real and is hardened |
 
-The survivor layer thickens as you move right: a prototype leaves you a validated design; a proof of concept adds a proven approach and a contract; the MVP adds real, kept code. By production, you are hardening, not rebuilding.
+The living documentation thickens as you move right: a prototype leaves you a validated design; a proof of concept adds a proven approach and a contract; the MVP adds real, kept code. By production, you are hardening, not rebuilding.
+
+### Graduating between stages
+
+Moving up a stage — most consequentially MVP → Production — is its own scope level, the fourth after setup, intake, and the milestone loop. It is *not* a label someone types: a project earns production through a human-confirmed roadmap of the hardening work, never through a bare flip. The `add` skill drives this in `graduate.md`; the shape is five steps.
+
+**The cue.** 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`. Until both tallies complete, nothing here applies — a project with no stage-goal-criteria block behaves exactly as before.
+
+1. **Gather the analytics.** `add.py graduation-report` 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, and observe-loop coverage gaps. It *gathers, never judges*: there is no readiness verdict, only the records you reason from.
+2. **Interview.** Synthesize *what production means here* with the human, using those records as the agenda. This synthesis is the judgment the engine refuses to make.
+3. **Draft the roadmap.** For each production outcome the interview surfaces, draft a production milestone with the existing command — `add.py new-milestone <slug> --stage production --goal "…"` — and write its exit criteria. The roadmap is **≥1** milestone; the hardening work itself is what those milestones contain.
+4. **Human confirms.** The human accepts, edits, or declines each draft. Nothing is created on an unconfirmed draft.
+5. **Flip — the final step.** Only now run `add.py stage production`.
+
+**The floor the engine enforces.** `add.py stage production` is guarded: it refuses with `stage_no_roadmap` (non-zero exit, state byte-unchanged) when no milestone has `stage: production`. The check is a *tally* — does a production-roadmap record exist? — never a readiness judgment, mirroring the milestone goal-gate. `--force` overrides it for grandfathered or edge cases; use it deliberately, not as the normal path. The guard is on the `→production` transition only; flips to prototype/poc/mvp are unchanged. The engine never advances the stage on its own — it gathers, counts, and holds the floor while the human judges and confirms.
 
 ---
 
@@ -88,14 +102,14 @@ The survivor layer thickens as you move right: a prototype leaves you a validate
 
 The default is one task at a time. But when a milestone holds several tasks whose dependencies are already `PASS` and a reviewer is ready, you may run them **concurrently** — one worker per ready task, each building behind its own frozen contract.
 
-**Be honest about the gain.** With one human reviewer you cannot beat `review_time × N_tasks`; the human-led seams are serial. So the win is **not throughput** — it is that the reviewer is *never blocked waiting on a build*. While a person reviews task A's front, the builds for B, C, and D run behind *their* frozen contracts. You hide build latency under human latency; do not promise more.
+**Be honest about the gain.** With one human reviewer you cannot beat `review_time × N_tasks`; the human-led decision points are serial. So the win is **not throughput** — it is that the reviewer is *never blocked waiting on a build*. While a person reviews task A's specification bundle, the builds for B, C, and D run behind *their* frozen contracts. You hide build latency under human latency; do not promise more.
 
 **Two queues, no new state** — both read from `add.py status`:
 
 - **READY-QUEUE** — tasks in the active milestone where the phase is not `done` and every dependency already reads `gate=PASS`. These are the only tasks a worker may pick up; a task finishing `PASS` unblocks its dependents on the next `status`.
-- **REVIEW-QUEUE** — the irreducibly serial part: the **one-approval front** (contract freeze) and any **Verify escalation**. One human, one queue, presented one at a time — never a batch that invites a rubber stamp.
+- **REVIEW-QUEUE** — the irreducibly serial part: the **bundle approval** (contract freeze) and any **Verify escalation**. One human, one queue, presented one at a time — never a batch that invites approval without reading.
 
-**The autonomy dial is the throttle.** At `conservative`, both gates queue on the human (pure pipelining — builds overlap, nothing auto-resolves). At `auto` (the default), only the front seam and residue escalations queue; Verify auto-PASSes on evidence, so real concurrency follows. The floor never drops below **one human approval per task, at the contract seam**.
+**The autonomy level is the throttle** — an explicit, overridable per-task token on an ordered ladder `manual < conservative < auto`. At `manual`, the human owns every gate and nothing auto-resolves (the strict floor). At `conservative`, both gates queue on the human (pure pipelining — builds overlap, nothing auto-resolves). At `auto` (the seeded default), only the bundle-approval decision point and residue escalations queue; Verify auto-PASSes on evidence, so real concurrency follows. The floor never drops below **one human approval per task, at the contract decision point**.
 
 **Design for failure (required).** Lease each task to its worker with a timeout — if a worker dies, release the claim back to READY rather than trusting partial work. A worker that hits a stop-and-escalate blocks only its own task; siblings keep running. And if several workers fail in one wave, trip a circuit-breaker and fall back to sequential — repeated failure means the scope was wrong, not the parallelism.
 

package/docs/11-governance.md

@@ -19,7 +19,11 @@ How much the AI is allowed to do is not one switch; it is a setting chosen per a
 
 The governing rule, restated from the principles: **operate only at the level your review capacity can sustain.** If the AI produces more than the team can verify, drop a level.
 
-The **per-scope default is auto-with-evidence behind a one-approval seam**: the AI drafts the front, a human approves the frozen contract once, and the build auto-gates on evidence. You *lower* a scope toward draft-and-review or suggest wherever risk is high or evidence is thin — and a high-risk or method-defining scope is *always* lowered (it is never auto-run). The default sets where you start; review capacity and risk set where you stay.
+The **per-scope default is auto-with-evidence behind a one-approval decision point**: the AI drafts the specification bundle, a human approves the frozen contract once, and the build auto-gates on evidence. You *lower* a scope toward draft-and-review or suggest wherever risk is high or evidence is thin — and a high-risk or method-defining scope is *always* lowered (it is never auto-run). The default sets where you start; review capacity and risk set where you stay.
+
+The engine expresses this per task as an explicit three-rung level — `autonomy: manual | conservative | auto`, an ordered ladder `manual < conservative < auto` declared in the `TASK.md` header and reviewed at the freeze. `auto` is auto-with-evidence behind the one approval (the seeded default); `conservative` is the deliberate lowering that keeps a person at the verify gate; `manual` is the strict floor where the human owns the gate and nothing auto-resolves. A high-risk or method-defining scope refuses an unguarded `auto` (`unguarded_high_risk_auto`) — it must be lowered to `conservative` or `manual`. The prose here and that engine token are one rule: prose ≡ enforcement.
+
+**Autonomy is earned by goal-clarity — the auto-ready goal.** The autonomy level decides *who* resolves Verify; an **auto-ready goal** decides whether a self-verifying run is even *meaningful*. A milestone goal is *auto-ready* when **every exit criterion cites a verifier** — `(verify: <test | command | metric>)` — so the engine can check the result against the goal without human judgment. `add.py check` raises a `goal_not_auto_ready` WARN (never red, the active milestone only) while the goal has criteria not all cited, and `status` surfaces a `goal-ready:` line every session, so the goal-clarity gap stays visible. The WARN *measures*, it never blocks: it changes neither the freeze gate nor the autonomy level — clarifying the goal is the prerequisite that *earns* trust, not a new gate (a zero-criteria goal reads not-auto-ready and is milestone-shaping's nudge, not this one's). The lint raises the floor — a citation slot per criterion — but cannot prove the citation is honest: a human can still write `(verify: it works)`, and closing that is a person's judgment, not the engine's.
 
 ## The gate-fail protocol and the three reports
 
@@ -46,7 +50,7 @@ When someone proposes skipping a step "to go faster," this table is the answer:
 
 ## The continuous concerns
 
-Four concerns are not steps but threads that run through every step, starting at project setup. Pulling them to the front ("shifting left") is far cheaper than bolting them on at the end.
+Four concerns are not steps but threads that run through every step, starting at project setup. Pulling them forward ("shifting left") is far cheaper than bolting them on at the end.
 
 | Concern | Begins at | Enforced at the build gate by |
 |---------|-----------|-------------------------------|

package/docs/12-roles.md

@@ -11,8 +11,8 @@ Everyone on an AIDD team becomes, in part, a *verifier*; most also become *autho
 - **Mission:** ensure the right thing gets built. You guard the problem.
 - **Leads:** Specify. **Contributes to:** Scenarios; the loop (deciding what the next cycle addresses).
 - **Owns:** the problem definition, the glossary of domain terms, the prioritized backlog.
-- **Done means:** the spec states real user value with no disputed terms and its assumptions ranked least-sure first — the one or two most likely wrong flagged with *why* and *what they cost*; after release, you have decided what the next loop must address.
-- **Apply it:** run the Specify prompt against a real ticket or interview, then read the AI's least-sure flag *first* and decide the one or two load-bearing assumptions before skimming the low-stakes tail. If you cannot confirm a load-bearing rule, it is not ready to build.
+- **Done means:** the spec states real user value with no disputed terms and its assumptions ranked lowest-confidence first — the one or two most likely wrong flagged with *why* and *what they cost*; after release, you have decided what the next loop must address.
+- **Apply it:** run the Specify prompt against a real ticket or interview, then read the AI's lowest-confidence flag *first* and decide the one or two load-bearing assumptions before skimming the low-stakes tail. If you cannot confirm a load-bearing rule, it is not ready to build.
 
 ## Architect / Engineering Lead
 
@@ -40,7 +40,7 @@ Everyone on an AIDD team becomes, in part, a *verifier*; most also become *autho
 
 ## QA / Test Engineer
 
-- **Mission:** make "done" machine-checkable; you are the safety net for AI-written code.
+- **Mission:** make "done" machine-checkable; you are the guardrail for AI-written code.
 - **Leads:** Tests. **Contributes to:** Scenarios (turning rules into checkable form); the loop (production monitors).
 - **Owns:** the test suite, the scenario files, the coverage target, the test report at each gate.
 - **Done means:** every scenario has a test that was red before the build; the suite is honest (nothing passes by default); coverage never regresses.

package/docs/13-adoption.md

@@ -19,7 +19,7 @@ Adopt the method on one real product, not as an all-at-once mandate.
 
 | Choose… | When… |
 |---------|-------|
-| **Express** | startup, spike, or internal tool; speed of learning dominates; small blast radius |
+| **Express** | startup, spike, or internal tool; speed of learning dominates; small scope of impact |
 | **Standard** | a normal product with real users and ordinary risk |
 | **Regulated** | finance, health, or anything audited; failure is expensive or legally consequential |
 

package/docs/14-foundation.md

@@ -1,6 +1,6 @@
 # 14 · The foundation: project context across milestones
 
-[← 13 Adoption](./13-adoption.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)
+[← 13 Adoption](./13-adoption.md) · [Contents](./README.md) · Next: [15 Foundations & Lineage →](./15-foundations-and-lineage.md)
 
 ---
 
@@ -18,7 +18,7 @@ guesses. That is the same failure the method exists to prevent ([00](./00-introd
 one level up.
 
 The **foundation** is the layer that holds this context and *outlives every
-milestone*. It is not new ceremony; it is the [survivor layer](./appendix-f-requirements-matrix.md)
+milestone*. It is not new ceremony; it is the [living documentation](./appendix-f-requirements-matrix.md)
 the method already names, made explicit as three concerns.
 
 ## Three concerns, one foundation
@@ -53,14 +53,14 @@ fifth, where the AI executes on it:
 
 ![ADD's five competencies — DDD · SDD · UDD · TDD · ADD: the first four are human-led and feed context to ADD, which is AI-led under your direction](./add-competencies.png)
 
-> The diagram's foundation (DDD · SDD · UDD) and the method's own words — survivor
-> layer · living document · ubiquitous language — name the same three ideas. This
+> The diagram's foundation (DDD · SDD · UDD) and the method's own words — living
+> documentation · the foundation document · ubiquitous language — name the same three ideas. This
 > chapter is where the diagram and the text finally meet.
 
 ## One file, not three
 
 A foundation that takes a week to write is a foundation no one keeps current. So
-ADD realizes all three concerns as **one survivor document — `PROJECT.md`** — with
+ADD realizes all three concerns as **one living document — `PROJECT.md`** — with
 one short section each, plus an append-only record of key decisions:
 
 ```
@@ -76,8 +76,8 @@ the detail belongs in a milestone or a contract, not the foundation. The foundat
 is the *thin, durable* context the engine reads first — not a place to relocate the
 work. And you do not hand-write it: at setup the AI **drafts** all four sections —
 silently from an existing codebase, or from a short four-lens interview on a
-greenfield repo — and a single human **lock-down** freezes that draft as committed
-direction (the setup-altitude analog of a contract freeze).
+greenfield repo — and a single human **baseline approval** freezes that draft as committed
+direction (the setup-level analog of a contract freeze).
 
 ## How it feeds the engine — and takes feedback back
 
@@ -101,24 +101,24 @@ life of the product, owned above any single milestone.
 
 | Tier | Lives in | Lifespan | Holds |
 |------|----------|----------|-------|
-| **Project** (foundation) | `.add/PROJECT.md` + survivor files | whole product | domain, spec stance, users, decisions |
+| **Project** (foundation) | `.add/PROJECT.md` + living-doc files | whole product | domain, spec stance, users, decisions |
 | **Milestone** | `.add/milestones/<slug>/MILESTONE.md` | one depth-bounded goal | scope, shared contracts, exit criteria |
 | **Task** | `.add/tasks/<slug>/TASK.md` | one feature | the seven-step artifacts |
 
 A milestone is a *version bump* to the foundation, not a fresh start: when it
-closes, fold what it validated into `PROJECT.md` (a decision, a settled domain
+closes, consolidate what it validated into `PROJECT.md` (a decision, a settled domain
 term, a confirmed user journey) and open the next one against the same, now-richer,
-ground. The fold is not informal: each loop emits **competency deltas** (tagged
+ground. The consolidation is not informal: each loop emits **lessons learned** (tagged
 `DDD · SDD · UDD · TDD · ADD`) in its Observe step, and at milestone close a person
-gathers the open ones and folds them — append-only, with the `foundation-version:`
-bumped — into the foundation. See [09 · The loop](./09-the-loop.md#competency-deltas-and-the-foundation-fold)
+gathers the open ones and consolidates them — append-only, with the `foundation-version:`
+bumped — into the foundation. See [09 · The loop](./09-the-loop.md#lessons-learned-and-the-retrospective-consolidation)
 for the grammar, the ritual, and the tooling (`add.py deltas`, `add.py check`).
 
 ## In the tooling
 
-- `add.py init` scaffolds `PROJECT.md` as a survivor file; the AI then drafts its
-  content and a single human **lock-down** (`add.py lock`) freezes it. Like every
-  survivor file, `init` **never overwrites a hand-edited one**.
+- `add.py init` scaffolds `PROJECT.md` as a living-doc file; the AI then drafts its
+  content and a single human **baseline approval** (`add.py lock`) freezes it. Like every
+  living-doc file, `init` **never overwrites a hand-edited one**.
 - `add.py status` shows a one-line pointer to the foundation, so a fresh session
   re-orients on context before code.
 - The guideline block written into `CLAUDE.md` / `AGENTS.md` tells any agent the

package/docs/15-foundations-and-lineage.md

@@ -0,0 +1,106 @@
+# 15 · Foundations & Lineage
+
+[← 14 The foundation](./14-foundation.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)
+
+---
+
+ADD did not appear from nowhere. It sits where four currents meet: the **recursive
+self-improvement** thesis (AI that helps build the next AI), a decade of **autonomous and
+agentic** research, the **spec-driven development** movement (the specification, not the
+code, is the source of truth), and the **tests-first** discipline that constrains a
+generate→check→refine loop with executable tests — turning fluent model output into
+trustworthy software. This chapter tells that story; [Appendix G](./appendix-g-references.md)
+is the verified source list it cites into. Every `[Author Year]` here resolves to an entry
+there.
+
+## 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 — *closing the loop* on the
+work of building AI itself [Favaro & Clark 2026]. That is the backdrop ADD is built for, and
+its position inside that picture is deliberately narrow: ADD is a **human-gated,
+evidence-trusted** instance of recursive self-improvement. The AI drives the whole inner
+cycle — specify → 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
+diff that merely reads plausibly. The argument is not that the loop should stay open
+forever; it is that the loop should be *bounded by human direction* rather than left to run
+unattended [Amodei 2024]. ADD is one concrete shape for that bound.
+
+## The four currents
+
+**Recursive self-improvement.** The mathematical anchor is the Gödel machine — a
+self-modifying agent that rewrites itself *only when it can prove the rewrite helps*
+[Schmidhuber 2003]. ADD enforces the same discipline socially rather than formally: the
+never-weaken-a-test rule is "only change on proof" expressed as a gate. The algorithmic kin
+arrived later — a scaffolding program that improves the code that improves code
+[Zelikman et al. 2023], a generate→critique→refine micro-loop [Madaan et al. 2023], agents
+that keep verbal reflections and retry [Shinn et al. 2023], an agent that grows a reusable
+skill library over time [Wang et al. 2023], and an evolutionary coder that beat a
+long-standing matrix-multiplication record under continuous checking
+[Novikov et al. 2025]. And where a self-rewarding loop has the model judge its own reward
+[Yuan et al. 2024], ADD diverges by design — it makes the tests and a human the reward
+signal, not the model's own opinion.
+
+**Autonomous and agentic workflows.** The architecture vocabulary comes from the canonical
+taxonomy of prompt-chaining, routing, orchestrator-workers, and the evaluator-optimizer loop
+[Schluntz & Zhang 2024] — where evaluator-optimizer *is* build→verify→refine and
+orchestrator-workers is ADD's wave parallelism. Underneath it sit the base agent loop of
+interleaved think→act→observe [Yao et al. 2022], the self-supervised tool use that lets an
+agent run its own tests and builds [Schick et al. 2023], and the designed agent–computer
+interface that materially lifts autonomous issue resolution [Yang et al. 2024] — the role
+ADD's `add.py` engine plays for the method. The production reports close the gap from theory
+to practice: checkpoints, subagents, and rollback for autonomous work [Anthropic 2025a], and
+a lead orchestrating subagents under an LLM judge [Anthropic 2025b].
+
+**Spec-driven development.** ADD's closest siblings are explicit specification systems.
+GitHub's **spec-kit** runs `constitution` → `specify` → `plan` → `tasks` → `implement` with
+the spec as the executable source of truth [GitHub 2025]; its launch framed task
+decomposition as "TDD for your AI agent" [Delimarsky 2025], and its rationale named the
+failure spec-driven work exists to solve — context degrading over a long session
+[Vesely 2025]. The academic vocabulary followed, with a taxonomy of Spec-First,
+Spec-Anchored, and Spec-as-Source rigor [Piskala 2026], and the pattern is converging across
+vendors [InfoQ 2025]. Nearest of all is **GSD** — a spec-driven, context-engineering system
+for the same Claude-Code niche [GSD 2025].
+
+**Tests-first and verification.** The empirical backbone is direct: supplying tests
+alongside the prompt measurably lifts pass rates [Mathews & Nagappan 2024], and the field's
+yardstick judges a fix solely by whether the project's own tests pass [Jimenez et al. 2023].
+"Done" means the tests pass — which is exactly how ADD gates a feature. The safety framing
+completes the current: human control and transparency made concrete [Anthropic 2025c], under
+a governance ceiling that grows *more* binding, not less, as the loop gets more capable
+[Anthropic 2026b].
+
+## Where ADD diverges
+
+The shared lineage is real, but ADD is not a re-skin of its siblings. spec-kit stops at
+`implement`; GSD ends at verify. ADD closes the loop past both by adding three things
+neither spec-kit [GitHub 2025] nor GSD [GSD 2025] carries as a first-class gate:
+
+- a **failing-tests-first gate** — no build starts until the tests are red for the right
+  reason, so the contract is proven executable before any code exists;
+- an **observe → `fold`** step — confirmed lessons learned consolidate back into a versioned
+  foundation, so the method improves itself across loops (retrospective consolidation is the
+  recursive-self-improvement current turned inward on ADD);
+- a **dynamic goal-loop** — the engine holds a milestone open and reopens tasks until its
+  exit criteria are met, rather than declaring done when a checklist empties.
+
+ADD also deliberately targets **less doc-time than GSD** — a lean foundation and one human
+approval per task instead of a document per phase. The tests-first gate, the `fold`, and the
+goal-loop are ADD's contribution; everything beneath them is inherited.
+
+## The evidence chain — the loop already runs
+
+The case that this is not speculative rests on three measured facts. First, the task
+time-horizon: the length of work models complete unaided keeps doubling [Favaro & Clark 2026].
+Second, the authorship share: by 2026 more than 80% of the code merged at Anthropic was
+Claude-authored [Favaro & Clark 2026]. Third, the **Automated Alignment Researchers** result:
+nine parallel Claude agents recovered roughly 97% of the human-expert gap on an alignment task
+in five days against the human team's seven [Anthropic 2026a] — parallel agents working under
+review, which is precisely ADD's wave-plus-verify shape. The loop already runs.
+
+What it does *not* yet supply is the discipline to trust the output. That is ADD's
+contribution: the frozen contract, the never-weaken-a-test rule, the evidence-over-inspection
+gate, and the security HARD-STOP that no autonomy level may auto-pass [Anthropic 2025c],
+held beneath the responsible-scaling governance ceiling [Anthropic 2026b]. As the loop grows
+more capable, those gates and the human-owned verify matter more, not less. ADD is the human-gated, evidence-trusted way to stand inside the
+closing loop and still own the result.

package/docs/README.md

@@ -51,6 +51,9 @@ For every feature, before AI writes any code, you write four short artifacts in
 - [13 · Adoption and onboarding](./13-adoption.md)
 - [14 · The foundation: project context across milestones](./14-foundation.md)
 
+**Lineage**
+- [15 · Foundations & Lineage](./15-foundations-and-lineage.md)
+
 **Part IV — Reference**
 - [Appendix A · Templates](./appendix-a-templates.md)
 - [Appendix B · Prompt library](./appendix-b-prompts.md)
@@ -58,6 +61,7 @@ For every feature, before AI writes any code, you write four short artifacts in
 - [Appendix D · The worked example, end to end](./appendix-d-worked-example.md)
 - [Appendix E · Checklists](./appendix-e-checklists.md)
 - [Appendix F · Document requirements matrix (Project → Milestone → Task)](./appendix-f-requirements-matrix.md)
+- [Appendix G · References & lineage](./appendix-g-references.md)
 
 ---
 

package/docs/appendix-a-templates.md

@@ -1,6 +1,6 @@
 # Appendix A · Templates
 
-[← 13 Adoption](./13-adoption.md) · [Contents](./README.md) · Next: [Appendix B Prompts →](./appendix-b-prompts.md)
+[← 15 Foundations & Lineage](./15-foundations-and-lineage.md) · [Contents](./README.md) · Next: [Appendix B Prompts →](./appendix-b-prompts.md)
 
 Copy-paste blanks. Project-level templates are filled once at setup; feature-level templates are filled once per feature.
 
@@ -46,8 +46,8 @@ Reject:
   - <bad input / situation> -> "<error_code>"
 After:
   - <state true once it succeeds>
-Assumptions — least-sure first:
-  ⚠ <most-likely-wrong assumption> — least sure because <why>; if wrong: <cost>
+Assumptions — lowest-confidence first:
+  ⚠ <most-likely-wrong assumption> — lowest confidence because <why>; if wrong: <cost>
   - [x] <confirmed / low-stakes assumption> — <one line>
 ```
 

package/docs/appendix-b-prompts.md

@@ -7,6 +7,9 @@ The contents of the `playbook/` folder. Each prompt is plain text that names the
 ---
 
 ### `playbook/1_specify.md`
+
+<prompt>
+
 ```
 Role: a domain analyst who brainstorms, then asks rather than assumes.
 Read first: ./PRD/* , ./GLOSSARY.md , ./inputs/ (tickets, interviews, contracts)
@@ -19,15 +22,20 @@ Steps:
      giving each refusal a named error code.
      # why: named errors become scenarios and contract responses; "handle bad input" does not.
   2. State the success state-change (After).
-  3. List the assumptions you had to make, RANKED least-sure first; flag the 1–2 you are least
-     sure about as `⚠ <assumption> — least sure because <why>; if wrong: <cost>`.
-     # why: a flat all-equal list gets rubber-stamped; a ranked one aims my attention at the risk.
-Exit: a domain owner disputes none of it; assumptions ranked least-sure first, the 1–2 ⚠ flags
+  3. List the assumptions you had to make, RANKED lowest-confidence first; flag the 1–2 where
+     your confidence is lowest as `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>`.
+     # why: a flat all-equal list gets approved without reading; a ranked one aims my attention at the risk.
+Exit: a domain owner disputes none of it; assumptions ranked lowest-confidence first, the 1–2 ⚠ flags
       carrying why + cost — or an honest "none material" that still names the single biggest risk.
-Never: resolve an ambiguity by guessing — ask. Never a blank "none" or a flat wall of equal ticks.
+Never: resolve an ambiguity by guessing — ask. Never a blank "none" or a flat list of equal ticks.
 ```
 
+</prompt>
+
 ### `playbook/2_scenarios.md`
+
+<prompt>
+
 ```
 Role: a specification tester.
 Read first: ./SPEC.md , ./GLOSSARY.md
@@ -41,7 +49,12 @@ Exit: every rule has at least one scenario with an observable result.
 Never: write a vague result ("then it works").
 ```
 
+</prompt>
+
 ### `playbook/3_contract.md`
+
+<prompt>
+
 ```
 Role: an interface/contract architect; contracts are immutable once frozen.
 Read first: ./SPEC.md , ./features/*.feature , ./GLOSSARY.md
@@ -57,7 +70,12 @@ Exit: contract tests pass against the mock; every spec rejection has a response.
 Never: change a frozen contract — a change is a request that reopens Specify.
 ```
 
+</prompt>
+
 ### `playbook/4_tests.md`
+
+<prompt>
+
 ```
 Role: a test author who writes tests before code.
 Read first: ./features/*.feature , ./contracts/*
@@ -73,7 +91,12 @@ Exit: one test per scenario; suite red for the right reason; target recorded.
 Never: assert on internals; write the implementation here.
 ```
 
+</prompt>
+
 ### `playbook/5_build.md`
+
+<prompt>
+
 ```
 Role: an execution agent. The human commands; you implement and report.
 Read first: ./SPEC.md , ./contracts/* , ./tests/* , ./CONVENTIONS.md
@@ -90,7 +113,12 @@ Never: change a test or the contract; add an unlisted dependency; exceed the tas
        without escalating; guess when unclear — ask.
 ```
 
+</prompt>
+
 ### `playbook/6_observe.md`
+
+<prompt>
+
 ```
 Role: a reliability analyst feeding the next cycle.
 Read first: telemetry exports , service-objective definitions , incident tickets
@@ -104,9 +132,14 @@ Exit: a reviewed SPEC delta linked into the backlog.
 Never: auto-roll back — recommend; a human owns the production decision.
 ```
 
+</prompt>
+
 ---
 
 ### Master prompt skeleton
+
+<prompt>
+
 ```
 Role: <one line — who the agent is for this step>
 Read first: <explicit repository paths — never chat memory>
@@ -117,3 +150,5 @@ Exit: <conditions a person or the pipeline can check>
 Never: <what the agent must not do>
 Evidence: <artifacts to attach for review>
 ```
+
+</prompt>

package/docs/appendix-c-glossary.md

@@ -10,31 +10,43 @@
 
 **Artifact** — a durable work product: the spec, the scenarios, the contract, the tests. The artifacts survive; the code is disposable.
 
-**Competency delta** — a single learning a loop produces, tagged by which of the five competencies (`DDD · SDD · UDD · TDD · ADD`) it improves, written in a task's OBSERVE phase as `- [<COMPETENCY> · <status>] <learning> (evidence: …)`. Emitted `open` by the AI; the human folds it into a versioned `PROJECT.md` (`folded`) or declines it (`rejected`). The mechanism by which the foundation self-improves instead of drifting. See the `add` skill's `deltas.md`.
+**Lesson learned** (formerly "competency delta") — a single learning a loop produces, tagged by which of the five competencies (`DDD · SDD · UDD · TDD · ADD`) it improves, written in a task's OBSERVE phase as `- [<COMPETENCY> · <status>] <learning> (evidence: …)`. Emitted `open` by the AI; the human folds it into a versioned `PROJECT.md` (`folded`) or declines it (`rejected`). The mechanism by which the foundation self-improves instead of drifting. See the `add` skill's `deltas.md`.
 
 **Contract** — the fixed external shape of a feature: interfaces, data structures, names, and error cases. Frozen before the build, it is the surface the AI builds against.
 
-**Co-specification** — how a spec is made in ADD: the AI and the human **brainstorm the shape together** (diverge), the AI **drafts** it, and the human **validates with the AI's advice** (validate). The AI's decisive advice is the *least-sure flag*. It replaces dictation-by-one-side — the human owns the decision, the AI owns surfacing what it does not yet know. See [03 Specify](./03-step-1-specify.md).
+**Co-specification** — how a spec is made in ADD: the AI and the human **brainstorm the shape together** (diverge), the AI **drafts** it, and the human **validates with the AI's advice** (validate). The AI's decisive advice is the *lowest-confidence flag*. It replaces dictation-by-one-side — the human owns the decision, the AI owns surfacing what it does not yet know. See [03 Specify](./03-step-1-specify.md).
 
 **Disposable code** — the view that code is one regenerable implementation of the artifacts, not a durable asset to be preserved.
 
 **Evidence bundle** — the proof attached to a change (passing tests, clean security scan, no coverage loss) that justifies trusting it and may unlock more AI autonomy.
 
-**Foundation version** — a monotonic integer marker in `PROJECT.md` that advances by one each time confirmed competency deltas are folded into the foundation. It makes the survivor layer's evolution auditable: a rising version with fewer new deltas per milestone is the signal that a competency is converging rather than drifting. Bumped only by the fold ritual (see the `add` skill's `fold.md`).
+**Foundation version** — a monotonic integer marker in `PROJECT.md` that advances by one each time confirmed lessons learned are consolidated into the foundation. It makes the living documentation's evolution auditable: a rising version with fewer new deltas per milestone is the signal that a competency is converging rather than drifting. Bumped only by the retrospective consolidation (see the `add` skill's `fold.md`).
 
 **Gate** — a checkpoint with an explicit pass/fail exit. Its outcome is `PASS`, `RISK-ACCEPTED`, or `HARD-STOP`.
 
+**Ground (phase-0 preamble)** — the per-task phase *before* Specify in which the AI gathers the real current codebase the task touches — files, symbols, signatures, patterns, conventions — into a lean **grounding map**, surfacing the **anchors** the frozen contract will cite. It is AI-owned and adds no approval (the one approval stays at the contract freeze); it precedes the seven steps as step 0 so the contract, tests, and build are grounded in the code as it actually is, not in assumption. Lives in the `add` skill's `phases/0-ground.md`.
+
+**Grounding map / anchors** — the §0 GROUND artifact: the real files, symbols, and conventions a task touches, plus the **anchors** — the symbols the frozen contract names. Task-specific delta only: it defers to `PROJECT.md` / `CONVENTIONS.md` for architecture and never re-runs the setup brownfield scan. `add.py status` / `check` surface whether the active task's contract is grounded (measure, never block — the contract-freeze checklist asks the human to confirm it).
+
 **`HARD-STOP`** — a gate outcome meaning work cannot proceed; triggered by any failing test or security finding.
 
-**Intake** — the step *before* a task: sizing a raw request into versioned scope by classifying it into one **request bucket**. The AI proposes `{bucket, rationale, command}`; the human confirms. Lives in the `add` skill's `intake.md` (the intake altitude, above the per-task flow).
+**Intake** — the step *before* a task: sizing a raw request into versioned scope by classifying it into one **request bucket**. The AI proposes `{bucket, rationale, command}`; the human confirms. Lives in the `add` skill's `intake.md` (the intake level, above the per-task flow).
 
-**Least-sure flag** — the AI's ranked declaration of the **1–2 things most likely to be wrong** in what it is asking a human to approve, each carrying *why* it is uncertain and *what it costs if wrong* (`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`). It reshapes the old flat assumptions list into a ranked one, so a single approval aims the reviewer's attention at the real risk instead of a wall of equal-looking ticks. Bundle-wide at the one-approval freeze seam; the §1 assumptions are its first feeder. If nothing is materially uncertain it still names the single biggest risk — never a blank "none". It makes a genuine review cheap and a lazy one visibly negligent, but cannot *force* the read. The "AI advises" half of **co-specification**.
+**Lowest-confidence flag** (formerly "least-sure flag") — the AI's ranked declaration of the **1–2 things most likely to be wrong** in what it is asking a human to approve, each carrying *why* it is uncertain and *what it costs if wrong* (`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`). It reshapes the old flat assumptions list into a ranked one, so a single approval aims the reviewer's attention at the real risk instead of a flat list of equal-looking ticks. Bundle-wide at the contract-freeze decision point; the §1 assumptions are its first input. If nothing is materially uncertain it still names the single biggest risk — never a blank "none". It makes a genuine review cheap and a lazy one visibly negligent, but cannot *force* the read. The "AI advises" half of **co-specification**.
 
 **Living document** — an artifact expected to change as the loop learns; never frozen forever (the one exception being a versioned contract, which changes only via a change request).
 
-**On-ramp** — the path a new user walks from install to their first milestone: install → `/add` → describe the goal → the agent runs intake (sizing the request into a milestone the human confirms) → the one-approval front → the self-driving run. The AI-first entry to the method; the human talks to the agent rather than hand-typing `add.py`.
+**Onboarding** (formerly "on-ramp") — the path a new user walks from install to their first milestone: install → `/add` → describe the goal → the agent runs intake (sizing the request into a milestone the human confirms) → the specification bundle → the self-driving run. The AI-first entry to the method; the human talks to the agent rather than hand-typing `add.py`.
+
+**Decision point** (formerly "seam") — a place where the flow stops for human judgment: the contract-freeze approval (the one approval), an escalated verify gate, intake confirmation, milestone close. The machine layer keeps the legacy name: the `--json` owner enum `seam`, the decide-digest key `seam`, and the `seam-audit` CI job.
+
+**The decision arc** — the three engine-sourced lines a gate report opens with at every **decision point**: `goal:` the milestone goal the work serves · `done:` the achievement, the proven progress toward it (the gate reports render this line as `done`) · `plan:` what comes next. What `done` reports adapts per gate (verify: tests + evidence · milestone close: exit-criteria met · intake: the request sized) while the three-part shape stays constant. Rendered first, above the report's summary, so the human confirms with sight of the whole trajectory, not a local snapshot. Engine-sourced like all evidence — goal · done · plan are pulled from `add.py` output, never re-typed. Presentation only: it never adds a gate or changes a `PASS` / `RISK-ACCEPTED` / `HARD-STOP` / freeze outcome. The report it opens is the chat report a person reads at a decision point — distinct from the three Test/Quality/Risk reports a verify gate produces ([11 Governance](./11-governance.md)). See the `add` skill's `report-template.md`.
+
+**Specification bundle** (formerly "the one-approval front") — §1–§4 of a task (spec · scenarios · contract · failing tests) drafted by the AI as one piece and approved by a person **once**, at the contract freeze. Rejecting any part returns the whole bundle to draft. The single approval it carries is the bundle approval.
 
-**Owner (of a phase)** — who drives a phase, exposed by `add.py … --json` as `human`, `seam`, or `ai`. It tells an autonomous harness where it may run (`ai`) and where it must checkpoint to a person (`human`/`seam`), following the who-does-what table (Verify is always `human`).
+**Retrospective consolidation** (formerly "the fold / fold ritual") — the milestone-close (or on-demand) step where a person gathers `open` lessons learned, confirms each, and the AI writes them append-only into the versioned foundation, bumping `foundation-version:`. The AI never self-approves a consolidation. The machine names keep their names: `fold.md`, the `folded` delta status, and `add.py deltas`.
+
+**Owner (of a phase)** — who drives a phase, exposed by `add.py … --json` as `human`, `seam`, or `ai` (machine enum values that keep their names; in prose the `seam` value's concept is now the decision point, formerly "seam"). It tells an autonomous harness where it may run (`ai`) and where it must checkpoint to a person (`human`/`seam`), following the who-does-what table (Verify is always `human`).
 
 **Profile** — the intensity at which the method is run: Express, Standard, or Regulated.
 
@@ -48,17 +60,41 @@
 
 **Spec (`SPEC.md`)** — the plain-language statement of what a feature must do, must reject, and assumes.
 
-**Spine / continuous concern** — a concern that runs through every step rather than being one step: security, testing, observability, cost.
+**Cross-cutting concern** (formerly "spine / continuous concern") — a concern that runs through every step rather than being one step: security, testing, observability, cost.
 
 **Stage** — one pass through the flow at a chosen depth: Prototype, Proof of Concept, MVP, or Production-Ready.
 
-**State surface** — everything an agent loads every session: the `add` skill (router `SKILL.md` + the active phase) and the lean operational docs — `PROJECT.md`, the active `MILESTONE.md` and `TASK.md`, and `state.json`. Kept small to avoid context rot. Contrast **Story surface**.
+**Stage graduation** — the orchestration loop that proposes the move to the next **stage** as a human-confirmed roadmap, never a bare flip; the 4th scope level after setup · intake · milestone-loop. The cue is every milestone `done` with the **stage-goal-criteria** all `[x]`; the flow is gather **graduation analytics** → interview *what production means here* → draft ≥1 production milestone → human confirms → `add.py stage production` as the final step. The →production flip is guarded: it refuses with `stage_no_roadmap` (a tally, not a readiness judgment) until ≥1 production milestone exists; `--force` overrides. Lives in the `add` skill's `graduate.md`.
+
+**Graduation analytics** — the five record-sets `add.py graduation-report` clusters from the whole MVP loop for the graduation interview: 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, only the records the human reasons from (gather-not-judge).
+
+**Stage-goal-criteria** — the human-authored `[x]` checklist in `PROJECT.md` that defines "MVP covered" for this project; when every milestone is `done` and these are all checked, `add.py status` prints the graduation cue. Authored by the human (judgment), never inferred by the engine.
+
+**Baseline approval** (formerly "the lock-down") — the single human gate ending autonomous setup: an explicit yes that freezes the foundation, first scope, and first contract together; runs as `add.py lock --by <name>`.
+
+**Scope level** (formerly "altitude") — the granularity a decision lives at: intake level (request → versioned scope) · milestone level · setup/foundation level · task level. (A cross-stage decision lives one level out, at the **stage-graduation** loop — which `graduate.md` also numbers as a scope level; see **Stage graduation**.) One ⚠-assumption notation is shared across every scope level.
+
+**Autonomy level** (formerly "autonomy dial") — the explicit per-task setting (`autonomy: manual | conservative | auto`, an ordered ladder manual < conservative < auto) choosing who resolves Verify: `auto` auto-PASSes on complete evidence, `conservative` keeps a human at the gate, `manual` is the strict floor (the human owns the gate; nothing auto-resolves). A high-risk scope refuses an unguarded `auto` — it must be lowered to `manual` or `conservative`. New tasks seed a visible, overridable `autonomy: auto`; a live task with no level warns (`implicit_autonomy`), a token outside the set is rejected (`unknown_autonomy_level`).
+
+**Auto-ready goal** — a milestone goal whose every exit criterion **cites a verifier** (`(verify: <test|command|metric>)`), so the engine can self-verify the result against the goal without human judgment. It is the prerequisite by which **autonomy is earned by goal-clarity**: the **autonomy level** governs *who* resolves Verify, but a clarified, machine-checkable goal is what makes a self-verifying run meaningful. `add.py check` raises a `goal_not_auto_ready` **WARN** (never red) for the active milestone until it has an auto-ready goal (≥1 exit criterion and every one cited), and `status` surfaces it (`goal-ready: auto-ready ✓` / cited-of-total); a zero-criteria goal reads not-auto-ready and is milestone-shaping's nudge, not this warning's. The lint forces a citation *slot* per criterion — it raises the floor but **cannot prove the citation is real** (a human can write `(verify: it works)`): citation-theater is the accepted irreducible floor, and the freeze gate and autonomy behavior are unchanged by it.
+
+**Automated quality gate** (formerly "evidence auto-gate") — the Verify resolver under `autonomy: auto`: a run may auto-PASS on complete evidence, recorded as *auto-resolved*; a security finding always escalates (`HARD-STOP`).
+
+**Change scope** (formerly "touch-boundary") — the hard boundary of a locked run: what it may edit (code, tests-to-green, evidence) and must not (the frozen contract, locked scope, any test weakening). The `<touch_boundary>` XML prompt tag keeps its name.
+
+**Non-functional review** (formerly "blind-spot checks") — the deliberate verify-time check of the risks tests rarely catch: concurrency, security, architecture. Security findings always escalate.
+
+**Failing-first suite** (formerly "red safety net") — the per-feature test suite written before any code and confirmed red for the right reason (a missing implementation, not a broken test); the TDD red phase at ADD step 4.
+
+**Method rationale** (formerly "trust layer") — the *why* behind every rule: the AIDD book in `.add/docs/`, read on demand via each phase guide's chapter pointer, never auto-loaded.
+
+**Working state** (formerly "state surface" — one of the two record surfaces) — everything an agent loads every session: the `add` skill (router `SKILL.md` + the active phase) and the lean operational docs — `PROJECT.md`, the active `MILESTONE.md` and `TASK.md`, and `state.json`. Kept small to avoid context rot. Contrast **audit trail**.
 
 **Stop signal** — the boolean an autonomous harness reads from `add.py … --json` (`stop = owner != "ai"`): true means pause for a person before proceeding. The irreducible stops are the contract freeze and the Verify gate. See **Owner (of a phase)**.
 
-**Story surface** — the book (`docs/*`): the whole method, read once by a person to trust ADD, then referenced by a pointer and **never auto-loaded** into agent context. Contrast **State surface**.
+**Audit trail** (formerly "story surface") — the book (`docs/*`): the whole method, read once by a person to trust ADD, then referenced by a pointer and **never auto-loaded** into agent context. Contrast **working state**.
 
-**Survivor layer** — the set of durable artifacts (conventions, glossary, frozen contracts) that outlive any particular code.
+**Living documentation** (formerly "survivor layer") — the set of durable artifacts (conventions, glossary, frozen contracts) that outlives any particular code.
 
 **Trust ladder / autonomy ladder** — the graduated levels of AI autonomy, earned with evidence and verification capacity.
 
@@ -73,6 +109,7 @@ This book uses plain step names. Teams connecting it to a larger formal standard
 | Plain step (this book) | Formal phase name |
 |------------------------|-------------------|
 | Project setup | Foundation |
+| Ground (preamble) | Codebase Discovery (the §0 grounding map) |
 | Specify | Domain Discovery + Spec Definition |
 | (design portion) | UX-Driven Design |
 | Scenarios | Behavior specification (Given/When/Then) |
@@ -82,4 +119,4 @@ This book uses plain step names. Teams connecting it to a larger formal standard
 | Verify | the review gate within the build |
 | Observe (loop) | Operate and Learn |
 
-The formal standard also names the *foundation* and *design* work as full phases in their own right; this book folds them into project setup and the Specify step (and the Prototype stage) to keep the flow to six memorable steps.
+The formal standard also names the *foundation* and *design* work as full phases in their own right; this book merges them into project setup and the Specify step (and the Prototype stage) to keep the flow to six memorable steps.