@pilotspace/add 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to the ADD method (`@pilotspace/add` on npm,
 `pilotspace-add` on PyPI) are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/); versions follow semver.
 
+## [1.2.0] — 2026-06-10
+
+The decision-arc release: the method now narrates the build as one continuous
+arc of decisions, and the loop reaches past a single milestone — graduating a
+prototype to production, gating milestones on their own goal, and running tasks
+in parallel waves. All additive; no breaking changes (SemVer MINOR).
+
+### Added
+- **The decision arc** — every human-gate report opens by naming where you are
+  on the arc (intent → cases → contract → tests → build → verify → observe), and
+  the book + GLOSSARY describe it as the spine of the method. The one human
+  approval is always placed on the arc, never floating.
+- **Graduation to production** — `add.py graduate` plus a graduate-guide and a
+  `→production` stage guard turn the mvp→production transition into an
+  analytics-driven, criteria-gated step instead of a label flip: a
+  graduation-report surfaces the evidence and a stage-goal-criteria cue tells you
+  when the prototype has earned the next stage.
+- **Goal-gated milestones & the dynamic task loop** — an explicit project GOAL
+  now rides on `status`/`guide`, a milestone completes only when every success
+  criterion is met, and a recorded `done → phase` reopen-transition lets a closed
+  task legitimately re-open without losing its history.
+- **verify-deepen** — the verify phase gained a deep-check rubric
+  (wiring · dead-code · semantic) so verification probes intent, not just a green
+  suite.
+- **Parallel waves** — `WAVE.md`, the wave ledger that is the resume point for
+  parallel task execution; `status` surfaces a live wave so a multi-task wave can
+  pause and resume cleanly.
+- **The flag-first freeze guard** — declaring a contract freeze is now
+  fail-closed: an `unflagged_freeze` is refused at `advance` time and flagged by
+  `add.py audit`, so a freeze can never be recorded without its explicit marker.
+- **Foundations & Lineage chapter** — the book gained an annotated Foundations
+  chapter with author-year citations and a references appendix, tracing the
+  method's lineage.
+
+### Changed
+- Engine prose now speaks one ubiquitous language — `add.py` output uses
+  consistent domain terms (scope level, decision point, retrospective, …).
+- `add.py compact` keeps the active state lean by compacting heavy archive
+  history, with the bundled engine frozen in lockstep.
+
 ## [1.1.0] — 2026-06-05
 
 Production-ready enforcement: the gates are now verified by machinery distinct

package/GETTING-STARTED.md

@@ -8,35 +8,12 @@ You'll learn the whole loop by doing it once:
 
 > **Specify → Scenarios → Contract → Tests → Build → Verify → Observe**
 
-ADD is **AI-first**: you talk to the agent and it drives the method — you don't
-hand-type the commands. The commands below are the agent's hands (and your escape
-hatch); the rest of this guide shows both so you can see what the agent does.
-
----
-
-## The fast path — talk to the agent
-
-After installing (step 1 below), the whole on-ramp is one move:
-
-```
-in Claude Code:  /add
-you:             "I want to let users transfer money between their own accounts."
-```
-
-From there the agent runs the **on-ramp** for you:
-
-1. **Orient** — it reads `add.py status` (the resume point), never re-reading your repo.
-2. **Intake** — it sizes your request into versioned scope and proposes a **milestone**
-   (goal · scope · breadth-first tasks · exit criteria). *You confirm the shape.*
-3. **One-approval front** — for each task it drafts Spec + Scenarios + Contract + Tests
-   as one bundle. *You give one approval at the frozen contract.*
-4. **Self-driving run** — build→verify runs to green; a security finding always stops
-   back to you.
-
-So a milestone-sized feature is: **describe it → confirm the milestone → approve each
-contract → review the result.** Everything between is the agent.
-
-> New term: **On-ramp** — the install→first-milestone path. See `docs/appendix-c-glossary.md`.
+ADD is **AI-first**: you talk to the agent and it drives the method. Reading this
+guide top to bottom, you will type exactly **one shell command — the install**.
+After that, everything happens in conversation (`/add` is how you start it, not
+a terminal command): the agent's hands are the CLI, and the same CLI is your
+escape hatch whenever you want to take the wheel (it's all in the appendix at
+the end).
 
 ---
 
@@ -49,90 +26,210 @@ contract → review the result.** Everything between is the agent.
 
 > **Windows:** use `py` wherever this guide writes `python3` (the Python launcher on
 > Windows) — e.g. `py .add\tooling\add.py status`. Both installers handle the install
-> step for you; only the by-hand `add.py` commands below differ.
+> step for you; only the by-hand `add.py` commands in the appendix differ.
 
 ---
 
-## 1 · Install
+## 1 · Install — the one command you type
 
 From your project root, pick **one** path — both produce the same install:
 
 **Option A — npm (Node.js ≥ 18):**
 
 ```bash
-npx @pilotspace/add init --name "My App" --stage prototype
+npx @pilotspace/add init
 ```
 
 **Option B — pip (Python 3.10+):**
 
 ```bash
 pip install pilotspace-add
-pilotspace-add init --name "My App" --stage prototype
+pilotspace-add init
 ```
 
+No flags needed — the agent infers your project's name from the folder and starts
+at the `prototype` stage. (Prefer to choose up front? Both installers take
+`--name "My App" --stage prototype|poc|mvp|production`; the stage can also be
+changed later — see the appendix.)
+
 Either one creates `.add/` (your runtime), drops the `add` skill into
-`.claude/skills/add/`, and bundles the book into `.add/docs/`. Pick the stage that
-matches your intent — `prototype`, `poc`, `mvp`, or `production`. You can change it
-later with `python3 .add/tooling/add.py stage mvp`.
+`.claude/skills/add/`, and bundles the book into `.add/docs/`. It deliberately
+does **not** initialise the project — that's the agent's first move, so nothing
+gets decided without you in the loop.
+
+**When the install finishes: open Claude Code and type `/add`.** That's the
+handoff — from here on it's conversation, not terminal commands.
 
 > Why stages exist: the steps never change, only how *deeply* you run them.
 > See `.add/docs/10-setup-and-stages.md`.
 
 ---
 
-## 2 · Orient — the command you'll use most
+## 2 · Your first feature — talk to the agent
+
+In Claude Code, the whole onboarding is one move:
+
+```
+in Claude Code:  /add
+you:             "I want to let users transfer money between their own accounts."
+```
+
+From there the agent runs the **onboarding** for you:
+
+1. **Orient** — it reads the project state (the resume point), never re-reading
+   your repo. On a fresh install it initialises the project itself and drafts
+   the foundation for your sign-off (the **baseline approval** — the one signature the
+   installer's closing message points at).
+2. **Intake** — it sizes your request into versioned scope and proposes a **milestone**
+   (goal · scope · breadth-first tasks · exit criteria). *You confirm the shape.*
+3. **Specification bundle** — for each task it drafts Spec + Scenarios + Contract + Tests
+   as one bundle, led by its lowest-confidence points. *You give one approval at the
+   frozen contract.*
+4. **Self-driving run** — build→verify runs to green; a security finding always stops
+   back to you.
+
+So a milestone-sized feature is: **describe it → confirm the milestone → approve each
+contract → review the result.** Everything between is the agent. For the
+transfer-money feature above, that's four short conversations — and zero typed
+commands.
+
+> New term: **Onboarding** — the install→first-milestone path. See `.add/docs/appendix-c-glossary.md`.
+
+---
+
+## 3 · What just happened (and your override)
+
+Behind the conversation, the agent drove the CLI: it read the resume point, sized
+the milestone, froze the contract you approved, ran the tests red, built to green,
+and recorded the gate. The state lives on disk, not in the chat window.
+
+If you ever want to see that state yourself — or take over entirely — the same
+CLI is yours:
 
 ```bash
 python3 .add/tooling/add.py status
 ```
 
-`add.py status` is your home base. It reads `.add/state.json` and tells you the
-project stage, the active task, and which phase you're in. **Start every session
-with it** — that's how ADD resumes work without re-reading your whole repo.
+`add.py status` is the resume point: project stage, active task, current phase.
+And `add.py guide` tells you what the current phase needs — its `guide  :` line
+names the exact phase-guide file to read (`.claude/skills/add/phases/…` — plain
+markdown), which is how **any** agent — Claude, Cursor, Copilot, Codex — follows
+ADD through the CLI alone.
 
 > Tip: shorten typing with an alias — `alias add="python3 .add/tooling/add.py"` —
-> then you can run `add status`, `add advance`, etc. The rest of this guide writes
-> the full `python3 .add/tooling/add.py ...` form so copy-paste always works.
+> then you can run `add status`, `add guide`, etc. These are override and resume
+> surfaces, not steps you owe the method: the appendix walks the full by-hand path
+> whenever you want the wheel.
+
+---
+
+## Resume next session
 
-And when you're mid-task and unsure what the current phase needs, ask:
+Close your laptop, come back tomorrow, type `/add` again — the agent reorients
+itself from disk and continues exactly where you left off. No context rot.
+
+The same resume point is yours directly:
 
 ```bash
-python3 .add/tooling/add.py guide
+python3 .add/tooling/add.py status
 ```
 
-`status` tells you *where* you are; `guide` tells you *what to do next* — the active
-task's phase, the one concrete next action, the chapter to read, and the exact command
-to run once that phase is done. Its `guide  :` line names the phase-guide file to
-read for the current phase (`.claude/skills/add/phases/…` — plain markdown), which is
-how **any** agent — Claude, Cursor, Copilot, Codex — follows ADD through the CLI alone.
-
 ---
 
-## 3 · Start your first feature
+## Self-check
+
+Confirm your project is internally consistent at any time:
 
 ```bash
-python3 .add/tooling/add.py new-task transfer --title "Transfer money between my accounts"
+python3 .add/tooling/add.py check
 ```
 
-This scaffolds `.add/tasks/transfer/TASK.md` — **one file holding all seven phase
-sections** — plus empty `tests/` and `src/` folders, and makes it the active task
-at phase `specify`.
+It verifies state is valid, every task has its TASK.md, and markers match. Exit
+code 0 means healthy — handy as a CI gate.
+
+---
+
+## Enforce the decision points in CI
+
+`add.py audit` re-verifies every recorded human gate on your board — a named
+human at each contract freeze, exactly one gate outcome per done task, a human
+reviewer wherever the security line carries a note. It exits non-zero naming
+the task and the finding, which makes it a CI gate: enforcement runs on a
+machine the agent does not control, so the agent can never stamp its own work
+green (*never self-gate*).
+
+Drop this workflow into `.github/workflows/seam-audit.yml`:
+
+```yaml
+name: seam-audit
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  seam-audit:
+    name: Decision-point audit (recorded human gates)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
 
-Open `.add/tasks/transfer/TASK.md` in your editor. You'll fill it top to bottom.
+      - name: Audit recorded decision points
+        run: python3 .add/tooling/add.py audit
+```
+
+The command is the same one you can run locally — the installer already placed
+`add.py` at `.add/tooling/add.py`, and the audit is read-only (it never edits
+your board). A red `seam-audit` job means a decision record is malformed or a
+security note was left to the auto-gate; fix the record (or escalate the gate
+to a human), never the auditor.
 
 ---
 
 ## Under the hood — the seven phases by hand (escape hatch)
 
-Everything above is what the agent drives for you through the one-approval front. This
-section is the **escape hatch**: the same seven phases run by hand, so you can see what
+Everything above is what the agent drives for you through the one-approval flow. This
+appendix is the **escape hatch**: the same seven phases run by hand, so you can see what
 each one produces and step in manually whenever you want to. You never *have* to type
 these — they are the agent's hands, and yours when you take the wheel.
 
 The rhythm is always: **fill the section → run `python3 .add/tooling/add.py advance`.**
 The tool keeps the `phase:` marker at the top of TASK.md in sync.
 
-### Phase 1 — Specify (`docs/03-step-1-specify.md`)
+### Before the phases — initialise and scaffold
+
+Starting cold? Install first as in §1 (`npx @pilotspace/add init`). Then
+initialise once and scaffold the task yourself (the agent normally does both):
+
+```bash
+python3 .add/tooling/add.py init
+python3 .add/tooling/add.py new-task transfer --title "Transfer money between my accounts"
+```
+
+> **Note:** the installer's closing hint shows `init --await-lock` — that form
+> arms the baseline-approval gate so a *human* signs the AI-drafted foundation before
+> any build. Plain `init` skips that gate, which is fine here: by hand, the
+> human IS the one driving every step.
+
+This scaffolds `.add/tasks/transfer/TASK.md` — **one file holding all seven phase
+sections** — plus empty `tests/` and `src/` folders, and makes it the active task
+at phase `specify`. Open it in your editor; you'll fill it top to bottom.
+
+You can also change the project's depth at any time:
+
+```bash
+python3 .add/tooling/add.py stage mvp
+```
+
+### Phase 1 — Specify (`.add/docs/03-step-1-specify.md`)
 
 Write the rules in **§1**. State what it *must* do, what it must *reject* (each
 with a named error code), and what's true after success:
@@ -156,7 +253,7 @@ Confirm every assumption (no FX, no daily limit in v1). Then:
 python3 .add/tooling/add.py advance
 ```
 
-### Phase 2 — Scenarios (`docs/04-step-2-scenarios.md`)
+### Phase 2 — Scenarios (`.add/docs/04-step-2-scenarios.md`)
 
 In **§2**, turn each rule into a Given/When/Then. For every rejection, assert what
 must stay **unchanged**:
@@ -171,7 +268,7 @@ Scenario: insufficient funds
 
 Then `python3 .add/tooling/add.py advance`.
 
-### Phase 3 — Contract (`docs/05-step-3-contract.md`)
+### Phase 3 — Contract (`.add/docs/05-step-3-contract.md`)
 
 In **§3**, fix the external shape and **freeze** it (`Status: FROZEN @ v1`):
 
@@ -182,21 +279,21 @@ POST /transfers  body: { fromAccountId, toAccountId, amount }
   403 -> { error: "forbidden" }
 ```
 
-A frozen contract is the seam that makes the AI build safe. Then advance.
+A frozen contract is the decision point that makes the AI build safe. Then advance.
 
-### Phase 4 — Tests, red first (`docs/06-step-4-tests.md`)
+### Phase 4 — Tests, red first (`.add/docs/06-step-4-tests.md`)
 
 Write one test per scenario into `.add/tasks/transfer/tests/`, then **run them and
 confirm they FAIL** — there's no code yet. A test that passes now is testing
 nothing. This is red/green TDD: red before green. Then advance.
 
-### Phase 5 — Build (`docs/07-step-5-build.md`)
+### Phase 5 — Build (`.add/docs/07-step-5-build.md`)
 
 Now let the AI write code into `.add/tasks/transfer/src/` until **every test
 passes** — without changing any test or the frozen contract. Honor the safety rule
 (here: debit + credit in one atomic transaction). Then advance.
 
-### Phase 6 — Verify (`docs/08-step-6-verify.md`)
+### Phase 6 — Verify (`.add/docs/08-step-6-verify.md`)
 
 In **§6**, confirm the evidence (all green, nothing weakened) and check what tests
 miss: concurrency, security, architecture. Record the gate — and close the task:
@@ -208,91 +305,20 @@ python3 .add/tooling/add.py gate PASS
 `gate PASS` marks the task `done`. (Use `gate HARD-STOP` to send it back to Build,
 or `gate RISK-ACCEPTED` for a signed, non-security waiver.)
 
-### Phase 7 — Observe (`docs/09-the-loop.md`)
+### Phase 7 — Observe (`.add/docs/09-the-loop.md`)
 
 In **§7**, note what to watch in production and the next spec delta. Every learning
 becomes the next `new-task`. The flow is a loop, not a finish line.
 
 ---
 
-## 5 · Self-check
-
-Confirm your project is internally consistent at any time:
-
-```bash
-python3 .add/tooling/add.py check
-```
-
-It verifies state is valid, every task has its TASK.md, and markers match. Exit
-code 0 means healthy — handy as a CI gate.
-
----
-
-## Enforce the seams in CI
-
-`add.py audit` re-verifies every recorded human gate on your board — a named
-human at each contract freeze, exactly one gate outcome per done task, a human
-reviewer wherever the security line carries a note. It exits non-zero naming
-the task and the finding, which makes it a CI gate: enforcement runs on a
-machine the agent does not control, so the agent can never stamp its own work
-green (*never self-gate*).
-
-Drop this workflow into `.github/workflows/seam-audit.yml`:
-
-```yaml
-name: seam-audit
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-
-permissions:
-  contents: read
-
-jobs:
-  seam-audit:
-    name: Seam audit (recorded human gates)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: '3.12'
-
-      - name: Audit recorded human seams
-        run: python3 .add/tooling/add.py audit
-```
-
-The command is the same one you can run locally — the installer already placed
-`add.py` at `.add/tooling/add.py`, and the audit is read-only (it never edits
-your board). A red `seam-audit` job means a seam record is malformed or a
-security note was left to the auto-gate; fix the record (or escalate the gate
-to a human), never the auditor.
-
----
-
-## 6 · Resume next session
-
-Close your laptop, come back tomorrow, run:
-
-```bash
-python3 .add/tooling/add.py status
-```
-
-It tells you exactly where you left off and what to do next. No context rot — the
-state lives on disk, not in a chat window.
-
----
-
-## 7 · Where to read more
+## Where to read more
 
 You just ran the method; now read *why* it's shaped this way:
 
 - The shift & principles — `.add/docs/00-introduction.md`, `.add/docs/01-principles.md`
 - The flow end to end — `.add/docs/02-the-flow.md`
-- Each step in depth — `.add/docs/03..09`
+- Each step in depth — `.add/docs/03-step-1-specify.md` through `.add/docs/09-the-loop.md`
 - Operating it on a team — `.add/docs/11-governance.md`, `.add/docs/12-roles.md`
 - A fully worked example — `.add/docs/appendix-d-worked-example.md`
 

package/README.md

@@ -34,15 +34,18 @@ Pick your ecosystem — both install the same skill, tooling, and book:
 
 ```bash
 # Node / npm
-npx @pilotspace/add init --name "My App" --stage prototype
+npx @pilotspace/add init
 ```
 
 ```bash
 # Python / pip
 pip install pilotspace-add
-pilotspace-add init --name "My App" --stage prototype
+pilotspace-add init
 ```
 
+No flags needed — the project name is inferred from your folder and the stage
+defaults to `prototype` (pass `--name "My App" --stage mvp` to choose up front).
+
 **New here?** Follow the [10-minute Quickstart](./GETTING-STARTED.md) — it walks
 your first feature end to end.
 
@@ -52,9 +55,12 @@ This installs:
 |------|------|
 | `.claude/skills/add/` | the `add` skill Claude loads (thin router + per-phase guides) |
 | `.add/tooling/add.py` | scaffolder + state tracker (Python, stdlib only) |
-| `.add/docs/` | the AIDD book — the trust layer |
-| `.add/state.json` | where the project is |
-| `.add/CONVENTIONS.md`, `GLOSSARY.md`, `MODEL_REGISTRY.md`, `dependencies.allowlist` | survivor-layer files |
+| `.add/docs/` | the AIDD book — the method rationale |
+
+Project state (`.add/state.json`) and the living-documentation files (`CONVENTIONS.md`,
+`GLOSSARY.md`, `MODEL_REGISTRY.md`, `dependencies.allowlist`) are *not* created
+here — the installer drops files only; initialisation is the agent's first move
+when you run `/add`.
 
 ## Use it
 
@@ -64,7 +70,7 @@ ADD is AI-first: you talk to the agent; it drives the method. In Claude Code, ru
 > `/add` — *"I want to let users transfer money between their own accounts."*
 
 The agent orients from `state.json`, **sizes your request into a milestone** (you
-confirm the shape), then drafts each feature's **one-approval front** — Spec +
+confirm the shape), then drafts each feature's **specification bundle** — Spec +
 Scenarios + Contract + Tests as one bundle — and you give **one approval at the
 frozen contract**. A self-driving build→verify run takes it to green; security
 findings always stop back to you.
@@ -80,7 +86,7 @@ python3 .add/tooling/add.py status      # where am I? (resume point)
 1. **Direction before speed** — no Build until spec, scenarios, contract, and *red*
    tests exist.
 2. **Trust evidence, not inspection** — a feature is trusted because its tests pass
-   and the blind spots (concurrency, security, architecture) were checked.
+   and the non-functional risks (concurrency, security, architecture) were checked.
 3. **Never weaken a test or edit a frozen contract** to make the build pass.
 4. **No silent skips** — every Verify records `PASS`, `RISK-ACCEPTED`, or
    `HARD-STOP`. Security findings are always `HARD-STOP`.

package/bin/cli.js

@@ -29,12 +29,20 @@ function warn(msg) { process.stderr.write("warn: " + msg + "\n"); }
 function fail(msg) { process.stderr.write("error: " + msg + "\n"); process.exit(1); }
 
 function parseArgs(argv) {
-  const args = { _: [], force: false, stage: "prototype", name: null };
+  // stage/name stay null unless EXPLICITLY passed — the engine's own `init`
+  // defaults the stage and infers the name from the folder, so the manual-init
+  // hint only echoes flags the user actually chose (shortest true command).
+  const args = { _: [], force: false, stage: null, name: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--force") args.force = true;
-    else if (a === "--stage") args.stage = argv[++i];
-    else if (a === "--name") args.name = argv[++i];
+    else if (a === "--stage" || a === "--name") {
+      const v = argv[++i];
+      // fail loudly on a trailing/abutting flag — never silently drop a value
+      // the user tried to pass (parity with the pip twin's argparse error)
+      if (v == null || v.startsWith("--")) fail(a + " requires a value");
+      if (a === "--stage") args.stage = v; else args.name = v;
+    }
     else if (a.startsWith("--")) warn("ignoring unknown flag " + a);
     else args._.push(a);
   }
@@ -99,7 +107,8 @@ function cmdInit(args) {
   log("");
   log("Prefer the CLI / not using Claude Code? Initialise it yourself (this arms the lock-down):");
   const launcher = process.platform === "win32" ? "py" : "python3";
-  log(`  ${launcher} .add/tooling/add.py init --await-lock --stage ${args.stage}` +
+  log(`  ${launcher} .add/tooling/add.py init --await-lock` +
+      (args.stage ? ` --stage ${args.stage}` : "") +
       (args.name ? ` --name "${args.name}"` : ""));
 }
 

package/docs/01-principles.md

@@ -34,7 +34,7 @@ The flow has an order, but it is not a one-way march. Any step may reveal a gap
 
 How much you let the AI do is not a single switch. It is a setting that lives *per scope*, and it can differ from one part of the system to another. A well-tested, low-risk area may run at full autonomy while a new, high-risk one is held back.
 
-The *default starting point* is a deliberate choice. A team that has built up evidence and tooling may **start a scope at auto** — the AI drafts the front, a human approves the frozen contract once, and the build runs and auto-gates on evidence — and *lower to conservative* wherever risk is high. (An earlier formulation started every scope conservative and made autonomy the earned exception; it is the same dial either way — what differs is which end you default to.) Two things never move with the default, whichever way it points: the contract-freeze seam stays human (the AI never freezes the interface it then builds against), and a high-risk scope is always lowered, never auto-run.
+The *default starting point* is a deliberate choice. A team that has built up evidence and tooling may **start a scope at auto** — the AI drafts the specification bundle, a human approves the frozen contract once, and the build runs and auto-gates on evidence — and *lower to conservative* wherever risk is high. (An earlier formulation started every scope conservative and made autonomy the earned exception; it is the same control either way — what differs is which end you default to.) Two things never move with the default, whichever way it points: the contract-freeze decision point stays human (the AI never freezes the interface it then builds against), and a high-risk scope is always lowered, never auto-run.
 
 **Consequence:** autonomy is a per-scope setting you choose deliberately and can lower at any time; high-risk scope is held to a human gate regardless of the default (see [11 Governance](./11-governance.md)).
 
@@ -60,9 +60,9 @@ The instructions you give the AI are plain text that reference files in the repo
 
 **Consequence:** the same project works whether the team uses one AI coding tool or another, and switching tools changes nothing structural.
 
-## 9. Two surfaces: the State you load, the Story you reference
+## 9. Two layers: the working state you load, the audit trail you reference
 
-A method that fills the context window with its own documentation defeats itself — the agent rots before it reaches the work. So ADD keeps two doc surfaces and never loads both. The **State surface** is everything an agent loads to do the work each session: the `add` skill itself (its router `SKILL.md` and the one phase currently in play) together with the lean, current operational docs — `PROJECT.md` (the foundation), the active `MILESTONE.md`, the active `TASK.md`, and `state.json`. The **Story surface** is this book: the whole method, read once by a person to understand and trust ADD, and thereafter **never auto-loaded** into agent context — only referenced by a pointer. Depth lives on the Story surface; leanness is enforced on the State surface; they never compete for the same tokens.
+A method that fills the context window with its own documentation defeats itself — the agent rots before it reaches the work. So ADD keeps two documentation layers and never loads both. The **working state** is everything an agent loads to do the work each session: the `add` skill itself (its router `SKILL.md` and the one phase currently in play) together with the lean, current operational docs — `PROJECT.md` (the foundation), the active `MILESTONE.md`, the active `TASK.md`, and `state.json`. The **audit trail** is this book plus the records behind it: the whole method, read once by a person to understand and trust ADD, and thereafter **never auto-loaded** into agent context — only referenced by a pointer. Depth lives in the audit trail; leanness is enforced on the working state; they never compete for the same tokens.
 
 **Consequence:** the book can be as rich as trust requires without costing a single runtime token, while the loaded surface stays small enough never to rot. It is why the guideline block in `CLAUDE.md`/`AGENTS.md` *points* to `add.py status` and `PROJECT.md` rather than copying them.