@pilotspace/add 1.16.1 → 2.0.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,18 @@ 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.
+const RETIRED_AGENTS = ["add-design.md", "add-build.md", "add-verify.md",
+                        "add-persona.md", "add-advisor.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
@@ -796,6 +807,37 @@ function sleepSync(ms) {
   Atomics.wait(ia, 0, 0, ms);
 }
 
+// An async, event-loop-YIELDING sleep (unlike sleepSync's Atomics.wait, which blocks the very
+// thread a setInterval-based heartbeat needs to fire on) — js-reclaim-lock-heartbeat.
+function sleepAsync(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// js-reclaim-lock-heartbeat: the JS analog of the Python `_lock_heartbeat` fix
+// (reclaim-ticket-race) — refreshes a held lock file's own mtime on a `.unref()`'d
+// `setInterval` for as long as it is held, so a live-but-slow holder is never misjudged
+// stale by a sibling racer purely because wall-clock age crosses `staleAfterMs`. `.unref()`
+// means the timer never keeps the process alive on its own; `stop()` clears it explicitly on
+// release (belt AND suspenders, mirrors the interval's own `max(50ms, min(staleAfterMs/4,
+// 5000ms))` formula the frozen contract cites). A crash simply stops the interval firing — the
+// file still ages out and self-heals via the existing reclaim-ticket mechanism, unchanged.
+//
+// This is a probabilistic mitigation, not a mathematical guarantee: a callback fires only
+// between synchronous JS turns, so whole-event-loop starvation (a long synchronous operation
+// blocking the process) can defeat it exactly as whole-process scheduling starvation once
+// defeated the Python fix's own real OS thread on real CI (see TASK.md's least-sure flag) —
+// accepted given production defaults (600s/120s) make that starvation window vanishingly
+// unlikely in practice.
+function startLockHeartbeat(lockPath, staleAfterMs) {
+  const intervalMs = Math.max(50, Math.min(staleAfterMs / 4, 5000));
+  const timer = setInterval(() => {
+    const now = new Date();
+    try { fs.utimesSync(lockPath, now, now); } catch (_e) {}   // released/reclaimed — best-effort
+  }, intervalMs);
+  timer.unref();
+  return { stop: () => clearInterval(timer) };
+}
+
 function pkgVersion() {
   try { return require(path.join(PKG_ROOT, "package.json")).version; }
   catch (_e) { return "0.0.0"; }
@@ -917,7 +959,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) {
@@ -930,6 +972,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:
@@ -947,7 +1019,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("/");
@@ -961,7 +1035,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) {
@@ -1003,12 +1077,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],
 ];
 
@@ -1031,7 +1107,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) {
@@ -1249,17 +1325,44 @@ function installGlobalDataRestore(chosenTarget, force) {
   else log("  (no snapshot for this project at " + snap + " — nothing restored)");
 }
 
+// Every "<lockFileName>.reclaim-*" directly under dir aged past staleAfterSeconds — a LEAKED
+// per-generation reclaim ticket (its own holder crashed between winning it and its own
+// best-effort cleanup; a live, currently-in-flight ticket is never this old). Returns full
+// paths, sorted; [] if dir does not exist. Mirror of _installer.py:_aged_reclaim_tickets.
+function agedReclaimTickets(dir, lockFileName, staleAfterSeconds, nowMs) {
+  if (!fs.existsSync(dir)) return [];
+  const prefix = lockFileName + ".reclaim-";
+  return fs.readdirSync(dir).filter((name) => name.startsWith(prefix)).map((name) => path.join(dir, name))
+    .filter((p) => {
+      try { return (nowMs - fs.statSync(p).mtimeMs) / 1000 > staleAfterSeconds; }
+      catch (_e) { return false; }               // vanished mid-sweep — nothing to report
+    }).sort();
+}
+
 // prune-data: reclaim ORPHANED snapshots under <home>/data. An orphan is a <home>/data/<key>
 // whose key is owned by NO LIVE registry entry (LIVE = a registered path that still EXISTS on
 // disk) — so unregistered AND registered-but-vanished are BOTH orphans (the explicit reclaim;
 // DIVERGES from update --global's keep-vanished). Reads the registry FIRST (corrupt throws,
-// before any removal). Returns {orphans, removed}. Mirror of _installer.py:_prune_data.
+// before any removal).
+//
+// sweep-orphan-reclaim-tickets: ALSO sweeps LEAKED per-generation reclaim tickets — a
+// "<LOCK_FILE>.reclaim-*" under home (home-scope) and a "<PROJECT_LOCK_FILE>.reclaim-*" under
+// every LIVE registered project's own .add/ (project-scope) — each aged past its OWN kind's
+// existing staleness constant (LOCK_TICKET_STALE_SECONDS / PROJECT_LOCK_TICKET_STALE_SECONDS,
+// reused verbatim; no new threshold). Reuses the registry already read for the data-orphan
+// sweep — no new read.
+//
+// Returns {orphans, removed, ticketOrphans, ticketsRemoved} — extends the prior {orphans,
+// removed} object non-breakingly (existing dot-access callers are unaffected). ticketOrphans/
+// ticketsRemoved are full paths; ticketsRemoved == [] on a dry-run, == ticketOrphans under
+// force (each unlinked best-effort, matching the existing reclaim code's own swallow-errors
+// convention). Mirror of _installer.py:_prune_data.
 function pruneData(home, force) {
   const reg = readRegistry(home);                           // corrupt -> throw (LOUD, zero removal)
-  const live = new Set(reg.filter((p) => fs.existsSync(p)).map(dataKey));
+  const livePaths = reg.filter((p) => fs.existsSync(p));
+  const live = new Set(livePaths.map(dataKey));
   const dataDir = path.join(home, "data");
-  if (!fs.existsSync(dataDir)) return { orphans: [], removed: [] };
-  const orphans = fs.readdirSync(dataDir).filter((name) => {
+  const orphans = !fs.existsSync(dataDir) ? [] : fs.readdirSync(dataDir).filter((name) => {
     try { return fs.statSync(path.join(dataDir, name)).isDirectory() && !live.has(name); }
     catch (_e) { return false; }
   }).sort();
@@ -1270,23 +1373,67 @@ function pruneData(home, force) {
       removed.push(key);
     }
   }
-  return { orphans: orphans, removed: removed };
+
+  const now = Date.now();
+  let ticketCandidates = agedReclaimTickets(home, LOCK_FILE, LOCK_TICKET_STALE_SECONDS, now)
+    .map((p) => ({ path: p, staleAfter: LOCK_TICKET_STALE_SECONDS }));
+  for (const project of livePaths) {
+    ticketCandidates = ticketCandidates.concat(
+      agedReclaimTickets(path.join(project, ".add"), PROJECT_LOCK_FILE, PROJECT_LOCK_TICKET_STALE_SECONDS, now)
+        .map((p) => ({ path: p, staleAfter: PROJECT_LOCK_TICKET_STALE_SECONDS }))
+    );
+  }
+  const ticketOrphans = ticketCandidates.map((c) => c.path);
+  const ticketsRemoved = [];
+  if (force) {
+    for (const { path: ticket, staleAfter } of ticketCandidates) {
+      try {
+        if ((Date.now() - fs.statSync(ticket).mtimeMs) / 1000 <= staleAfter) continue;  // no longer stale at unlink time — §5 safety rule
+        fs.unlinkSync(ticket);
+        ticketsRemoved.push(ticket);
+      } catch (_e) { /* already gone — harmless, matches reclaim's own convention */ }
+    }
+  }
+
+  return { orphans: orphans, removed: removed, ticketOrphans: ticketOrphans, ticketsRemoved: ticketsRemoved };
 }
 
 // prune-data command: dry-run lists orphans (removes nothing); --force deletes. no_global_home /
 // registry_corrupt = fail-closed (LOUD, nothing removed). Mirror of pip _installer.prune_data.
+//
+// prune-data-update-lock: the registry-read + orphan-computation + removal critical section now
+// holds the SAME home lock (acquireUpdateLock) `update --global` already holds during its own
+// reconcile (which refreshes an existing project's <home>/data/<key> snapshot) — so the two can
+// never interleave. Reuses the existing, proven primitive verbatim (fail-fast, no poll — the
+// primitive's own fail() call handles a contended lock, no extra catch needed here).
+//
+// sweep-orphan-reclaim-tickets: ALSO reports (and, with --force, removes) leaked reclaim
+// tickets found by pruneData — see its own comment; a separate, additive count from the
+// data-orphan sweep above.
 function cmdPruneData(args) {
   const home = resolveGlobalHome(process.env);
   if (!fs.existsSync(path.join(home, STAMP_FILE))) {
     fail("no global ADD install at " + home + " (.add-version not found) — nothing to prune");
   }
+  acquireUpdateLock(home, { timeout: null }, process.env);
   let result;
   try { result = pruneData(home, args.force); }
   catch (_e) { fail("global registry " + registryPath(home) + " is corrupt — fix or delete it; not pruning"); }
-  if (result.orphans.length === 0) { log("  no orphaned snapshots — nothing to prune"); return; }
-  if (args.force) { log("  ✓ " + result.removed.length + " removed"); return; }
+  if (result.orphans.length === 0 && result.ticketOrphans.length === 0) {
+    log("  no orphaned snapshots — nothing to prune");
+    return;
+  }
+  if (args.force) {
+    if (result.orphans.length > 0) log("  ✓ " + result.removed.length + " removed");
+    if (result.ticketOrphans.length > 0) log("  ✓ " + result.ticketsRemoved.length + " reclaim ticket(s) removed");
+    return;
+  }
   for (const key of result.orphans) log("  orphan: " + key);
-  log("  " + result.orphans.length + " orphan(s); re-run with --force to remove");
+  if (result.orphans.length > 0) log("  " + result.orphans.length + " orphan(s); re-run with --force to remove");
+  for (const ticket of result.ticketOrphans) log("  ticket orphan: " + ticket);
+  if (result.ticketOrphans.length > 0) {
+    log("  " + result.ticketOrphans.length + " reclaim ticket orphan(s); re-run with --force to remove");
+  }
 }
 
 // init --global: install the managed layer ONCE to the shared home + register this project,
@@ -1477,7 +1624,9 @@ function acquireUpdateLock(home, { timeout = null } = {}, env = process.env) {
   }
   try { fs.writeSync(fd, process.pid + " " + new Date().toISOString() + "\n"); }
   catch (_e) {}   // diagnostics are best-effort — never fail an acquired lock over this
+  const heartbeat = startLockHeartbeat(lockPath, staleAfterMs);   // js-reclaim-lock-heartbeat
   const release = () => {
+    heartbeat.stop();   // cleared FIRST — never outlives the fd/lockPath it refreshes
     try { fs.closeSync(fd); } catch (_e) {}
     try { fs.unlinkSync(lockPath); } catch (_e) {}
   };
@@ -1631,7 +1780,9 @@ function acquireProjectLock(addDir, env = process.env) {
   }
   try { fs.writeSync(fd, process.pid + " " + new Date().toISOString() + "\n"); }
   catch (_e) {}   // diagnostics are best-effort — never fail an acquired lock over this
+  const heartbeat = startLockHeartbeat(lockPath, staleAfterMs);   // js-reclaim-lock-heartbeat
   const release = () => {
+    heartbeat.stop();   // cleared FIRST — never outlives the fd/lockPath it refreshes
     try { fs.closeSync(fd); } catch (_e) {}
     try { fs.unlinkSync(lockPath); } catch (_e) {}
     if (createdDir) {
@@ -1734,10 +1885,59 @@ 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
+// real multi-process contention against acquireUpdateLock/acquireProjectLock without duplicating
+// their acquire/release logic in the test itself. Intercepted BEFORE the `cmd`/switch dispatch
+// below, guarded behind an undocumented flag — never listed in --help, never reachable via any
+// documented public command, so it carries zero surface on the real CLI path.
+async function cmdInternalAcquireLock(argv) {
+  const kind = argv[0];
+  const targetPath = argv[1];
+  const holdMs = Number(argv[2]);
+  let release;
+  if (kind === "update") {
+    release = acquireUpdateLock(targetPath, { timeout: null }, process.env);
+  } else if (kind === "project") {
+    release = acquireProjectLock(targetPath, process.env);
+  } else {
+    fail("internal_acquire_lock_bad_kind: expected 'update' or 'project', got '" + kind + "'");
+    return;
+  }
+  log("HELD " + Date.now());
+  await sleepAsync(holdMs);   // event-loop-yielding — lets the heartbeat's setInterval fire
+  log("RELEASED " + Date.now());
+  release();
+  process.exit(0);
 }
 
 async function main() {
   const argv = process.argv.slice(2);
+  if (argv[0] === "--internal-acquire-lock") {
+    await cmdInternalAcquireLock(argv.slice(1));
+    return;
+  }
   const cmd = argv[0] && !argv[0].startsWith("--") ? argv.shift() : "init";
   const args = parseArgs(argv);
   switch (cmd) {
@@ -1753,13 +1953,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.16.1",
-  "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.0.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.