@pilotspace/add 1.17.0 → 2.0.0

package/CHANGELOG.md

@@ -4,6 +4,150 @@ 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.
 
+## [2.0.0] — 2026-07-18
+
+Major: ADD 2.0 — a skill-led method on a thin state kernel. The skill drives
+the loop; `add.py` records state and guards the seams; **personas carry the
+playbooks** the platform pillars used to hard-code.
+
+- **engine-kernel-trim** — the verb surface collapses 54 → 31: the platform
+  pillars die as engine code (streams/waves/DAG orchestration · components/
+  federation · release/graduation engines · gate-audit machinery · fold/compact
+  consolidation · team verbs · the SPEC-delta trio · doctor/worktree-prep) and
+  their workflows live on as seed-persona playbooks. `add.py` shrinks
+  9,558 → 6,596 lines; the phase guides fold 17 → 12.
+- **PLAN.md** — the task doc is `PLAN.md` everywhere (was TASK.md; the
+  template is `PLAN.md.tmpl`), and the new one-shot **`add.py migrate`**
+  converts a 1.x board: renames live + archived task docs, seeds any missing
+  living spec, idempotent, refuses `migrate_conflict` before touching anything.
+- **5-DD living specs** — `.add/specs/` (domain · system · experience ·
+  quality · method) with **`add.py delta-append`** as the in-flight lesson
+  channel; the fold ceremony is gone.
+- **book-stops-shipping** — the AIDD book publishes at
+  https://pilotspace.github.io/ADD/ and never installs; engine chapter
+  pointers deep-link the site (`BOOK_URL`), installers drop the docs tree,
+  and a legacy `.add/docs/` from 1.x is user-space (never swept).
+- **phase-collapse-3** — the lifecycle is direction · build · verify: ONE
+  freeze approval crosses the whole Direction bundle; the 3-call walk
+  (`new-task` · `freeze --by --cross` · `gate PASS`) is the whole ceremony.
+- **persona routes + route scoreboard (GEPA)** — the persona proposes the
+  lane (`route:` header, ratified at freeze); every recorded gate appends a
+  route-outcome trace, and `add.py deltas` rolls the traces up per lane —
+  the evidence the PM persona reflects on GEPA-style, proposing route-rule
+  deltas the human folds into the persona file.
+
+Breaking (the 2.0 line): removed verbs refuse as unknown commands; task docs
+must be `PLAN.md` (`add.py migrate` is the paved path); the book no longer
+lands in `.add/docs/`; `TASK.fast.md.tmpl` is gone (one template, every lane).
+
+## [1.18.0] — 2026-07-14
+
+Minor: eleven milestones, expanded from the original July-7 two-milestone cut
+(unpublished — the 1.17.0-amend precedent) to attribute everything merged
+since. Headline: **six-phase-loop** — the lifecycle merges 8 phases into 6
+(specify absorbs scenarios; verify absorbs observe), phase guides disclose
+into the roster's bundle subagents, and the tick into build re-renders the
+frozen spec. Also: **expectations-first** (plan phase; ONE freeze),
+**plan-legibility**, **quality-floors**, **risk-proportional-ceremony**,
+**three-phase-flow**, **add-bench** + **add-bench-v2** (the trust benchmark
+that measured it all), **add-lean-loop**, plus the original
+**build-strategy-facets** and **delta-drain**. The ceremony-to-effort and
+call-floor features (compound ticks · scope echo · kickoff truth · skill
+orient split) ship here too; their milestones remain open on measurement
+criteria. Folded in after the July-14 cut: the **engine-minimalism /
+context-cost thread** — a progressive foundation read, a lean default `status`,
+and one fewer ceremony turn per crossing — measured by **token-anatomy** and
+**honest-fidelity-meter**. No gate weakened; a security finding still HARD-STOPs.
+
+### Changed (the headline)
+- **The loop is six phases**: `specify → plan → tests → build → verify → done`.
+  Scenarios live inside SPECIFY (§2 unchanged as a section); the observe duties
+  live inside VERIFY (§7 unchanged). Legacy phase tokens (`ground`, `contract`,
+  `scenarios`, `observe`) normalize on read — in-flight boards migrate loud and
+  safe; the skip grammar is retired (nothing is skippable; vestigial `skips:`
+  headers are noted at gate, never fatal) (six-phase-loop).
+- **Guides re-cut to 6 files**; delegating spawns a bundle agent that loads its
+  own phase guides — the orchestrator reads only SKILL.md; the inline lane stays
+  first-class (six-phase-loop).
+- The specification bundle approves at ONE freeze on the plan phase
+  (expectations-first); the freeze report renders the BUILD PLAN block and the
+  resolved scope echo (plan-legibility, ceremony-to-effort).
+
+### Added
+- **Build-entry spec echo** — the tests→build tick prints the §1 Must/Reject
+  rules + the frozen §3 contract head, so the builder starts from the spec on
+  the screen, not from memory; fail-open, both entry paths (six-phase-loop).
+- **Per-phase persona presets** — teacher-grade expert stances per owned phase
+  in the roster agents; project-persona routing stays first; a preset never
+  lowers a gate (six-phase-loop).
+- **Compound ticks** — `freeze --cross` lands in tests; `gate` records from
+  build (one call fewer per crossing); init prints the resume pointer
+  (call-floor).
+- **Quality floors** — spec-dialect warn at build entry · fast-lane
+  `Boundary:` freeze-refusal · §6 DIALECT check line (quality-floors).
+- **The trust benchmark** — arms × workload-milestones harness with
+  deterministic oracles, tamper/regression meters, and the
+  cost-per-trusted-feature verdict (add-bench, add-bench-v2).
+- **AI-plan-verify gate + phase bundles** (three-phase-flow) · message-layer
+  error ergonomics, −24% turns at equal rigor (risk-proportional-ceremony).
+
+### Added (from the original July-7 cut)
+- **Faceted §5 build strategy** — four domain-generic facet lines drafted at
+  the tests→build cross: `Approach` (domain strategy) · `Data strategy` ·
+  `Pattern` · `Optimization stance`; the fast lane collapses them to one line
+  (build-strategy-facets).
+- **per-facet ADR harvest** — each §5 facet lands in §7 Decisions (ADR) as its
+  own actor-tagged line at done (build-strategy-facets).
+- **compact-foundation `--propose`** — a read-only preview of the compaction a
+  run would take; inspect before any byte moves (delta-drain).
+- **`verify` flow value for personas** — personas route to the verify surface
+  directly; the streams.md worker-contract `<persona>` block names the flow
+  preference (delta-drain).
+- **persona roster line** — `status`/`check` render an engine-built roster with
+  flows, never hand-maintained (delta-drain).
+
+### Changed
+- §5 build strategy guidance, phase guides, and the TASK.md/TASK.fast.md
+  templates teach and carry the facet block (build-strategy-facets).
+
+### Fixed
+- **Installer data loss** — `.claude/agents` is a shared namespace: init/update
+  now land only ADD's own roster files per-file (atomic), removal is
+  explicit-tombstone-only — the user's own subagents survive every install and
+  update (loose task installer-shared-namespace-guard, PR #151).
+
+### Added (engine-minimalism — the context-cost thread)
+- **Progressive foundation read** — `status --foundation` prints a MAP (the preamble +
+  `invariants:` + Domain + Spec in full; every other section collapsed to its heading +
+  an on-demand `add.py status --foundation "<section>"` pull), so the cross-milestone
+  foundation that is re-read every turn is a slice, not the whole file; a named section
+  fleshes out on demand and `--all` restores the whole foundation (foundation-slice, −59%
+  on a 55KB foundation). Invariants never collapse — the contracts that bind every task
+  always survive the map.
+- **Lean default `status`** — bare `status` prints the resume essentials; five heavy
+  blocks gate behind `--all`; `status --brief` is the mid-task resume; `status --section
+  <n>` reads one TASK.md §body instead of the whole growing file (engine-minimalism).
+- **`--help` diet** — the top-level help drops from 121 lines to 19 (engine-minimalism).
+
+### Changed (engine-minimalism)
+- **One fewer ceremony turn per crossing** — a green build steers straight to `gate PASS`;
+  the redundant pre-gate `advance` is folded away (ceremony-turn-cut / advance-fold).
+- **Leaner per-turn engine output** — bare `status` stops restating the 'now' card in its
+  resume block; `new-task` teaches the full annotated recipe once per project, compact
+  thereafter; the skill re-orients from each verb's `next:` footer instead of re-running
+  `status` (engine-output-trim, status-brief-adoption, trust-the-footer).
+
+### Added (measurement — not shipped in the package)
+- **Token anatomy** attributes a benchmark run's cache-read cost by category; a
+  deterministic **`requirement_coverage`** meter replaces the artifact-blind spec-fidelity
+  judge (now a source-aware, non-gating annotation); scoring is hermetic per boot
+  (token-anatomy, honest-fidelity-meter). Dev harness under `benchmark/` — not in the
+  npm/PyPI tarball.
+
+### Disclosed waivers (non-security, signed)
+- `reclaim-ticket-race` — lock-reclaim TOCTOU flake; owner Tin Dang, expires 2026-08-04.
+- `js-reclaim-lock-heartbeat` — JS lock-heartbeat race; owner Tin Dang, expires 2026-08-04.
+
 ## [1.17.0] — 2026-07-06
 
 Minor: four milestones — **method-ergonomics** (every recurring gate rule becomes

package/GETTING-STARTED.md

@@ -53,7 +53,8 @@ at the `prototype` stage. (Prefer to choose up front? Both installers take
 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/`. It deliberately
+`.claude/skills/add/`. The book itself is published at
+https://pilotspace.github.io/ADD/ and never installs into the project. It deliberately
 does **not** initialise the project — that's the agent's first move, so nothing
 gets decided without you in the loop.
 
@@ -61,7 +62,7 @@ gets decided without you in the loop.
 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`.
+> See https://pilotspace.github.io/ADD/10-setup-and-stages/.
 
 ### Updating to a newer ADD — no re-install
 
@@ -79,7 +80,7 @@ pipx run pilotspace-add update
 pip install -U pilotspace-add && pilotspace-add update
 ```
 
-`update` clean-replaces the managed layer (`skill` · `.add/tooling` · `.add/docs`)
+`update` clean-replaces the managed layer (`skill` · `.add/tooling`)
 and **never touches your work** — `state.json`, `PROJECT.md`, milestones, tasks and
 archive are left exactly as they were (it backs `state.json` up first regardless). It
 is idempotent (same version twice is a no-op) and writes a `.add/.add-version` stamp.
@@ -115,7 +116,7 @@ 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`.
+> New term: **Onboarding** — the install→first-milestone path. See https://pilotspace.github.io/ADD/appendix-c-glossary/.
 
 ---
 
@@ -169,56 +170,11 @@ Confirm your project is internally consistent at any time:
 python3 .add/tooling/add.py check
 ```
 
-It verifies state is valid, every task has its TASK.md, and markers match. Exit
+It verifies state is valid, every task has its PLAN.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'
-
-      - 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 flow. This
@@ -227,7 +183,7 @@ each one produces and step in manually whenever you want to. You never *have* to
 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.
+The tool keeps the `phase:` marker at the top of PLAN.md in sync.
 
 ### Before the phases — initialise and scaffold
 
@@ -244,7 +200,7 @@ python3 .add/tooling/add.py new-task transfer --title "Transfer money between my
 > 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
+This scaffolds `.add/tasks/transfer/PLAN.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.
 
@@ -254,7 +210,7 @@ You can also change the project's depth at any time:
 python3 .add/tooling/add.py stage mvp
 ```
 
-### Phase 1 — Specify (`.add/docs/03-step-1-specify.md`)
+### Phase 1 — Specify (https://pilotspace.github.io/ADD/03-step-1-specify/)
 
 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:
@@ -278,7 +234,7 @@ Confirm every assumption (no FX, no daily limit in v1). Then:
 python3 .add/tooling/add.py advance
 ```
 
-### Phase 2 — Scenarios (`.add/docs/04-step-2-scenarios.md`)
+### Phase 2 — Scenarios (https://pilotspace.github.io/ADD/04-step-2-scenarios/)
 
 In **§2**, turn each rule into a Given/When/Then. For every rejection, assert what
 must stay **unchanged**:
@@ -293,7 +249,7 @@ Scenario: insufficient funds
 
 Then `python3 .add/tooling/add.py advance`.
 
-### Phase 3 — Contract (`.add/docs/05-step-3-contract.md`)
+### Phase 3 — Contract (https://pilotspace.github.io/ADD/05-step-3-plan/)
 
 In **§3**, fix the external shape and **freeze** it (`Status: FROZEN @ v1`):
 
@@ -306,19 +262,19 @@ POST /transfers  body: { fromAccountId, toAccountId, amount }
 
 A frozen contract is the decision point that makes the AI build safe. Then advance.
 
-### Phase 4 — Tests, red first (`.add/docs/06-step-4-tests.md`)
+### Phase 4 — Tests, red first (https://pilotspace.github.io/ADD/06-step-4-tests/)
 
 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 (`.add/docs/07-step-5-build.md`)
+### Phase 5 — Build (https://pilotspace.github.io/ADD/07-step-5-build/)
 
 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 (`.add/docs/08-step-6-verify.md`)
+### Phase 6 — Verify (https://pilotspace.github.io/ADD/08-step-6-verify/)
 
 In **§6**, confirm the evidence (all green, nothing weakened) and check what tests
 miss: concurrency, security, architecture. Record the gate — and close the task:
@@ -330,7 +286,7 @@ 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 (`.add/docs/09-the-loop.md`)
+### Phase 7 — Observe (https://pilotspace.github.io/ADD/09-the-loop/)
 
 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.
@@ -341,11 +297,11 @@ becomes the next `new-task`. The flow is a loop, not a finish line.
 
 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-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`
+- The shift & principles — https://pilotspace.github.io/ADD/00-introduction/, https://pilotspace.github.io/ADD/01-principles/
+- The flow end to end — https://pilotspace.github.io/ADD/02-the-flow/
+- Each step in depth — https://pilotspace.github.io/ADD/03-step-1-specify/ through https://pilotspace.github.io/ADD/09-the-loop/
+- Operating it on a team — https://pilotspace.github.io/ADD/11-governance/, https://pilotspace.github.io/ADD/12-roles/
+- A fully worked example — https://pilotspace.github.io/ADD/appendix-d-worked-example/
 - Building UI? The render-ready UDD foundation — `.add/DESIGN.md` is the prose
   front-door to a lintable design system (`.add/design/` tokens · catalog ·
   prototypes) the AI drafts from; `add.py check` lints it (delete `DESIGN.md` if

package/README.md

@@ -2,27 +2,34 @@
   <a href="https://www.npmjs.com/package/@pilotspace/add"><img alt="npm version" src="https://img.shields.io/npm/v/@pilotspace/add.svg"></a>
   <a href="https://pypi.org/project/pilotspace-add/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/pilotspace-add.svg"></a>
   <a href="https://github.com/pilotspace/ADD/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
+  <a href="https://pilotspace.github.io/ADD/"><img alt="Read the book" src="https://img.shields.io/badge/docs-read%20the%20book-blue.svg"></a>
   <a href="https://github.com/pilotspace/ADD/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/pilotspace/ADD.svg"></a>
 </p>
 
 # ADD — AI-Driven Development
 
-**One skill. Eight steps. Five disciplines. Every feature ships through the loop.**
+**Your AI's first milestone is always great. ADD is for every milestone after that.**
 
 > A minimal, state-tracked skill for building software when the AI writes the code
 > and **you** own the two things it cannot do alone: decide *what* to build, and
 > *verify* it is correct. Native on Claude Code; every other CLI coding agent
 > follows the same loop through the phase guides.
 
-ADD is the **orchestration engine** of the AIDD method. It sits on top of a
-context foundation (DDD → SDD → UDD) and runs as a red/green TDD ↔ AI-build loop.
-The full reasoning — *why* every rule exists — is the AIDD book bundled in
-[`docs/`](./docs/README.md). Read it once; keep it open beside you.
+**The agent is the hands. ADD is the memory, judgment, and conscience — the part
+of the team that survives when the context window doesn't.** Memory: the board,
+frozen contracts, and living specs on disk (`add.py status` resumes any session
+losslessly). Judgment: personas propose each task's lane and the loop learns from
+the traced outcomes (`add.py deltas`). Conscience: evidence-scored gates, the
+tamper tripwire, the security hard-stop. It sits on top of a context foundation
+(DDD → SDD → UDD) and runs as a red/green TDD ↔ AI-build loop.
+The full reasoning — *why* every rule exists — is [the AIDD book, published
+online](https://pilotspace.github.io/ADD/). Read it once; keep it open beside you.
 
 ```
   Foundation (context):  DDD  ·  SDD  ·  UDD
   Engine (this skill):   TDD  ⇄  ADD
-  Flow per feature:  Specify → Scenarios → Contract → Tests → Build → Verify → Observe ↻
+  Flow per task:  Direction (spec · scenarios · contract · red tests → ONE freeze)
+                  → Build (red → green)  → Verify (evidence-scored gate)  ↻
 ```
 
 ## Quick Start
@@ -41,29 +48,66 @@ Then, in your coding agent, say what you want to build:
 
 > `/add` — *"Let users log in with email + password / SSO, and keep them signed in for 30 days unless they explicitly log out."*
 
-The agent sizes it into a milestone (you confirm the shape), drafts the spec →
-scenarios → contract → tests as one bundle (you approve once, at the frozen
-contract), then builds and verifies to green. Full detail below — **Install**,
-**Use it**, and the [10-minute Quickstart](./GETTING-STARTED.md).
-
-## Why ADD (and why it is minimal)
-
-Heavy doc-first methods burn your time writing documents and lose the thread
-across sessions (context rot). ADD fixes both:
+The agent sizes it into a milestone (you confirm the shape), drafts the
+specification bundle — spec → scenarios → contract → red tests as one Direction
+pass (you approve once, at the frozen contract), then builds and verifies to
+green. Full detail below — **Install**, **Use it**, and the
+[10-minute Quickstart](./GETTING-STARTED.md).
+
+## Highlights
+
+- 📉 **Anti-context-rot by design** — every decision lives on disk (`PLAN.md`, frozen contracts, red suites, `.add/state.json`), so a fresh session resumes losslessly; measured flat 1.0 quality across evolving milestones while conversation-carried flows decayed.
+- ✅ **Approve once, then let it run** — one human sign-off at the frozen contract; the agent drives Direction → Build → Verify.
+- 🔬 **Proof, not promises** — verified against observed behavior and pre-declared expectations, never just a plausible-looking diff; weakening a test to reach green is treated as tampering.
+- 💸 **Lean by measurement** — a thin 31-verb state kernel, a 3-call task walk, one file per feature; $2.20 per trusted milestone vs spec-kit's $3.90 in the latest head-to-head.
+- 🔒 **Security never gets waved through** — any security finding is a hard stop, human in the loop.
+- 🧠 **Personas route the work** — a project-owned persona proposes each task's lane, the freeze ratifies it, outcomes are traced, and the loop reflects on the record (GEPA) so the method adapts to your codebase.
+- 🎨 **See it before you build it** — a wireframe and a zero-dependency HTML mock, approved before any code.
+- 👥 **Built for teams** — git-native multi-user, N parallel milestones, DAG-scheduled waves.
+- 🧩 **One slice, many components** — monorepo or multi-repo, in one team.
+- 🤝 **Works with your AI** — Claude, Copilot, Cursor, Codex, Gemini; install via npm, pip, or the Claude Code plugin.
+
+> _Direction before speed. Trust comes from passing tests — not from reading code and finding it plausible._
+
+## Why ADD — the pain point is context rot, and we measured it
+
+Every AI coding tool can write code fast now, and every flow we benchmark aces a
+greenfield first milestone. The unsolved part is **trust across change**: when the
+spec evolves in milestone 2 and breaks compatibility in milestone 3, does the work
+you already trusted *stay* trusted?
+
+Our benchmark runs the same six-milestone evolving project through each flow under
+a pinned model with deterministic probe scoring
+([report, revised edition](https://github.com/pilotspace/ADD/blob/main/benchmark/results/2026-07-add-2.0-remeasure.md)).
+The causal finding: when ONE continued conversation carried the milestones, every
+flow decayed the same way (coverage .92 → .75, with an early list-shape spec
+violation carried through five further milestones, never re-examined). When every
+milestone instead started a **fresh session resuming from disk**, ADD held every
+floor at 1.0 across all six milestones — through a breaking shape change and a
+cross-cutting refactor — with zero regressions, at ~$2.90 per milestone (a 3–5×
+cut vs ADD 1.x's $4.65–13.94 per trusted feature). Honesty note, from the same
+report: on this friendly workload a strong model under spec-kit also passed the
+restart-mode floors (and ran cheaper) — we published the retraction of our own
+earlier collapse claim when we found the meter defect behind it. What ADD uniquely
+adds is the *guarantees*: contracts that can't be silently edited, tests that
+can't be quietly weakened, security findings that can't scroll past.
+
+That's the design, in three moves:
 
 - **One file per feature.** Spec, scenarios, contract, test-plan, and gate record
-  all live inline in a single `TASK.md`. No sprawling doc tree.
-- **State on disk, not in chat.** A Python tool tracks where you are in
+  all live inline in a single `PLAN.md`. No sprawling doc tree.
+- **State on disk, not in chat.** A stdlib-Python kernel tracks where you are in
   `.add/state.json`, so a fresh session resumes with one command instead of
-  re-reading the repo.
-- **Progressive disclosure.** The skill loads only the guide for the phase you are
-  in — the context window stays lean.
+  re-reading the repo — and instead of trusting a long conversation's memory.
+- **Progressive disclosure.** The skill narrates the whole loop itself and loads a
+  deeper phase reference only when the beat needs it — the context window stays
+  lean.
 
 ## Where ADD fits vs. skill libraries (e.g. agency-agents)
 
-ADD is an **orchestration method** — the gated loop (spec → scenarios → contract → tests → build →
-verify → observe) that decides when work is trusted. It is not a catalog of ready-made expert
-personas. Skill libraries like [agency-agents](https://github.com/msitarzewski/agency-agents), or
+ADD is the **trust layer** — the gated loop (Direction → Build → Verify)
+that decides when work is trusted, and the on-disk memory it runs on. It is not a
+catalog of ready-made expert personas. Skill libraries like [agency-agents](https://github.com/msitarzewski/agency-agents), or
 role-specific subagents (a backend expert, a security reviewer, a senior Java engineer), sit at a
 different layer: they answer **who does the work** — a domain stance, vocabulary, and craft rules
 for one kind of task. ADD answers **how you trust what gets built**, no matter who or what wrote it.
@@ -75,23 +119,26 @@ never a runtime dependency — down to the three parts a project actually needs:
 stance), **Critical Rules** (the non-negotiables), and **Success Metrics** (the done-bar). The
 project then owns that persona outright.
 
-A distilled persona is applied as an **advisory overlay** during design, build, or verify — it
+A distilled persona is applied as an **advisory overlay** during direction, build, or verify — it
 shapes *how* a step gets done, never whether it happens: it can't skip a gate, edit a frozen
-contract, or wave through a security finding. That gated loop is what ADD contributes underneath
-any persona, distilled or not.
+contract, or wave through a security finding. In 2.0 personas also carry **task-kinds** and
+propose each task's route (full walk · fast lane · inline); the freeze ratifies the route, the
+gate traces the outcome, and `add.py deltas` rolls the traces into a per-lane scoreboard the
+loop reflects on (GEPA). That gated loop is what ADD contributes underneath any persona,
+distilled or not.
 
 ## Best setup: ADD alongside other agent libraries
 
 1. **Install ADD** (below) — it drives the loop: which phase you're in, what needs your approval,
    whether something is proven.
-2. **Keep whatever subagent libraries you already use.** ADD's own five phase specialists
-   (`add-design`, `add-build`, `add-verify`, `add-persona`, `add-advisor`) live in the same
-   `.claude/agents/` mechanism as any other Claude Code subagent — a distilled persona, an
-   agency-agents-derived specialist, a built-in one (a backend expert, a security reviewer). They
-   coexist with zero conflict; nothing is replaced.
-3. **Prefer ADD's named roster first for anything phase-shaped** — spawning `add-verify` for the
-   independent adversarial refute-read, `add-build` for a red→green batch — before an ad-hoc spawn.
-   Reach for another specialist when a piece needs deep domain expertise a generic phase agent
+2. **Keep whatever subagent libraries you already use.** ADD ships ONE `add` agent in the same
+   `.claude/agents/` mechanism as any other Claude Code subagent — the spawn names the mode
+   (direction · build · verify · advise · persona) and the agent loads that beat's guide plus the
+   best-fit persona. It coexists with a distilled persona, an agency-agents-derived specialist,
+   or a built-in expert with zero conflict; nothing is replaced.
+3. **Prefer the `add` agent for anything phase-shaped** — spawn it in verify mode for the
+   independent adversarial refute-read, in build mode for a red→green batch — before an ad-hoc
+   spawn. Reach for another specialist when a piece needs deep domain expertise the phase guide
    doesn't carry (a Java-specific review, a payments-domain lens).
 4. **The gates hold no matter who did the work.** A delegated subagent proposes; the orchestrating
    agent records. A security finding is always a `HARD-STOP`, and a low self-reported confidence
@@ -99,7 +146,7 @@ any persona, distilled or not.
 
 ## Install
 
-Pick your ecosystem — all three install the same skill, tooling, and book:
+Pick your ecosystem — all three install the same skill and tooling:
 
 ```bash
 # Node / npm
@@ -118,8 +165,8 @@ pilotspace-add init
 /plugin install add@add-method
 ```
 
-The plugin carries the engine and the book. On first `/add`, the skill materializes them
-into the project (`node "${CLAUDE_PLUGIN_ROOT}/bin/cli.js" init --no-skill`) and scaffolds
+The plugin carries the engine. On first `/add`, the skill materializes it into the
+project (`node "${CLAUDE_PLUGIN_ROOT}/bin/cli.js" init --no-skill`) and scaffolds
 `.add/` — a self-contained, portable result identical to the npm/pip flow. The skill stays
 in the plugin, so nothing is duplicated.
 
@@ -128,9 +175,12 @@ defaults to `prototype` (pass `--name "My App" --stage mvp` to choose up front).
 
 **Already installed?** Refresh to the latest without a re-install —
 `npx @pilotspace/add@latest update` (or `pipx run pilotspace-add update`)
-re-materializes the skill, tooling, and book while leaving your project work
+re-materializes the skill and tooling while leaving your project work
 (`.add/state.json`, `PROJECT.md`, milestones, tasks) untouched; add `--check` to
-see whether a project is behind the installed package.
+see whether a project is behind the installed package. Coming from 1.x? One
+command — `python3 .add/tooling/add.py migrate` — converts the whole board
+(task docs to `PLAN.md`, living 5-DD specs seeded); it's idempotent and refuses
+to guess on conflicts.
 
 **New here?** Follow the [10-minute Quickstart](./GETTING-STARTED.md) — it walks
 your first feature end to end.
@@ -139,11 +189,15 @@ This installs:
 
 | Path | What |
 |------|------|
-| `.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 method rationale |
+| `.claude/skills/add/` | the `add` skill Claude loads — the loop itself, plus three on-demand phase references |
+| `.add/tooling/add.py` | the state kernel — scaffolder + tracker, 31 verbs (Python, stdlib only) |
+| `.add/personas-teacher/` | the vendored teacher corpus personas are distilled from (off-build reading, never runtime) |
 | `.add/DESIGN.md` | (UI projects) the prose front-door to the **render-ready UDD foundation** — delete it if your project has no UI |
 
+The AIDD book itself no longer installs into projects — it lives online at
+[pilotspace.github.io/ADD](https://pilotspace.github.io/ADD/), and the engine
+deep-links the exact chapter whenever a gate or guide cites its rationale.
+
 On a UI project, UDD gives the AI a frozen design ground to draft from: `DESIGN.md`
 plus a lintable JSON foundation under `.add/design/` (design tokens · component
 catalog · prototype trees). `add.py check` lints that foundation, going red with a
@@ -165,9 +219,9 @@ exactly what that means, so there are no surprises:
 - **What it runs:** the bundled engine and bootstrapper only — `node bin/cli.js` and
   `python3 .add/tooling/add.py`. No downloaded or remote code is executed; everything it
   runs ships in the package.
-- **What it writes:** files under your project's `.add/` (state, milestones, tasks, the
-  book) and the managed guideline block in `CLAUDE.md` / `AGENTS.md`. On a plugin install
-  it also materializes the engine + book into `.add/` on first run. It writes nowhere
+- **What it writes:** files under your project's `.add/` (state, milestones, tasks) and
+  the managed guideline block in `CLAUDE.md` / `AGENTS.md`. On a plugin install
+  it also materializes the engine into `.add/` on first run. It writes nowhere
   outside the project working directory; it never touches files above the project root.
 - **Network:** one optional, advisory update check. On `status` / `guide` the engine may
   make a single HTTPS GET to `https://registry.npmjs.org/@pilotspace/add/latest` to see if
@@ -192,9 +246,9 @@ the `/add` skill natively; every other agent follows the same loop through the
 phase guides via `add.py status` / `guide`.
 
 The agent orients from `state.json`, **sizes your request into a milestone** (you
-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
+confirm the shape), then drafts each task's **specification bundle** — Spec +
+Scenarios + Contract + Tests as one Direction pass — 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.
 
 Under the hood the agent runs the CLI as its hands — and you can hand-drive it too:
@@ -218,19 +272,37 @@ python3 .add/tooling/add.py status      # where am I? (resume point)
 
 The durable asset is the decisions — spec, scenarios, contract, tests. The code is
 one implementation that satisfies them and can be regenerated. If the thing you'd
-be upset to lose is "the code," you're still working the old way.
+be upset to lose is "the code," you're still working the old way. This is also the
+anti-context-rot stance in one sentence: the artifacts on disk, not the
+conversation, are the project's memory.
 
 ## Read the method
 
-Start at [`docs/README.md`](./docs/README.md) — Foundations → the six steps →
+Start at [the book](https://pilotspace.github.io/ADD/) — Foundations → the loop →
 operating it across a team → templates, prompts, and a full worked example.
 
-## What's next
-
-**Dynamic Agent Skills** — the next scope: skills that adapt at runtime to the
-project's current state, stage, and active phase rather than loading a static
-guide. The agent picks the right depth and tooling automatically as the project
-evolves.
+More entry points:
+
+- 📖 [Read the book online](https://pilotspace.github.io/ADD/) — the full AIDD method, chapter by chapter
+- 🔍 [Full hands-on walkthrough](./GETTING-STARTED.md) — one real feature, end to end
+- 📊 [Benchmark results](https://github.com/pilotspace/ADD/tree/main/benchmark/results) — every trust and cost claim, measured
+- ⚖️ [ADD vs spec-kit — the honest comparison](https://pilotspace.github.io/ADD/appendix-h-add-vs-spec-kit/) — where we tie, where they win, what only ADD guarantees
+- 🗞️ [ADD Across the Org: AI-Driven Development Beyond Code](https://inkpaper-blog.pages.dev/series/add-across-the-org/)
+
+## What's new in 2.0
+
+- **Skill-led loop on a thin kernel** — the skill narrates Direction → Build →
+  Verify; `add.py` shrinks to a 31-verb state kernel (54 → 31).
+- **`PLAN.md` + one-shot `migrate`** — the per-task file is the plan; a whole 1.x
+  board converts with one idempotent command.
+- **Five living 5-DD specs with `delta-append`** — the project's evolving truth,
+  compacted forward instead of rewritten.
+- **Persona routes + the GEPA scoreboard** — personas propose lanes, gates trace
+  outcomes, `deltas` shows the per-lane record, and the loop reflects on it.
+- **The book stops shipping** — published online only, deep-linked from the engine.
+- **Measured**: every trust floor 1.0 across the 3-milestone benchmark at $2.20 per
+  trusted milestone; plus a new `--session-mode continue` harness that measures
+  context rot itself.
 
 ## Develop