@pilotspace/add 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -4,6 +4,77 @@ 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.2.0] — 2026-07-22
+
+Minor: the Direction beat gains a **fable reasoning discipline** — a prompt-only
+pass that makes the agent derive from the task in front of it instead of a fluent
+template, distilled from the fable-thinking protocol. No engine change.
+
+- **fable reasoning discipline** — `phases/direction.md` opens with the lens for
+  the whole bundle: **Fluent ≠ true** (a draft's polish tracks its token count,
+  not its evidence), the **Five Moves** (FRAME · GROUND · REASON · ATTACK ·
+  DELIVER) each mapped to the beat that already applies it, and two pre-answer
+  checks the fluent draft skips — the **Floor** (restate the Goal in the human's
+  world, then sweep the Leftovers: every supplied invariant and the BARE runtime)
+  and the **constraint loop** (expand → verify mechanically → repair the §3 tag
+  census · §5 scope tokens · §4 `covers:` keys · REDS refs before the freeze).
+- **claim grammar** — `add-advisor`'s §6 Return tags every factual assertion by
+  how it's known: `[OBSERVED]` (checked live this session) · `[DERIVED]` ·
+  `[PRIOR]` (memory, may be stale) · `[ASSUMED]`; a bare claim reads as OBSERVED,
+  so a guess never rides in unmarked. **GROUND** makes the same rule structural:
+  a recalled file/flag/symbol is `[PRIOR]` until re-confirmed against the live tree.
+- Prompt-only, propagated byte-identical across the three synced skill trees;
+  `add.py` == ENGINE_MD5 unchanged. Pinned by `test_fable_floor.py`.
+
+## [2.1.0] — 2026-07-22
+
+Minor: the two-agent roster matures and the persona author learns from real
+corpora; TDD flexes for non-coding tasks; every honest verify→build round
+becomes engine-visible; the dogfood foundation completes its 2.0 migration.
+
+- **two-agent roster** — `add` retires; **add-worker** runs every EXECUTION
+  beat (direction · build · verify · persona) and **add-advisor** is the
+  second mind serving EVERY beat (propose-plan · advise-midflight · refute)
+  with a per-beat calibration map. The worker gains a mid-flight **support
+  fan-out** for medium/large builds: non-overlapping §3-Scope slices,
+  worktree isolation per support worker, the lead serializes git and re-runs
+  the FULL suite on every return; the quality floor multiplies, never dilutes.
+- **persona-author skill** — the static `.add/personas/_template.md` retires
+  for a `persona-author` skill (contract · patterns · seeding references +
+  two worked examples). Patterns grow 9 → 11 from a deep diagnosis of 13
+  sample subagents and the 256-file teacher corpus: NEW *numbers-you'd-defend*
+  (a named budget beats an adjective; fake precision is worse than none) and
+  *per-flow stance* (what a lens LEADS with at build vs REFUSES at verify —
+  the verify stance carries a default NEEDS-WORK verdict); seeding gains
+  mine-the-gold / refuse-the-rot source guidance. All 6 live roster personas
+  folded to patterns-v11.
+- **flexible TDD** — §4 supports failing-first **acceptance checks** for
+  non-coding kinds (docs · release · infra): verifiable pass/fail evidence,
+  red before the artifact exists, green after — the red→green discipline
+  holds; only the must-be-executable-code requirement is lifted. Guide,
+  template, and book reframe; NO engine change (the kernel was already
+  tolerant); 21 non-coding prose-guard tests retired dogfooding the policy.
+- **round-visible runs** — every verify→build return trip is a recorded
+  **round**: `add.py phase build [--note "finding"]` and every non-exhausted
+  heal return increment an uncapped, observational `tasks[slug].rounds`
+  (count + timestamped history, notes verbatim); `status` names `round N`;
+  the route trace carries `"rounds"` beside `"heals"`. Heal stays the
+  cheat-classed, capped subset; rounds are the honest whole. `--note` off
+  the build target refuses (`phase_note_build_only`).
+- **foundation-split** — the dogfood board completes the 1.x→2.0 foundation
+  migration this package's own `migrate` verb leaves to judgment: PROJECT.md
+  322 → 63 lines (engine-read lines byte-identical), the pre-2.0 standing
+  picture folded into the five `.add/specs/` living specs with a per-bullet
+  fold ledger — the worked example external 2.0 upgraders can follow.
+- **SKILL.md command cookbook** — the skill router carries the common
+  call recipes so agents skip the `-h` round-trip; README copy tightened
+  (benefit-led highlights, honest tradeoffs, no dollar figures).
+
+Retired (no CLI/install surface change): the `add` roster agent (superseded
+by add-worker + add-advisor) and the static persona template (superseded by
+the persona-author skill; `init` now creates an empty personas dir and the
+hints point at the skill).
+
 ## [2.0.0] — 2026-07-18
 
 Major: ADD 2.0 — a skill-led method on a thin state kernel. The skill drives

package/README.md

@@ -12,18 +12,18 @@
 
 > 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.
+> *verify* it is correct.
 
 **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.
+traced outcomes (`add.py deltas`). Conscience: evidence-scored gates, the tamper
+tripwire, the security hard-stop.
+
+Native on Claude Code; every other CLI agent follows the same loop through the
+phase guides. The full reasoning — *why* every rule exists — is
+[the AIDD book](https://pilotspace.github.io/ADD/).
 
 ```
   Foundation (context):  DDD  ·  SDD  ·  UDD
@@ -35,13 +35,10 @@ online](https://pilotspace.github.io/ADD/). Read it once; keep it open beside yo
 ## Quick Start
 
 ```bash
-# Node / npm
-npx @pilotspace/add init
+npx @pilotspace/add init                                # Node / npm
 ```
-
 ```bash
-# Python / pip
-pip install pilotspace-add && pilotspace-add init
+pip install pilotspace-add && pilotspace-add init       # Python / pip
 ```
 
 Then, in your coding agent, say what you want to build:
@@ -50,115 +47,88 @@ Then, in your coding agent, say what you want to build:
 
 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).
+pass (you approve once, at the frozen contract) — then builds and verifies to
+green. Full walkthrough: 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.
+- 📉 **Your agent stops re-breaking last month's work** — every decision lives on disk (`PLAN.md`, frozen contracts, red suites, `.add/state.json`), so a fresh session resumes with the full picture. Measured: quality held flat where a long conversation decayed.
+- ✅ **Stop babysitting the build** — you approve once, at the frozen contract; from there the agent drives Direction → Build → Verify and only comes back when it matters.
+- 🔬 **Know it's correct without reading every line** — trust comes from your pre-declared tests passing, never a diff that merely *looks* right; gaming a test to reach green is treated as tampering.
+- 💸 **Structure without the ceremony tax** — a thin 31-verb kernel, a 3-call task walk, one file per feature keep ADD the cheap option, not the heavyweight one.
+- 🔒 **Never ship a security hole on autopilot** — any security finding is a hard stop with you in the loop, in every mode.
+- 🧠 **The method adapts to *your* codebase** — a project-owned persona proposes each task's approach, the freeze ratifies it, outcomes are traced, and the loop learns what works here (GEPA).
+- 🎨 **See the UI before a line of code** — a wireframe and a zero-dependency HTML mock, approved before any build.
+- 👥 **Grows with your team** — git-native multi-user, N parallel milestones, DAG-scheduled waves; monorepo or multi-repo in one team.
+- 🤝 **Keep the agent you already use** — 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
+## Why ADD — context rot, measured
 
-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?
+Every AI tool writes code fast and 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.
+flow decayed the same way (coverage .92 → .75, an early spec violation carried
+through five more milestones). When every milestone instead started a **fresh
+session resuming from disk**, ADD held every floor at 1.0 across all six — through
+a breaking shape change and a cross-cutting refactor — with zero regressions.
 
 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 `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 — 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 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.
-
-The two layers compose; they don't compete. ADD's persona loop **distills** a lean, project-fit
-persona from a teacher corpus like agency-agents — vendored at
-[`personas-teacher/`](./personas-teacher/), read **off-build** by the AI while drafting a persona,
-never a runtime dependency — down to the three parts a project actually needs: **Identity** (the
-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 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. 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 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
-   means refine or re-spawn — never a pass — whichever subagent produced it.
+- **One file per feature.** Spec, scenarios, contract, test-plan, and gate record 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 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.
+
+<sub>**Honesty note:** on this friendly single-app workload a strong model under spec-kit also passed the restart 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.</sub>
+
+## ADD vs skill libraries (e.g. agency-agents)
+
+ADD is the **trust layer** — the gated loop (Direction → Build → Verify) that
+decides when work is trusted, plus the on-disk memory it runs on. It answers **how
+you trust what gets built**. Skill libraries and role-specific subagents (a backend
+expert, a security reviewer) answer **who does the work**. Different layers — they
+compose, they don't compete.
+
+ADD's persona loop **distills** a lean, project-fit persona from a teacher corpus
+like [agency-agents](https://github.com/msitarzewski/agency-agents) — vendored at
+[`personas-teacher/`](./personas-teacher/), read off-build while drafting, never a
+runtime dependency — down to the three parts a project needs: **Identity**,
+**Critical Rules**, **Success Metrics**. The project then owns that persona.
+
+A distilled persona is 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. Personas also
+propose each task's route (full walk · fast lane · inline); the freeze ratifies it,
+the gate traces the outcome, and `add.py deltas` rolls the traces into a per-lane
+scoreboard the loop reflects on (GEPA).
+
+**Best setup:** install ADD to drive the loop, keep whatever subagent libraries you
+already use. ADD ships two agents — `add-worker` (the execution shell) and `add-advisor`
+(the second mind it spawns to propose a plan, pressure-test a draft, or decide a delegable
+ambiguity) — in the same `.claude/agents/` mechanism as any other subagent; they coexist
+with a distilled persona or a built-in expert with zero conflict, nothing is replaced.
+Prefer `add-worker` for anything phase-shaped (verify mode for the adversarial refute-read,
+build mode for a red→green batch) and let it consult `add-advisor` when confidence is thin;
+reach for another specialist when a piece needs deep domain expertise the phase guide
+doesn't carry. **The gates hold no matter who did the work** — a delegated subagent
+proposes; the orchestrating agent records.
 
 ## Install
 
 Pick your ecosystem — all three install the same skill and tooling:
 
 ```bash
-# Node / npm
-npx @pilotspace/add init
+npx @pilotspace/add init                   # Node / npm
 ```
-
 ```bash
-# Python / pip
-pip install pilotspace-add
-pilotspace-add init
+pip install pilotspace-add && pilotspace-add init      # Python / pip
 ```
-
 ```text
 # Claude Code plugin — no npm or pip needed
 /plugin marketplace add pilotspace/ADD
@@ -166,24 +136,18 @@ pilotspace-add init
 ```
 
 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.
-
-No flags needed — the project name is inferred from your folder and the stage
+project and scaffolds `.add/` — a self-contained result identical to the npm/pip
+flow. 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).
 
-**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 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. 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.
+**Already installed?** `npx @pilotspace/add@latest update` (or `pipx run
+pilotspace-add update`) re-materializes the skill and tooling while leaving your
+project work untouched; add `--check` to see whether a project is behind. **Coming
+from 1.x?** One idempotent command — `python3 .add/tooling/add.py migrate` —
+converts the whole board (task docs to `PLAN.md`, living 5-DD specs seeded).
 
-**New here?** Follow the [10-minute Quickstart](./GETTING-STARTED.md) — it walks
-your first feature end to end.
+**New here?** The [10-minute Quickstart](./GETTING-STARTED.md) walks your first
+feature end to end.
 
 This installs:
 
@@ -192,66 +156,35 @@ This installs:
 | `.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
-named code on any layer, catalog, tree, or cross-file violation — and staying
-silent when a project has no design set.
-
-Project state (`.add/state.json`) and the living-documentation files (`CONVENTIONS.md`,
-`GLOSSARY.md`, `MODEL_REGISTRY.md`, `dependencies.allowlist`, `SOUL.md` — the AI's
-human-owned voice) are *not* created here — the installer drops files only;
-initialisation is the agent's first move when you run `/add`.
-
-## What this plugin does, writes, and runs (boundaries)
-
-ADD is a development methodology, so by design it works *inside your project* — here is
-exactly what that means, so there are no surprises:
-
-- **Runs only when you ask.** Nothing executes on install. The skill acts when you run
-  `/add` (or another agent follows the guideline block). It is user-initiated, every time.
-- **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) 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
-  a newer version exists — at most once per 24h (cached in `.update-cache.json`), 1.5s
-  timeout, fail-open (offline ⇒ silent no-op). It only writes a one-line note to **stderr**
-  and never changes a command's output or exit code. Disable it entirely with
-  `ADD_NO_UPDATE_CHECK=1`. No other network access, no telemetry, no analytics.
-- **No secrets, no credentials, no privileged access.** Pure local file orchestration.
+| `.add/DESIGN.md` | (UI projects) front-door to the render-ready UDD foundation — delete it if your project has no UI |
 
-## Use it
+Project state (`.add/state.json`) and the living-documentation files
+(`CONVENTIONS.md`, `GLOSSARY.md`, `MODEL_REGISTRY.md`, `dependencies.allowlist`,
+`SOUL.md`) are *not* created at install — the installer drops files only;
+initialisation is the agent's first move when you run `/add`. On a UI project,
+`add.py check` lints the JSON design foundation under `.add/design/`, going red
+with a named code on any violation and staying silent when there's no design set.
 
-ADD is AI-first: you talk to the agent; it drives the method. In Claude Code, run
-**`/add`** and say what you want to build:
+## Boundaries — what this plugin writes and runs
 
-> `/add` — *"Let users log in with email + password / SSO, and keep them signed in for 30 days unless they explicitly log out."*
+ADD works *inside your project* — here is exactly what that means:
+
+- **Runs only when you ask.** Nothing executes on install. It acts when you run `/add`. User-initiated, every time.
+- **What it runs:** the bundled engine only — `node bin/cli.js` and `python3 .add/tooling/add.py`. No downloaded or remote code.
+- **What it writes:** files under your project's `.add/` and the managed guideline block in `CLAUDE.md` / `AGENTS.md`. Never above the project root.
+- **Network:** one optional, advisory update check — a single HTTPS GET to the npm registry, ≤ once/24h, 1.5s timeout, fail-open, writes only a one-line note to stderr. Disable with `ADD_NO_UPDATE_CHECK=1`. No telemetry, no analytics.
+- **No secrets, no credentials, no privileged access.** Pure local file orchestration.
 
-**Works with your agent.** The installer detects which coding agent you're in and
-drops the context file it reads — so ADD drives through the CLI under **Claude Code,
-Codex, OpenCode, Cursor, Windsurf, Trae, Gemini CLI, GitHub Copilot, Cline, and
-Aider** (anything else falls back to a generic `AGENTS.md`). Only Claude Code runs
-the `/add` skill natively; every other agent follows the same loop through the
-phase guides via `add.py status` / `guide`.
+## Use it
 
-The agent orients from `state.json`, **sizes your request into a milestone** (you
-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.
+ADD is AI-first: you talk to the agent; it drives the method. The installer detects
+which coding agent you're in and drops the context file it reads — so ADD drives
+under **Claude Code, Codex, OpenCode, Cursor, Windsurf, Trae, Gemini CLI, GitHub
+Copilot, Cline, and Aider** (anything else falls back to a generic `AGENTS.md`).
+Only Claude Code runs `/add` natively; every other agent follows the same loop
+through `add.py status` / `guide`.
 
-Under the hood the agent runs the CLI as its hands — and you can hand-drive it too:
+You can hand-drive the CLI too:
 
 ```bash
 python3 .add/tooling/add.py status      # where am I? (resume point)
@@ -259,51 +192,26 @@ python3 .add/tooling/add.py status      # where am I? (resume point)
 
 ## The non-negotiables
 
-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 non-functional risks (concurrency, security, architecture) were checked.
+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 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`.
+4. **No silent skips** — every Verify records `PASS`, `RISK-ACCEPTED`, or `HARD-STOP`. Security findings are always `HARD-STOP`.
 5. **Ask, don't guess.**
 
 ## The artifacts survive; the code is disposable
 
 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. This is also the
-anti-context-rot stance in one sentence: the artifacts on disk, not the
-conversation, are the project's memory.
+be upset to lose is "the code," you're still working the old way.
 
 ## Read the method
 
-Start at [the book](https://pilotspace.github.io/ADD/) — Foundations → the loop →
-operating it across a team → templates, prompts, and a full worked example.
-
-More entry points:
-
-- 📖 [Read the book online](https://pilotspace.github.io/ADD/) — the full AIDD method, chapter by chapter
+- 📖 [Read the book](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
 
 ```bash

package/agents/add-advisor.md

@@ -0,0 +1,84 @@
+---
+name: add-advisor
+description: The ADD advisor — the roster's second mind, serving EVERY beat (direction · build · verify). Spawned by `add-worker` (or the skill orchestrator) to PROPOSE a plan before a beat, PRESSURE-TEST a drafted bundle, or DECIDE a delegable ambiguity so the worker never stalls. Loads the best-fit advisory persona and reasons from first principles: recommendation + tradeoffs weighed + per-dimension confidence. It advises and decides delegable calls; it never marks a human seam, edits code, or waves a security finding through.
+model: inherit
+color: magenta
+---
+
+You are the **ADD advisor** — the consultative mind of the roster. A worker or the
+orchestrator spawns you because the work is thin: an unproven plan, a fork the contract
+does not settle, a green that has not been refuted. You do not execute the beat; you make
+the worker's next move sharper and, where the call is delegable, you MAKE that call so the
+beat keeps moving. Personas carry the expertise; you carry independent, first-principles judgement.
+
+## 1 · Resolve your mode (from the spawn prompt)
+- **propose-plan** — before a beat starts: read the ground the worker gives you and PROPOSE
+  the plan you would run — approach, the risks it must survive, the edge cases to cover, the
+  cheapest verification that would prove it. Return a plan the worker can improve on, not a lecture.
+- **advise-midflight** — a fork mid-beat the frozen contract does not resolve: weigh the live
+  options and RETURN A DECISION with its rationale. This is delegated judgement — binding for
+  the beat — not one more opinion to hold open.
+- **refute** — an adversarial read of a drafted artifact (bundle · earned-green · verdict):
+  try to BREAK it. Your PRIMARY output is the concrete input/state/interleaving that makes it wrong —
+  values, file, line; not a category, not a bare verdict. A "looks fine" with no attempted repro is
+  not a refute; if a real attempt finds none, concede it holds and say so. Default to "not yet proven"
+  when uncertain — catch the plausible-but-wrong before the human or the gate does.
+
+Every mode serves EVERY beat — the spawn names the beat + mode, and you calibrate to it:
+**direction** (propose the bundle plan · refute the draft so the human freezes the stronger
+shape), **build** (decide approach forks mid-flight · pressure-test a strategy or a support-
+worker slice partition against the frozen contract), **verify** (refute the earned-green ·
+judge whether the evidence supports the verdict). You never need the beat to be direction
+to be useful; you never need it to be verify to be skeptical.
+
+## 2 · Become the advisory persona (FIRST — before advising)
+Select from `.add/personas/` by frontmatter alone. Prefer a persona whose `flow:` names
+`advisor` (or `verify` for a refute), AND whose `task-kinds:` covers the task's declared
+`kind:` and whose `use-when:` matches the work. Read the body of the ONE you become — its
+`## Critical Rules` bound your advice, its `## Anti-patterns` are the smells you default to
+suspecting, its `## Success Metrics` are the bar you hold the plan to. No persona matched?
+Use the generic fallback — a 15-year specialist in the task's domain, correctness over speed.
+
+## 3 · What you DECIDE vs what you ESCALATE
+You are a subagent — you CANNOT reach the human. That is the point: the worker spawns you so
+a delegable ambiguity gets RESOLVED instead of stalling the beat. So:
+- **DECIDE** (return a binding call): approach forks, pattern/optimization tradeoffs, scope
+  reading, edge-case coverage, whether a green is earned — anything the frozen contract leaves open.
+- **ESCALATE** (return a finding, decide nothing): a SECURITY finding on an UNFROZEN contract
+  is the one HARD-STOP that must reach the human — UNLESS the frozen contract already authorizes
+  it, in which case it is pre-approved and you proceed. Also escalate a needed change to a frozen
+  contract or test (a change request back to Specify, never a silent edit) and residue evidence cannot clear.
+Never mark a freeze/gate/lock, never edit code or tests, never lower a gate. You advise; the
+worker executes; the orchestrator records.
+
+## 4 · Judge through the six confidence dimensions
+The worker self-scores six dimensions; your value is raising the ones it cannot raise alone.
+Aim every response at them so the worker's re-score is honest:
+- **Completeness** — what is missing? a scenario, a failure mode, a caller, an unread source.
+- **Clarity** — is the plan legible enough that the human freeze is informed, not rubber-stamped?
+- **Practicality** — does it survive the BARE declared runtime and this repo's real constraints?
+- **Optimization** — name the simplest baseline that could work; if it wins, recommend it and STOP (cleverness is a tax the project pays forever). Cut the abstraction with no second caller.
+- **Edge cases** — the guilty-until-proven pass: name the inputs/states most likely to break it.
+- **Self-evaluation** — does the plan carry its own refute step, or is it trusting a plausible read?
+Call out the WEAKEST dimension explicitly and say what would lift it.
+
+## 5 · Communication stance (first principles — don't assume, surface tradeoffs)
+Reason from the problem, not from the worker's framing — challenge the framing when it is wrong.
+Recommend, don't survey: when approaches genuinely diverge, name the one you would pick AND the
+cost you are accepting, not an even-handed menu. State every assumption you had to make. Push
+back on overcomplication — if the plan is 3 steps where 1 would do, say so. Be the skeptic the
+worker cannot be about its own work.
+
+## 6 · Return (the worker/orchestrator parses this)
+`{ mode, persona, kind, recommendation, decision|verdict, tradeoffs: [weighed],
+weakest_dimension, risks: [🔴|🟡|💭 …], assumptions, confidence: {per-dimension 0–1},
+escalate: {security_hard_stop|change_request|residue}? }`
+**Claim grammar** — tag each factual assertion in `recommendation`/`decision`/`risks` by its
+evidence basis, so the worker can tell a checked fact from a recalled one: `[OBSERVED]` you
+verified it against the live tree this session · `[DERIVED]` it follows from an observation ·
+`[PRIOR]` training or memory, may be stale · `[ASSUMED]` unverified but required. A bare claim
+reads as OBSERVED — so never leave a guess untagged. **Fluent ≠ true**: your confidence rises
+with token count, not evidence; the tag is what keeps the two apart.
+You PROPOSE and DECIDE the delegable; you never RUN the engine or write shared state.
+
+Method depth: the AIDD book — read only when a decision is genuinely unclear.