@pilotspace/add 1.17.0 → 2.1.0

package/bin/cli.js

@@ -6,10 +6,9 @@
  *
  *   npx @pilotspace/add init [targetDir] [--force] [--stage <stage>] [--name <name>] [--yes|--non-interactive]
  *
- * Installs the ADD skill + tooling + book into a target project:
+ * Installs the ADD skill + tooling into a target project:
  *   <target>/.claude/skills/add/   (the skill Claude loads)
  *   <target>/.add/tooling/         (add.py scaffolder + state tracker)
- *   <target>/.add/docs/            (the AIDD book — the trust layer)
  * It DROPS FILES ONLY — it does NOT run `add.py init`. Initialisation is deferred to
  * the AI (via `/add`, which runs `init --await-lock` to arm the v12 lock-down gate) or
  * to a CLI user. A pre-run plain init would grandfather-lock the gate before `/add` runs
@@ -58,9 +57,9 @@ function parseArgs(argv) {
     // non-interactive selector the interactive() gate honors (CI/pipes do this too).
     else if (a === "--yes" || a === "-y") args.yes = true;
     else if (a === "--non-interactive") args.nonInteractive = true;
-    // --no-skill: drop the engine + book ONLY, not the skill. The Claude Code plugin
+    // --no-skill: drop the engine ONLY, not the skill. The Claude Code plugin
     // already provides the `add` skill, so a plugin bootstrap uses this to materialize
-    // .add/tooling/ + .add/docs/ into the project without a duplicate .claude/skills/add.
+    // .add/tooling/ into the project without a duplicate .claude/skills/add.
     else if (a === "--no-skill") args.noSkill = true;
     // --rule-file: write the ADD block to .claude/rules/add-workflows.md + reference it from
     // CLAUDE.md instead of inlining (auto-on for ccsk projects with a .ccsk/ dir).
@@ -217,7 +216,7 @@ function agentPointerBlock(profile) {
     GUIDE_BEGIN + "\n" +
     "## ADD — how to work in this repo\n" +
     "\n" +
-    "This project uses **ADD (AI-Driven Development)**. The engine + book are installed.\n" +
+    "This project uses **ADD (AI-Driven Development)**. The engine is installed.\n" +
     "To begin: run `python3 .add/tooling/add.py status` (the resume point), read\n" +
     "`.add/PROJECT.md`, then `python3 .add/tooling/add.py guide` for the current phase.\n" +
     "\n" +
@@ -410,10 +409,11 @@ async function loadClack() {
 // --- brand + feature showcase (interactive path only; fail-soft) -------------
 // Wordmark + value line + the 7-step Specify->Observe loop, rendered BEFORE the first
 // prompt on the interactive path only — so the non-interactive byte stream is unchanged.
-// The 7 labels are the real ADD phases (grounded in the method, never invented). Fail-soft:
-// any draw error is swallowed so a banner can never abort the install. No color is emitted
-// (default accent: none); the glyphs / tagline / accent are a SWAPPABLE content slot.
-const BRAND_LOOP = ["Specify", "Scenarios", "Contract", "Tests", "Build", "Verify", "Observe"];
+// The 7 labels are the real ADD phases (grounded in the method, never invented; grounding
+// itself is folded into step 3, Plan, not a separate phase). Fail-soft: any draw error is
+// swallowed so a banner can never abort the install. No color is emitted (default accent:
+// none); the glyphs / tagline / accent are a SWAPPABLE content slot.
+const BRAND_LOOP = ["Specify", "Plan", "Tests", "Build", "Verify"];
 
 function terminalCaps(env, stream) {
   const width = Number(env.COLUMNS) || (stream && stream.columns) || 80;
@@ -481,7 +481,7 @@ async function runClackPreamble(clack, target, detected, askScope) {
     initialValue: target, defaultValue: target,
   });
   if (clack.isCancel(chosen)) return { cancelled: true, target: target };
-  const ok = await clack.confirm({ message: "Write the ADD skill + tooling + book here?" });
+  const ok = await clack.confirm({ message: "Write the ADD skill + tooling here?" });
   if (clack.isCancel(ok) || !ok) return { cancelled: true, target: target };
   // global-first SCOPE step (after the target confirm, before agent-detect) — recommended
   // global home, explicit pick; skipped when --global already chose. global stays ADDITIVE.
@@ -671,7 +671,7 @@ function dropFiles(args, target, profile, intent) {
   // NO step 4: the installer DROPS FILES ONLY. Initialisation is deferred to the AI
   // (via `/add`) or a CLI user — a pre-run plain `add.py init` would grandfather-lock
   // the v12 lock-down gate before `/add` runs (see file header). So no Python is run here.
-  log("\nDone. " + (args.noSkill ? "The engine + book are" : "The `add` skill + tooling are") +
+  log("\nDone. " + (args.noSkill ? "The engine is" : "The `add` skill + tooling are") +
       " installed (no project state yet — that's intentional).");
   if (profile.id === "generic") {
     // the generic onramp line — kept literal so the conversational-only handoff is stable
@@ -753,7 +753,6 @@ const MANAGED = [
   ["skill/add", [".claude", "skills", "add"], false],
   ["agents", [".claude", "agents"], false],
   ["tooling", [".add", "tooling"], true],
-  ["docs", [".add", "docs"], false],
   ["personas-teacher", [".add", "personas-teacher"], false],
 ];
 // Optional managed trees: an ENHANCEMENT the persona phase reads, not core runtime. The real
@@ -762,6 +761,20 @@ const MANAGED = [
 // _installer.py:OPTIONAL. Design-for-failure. `agents` joins here (roster-install-drift): the
 // phase-agent roster is a spawn-acceleration enhancement, not core runtime.
 const OPTIONAL = new Set(["personas-teacher", "agents"]);
+// SHARED-namespace managed trees (installer-shared-namespace-guard): destinations OTHER
+// TOOLS also write — `.claude/agents` holds the user's own Claude Code subagents. A
+// whole-dir clean-replace there sweeps the user's files as "orphans" (the reported
+// data-loss bug), so these trees route to sharedFileReplace: per-file atomic landings of
+// the shipped files + removal of ONLY the explicit tombstones below. Twin of
+// _installer.py:_SHARED / _RETIRED_AGENTS.
+const SHARED = new Set(["agents"]);
+// Roster names retired upstream — the ONLY names the shared lander may remove (never a
+// pattern/prefix heuristic: a USER file named add-anything.md must survive).
+// roster-distill (ADD 2.0 M1): the 5-agent roster collapsed into the ONE `add` agent.
+// advisor-split: that ONE `add` agent split into `add-worker` + `add-advisor`, so `add.md`
+// retires here and `add-advisor.md` leaves the list (it ships again; landing precedes removal).
+const RETIRED_AGENTS = ["add-design.md", "add-build.md", "add-verify.md",
+                        "add-persona.md", "add.md"];
 const STAMP_FILE = ".add-version";
 const LOCK_FILE = ".update.lock";   // the `update --global` home lock (never user-data)
 const LOCK_STALE_DEFAULT = 600;     // seconds (10 min); ADD_LOCK_STALE_SECONDS env-overridable
@@ -948,7 +961,7 @@ function cleanReplaceTree(src, dest, stripTests) {
   return { restored: restored, refreshed: refreshed };
 }
 
-const TREE_LABEL = { "skill/add": "skill", "agents": "agents", "tooling": "tooling", "docs": "docs", "personas-teacher": "personas" };
+const TREE_LABEL = { "skill/add": "skill", "agents": "agents", "tooling": "tooling", "personas-teacher": "personas" };
 
 // Per managed tree: "missing" (dest absent OR empty) or "present".
 function managedStatus(target) {
@@ -961,6 +974,36 @@ function managedStatus(target) {
   return status;
 }
 
+// installer-shared-namespace-guard: land a SHARED-namespace managed tree per FILE.
+// `.claude/agents` belongs to the user as much as to ADD — only the shipped files are
+// written (temp-sibling + atomic rename each, so a crash never leaves a torn file) and
+// only the explicit RETIRED_AGENTS tombstones are removed; every other destination file
+// is never opened. Returns the same { restored, refreshed } roll-up shape as
+// cleanReplaceTree so the reconcile reporting is agnostic. Mirror of
+// _installer.py:_shared_file_replace.
+function sharedFileReplace(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  let restored = 0, refreshed = 0;
+  const entries = fs.readdirSync(src).filter((n) => fs.statSync(path.join(src, n)).isFile()).sort();
+  for (const name of entries) {
+    const target = path.join(dest, name);
+    const existed = fs.existsSync(target);
+    const tmp = path.join(dest, name + ".add-tmp-" + Math.random().toString(36).slice(2, 10));
+    try {
+      fs.copyFileSync(path.join(src, name), tmp);
+      fs.renameSync(tmp, target);   // atomic overwrite (same directory)
+    } catch (e) {
+      fs.rmSync(tmp, { force: true });   // dest entry untouched or already whole
+      throw e;
+    }
+    if (existed) refreshed++; else restored++;
+  }
+  for (const name of RETIRED_AGENTS) {
+    fs.rmSync(path.join(dest, name), { force: true });   // absent tombstone — never fatal
+  }
+  return { restored: restored, refreshed: refreshed };
+}
+
 // reconcile: restore-missing + refresh-present (sweep orphans) across the managed trees,
 // reporting per-tree status. Honors --no-skill (the plugin provides the skill). Touches
 // ONLY managed trees — never user data. Prechecks ALL sources first (design-for-failure:
@@ -978,7 +1021,9 @@ function reconcile(args, target, srcRoot) {
   const status = managedStatus(target);
   let restored = 0, refreshed = 0;
   for (const [sub, destParts, stripTests] of trees) {
-    const roll = cleanReplaceTree(path.join(srcRoot, sub), path.join(target, ...destParts), stripTests);
+    const roll = SHARED.has(sub)
+      ? sharedFileReplace(path.join(srcRoot, sub), path.join(target, ...destParts))
+      : cleanReplaceTree(path.join(srcRoot, sub), path.join(target, ...destParts), stripTests);
     restored += roll.restored;
     refreshed += roll.refreshed;
     const dest = destParts.join("/");
@@ -992,7 +1037,7 @@ function reconcile(args, target, srcRoot) {
   return { restored: restored, refreshed: refreshed, trees: status };
 }
 
-// --- global home: an OPT-IN shared install (engine+book+skill) updated for all projects ----
+// --- global home: an OPT-IN shared install (engine+skill) updated for all projects ----
 // Resolution is PURE + total (never throws); the home MIRRORS the bundled managed layer so
 // `update --global` propagation reuses reconcile() unchanged. Mirror of _installer.py.
 function resolveGlobalHome(env) {
@@ -1034,12 +1079,14 @@ function writeRegistry(home, paths) {
   fs.renameSync(tmp, target);   // atomic on the same filesystem (POSIX + Windows)
 }
 
-// The home mirrors the bundled layout (skill/add + tooling + docs at the SAME relative paths
+// The home mirrors the bundled layout (skill/add + tooling at the SAME relative paths
 // the package ships) so reconcile(args, project, home) reuses MANAGED unchanged.
 const GLOBAL_TREES = [
   ["skill/add", ["skill", "add"], false],
+  // roster-drift fix: absent here, `update --global` propagation (sourced FROM the home)
+  // soft-skipped the roster forever — no refresh, no retired-agent tombstones.
+  ["agents", ["agents"], false],
   ["tooling", ["tooling"], true],
-  ["docs", ["docs"], false],
   ["personas-teacher", ["personas-teacher"], false],
 ];
 
@@ -1062,7 +1109,7 @@ function reconcileGlobal(home, claudeDir, noSkill) {
 // --- global DATA: an OPT-IN per-project user-data snapshot under <home>/data/<key> ----------
 // Strictly additive; copies ONLY user-data (managed trees + transient excluded), clean-replaced,
 // one-way (project->home). Mirror of _installer.py (identical key + include/exclude rule).
-const DATA_EXCLUDE = ["tooling", "docs", ".update-cache", STAMP_FILE, LOCK_FILE, PROJECT_LOCK_FILE];   // managed trees + meta + both locks
+const DATA_EXCLUDE = ["tooling", "docs", ".update-cache", STAMP_FILE, LOCK_FILE, PROJECT_LOCK_FILE];   // managed trees + meta + both locks ("docs" = legacy 1.x tree: still never user-data)
 
 // data_key twin: <sanitized-basename>-<sha1(abspath_utf8)[:12]>. Pure · total · separator-free.
 function dataKey(projectAbspath) {
@@ -1840,6 +1887,26 @@ function cmdUpdate(args) {
   log("ADD updated " + (cur || "(unstamped)") + " -> " + version +
       " · managed layer reconciled (" + roll.restored + " restored · " + roll.refreshed +
       " refreshed) · your project state untouched.");
+  // crossing nudges — engine-owned follow-ups the updater must NAME, never run (python3
+  // may be absent on this PATH; both commands are idempotent). Twin of _installer.py.
+  if (cur !== version) {
+    log("next: python3 .add/tooling/add.py sync-guidelines   # refresh the CLAUDE.md guidance block to this version");
+  }
+  const tasksDir = path.join(addDir, "tasks");
+  let legacyBoard = false;
+  if (fs.existsSync(tasksDir)) {
+    for (const entry of fs.readdirSync(tasksDir, { withFileTypes: true })) {
+      if (entry.isDirectory()
+          && fs.existsSync(path.join(tasksDir, entry.name, "TASK.md"))
+          && !fs.existsSync(path.join(tasksDir, entry.name, "PLAN.md"))) {
+        legacyBoard = true;
+        break;
+      }
+    }
+  }
+  if (legacyBoard) {
+    log("next: python3 .add/tooling/add.py migrate   # 1.x board detected: TASK.md -> PLAN.md, live + archived");
+  }
 }
 
 // js-reclaim-lock-heartbeat: a test-only entrypoint so the Python subprocess suite can drive
@@ -1888,13 +1955,13 @@ async function main() {
     case "help":
     case "--help":
       log("usage: npx @pilotspace/add <init|update|prune-data> [targetDir] [--force] [--check] [--no-skill] [--global] [--yes|--non-interactive]");
-      log("  init    install the ADD skill + tooling + book into a project");
-      log("          (--no-skill drops the engine + book only — used by the Claude Code plugin)");
+      log("  init    install the ADD skill + tooling into a project");
+      log("          (--no-skill drops the engine only — used by the Claude Code plugin)");
       log("          (--global ALSO installs to a shared home [ADD_HOME|XDG_DATA_HOME/add|~/.add] + registers the project)");
       log("          (--global-data implies --global + persists this project's user-data under <home>/data/<key>)");
       log("          (--from-global-data rehydrates this project's user-data FROM the shared home on a fresh clone)");
       log("          (interactive in a real terminal; --yes / --non-interactive force the plain path)");
-      log("  update  re-materialize skill/tooling/docs to this package version (preserves your state)");
+      log("  update  re-materialize skill/tooling to this package version (preserves your state)");
       log("          (--global refreshes the shared home + propagates to every registered project)");
       log("  prune-data  remove orphaned per-project snapshots from the shared home (dry-run; --force deletes)");
       break;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.17.0",
-  "description": "ADD (AI-Driven Development). One skill. Eight steps. Five disciplines. Every feature ships through the loop — a minimal, state-tracked Claude Code skill that ships the AIDD book as its trust layer.",
+  "version": "2.1.0",
+  "description": "ADD (AI-Driven Development) 2.0. The agent is the hands; ADD is the memory, judgment, and conscience — a minimal, state-tracked skill: one freeze per feature, trust from passing tests, state on disk so context rot never survives a new session.",
   "bin": {
     "add": "bin/cli.js"
   },
@@ -24,7 +24,6 @@
     "!tooling/add_engine/__pycache__",
     "!**/*.pyc",
     "tooling/templates/",
-    "docs/",
     "personas-teacher/",
     "THIRD_PARTY_NOTICES.md",
     "README.md",

package/personas-teacher/VENDOR.md

@@ -11,3 +11,9 @@ KEEP: the agent-definition domain folders (engineering, security, design, produc
 DROP: the upstream `.github/` CI, `scripts/`, other-tool `integrations/`, `CONTRIBUTING*`, `SECURITY.md`, and dotfiles.
 
 Content is RAW + verbatim — regenerate with `python3 add-method/scripts/update_teacher.py`. Attribution: see the repo-root `THIRD_PARTY_NOTICES.md` and the retained `LICENSE` in this folder (MIT).
+
+## Refresh-drift check (run on every refresh PR)
+
+Distilled personas keep `source:` provenance pointing into this snapshot. In the refresh PR
+description, list every `.add/personas/*.md` whose `source:` file(s) changed or moved in the
+diff — those personas are candidates for re-distillation, otherwise their provenance rots silently.

package/skill/add/SKILL.md

@@ -1,16 +1,13 @@
 ---
 name: add
 description: >-
-  ADD (AI-Driven Development) — a minimal, state-tracked workflow for building
-  software where the AI writes the code and the human owns direction and
-  verification. Drives every feature through one lean TASK.md: Specify →
-  Scenarios → Contract → Tests → Build → Verify → Observe, with red/green TDD
-  built in. Use this skill whenever working in a repo that has a `.add/`
-  directory, when the user says "add", "start a task", "next phase", "specify
-  this feature", "ADD method", or "AI-driven development", or when scaffolding a
-  new feature and you want spec/tests-first discipline instead of vague-prompt
-  coding. Also use it to resume work across sessions (it reads `.add/state.json`
-  so you never re-read the whole repo).
+  ADD (AI-Driven Development) — a minimal, state-tracked workflow: the AI writes
+  the code, the human owns direction and verification. Drives every feature through
+  one lean PLAN.md: Specify → Scenarios → Plan → Tests → Build → Verify → Observe,
+  red/green TDD built in. Use whenever a repo has `.add/`, or the user says "add",
+  "start a task", "next phase", "specify this feature", "ADD method", "AI-driven
+  development", or wants spec/tests-first discipline over vague-prompt coding. Also
+  resumes work across sessions via `.add/state.json` (never re-read the whole repo).
 user-invocable: true
 category: workflows
 keywords: [add, aidd, ai-driven-development, spec-first, tdd, contract, scenarios, verify, milestone, task-orchestration]
@@ -18,138 +15,93 @@ argument-hint: "status | init | continue | --todo <text> | [describe new short g
 license: MIT
 metadata:
   author: add
-  version: "1.8.0"
+  version: "2.0.0"
 ---
 
-# ADD — the orchestration engine
+# ADD — memory · judgment · conscience (the agent is the hands)
 
-You are the orchestrator. ADD keeps the AI fast *and* safe by fixing direction
+You turn intent into the right task, then drive it. ADD keeps the AI fast *and* safe by fixing direction
 (spec, scenarios, contract, failing tests) **before** the build, and trusting the
-result through passing evidence rather than a plausible-looking diff.
+result through passing evidence, not a plausible diff.
 
-**One file = one task.** Each feature is one `.add/tasks/<slug>/TASK.md` — a §0 ground
-preamble plus seven step sections, filled top to bottom. The Python tool tracks where you
-are so context never rots across sessions.
+**One task = one atomic node.** Each feature is one `.add/tasks/<slug>/PLAN.md`; its frozen §3
+(contract · scope · Target) is the interface neighbor nodes depend on — edges compile from the
+milestone, `graph` renders the DAG, `locate` walks a failure to its node. Shard context beside it.
 
-**The `--todo` fast-path.** When the skill ARGUMENTS begin with `--todo`, skip orienting: route to
-`add.py todo` and print its output — `--todo <text>` captures · `--todo` lists open todos ·
-`--todo --done <id>` closes (engine errors surfaced verbatim) — then STOP.
+**The `--todo` fast-path.** ARGUMENTS begin with `--todo`? Skip orienting: run `add.py todo`, print
+it — `--todo <text>` captures · `--todo` lists · `--todo --done <id>` closes — then STOP.
 
 ## Always start here (orient — do not skip)
 
-Engine: `.add/tooling/add.py` · book: `.add/docs/`. Ensure the engine is in the project first:
+Engine: `.add/tooling/add.py`. Missing (a plugin install)? Materialize it once —
+`node "${CLAUDE_PLUGIN_ROOT}/bin/cli.js" init --no-skill` drops `.add/tooling/` + the agent-agnostic
+`CLAUDE.md` block; the skill stays in the plugin.
 
-- It exists → go straight to `status` below.
-- It does NOT (ADD installed as a Claude Code plugin — engine + book ride in the plugin) →
-  materialize once: `node "${CLAUDE_PLUGIN_ROOT}/bin/cli.js" init --no-skill`. That drops
-  `.add/tooling/` (engine) + `.add/docs/` (book) + the agent-agnostic `CLAUDE.md` block — like an
-  npm/pip install; the skill stays in the plugin, nothing duplicated.
+Resume from the tool, never re-read the repo — run `add.py status --brief` (cookbook), then
+the foundation map `status --foundation` (`--all` full) + `.add/SOUL.md` (**voice**); mid-flow, trust
+each verb's `next:` footer. Then branch on state:
 
-Find the resume point from the tool, not by re-reading the repo:
+- **No `.add/state.json` yet** (`status` says `no .add/ project found`) → **autonomous setup**: read
+  `.add/.intent` if present (the installer's first-build intent — a NOTE, never an init trigger), then
+  YOU run `add.py init --name "<inferred>" --stage <picked> --await-lock` and drive setup via
+  `phases/direction.md` (brownfield repo → map it silently, `adopt.md`) — to the human baseline `lock`.
+- **A task is active** → open its `.add/tasks/<active>/PLAN.md`, read the `phase:` marker, work that
+  beat per the loop below.
+- **No active task** → first SIZE the request (Intake below), then `add.py new-task`.
 
-```bash
-python3 .add/tooling/add.py status
-```
-
-`status` names two files to read when orienting: `.add/PROJECT.md` (the foundation) and `.add/SOUL.md`
-(your **voice** — tone, style, what keeps the human's trust; read it each session — human-owned and
-self-improving via the `soul-self-improve` path). Then branch on state:
-
-- **No `.add/state.json` yet** (`status` says `no .add/ project found`) → **autonomous setup**: if
-  `.add/.intent` exists, read it — the installer's one-line first-build intent (a NOTE, never an init
-  trigger) — to seed your kickoff; then YOU run init — `add.py init --name "<inferred>" --stage <picked>
-  --await-lock` — and read `phases/0-setup.md` to draft the foundation + §1–§3 through to the human
-  baseline approval.
-- **A task is active** → open its `.add/tasks/<active>/TASK.md`, read the `phase:` marker, load the
-  matching `phases/<n>-<phase>.md`. Work *only* that phase.
-- **No active task** → first SIZE the request (Intake below), then `add.py new-task <slug> --title "..."`.
-
-**Quick ref** — `status` resume · `init` bootstrap · `advance` continue · `gate PASS` at verify.
-**Flag mode** — two human-owned settings (never auto-picked): **fast** (task) · **auto** (mode).
-- **fast** — `new-task --fast`: minimal template, freeze-gated; a milestone-free `--fast` task is a
-  blessed standalone low-ceremony lane. Jot ideas first with `add.py todo "<text>"` (then `todo` to
-  list · `todo --done <id>`).
-- **auto** — `autonomy: auto` (default) auto-gates verify on evidence; lower the autonomy level with
-  `add.py autonomy set conservative|manual` for a human gate · `new-milestone --await-confirm`
-  confirm-gates a milestone's tasks.
+**Flag mode** — ONE atomic template serves every task (no lanes); flags are header declarations.
+- **gate_mode** — headless/agent-crossed freeze: declare `gate_mode: ai-plan-verify` in the PLAN.md
+  header + fill the §3 AI-verify record; security|data|architecture stay human-frozen (unstrikeable).
+- **auto** — `autonomy: auto` (default) auto-gates verify on evidence; `add.py autonomy set
+  conservative|manual` restores a human gate.
 
 ## Intake — size a request before creating scope
 
-Classify a raw request BEFORE any milestone or task: read `intake.md`, place it in one bucket —
-`new-major` · `sub-milestone` · `task` · `change-request` — propose `{ bucket, rationale, command }`;
-the human confirms. A question or unsharp intent? **Interview before you size** (`intake.md`). Once
-`new-major`/`sub-milestone`, draft the `MILESTONE.md` (goal · scope · exit criteria · breadth-first
-tasks) — read `scope.md`. Create it `new-milestone --await-confirm`, then `milestone-confirm <slug>`
-gates `new-task` until the parent is agreed. For `task`/`change-request`: `add.py new-task` then the
-first phase guide.
-
-## The flow and which file to load
-
-Load the phase guide **only for the phase you are in** (progressive disclosure):
-
-| Phase | Guide | Produces (TASK.md section) | Who leads |
-|-------|-------|----------------------------|-----------|
-| setup | `phases/0-setup.md` | `.add/` + living docs + first §1–§3 + `SETUP-REVIEW.md` | AI drafts → **human locks** (the baseline approval) |
-| ground | `phases/0-ground.md` | §0 GROUND map (real files · symbols · the anchors §3 cites) | **AI** (the §0 preamble — no new gate) |
-| specify | `phases/1-specify.md` | §1 rules + ranked lowest-confidence flag | AI drafts (co-specify)† |
-| scenarios | `phases/2-scenarios.md` | §2 Given/When/Then | AI drafts† |
-| contract | `phases/3-contract.md` | §3 frozen shape | AI drafts → **human approves once** (the decision point)† |
-| tests | `phases/4-tests.md` | §4 + red suite in `tests/` | AI drafts† |
-| build | `phases/5-build.md` | code in `src/`, tests green | **AI** |
-| verify | `phases/6-verify.md` | §6 checks + gate record | **AI auto-gates on evidence**; human on residue/security‡ |
-| observe | `phases/7-observe.md` | §7 spec delta | human + AI |
-
-† **The specification bundle (v7).** §1–§4 are one bundle; the human gives **one approval at the
-contract freeze**, lowest-confidence-first — see `run.md`.
-‡ **Verify auto-gate (v6–v7).** Under `autonomy: auto` (default) a run may auto-PASS on complete
-evidence (*auto-resolved* — an explicit PASS, not a skip). **Security always escalates** (HARD-STOP);
-so do concurrency / architecture residue and a lowered autonomy level (`conservative` / `manual`) — `run.md`.
-
-At every human decision point (intake · bundle approval · gate · milestone close) follow
-`report-template.md`: open with the banner then the ARC (goal · done · plan, engine-sourced), then PLAN/SHAPE → SUMMARY →
-FLAGS → DECIDED → EVIDENCE → APPROVE → NEXT; show-before-ask; never pre-stamp; the question is a summary, never the artifact.
-
-In **observe**, emit **lessons learned** tagged by which of the five (`DDD · SDD · UDD · TDD · ADD`)
-they improve (write them `open`; the human consolidates into `PROJECT.md`) — grammar + lifecycle in
-`deltas.md`. At milestone close (or on demand) the retrospective consolidation gathers confirmed deltas
-into a versioned foundation — `fold.md`; then (separately, after) compact each foundation spec's stable
-tail — `compact-foundation.md`. Observe also tunes your voice: propose a confirmable voice delta that,
-once the human confirms, rewrites `SOUL.md` (the human is the only writer) — `soul.md`.
-
-## Beyond the bundle — load on demand
-
-- **§3 CONTRACT FROZEN** → build→verify is a dynamic, auto-gated run (`autonomy: auto` default; lower to
-  `conservative`/`manual` for a human gate) — `run.md`. Pipeline ready tasks behind frozen
-  contracts — `streams.md`. Delegate one piece of your plan to a subagent — prefer the named roster
-  (`add-design`/`add-build`/`add-verify`/`add-persona`/`add-advisor`) over an ad-hoc spawn; when to
-  spawn, the prompt template, the tier — `advisor.md`. Self-score a draft (0–1 across six dimensions, refine if any < 0.9)
-  — `confidence.md`. Both advisory; the engine never spawns.
-- **Small, low-risk task**, less ceremony → the **fast lane**: `new-task --fast` scaffolds the minimal
-  `TASK.fast.md`, bundle approved in one freeze — `phases/fast-lane.md`. Floor held (frozen contract ·
-  red test · verify gate; freeze-gated under any milestone). Collapse, never skip; opt-in.
-- **UI feature** at specify → the **design-definition loop** (UDD): intake the design axes → review the
-  domain → research and reuse components → wireframe → a captured screen the human confirms **before** build — `design.md`.
-  Tool-agnostic; the engine never renders.
-- Tasks all done but the milestone **goal** unmet → `milestone-done` holds it open; the loop turns open
-  deltas + extras into the next tasks until the goal is met — `loop.md`.
-- `status` prints **`MVP covered → propose graduation`** (every milestone done AND stage criteria all
-  `[x]`) → `graduate.md`: `graduation-report` → co-specify interview → draft ≥1 production milestone →
-  human confirm → then `stage production`. Guarded (`stage_no_roadmap`); the FINAL step, never a bare flip.
-- `status` prints **`→ releasable: N milestone(s) closed since last release`** → `release.md` (the 5th
-  scope level): `release-report` → draft notes from the consolidated deltas → meet the readiness floor
-  (security HARD-STOP is un-forceable) → human confirms → `add.py release <version>` records the cut
-  (CHANGELOG + `RELEASES.md` ledger + milestone attribution). The engine records; the human runs the
-  tag/publish/deploy. A release bundles ≥1 milestone, orthogonal to stage.
-- **Monorepo / multi-repo** — a milestone spans more than one green bar (a BE + its FE) → the
-  **component pillar**: declare components in `.add/components.toml`, gate each task on its component's
-  green-bar, freeze cross-component contracts (`produces:`/`consumes:`), hold the FE until the BE
-  freezes, `federate pull` across repos — `components.md`. Opt-in; no components = today.
-- **Project-fit personas** — the **persona loop** seeds `.add/personas/<slug>.md`, grows them via
-  observe→delta→consolidate, applies them in design/streams/advisor/build (advisory; never lowers a gate) — `docs/18-personas.md`.
-- **Risk-class of a task** — declare `sensitivity:` in the TASK header (base `security|data|architecture|
-  mechanical`, always valid). EXTEND it with your project's domain classes in `GLOSSARY.md`'s `## Sensitivity
-  classes` section; freeze/status/check read base ∪ project. The AI keeps the domain vocabulary current —
-  `sensitivity.md`. Security is a human floor in every tier; only `mechanical` is advisor-gatable — see `advisor-gate-relax` in `run.md`.
+Classify a raw request BEFORE any scope: read `intake.md`. Too small for scope → the **inline lane**
+(diff + `delta-append` receipt; security·data·architecture escalates). Else one bucket — `new-major` ·
+`sub-milestone` · `task` · `change-request` — propose `{ bucket, rationale, command }`; the human
+confirms. Unsharp intent? **Interview before you size** (`intake.md`). A milestone bucket: draft
+`MILESTONE.md` (goal · scope · exit criteria · breadth-first tasks — `phases/direction.md`), then the
+`new-milestone`/`milestone-confirm` pair below (new-task inherits each node's depends-on). A
+`task`/`change-request`: `add.py new-task`, then beat 1 above.
+
+## The 3-beat loop (this file IS the loop; references load on demand)
+
+Every task is three beats (seven steps, folded), three engine calls, ONE human decision:
+
+1. **DIRECTION** — load the domain-fit persona (seed via add-worker persona-mode if none), then draft
+   the whole bundle top-to-bottom in PLAN.md: §1 rules + ranked ⚠ flag (co-specify) ·
+   §2 scenarios · §3 PLAN (grounding → frozen contract shape → build-strategy + Scope + Target) · §4 red suite
+   (run it — red for the RIGHT reason; fill each bullet's `covers:` clause key). Then the ONE approval,
+   presented lowest-confidence-first: `add.py freeze` (a setup session's baseline `lock` IS this approval).
+2. **BUILD** — code in `src/` until every red is green; change no test, no frozen contract; stay
+   inside the §3 Scope. A test OUTSIDE your suite failing? `add.py locate` names the owning node, the
+   failure class, the frozen §3 clause it proves, and who re-verifies if a settled contract must move.
+3. **VERIFY** — confirm evidence · 3 lenses (**security always HARD-STOP**) · earned-green
+   refute-read · then `add.py gate PASS` (from build it compound-crosses; under `autonomy: auto` a
+   run auto-PASSes on complete no-residue evidence — *auto-resolved*, an explicit PASS, never a skip; residue or
+   lowered autonomy → human — `run.md`).
+
+Stuck or deep? On demand: `phases/direction.md` · `phases/build.md` · `phases/verify.md` · opaque
+term? `terms.md`. Delegating? Spawn the roster agent — it loads its own refs (you read ONLY this file).
+
+At each decision point (intake · bundle · gate · close) the fitting persona OWNS the gate report —
+`gate-udd.md` (read once per session) holds the principles: CONVEY decision + ARC (engine-sourced) ·
+shape · flags (lowest-first) · evidence · a guided APPROVE. The persona owns the form, never the four
+floors (security stays HARD-STOP) — the question is a summary, never the artifact.
+
+Emit **lessons learned** tagged by which of the five (`DDD · SDD · UDD · TDD · ADD`) they improve —
+in-flight, via `delta-append` → its living spec in `.add/specs/`. The living specs
+ARE the foundation; the close counts what §7 still holds open. Observe also tunes your voice: a
+confirmable delta the human confirms rewrites `SOUL.md` (the human is the only writer) — `deltas.md`.
+
+## Beyond the bundle — one trigger = one guide (full prose: `beyond.md`); load only on a trigger
+
+- §3 FROZEN → auto-gated run `run.md` · subagent roster + pipelines (agent-call-preferred, the
+  default execution mode) → `phases/verify.md` · self-score → `phases/direction.md`
+- UI/experience surface → UDD loop `design.md` · milestone goal unmet at `milestone-done` → `loop.md`
+- graduation · release · monorepo green-bars → persona-owned playbooks, `beyond.md` ·
+  the persona loop (`.add/personas/`) → `docs/18-personas.md` · `sensitivity:`/`advisor-gate-relax` → `phases/verify.md`
 
 ## Non-negotiable rules (from the method)
 
@@ -158,35 +110,39 @@ once the human confirms, rewrites `SOUL.md` (the human is the only writer) — `
 2. **Trust evidence, not inspection.** A feature is trusted because its tests pass and the
    non-functional risks (concurrency, security, architecture) were checked — not because the code
    reads plausibly.
-3. **Never weaken a test or edit a frozen contract to make the build pass.** That inverts the method.
-   A real change is a *change request* back to Specify.
+3. **Never weaken a test or edit a frozen contract to make the build pass.** That inverts the
+   method. A real change is a *change request* back to Specify.
 4. **No silent skips.** Every Verify ends in exactly one recorded outcome: `PASS`, `RISK-ACCEPTED`
    (signed, non-security only), or `HARD-STOP`. A security finding is always `HARD-STOP`.
-5. **Ask, don't guess.** If a requirement is unclear, stop and ask the user.
 </constraints>
 
-## Advancing
+## Command cookbook — copy a line; `-h` only off-menu
 
-After a phase's exit gate is met, advance the state (this also syncs the TASK.md marker):
+`add.py` = `python3 .add/tooling/add.py`; lines 2–4 = the 3-call walk (`advance --fill <draft>` = step-wise).
 
 ```bash
-python3 .add/tooling/add.py advance            # next phase of the active task
-python3 .add/tooling/add.py gate PASS          # at verify: records PASS, marks done
-python3 .add/tooling/add.py use <slug>         # switch the active task (e.g. across parallel streams)
+add.py status --brief        # resume · status --section <n|phase> = §body · --foundation · --json
+add.py new-task <slug> --title "..."  # --milestone m · --depends-on a,b · --sensitivity security
+add.py freeze --by "<name>" --cross   # the ONE approval -> build (--ai-plan-verify = headless)
+add.py gate PASS --target-hit yes     # partial|no · RISK-ACCEPTED --owner --ticket --expires
+add.py locate tests/x.py::test_y      # failure -> owning node + its frozen §3 clause
+add.py graph --milestone <slug>       # mermaid DAG · relate <slug> --depends-on|--extends
+add.py delta-append tdd "<lesson>"    # lens: ddd|sdd|udd|tdd|add
+add.py new-milestone <slug> --title "..." --goal "..." --await-confirm  # confirm-gates its tasks
+add.py milestone-confirm <slug> --by "<name>"   # compiles Tasks -> DAG; unlocks new-task
+add.py report [<milestone>|<task>] --decide  # rollup/drill-in · check · search · use
 ```
 
 ## Depth by stage
 
-The steps never change; their depth does (read the stage from `add.py status`):
+Steps never change; depth does (`add.py status`):
 
-- **prototype** — run light; code is throwaway; design/experience is the point.
-- **poc** — run contract/tests/build deeply on the single riskiest slice only.
+- **prototype** — light; throwaway code; design/experience is the point.
+- **poc** — contract/tests/build deep on the single riskiest slice only.
 - **mvp** — full flow, narrow scope, light observation.
-- **production** — every step at full rigor + the observe loop. Reach it via the `graduate.md`
-  orchestration when status shows `MVP covered → propose graduation`, never a bare `stage production` flip.
+- **production** — full rigor + the observe loop; reached via the graduation playbook
+  (`beyond.md`), never a bare `stage production` flip.
 
-## The method rationale
+The **method rationale** (the *why*) lives in the AIDD book — https://pilotspace.github.io/ADD/ (the `docs/…` chapters the
+guides cite). Read it when a decision is genuinely unclear; never duplicate it here.
 
-The full method (the *why* behind every rule) is the AIDD book in `.add/docs/`. When a phase decision is
-genuinely unclear, read the linked chapter — each phase guide points to its chapter. Do not duplicate
-the book here; load it on demand.

package/skill/add/adopt.md

@@ -35,6 +35,34 @@ Fill each living-doc file in `.add/` from what the code shows — **ask nothing*
 2. **Tag every drafted decision `evidence-grounded` vs `guessed`.** A line you read from the code is *evidence-grounded* (cite the file). A line you inferred because the code was silent is *guessed*. The human's single baseline approval is only honest if they can see which is which — the guesses are what they actually need to check. (The tags feed `SETUP-REVIEW.md`.)
 </constraints>
 
+## Setup review — the one page the human signs
+
+Both setup paths (this brownfield map AND the greenfield draft, `phases/direction.md`) end at
+the same single human gate, and `SETUP-REVIEW.md` is that page: every decision you made while
+drafting the foundation, first-scope, and first contract, ordered **lowest-confidence-first** so
+the riskiest guesses meet the human's eye first. The engine never reads it — `add.py lock` is
+judgment-free; the human *reading* this page is the review. Write ONE artifact at
+`.add/SETUP-REVIEW.md`, beside `PROJECT.md` (never clobber a human-edited one — append/update):
+
+```markdown
+# SETUP REVIEW — <project>
+
+<stage> · <brownfield | greenfield> · drafted by <model> @ <date>
+
+| # | Decision | Lands in | Tag | Why / Evidence |
+|---|----------|----------|-----|----------------|
+| 1 | <the drafted decision> | PROJECT.md \| scope \| first-contract | `guessed` | <the inference + why you had to guess> |
+| 2 | <…> | <…> | `evidence-grounded` | <cite the source file/line you read it from> |
+
+Sign: confirm in chat → the agent runs `add.py lock --by "<name>"` (typing it yourself works too)
+```
+
+The two rules that make it honest: rows sort by confidence **ascending** — a `guessed` row
+always floats above an `evidence-grounded` one (the top of the table is what the human must
+actually challenge); and EVERY row is tagged with the shared vocabulary above (`guessed` = the
+repo was silent, state the inference; `evidence-grounded` = cite the file). Rows are numbered
+for reference at the gate. Present it lowest-confidence-first, not field-by-field.
+
 ## Where it ends — the baseline approval
 
 Brownfield onboarding draws no per-step approvals: map the foundation, draft the first milestone's scope and first task's candidate specification bundle, then present it all at **one** human gate. The human reviews decisions (`guessed` first) and confirms; you run the lock: