@pilotspace/add 1.0.0 → 1.2.0

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:
 
 ```
@@ -74,7 +74,10 @@ one short section each, plus an append-only record of key decisions:
 Keep it to one screen. If a section wants to grow into a manual, that is a signal
 the detail belongs in a milestone or a contract, not the foundation. The foundation
 is the *thin, durable* context the engine reads first — not a place to relocate the
-work.
+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 **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
 
@@ -98,19 +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.
+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 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 — and, like every
-  survivor file, **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,39 @@
 
 **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`.
 
 **`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`.
 
-**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`).
+**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.
+
+**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 +56,39 @@
 
 **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 per-task setting (`autonomy: auto | conservative`) choosing who resolves Verify; high-risk scope refuses an unguarded `auto`.
+
+**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.
 
@@ -82,4 +112,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.

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

@@ -23,8 +23,8 @@ Reject:
   - source == destination -> "same_account"
   - balance < amount      -> "insufficient_funds"
   - account not mine      -> "forbidden"
-Assumptions — least-sure first:
-  ⚠ same currency only (no FX) in v1 — least sure because the ticket never said; if wrong: the amount/rounding model changes and this contract is wrong
+Assumptions — lowest-confidence first:
+  ⚠ same currency only (no FX) in v1 — lowest confidence because the ticket never said; if wrong: the amount/rounding model changes and this contract is wrong
   - [x] no daily limit in v1 — confirmed: out of scope for v1
 ```
 

package/docs/appendix-e-checklists.md

@@ -18,7 +18,7 @@ Every exit check in the book, collected for quick use. Print this page.
 - [ ] Every required behavior stated explicitly.
 - [ ] Every rejection has a named error code.
 - [ ] Success state-change described.
-- [ ] Assumptions ranked least-sure first; the 1–2 most-likely-wrong ⚠-flagged with why + cost (or an honest "none material" that still names the single biggest risk).
+- [ ] Assumptions ranked lowest-confidence first; the 1–2 most-likely-wrong ⚠-flagged with why + cost (or an honest "none material" that still names the single biggest risk).
 
 ## Step 2 — Scenarios
 
@@ -70,7 +70,7 @@ Every exit check in the book, collected for quick use. Print this page.
 
 A feature is shippable only when all are true:
 
-- [ ] Spec complete: behavior stated, rejections named, assumptions ranked least-sure first with the biggest risk flagged.
+- [ ] Spec complete: behavior stated, rejections named, assumptions ranked lowest-confidence first with the biggest risk flagged.
 - [ ] Every rule has a scenario.
 - [ ] Contract frozen; contract tests green.
 - [ ] A test per scenario; suite was red before the build.

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

@@ -10,11 +10,11 @@ This appendix maps every AIDD document to a three-level project hierarchy, so th
 
 | Level | What it is | AIDD meaning | Spans |
 |-------|-----------|--------------|-------|
-| **Project** | the whole product or engagement | the survivor layer — documents created once and kept for the life of the product | all milestones |
+| **Project** | the whole product or engagement | the living documentation — documents created once and kept for the life of the product | all milestones |
 | **Milestone** | a stage or release | one pass of the flow at a chosen depth: Prototype, POC, MVP, or Production-Ready; groups many tasks | many tasks |
-| **Task** | one feature through the flow | a single pass of Specify → … → Verify; the smallest unit with its own gate records | the six steps |
+| **Task** | one feature through the flow | a single pass of Specify → … → Verify → Observe; the smallest unit with its own gate records | the seven steps |
 
-A **project** sets up the survivor-layer documents once. A **milestone** is a depth-bounded goal that groups tasks and has its own entry and exit document gates. A **task** is one feature, and it produces the per-feature artifacts.
+A **project** sets up the living documentation once. A **milestone** is a depth-bounded goal that groups tasks and has its own entry and exit document gates. A **task** is one feature, and it produces the per-feature artifacts.
 
 ## How the hierarchy decomposes
 
@@ -53,12 +53,12 @@ Which document lives at which level, who is accountable for it, and how long it
 | `SLO.md` (objectives) | Milestone (MVP+) | from MVP | from MVP onward | DevOps / SRE |
 | `SPEC.md` | Task | per feature | living | Product / Domain |
 | `features/*.feature` | Task | per feature | living | QA / Test |
-| `contracts/*.md` | Task → **Project** | per feature, then frozen | survivor (promoted to project) | Architect / Lead |
+| `contracts/*.md` | Task → **Project** | per feature, then frozen | living doc (promoted to project) | Architect / Lead |
 | `tests/*` | Task | per feature | living | QA / Engineer |
 | Source code | Task | per feature | **disposable** | Engineer |
 | Gate outcome records | Task | per step | kept for audit | the reviewer |
 
-> Note the one promotion: a **contract** is authored at task level but, once frozen, becomes part of the project's survivor layer — other tasks depend on it. That promotion is why a contract change is a project-level change request, not a task-local edit.
+> Note the one promotion: a **contract** is authored at task level but, once frozen, becomes part of the project's living documentation — other tasks depend on it. That promotion is why a contract change is a project-level change request, not a task-local edit.
 
 ---
 
@@ -87,20 +87,21 @@ Which documents must exist, and at what depth, to **exit** each milestone. Depth
 
 ---
 
-## Matrix 3 — Documents required per task (the six steps)
+## Matrix 3 — Documents required per task (the seven steps)
 
 Every task, regardless of milestone, produces this artifact chain. The depth varies by milestone (Matrix 2); the *sequence and exit gate* do not.
 
 | Step | Required document | Exit gate (the proof) | Detail |
 |------|-------------------|------------------------|--------|
-| 1 Specify | `SPEC.md` | rules + named rejections, assumptions ranked least-sure first (biggest risk ⚠-flagged) | [03](./03-step-1-specify.md) |
+| 1 Specify | `SPEC.md` | rules + named rejections, assumptions ranked lowest-confidence first (biggest risk ⚠-flagged) | [03](./03-step-1-specify.md) |
 | 2 Scenarios | `features/<task>.feature` | one scenario per rule | [04](./04-step-2-scenarios.md) |
 | 3 Contract | `contracts/<task>.md` | frozen + contract tests green | [05](./05-step-3-contract.md) |
 | 4 Tests | `tests/<task>_*` | one test per scenario, red first | [06](./06-step-4-tests.md) |
 | 5 Build | source code + evidence bundle | all tests green, nothing weakened | [07](./07-step-5-build.md) |
-| 6 Verify | gate outcome record | `PASS` / `RISK-ACCEPTED` / `HARD-STOP` | [08](./08-step-6-verify.md) |
+| 6 Verify | gate outcome record | `PASS` / `RISK-ACCEPTED` / `HARD-STOP` (auto-resolved on evidence under `autonomy: auto`; security always escalates) | [08](./08-step-6-verify.md) |
+| 7 Observe | `TASK.md` §7 OBSERVE block | released behind a flag; scenario-monitors live; spec delta + lessons learned captured | [09](./09-the-loop.md) |
 
-A task is **done** only when all six documents exist and the Verify record reads `PASS` (or a signed `RISK-ACCEPTED`). See the master shippable checklist in [Appendix E](./appendix-e-checklists.md).
+A task is **done** when the build's documents exist and the Verify record reads `PASS` (or a signed `RISK-ACCEPTED`); the seventh step — **Observe** (§7) — then runs in production and feeds the next loop's Specify. See the master shippable checklist in [Appendix E](./appendix-e-checklists.md).
 
 ---
 
@@ -135,13 +136,13 @@ The tests are the source of truth; this table is their index. If a row here is e
 
 ## Worked example — the hierarchy filled in
 
-- **Project:** *Mobile Banking App.* Survivor-layer documents: `CONVENTIONS.md`, `GLOSSARY.md` (defines *account*, *balance*, *transfer*), `MODEL_REGISTRY.md`, `dependencies.allowlist`, `playbook/`.
+- **Project:** *Mobile Banking App.* Living documentation: `CONVENTIONS.md`, `GLOSSARY.md` (defines *account*, *balance*, *transfer*), `MODEL_REGISTRY.md`, `dependencies.allowlist`, `playbook/`.
 - **Milestone:** *MVP — core money movement.* Exit requires the full per-feature document set for each task below, plus a light `SLO.md` and a milestone exit report.
   - **Task:** *Transfer between own accounts* → `SPEC.md`, `features/transfer.feature`, `contracts/transfer.md` (frozen at v1), `tests/transfer_test.py`, code, and a `PASS` gate record. (The full set is in [Appendix D](./appendix-d-worked-example.md).)
   - **Task:** *View balance* → its own SPEC, feature, contract, tests, code, record.
   - **Task:** *Transaction history* → its own set.
 
-When all three tasks read `PASS` and the milestone documents exist, the MVP milestone exits — and the frozen `transfer` contract is now a project-level survivor artifact the next milestone builds on.
+When all three tasks read `PASS` and the milestone documents exist, the MVP milestone exits — and the frozen `transfer` contract is now a project-level living-documentation artifact the next milestone builds on.
 
 ---