@pilotspace/add 1.1.0 → 1.2.0

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

package/docs/appendix-g-references.md

@@ -0,0 +1,106 @@
+# Appendix G — References & Lineage
+
+ADD did not appear from nowhere. It sits at the meeting point of three currents:
+the **recursive self-improvement** thesis (AI that helps build the next AI), the
+**spec-driven development** movement (the specification, not the code, is the
+source of truth), and a decade of **agentic + tests-first** research showing that
+a generate→check→refine loop, constrained by executable tests, turns fluent model
+output into trustworthy software. This appendix is the curated, verified grounding
+for that lineage — every source below is reachable and annotated with a `↔ ADD:`
+line saying exactly how it relates to the method.
+
+**The frame — "closing the loop."** Anthropic's recursive-self-improvement picture
+runs from autonomous agents delegating to workers *today* toward a future where
+Claude improves Claude. ADD is a deliberately **human-gated, evidence-trusted**
+instance of that loop: the AI drives spec→build→verify→observe, but a human owns the
+frozen contract and the verify gate, and trust comes from passing tests and
+re-resolved evidence — never from a plausible-looking diff. The sources here are
+the shoulders that posture stands on.
+
+The four sections below are the four currents. The comparison table places ADD next
+to its two closest peers — GitHub's **spec-kit** and **GSD (Get Shit Done)** — and
+names where ADD diverges. Read "How to cite" first; the rest of the book cites into
+the keys defined here.
+
+## How to cite
+
+The book uses one inline citation form — **author-year** — and every entry's lead
+`(Author Year)` *is* its cite-key. Resolve any inline `[…]` to the matching entry below.
+
+| Authors | Inline form | Example |
+|---|---|---|
+| one author | `[Surname Year]` | `[Schmidhuber 2003]` |
+| two authors | `[Surname & Surname Year]` | `[Mathews & Nagappan 2024]` |
+| three or more | `[Surname et al. Year]` | `[Zelikman et al. 2023]` |
+| an organisation | `[Org Year]` | `[Anthropic 2026a]` · `[GitHub 2025]` |
+| several at once | joined by `; ` | `[Schmidhuber 2003; Zelikman et al. 2023]` |
+| same author, same year | add a `Year`-letter suffix | `[Anthropic 2025a]` / `[Anthropic 2025b]` |
+
+The 3+-author rule becomes **et al.**; an organisation stands in as the author
+when no individual is credited; and when two org-authored sources collide on a year
+(several Anthropic 2025/2026 items do, below) a trailing letter disambiguates them.
+There is exactly one entry per cite-key.
+
+## spec-kit ↔ ADD (and GSD)
+
+ADD shares the spec-first DNA of GitHub's **spec-kit** and the Claude-Code,
+context-rot-fighting niche of **GSD**. The phase models line up closely:
+
+| ADD phase | spec-kit command | GSD phase |
+|---|---|---|
+| foundation · principles | `/speckit.constitution` → `constitution.md` | (project setup / `CLAUDE.md`-level) |
+| §1 specify (what / why) | `/speckit.specify` → `spec.md` | **discuss** — capture decisions before planning |
+| §3 contract (how, frozen) | `/speckit.plan` → `plan.md`, `contracts/` | **plan** — research, decompose, fit fresh context |
+| milestone tasks / waves | `/speckit.tasks` → `tasks.md` | (phases → parallel waves) |
+| §5 build | `/speckit.implement` | **execute** — parallel waves, fresh 200k-token context each |
+| §6 verify | `/speckit.analyze` + `/speckit.checklist` | **verify** — walk what was built, fix before declaring done |
+
+**Where ADD diverges.** spec-kit stops at `implement`; GSD ends at verify (GSD Core
+adds a fifth *ship* phase). ADD closes the loop past both by adding three things
+neither has as a first-class gate: a **failing-tests-first** gate (§4 — no build
+starts until the tests are red for the right reason), an **observe→`fold`**
+self-improvement step (§7 — confirmed learnings consolidate into a versioned foundation),
+and an engine-tracked **dynamic goal-loop** that will hold a milestone open and
+reopen tasks until its exit criteria are met. ADD also deliberately targets **less
+doc-time than GSD** — a lean foundation and one human approval per task, rather than
+a document per phase. The shared lineage is real; the tests-first gate, the `fold`,
+and the goal-loop are ADD's contribution.
+
+## 1. Recursive self-improvement
+
+- **When AI builds itself** (Favaro & Clark 2026) — https://www.anthropic.com/institute/recursive-self-improvement — essay. The RSI thesis: by 2026 >80% of code merged at Anthropic was Claude-authored and the 50%-task time-horizon keeps doubling; recursive self-improvement would shift humans from builders to validators. ↔ ADD: the seed source — ADD is the human-gated, evidence-trusted way to run a spec→build→verify→observe loop while the human stays the validator.
+- **Automated Alignment Researchers** (Anthropic 2026a) — https://www.anthropic.com/research/automated-alignment-researchers — research. Nine parallel Claude agents recovered ~97% of the human-expert gap on an alignment task in 5 days versus 7 for the human team. ↔ ADD: the strongest evidence the recursive loop is not speculative — parallel agents under review are exactly ADD's wave-plus-verify shape.
+- **Machines of Loving Grace** (Amodei 2024) — https://www.darioamodei.com/essay/machines-of-loving-grace — essay. A "country of geniuses in a datacenter," argued with a measured, bounded position on recursive self-improvement. ↔ ADD: the intent framing behind milestoning — bound the loop with human direction rather than let it run open.
+- **Gödel Machines: Self-Referential Universal Problem Solvers** (Schmidhuber 2003) — https://arxiv.org/abs/cs/0309048 — paper. A provably-optimal self-modifying agent that rewrites itself only when it can prove the rewrite helps. ↔ ADD: the mathematical anchor of the lineage — and a precedent for "only change on proof," which ADD enforces socially via the never-weaken-a-test rule.
+- **STOP: Self-Taught Optimizer** (Zelikman et al. 2023) — https://arxiv.org/abs/2310.02304 — paper. A scaffolding program recursively improves the code that improves code. ↔ ADD: the algorithmic kin of the `fold` step — consolidate confirmed learnings back into the method that produced them.
+- **Self-Refine: Iterative Refinement with Self-Feedback** (Madaan et al. 2023) — https://arxiv.org/abs/2303.17651 — paper. Generate→critique→refine with the same model lifts quality ~20% with no extra training. ↔ ADD: the micro-loop inside build→verify — produce, check against the contract, refine.
+- **Self-Rewarding Language Models** (Yuan et al. 2024) — https://arxiv.org/abs/2401.10020 — paper. A model acts as its own reward judge to improve across iterations. ↔ ADD: the risk ADD answers — a self-judging loop needs an external gate; ADD makes tests and a human the reward signal, not the model's own opinion.
+- **Reflexion: Language Agents with Verbal Reinforcement Learning** (Shinn et al. 2023) — https://arxiv.org/abs/2303.11366 — paper. Agents keep verbal reflections in episodic memory and retry, reaching 91% on HumanEval. ↔ ADD: the principle behind "reopen the task if criteria are unmet" — a failed check becomes feedback for the next attempt, not a dead end.
+- **Voyager: An Open-Ended Embodied Agent with LLMs** (Wang et al. 2023) — https://arxiv.org/abs/2305.16291 — paper. An auto-curriculum agent that grows a reusable skill library over time. ↔ ADD: the growing foundation — each milestone's consolidated deltas are ADD's accumulating skill library.
+- **AlphaEvolve: A Coding Agent for Scientific and Algorithmic Discovery** (Novikov et al. 2025) — https://arxiv.org/abs/2506.13131 — paper. An evolutionary coding agent that beat a long-standing matrix-multiplication record and shipped a production scheduler improvement. ↔ ADD: the end-state evidence — a generate-and-verify loop can exceed human baselines when every candidate is checked.
+
+## 2. Autonomous & agentic workflows
+
+- **Building Effective Agents** (Schluntz & Zhang 2024) — https://www.anthropic.com/research/building-effective-agents — blog. The canonical taxonomy: prompt-chaining, routing, orchestrator-workers, and the evaluator-optimizer loop. ↔ ADD: the architecture cite — evaluator-optimizer is build→verify→refine; orchestrator-workers is ADD's wave parallelism.
+- **Enabling Claude Code to work more autonomously** (Anthropic 2025a) — https://www.anthropic.com/news/enabling-claude-code-to-work-more-autonomously — news. Checkpoints, subagents, hooks, background tasks, and `/rewind` rollback. ↔ ADD: checkpoint/rewind is the rollback strategy behind phase gates; hooks are where the engine enforces them.
+- **How we built our multi-agent research system** (Anthropic 2025b) — https://www.anthropic.com/engineering/multi-agent-research-system — blog. An Opus lead orchestrating Sonnet subagents, with an LLM acting as judge, lifting task performance ~90%. ↔ ADD: the lead-plus-subagents-plus-judge pattern is exactly ADD's wave execution under a verify gate.
+- **ReAct: Synergizing Reasoning and Acting in Language Models** (Yao et al. 2022) — https://arxiv.org/abs/2210.03629 — paper. Interleaving think→act→observe turns a model into an agent. ↔ ADD: the base loop every ADD phase runs on.
+- **Toolformer: Language Models Can Teach Themselves to Use Tools** (Schick et al. 2023) — https://arxiv.org/abs/2302.04761 — paper. Self-supervised learning of when and how to call external tools. ↔ ADD: the capability that lets an agent run its own tests, linters, and builds — the evidence ADD trusts.
+- **SWE-agent: Agent–Computer Interfaces Enable Automated Software Engineering** (Yang et al. 2024) — https://arxiv.org/abs/2405.15793 — paper. A designed agent–computer interface materially improves autonomous issue resolution. ↔ ADD: the structured agent↔environment contract — ADD's `add.py` engine is that interface for the method.
+- **The AI Scientist: Towards Fully Automated Open-Ended Scientific Discovery** (Lu et al. 2024) — https://arxiv.org/abs/2408.06292 — paper. A full idea→experiment→write→review research loop at ~$15 per paper. ↔ ADD: the research analog of ADD's loop — and a reminder that an automated reviewer is the weak link a human gate protects.
+
+## 3. Spec-driven development & spec-kit
+
+- **GitHub Spec Kit** (GitHub 2025) — https://github.com/github/spec-kit — repo. The reference SDD toolkit: the phase model is `constitution` → `specify` → `plan` → `tasks` → `implement`, with the spec as the executable source of truth. ↔ ADD: the closest spec-first sibling — ADD's specify and contract phases map onto specify and plan; see the comparison table for the divergence.
+- **Spec-driven development with AI: get started with a new open-source toolkit** (Delimarsky 2025) — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/ — blog. The spec-kit launch post; frames `tasks` as "TDD for your AI agent." ↔ ADD: independent articulation of why decomposing a spec into checkable units beats one big prompt.
+- **Spec-driven development: using Markdown as a programming language when building with AI** (Vesely 2025) — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-using-markdown-as-a-programming-language-when-building-with-ai/ — blog. Spec-as-source, with context-rot named as the failure SDD exists to solve. ↔ ADD: the rationale for the frozen contract — a stable written spec is what survives when the model's context degrades.
+- **Get Shit Done (GSD)** (GSD 2025) — https://github.com/open-gsd/gsd-core — repo. A meta-prompting, context-engineering, spec-driven system for Claude Code; its `discuss` → `plan` → `execute` → `verify` cycle runs each phase in a fresh subagent context to fight context-rot (originally `gsd-build/get-shit-done`, now continued as GSD Core). ↔ ADD: ADD's closest peer — same Claude-Code, context-rot niche; ADD diverges with the tests-first gate, the observe→`fold` step, and the dynamic goal-loop, and aims for less doc-time than GSD.
+- **Beyond Vibe Coding: Amazon Introduces Kiro, the Spec-Driven Agentic IDE** (InfoQ 2025) — https://www.infoq.com/news/2025/08/aws-kiro-spec-driven-agent/ — blog. Kiro structures work as requirements→design→tasks with execution hooks. ↔ ADD: cross-vendor confirmation that spec-first is converging across the industry, not a single-tool idea.
+- **Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants** (Piskala 2026) — https://arxiv.org/abs/2602.00180 — paper. A taxonomy of SDD rigor — Spec-First, Spec-Anchored, Spec-as-Source — reporting human-refined specs can cut LLM code errors substantially, with BDD as SDD's ancestor. ↔ ADD: places ADD as "Spec-Anchored" and gives the academic vocabulary for the contract-freeze decision.
+
+## 4. Tests-first & verification
+
+- **Test-Driven Development for Code Generation** (Mathews & Nagappan 2024) — https://arxiv.org/abs/2402.13521 — paper. Supplying tests alongside the prompt measurably lifts pass rates on MBPP and HumanEval. ↔ ADD: the empirical backbone of the failing-tests-first gate — tests as the constraint that makes generation verifiable.
+- **SWE-bench: Can Language Models Resolve Real-World GitHub Issues?** (Jimenez et al. 2023) — https://arxiv.org/abs/2310.06770 — paper. 2,294 real issues judged by whether the project's own tests pass; <2% solved at release. ↔ ADD: the yardstick that proves the point — "done" means the tests pass, which is exactly how ADD gates a feature.
+- **Our framework for developing safe and trustworthy agents** (Anthropic 2025c) — https://www.anthropic.com/news/our-framework-for-developing-safe-and-trustworthy-agents — news. Five principles: human control, transparency, alignment, privacy, and security. ↔ ADD: the frozen-contract gate and never-weaken-a-test rule are human control and transparency made concrete; the security HARD-STOP is the security principle.
+- **Responsible Scaling Policy v3.0** (Anthropic 2026b) — https://www.anthropic.com/news/responsible-scaling-policy-v3 — policy. The AI Safety Level framework; ASL-3 governs autonomous R&D capability. ↔ ADD: the governance ceiling that makes ADD's discipline necessary — as the loop gets more capable, the gates and the human-owned verify matter more, not less.

package/package.json

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