@pilotspace/add 1.13.0 → 1.15.0

package/bin/cli.js

@@ -39,7 +39,8 @@ function parseArgs(argv) {
   // defaults the stage and infers the name from the folder, so the manual-init
   // hint only echoes flags the user actually chose (shortest true command).
   const args = { _: [], force: false, check: false, noSkill: false, stage: null, name: null,
-                 yes: false, nonInteractive: false, global: false, globalData: false, ruleFile: false };
+                 yes: false, nonInteractive: false, global: false, globalData: false,
+                 fromGlobalData: false, ruleFile: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--force") args.force = true;
@@ -50,6 +51,9 @@ function parseArgs(argv) {
     // --global-data: (implies --global) ALSO persist this project's user-data under
     // <home>/data/<key> keyed by path (opt-in, one-way snapshot).
     else if (a === "--global-data") args.globalData = true;
+    // --from-global-data: the INVERSE — rehydrate this project's user-data FROM the shared
+    // home on a fresh clone (non-destructive fill-gaps; --force overwrites with a .bak).
+    else if (a === "--from-global-data") args.fromGlobalData = true;
     // --yes / --non-interactive: skip all prompts, take defaults — the explicit
     // non-interactive selector the interactive() gate honors (CI/pipes do this too).
     else if (a === "--yes" || a === "-y") args.yes = true;
@@ -581,11 +585,21 @@ function seedSoulMd(target) {
   }
 }
 
-// Ensure .add/.gitignore lists the engine's transient artifacts. Seed it from the bundled
-// tooling/templates/gitignore.tmpl if absent; else APPEND-IF-ABSENT each pattern line the
-// template carries that the file lacks — additive only, never reorders/removes user lines,
-// idempotent; comment/blank lines are not appended to an existing file. Fail-soft. Twin of
-// _installer.py:_seed_gitignore.
+// kept OUTSIDE add_engine/constants.py / gitignore.tmpl deliberately: the engine's own
+// _GITIGNORE_BODY constant must never contain "personas-teacher" (test_engine_unchanged_
+// and_handsoff — the engine stays hands-off of the teacher vendor tree). The INSTALLER
+// already names that tree explicitly (MANAGED/OPTIONAL), so it is free to seed this one
+// extra ignore line itself. BARE (not repo-root style): .add/.gitignore lives INSIDE
+// .add/, so git resolves its patterns relative to .add/ itself. Twin of
+// _installer.py:_INSTALLER_MANAGED_IGNORE_EXTRA.
+const INSTALLER_MANAGED_IGNORE_EXTRA = ["personas-teacher/"];
+
+// Ensure .add/.gitignore lists the engine's transient artifacts + managed vendor trees.
+// Seed it from the bundled tooling/templates/gitignore.tmpl (plus
+// INSTALLER_MANAGED_IGNORE_EXTRA) if absent; else APPEND-IF-ABSENT each pattern line that
+// combined body carries that the file lacks — additive only, never reorders/removes user
+// lines, idempotent; comment/blank lines are not appended to an existing file. Fail-soft.
+// Twin of _installer.py:_seed_gitignore.
 function seedGitignore(target) {
   const source = path.join(PKG_ROOT, "tooling", "templates", "gitignore.tmpl");
   if (!fs.existsSync(source)) {
@@ -594,7 +608,9 @@ function seedGitignore(target) {
   }
   const dest = path.join(target, ".add", ".gitignore");
   try {
-    const body = fs.readFileSync(source, "utf8");
+    let body = fs.readFileSync(source, "utf8");
+    if (!body.endsWith("\n")) body += "\n";
+    body += INSTALLER_MANAGED_IGNORE_EXTRA.join("\n") + "\n";
     if (!fs.existsSync(dest)) {
       fs.mkdirSync(path.dirname(dest), { recursive: true });
       fs.writeFileSync(dest, body);                       // seed-if-missing
@@ -694,12 +710,23 @@ async function cmdInit(args) {
     }
   }
   if (args.globalData) args.global = true;   // --global-data implies --global (need a home)
+  // OPT-IN restore: the home MUST already exist — no_global_home is a HARD fail, checked FAST
+  // here so nothing lands in the target on a missing home (the restore itself runs after the drop).
+  if (args.fromGlobalData) {
+    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 restore " +
+           "from; run `init --global-data` on a source checkout first");
+    }
+  }
   // OPT-IN global home, BEFORE the per-project drop (fail-closed if the home is unwritable
   // or its registry is corrupt — the package + the self-contained default stay usable).
   if (args.global) installGlobal(args, chosenTarget);
   dropFiles(args, chosenTarget, profile, intent);
   // OPT-IN data persist, AFTER the drop (one-way snapshot of existing user-data).
   if (args.globalData) installGlobalData(chosenTarget);
+  // OPT-IN restore (consume), AFTER the drop: rehydrate user-data from the home into this clone.
+  if (args.fromGlobalData) installGlobalDataRestore(chosenTarget, args.force);
 }
 
 // --- update: re-materialize the managed layer without a re-install -----------
@@ -710,8 +737,15 @@ const MANAGED = [
   ["skill/add", [".claude", "skills", "add"], 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
+// package always ships these (guarded by test_packaging); a malformed/older package missing one
+// must NOT abort the install — the core lands and the optional tree is soft-skipped. Twin of
+// _installer.py:OPTIONAL. Design-for-failure.
+const OPTIONAL = new Set(["personas-teacher"]);
 const STAMP_FILE = ".add-version";
+const LOCK_FILE = ".update.lock";   // the `update --global` home lock (never user-data)
 
 function pkgVersion() {
   try { return require(path.join(PKG_ROOT, "package.json")).version; }
@@ -732,8 +766,30 @@ function writeStamp(addDir, version, channel) {
   );
 }
 
+// The set of FILE paths (recursive leaves) under root, RELATIVE to root. ∅ if absent.
+// Directories are not counted — only files (the "manifest" the roll-up measures).
+function treeFiles(root) {
+  const out = new Set();
+  if (!fs.existsSync(root)) return out;
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else out.add(path.relative(root, full));
+    }
+  };
+  walk(root);
+  return out;
+}
+
+// Returns a file-level roll-up of the heal: { restored, refreshed } where `restored` = a
+// file in the FINAL tree whose relative path was ABSENT before the wipe (fresh or
+// partially-gutted trees heal these), `refreshed` = a final file that was PRESENT before
+// (re-materialized). Orphans (present before, gone after) are swept, counted as neither.
+// Pure observation — copy semantics unchanged. Mirror of _installer.py:_clean_replace.
 function cleanReplaceTree(src, dest, stripTests) {
   if (!fs.existsSync(src)) fail("missing packaged source: " + src);
+  const before = treeFiles(dest);                 // snapshot BEFORE the wipe, or it's always ∅
   fs.mkdirSync(path.dirname(dest), { recursive: true });
   if (fs.existsSync(dest)) fs.rmSync(dest, { recursive: true, force: true });
   fs.cpSync(src, dest, { recursive: true });
@@ -743,9 +799,12 @@ function cleanReplaceTree(src, dest, stripTests) {
       if (/^test_.*\.py$/.test(entry)) fs.rmSync(path.join(dest, entry), { force: true });
     }
   }
+  let restored = 0, refreshed = 0;
+  for (const f of treeFiles(dest)) (before.has(f) ? refreshed++ : restored++);
+  return { restored: restored, refreshed: refreshed };
 }
 
-const TREE_LABEL = { "skill/add": "skill", "tooling": "tooling", "docs": "docs" };
+const TREE_LABEL = { "skill/add": "skill", "tooling": "tooling", "docs": "docs", "personas-teacher": "personas" };
 
 // Per managed tree: "missing" (dest absent OR empty) or "present".
 function managedStatus(target) {
@@ -764,15 +823,20 @@ function managedStatus(target) {
 // a corrupt package leaves the target untouched).
 function reconcile(args, target, srcRoot) {
   srcRoot = srcRoot || PKG_ROOT;   // default: the package; the global home feeds propagation
-  const trees = MANAGED.filter(([sub]) => !(sub === "skill/add" && args.noSkill));
+  const trees = MANAGED
+    .filter(([sub]) => !(sub === "skill/add" && args.noSkill))
+    .filter(([sub]) => !(OPTIONAL.has(sub) && !fs.existsSync(path.join(srcRoot, sub))));  // soft-skip absent optional
   for (const [sub] of trees) {
     if (!fs.existsSync(path.join(srcRoot, sub))) {
       fail("missing packaged source: " + path.join(srcRoot, sub));
     }
   }
   const status = managedStatus(target);
+  let restored = 0, refreshed = 0;
   for (const [sub, destParts, stripTests] of trees) {
-    cleanReplaceTree(path.join(srcRoot, sub), path.join(target, ...destParts), stripTests);
+    const roll = cleanReplaceTree(path.join(srcRoot, sub), path.join(target, ...destParts), stripTests);
+    restored += roll.restored;
+    refreshed += roll.refreshed;
     const dest = destParts.join("/");
     if (status[sub] === "missing") {
       log("  ✓ restored  " + TREE_LABEL[sub].padEnd(8) + "-> " + dest + "  (was missing)");
@@ -780,7 +844,8 @@ function reconcile(args, target, srcRoot) {
       log("  ✓ refreshed " + TREE_LABEL[sub].padEnd(8) + "-> " + dest);
     }
   }
-  return status;
+  log("  → " + restored + " restored · " + refreshed + " refreshed");
+  return { restored: restored, refreshed: refreshed, trees: status };
 }
 
 // --- global home: an OPT-IN shared install (engine+book+skill) updated for all projects ----
@@ -831,18 +896,20 @@ const GLOBAL_TREES = [
   ["skill/add", ["skill", "add"], false],
   ["tooling", ["tooling"], true],
   ["docs", ["docs"], false],
+  ["personas-teacher", ["personas-teacher"], false],
 ];
 
 // Clean-replace the bundled managed layer INTO <home> (canonical mirror), then DEPLOY the
 // skill to ~/.claude/skills/add. Throws if a dir can't be written (caller -> home_unwritable).
 // Prechecks ALL sources first (design-for-failure: a corrupt package leaves the home as-is).
 function reconcileGlobal(home, claudeDir, noSkill) {
-  for (const [sub] of GLOBAL_TREES) {
+  const trees = GLOBAL_TREES.filter(([sub]) => !(OPTIONAL.has(sub) && !fs.existsSync(path.join(PKG_ROOT, sub))));
+  for (const [sub] of trees) {
     if (!fs.existsSync(path.join(PKG_ROOT, sub))) {
       fail("missing packaged source: " + path.join(PKG_ROOT, sub));
     }
   }
-  for (const [sub, destParts, stripTests] of GLOBAL_TREES) {
+  for (const [sub, destParts, stripTests] of trees) {
     cleanReplaceTree(path.join(PKG_ROOT, sub), path.join(home, ...destParts), stripTests);
   }
   if (!noSkill) cleanReplaceTree(path.join(home, "skill", "add"), claudeDir, false);
@@ -851,7 +918,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];   // managed trees + meta
+const DATA_EXCLUDE = ["tooling", "docs", ".update-cache", STAMP_FILE, LOCK_FILE];   // managed trees + meta + lock
 
 // data_key twin: <sanitized-basename>-<sha1(abspath_utf8)[:12]>. Pure · total · separator-free.
 function dataKey(projectAbspath) {
@@ -902,6 +969,95 @@ function installGlobalData(chosenTarget) {
   else log("  (no project data to persist yet — run /add to create one, then re-run --global-data)");
 }
 
+function isSymlink(p) {
+  try { return fs.lstatSync(p).isSymbolicLink(); } catch (_e) { return false; }
+}
+
+// Restore USER-DATA from <home>/data/<key> into <project>/.add — the NON-DESTRUCTIVE inverse of
+// persistData. FILL-GAPS by default (write only ABSENT entries); force overwrites a present entry,
+// writing a <name>.bak FIRST. Copies only isUserData entries; DEREFERENCES symlinks to content
+// (cpSync dereference). true if >=1 restored, false if nothing to restore. Throws on an unwritable
+// dest -> restore_failed. Mirror of _installer.py:_restore_data (identical key + fill-gaps rule).
+function restoreData(home, projectAbspath, force) {
+  const src = path.join(home, "data", dataKey(projectAbspath));
+  if (!fs.existsSync(src)) return false;
+  const entries = fs.readdirSync(src).filter(isUserData).sort();
+  if (entries.length === 0) return false;
+  const addDir = path.join(projectAbspath, ".add");
+  fs.mkdirSync(addDir, { recursive: true });
+  let restored = false;
+  for (const e of entries) {
+    const dest = path.join(addDir, e);
+    if (fs.existsSync(dest) || isSymlink(dest)) {
+      if (!force) continue;                                 // fill-gaps: never clobber a present entry
+      const bak = dest + ".bak";
+      if (fs.existsSync(bak) || isSymlink(bak)) fs.rmSync(bak, { recursive: true, force: true });
+      fs.renameSync(dest, bak);                             // back up the original BEFORE replacing
+    }
+    fs.cpSync(path.join(src, e), dest, { recursive: true, dereference: true });   // deref symlinks
+    restored = true;
+  }
+  return restored;
+}
+
+// init --from-global-data: rehydrate user-data after the per-project drop. Resolves the SAME
+// realpath the snapshot key uses. The home is verified BEFORE the drop (no_global_home fails fast,
+// in cmdInit). An unwritable dest -> restore_failed; a missing snapshot is an honest skip.
+function installGlobalDataRestore(chosenTarget, force) {
+  const home = resolveGlobalHome(process.env);
+  let resolved = chosenTarget;
+  try { resolved = fs.realpathSync(chosenTarget); } catch (_e) { /* fall back to the abspath */ }
+  const snap = path.join(home, "data", dataKey(resolved));
+  let restored;
+  try { restored = restoreData(home, resolved, force); }
+  catch (e) {
+    fail("restore_failed: cannot write restored data into " + path.join(resolved, ".add") +
+         " — " + (e && e.message ? e.message : e));
+  }
+  if (restored) log("  ✓ restored data <- " + snap);
+  else log("  (no snapshot for this project at " + snap + " — nothing restored)");
+}
+
+// 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.
+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 dataDir = path.join(home, "data");
+  if (!fs.existsSync(dataDir)) return { orphans: [], removed: [] };
+  const orphans = fs.readdirSync(dataDir).filter((name) => {
+    try { return fs.statSync(path.join(dataDir, name)).isDirectory() && !live.has(name); }
+    catch (_e) { return false; }
+  }).sort();
+  const removed = [];
+  if (force) {
+    for (const key of orphans) {
+      fs.rmSync(path.join(dataDir, key), { recursive: true, force: true });
+      removed.push(key);
+    }
+  }
+  return { orphans: orphans, removed: removed };
+}
+
+// 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.
+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");
+  }
+  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; }
+  for (const key of result.orphans) log("  orphan: " + key);
+  log("  " + result.orphans.length + " orphan(s); re-run with --force to remove");
+}
+
 // init --global: install the managed layer ONCE to the shared home + register this project,
 // fail-closed BEFORE the per-project drop. Returns the resolved target for the normal drop.
 function installGlobal(args, chosenTarget) {
@@ -924,34 +1080,83 @@ function installGlobal(args, chosenTarget) {
 
 // update --global: refresh the home mirror + skill, then propagate to every registered+existing
 // project via reconcile(.., home); prune vanished projects (warn) + rewrite the registry atomically.
+// True iff path.normalize(p) is an EXISTING ADD project (a dir containing .add/). The is-.add/
+// backstop: a managed-file reconcile NEVER lands in a dir without a .add/ marker. Absoluteness is
+// the SEPARATE LOUD gate in cmdUpdateGlobal (a relative path is the traversal vector). pip twin:
+// _installer.py:_valid_registry_path.
+function validRegistryPath(p) {
+  const np = path.normalize(String(p));
+  try { return fs.statSync(np).isDirectory() && fs.statSync(path.join(np, ".add")).isDirectory(); }
+  catch (_e) { return false; }
+}
+
+// Serialize `update --global` with an EXCLUSIVE lockfile (O_CREAT|O_EXCL via the "wx" flag).
+// Already held -> update_in_progress (fail-fast). Released on process exit (normal completion OR
+// fail()'s process.exit), so it never outlives the run; a hard crash may leave a stale lock to
+// remove by hand. pip twin: _installer.py:_update_lock (the SAME O_EXCL lockfile, cross-compatible).
+function acquireUpdateLock(home) {
+  fs.mkdirSync(home, { recursive: true });
+  const lockPath = path.join(home, LOCK_FILE);
+  let fd;
+  try { fd = fs.openSync(lockPath, "wx"); }
+  catch (e) {
+    if (e && e.code === "EEXIST") {
+      fail("update_in_progress: another `update --global` is already running — retry shortly " +
+           "(remove " + lockPath + " if it is stale)");
+    }
+    throw e;
+  }
+  const release = () => {
+    try { fs.closeSync(fd); } catch (_e) {}
+    try { fs.unlinkSync(lockPath); } catch (_e) {}
+  };
+  process.on("exit", release);   // covers normal completion AND fail()'s process.exit
+  return release;
+}
+
 function cmdUpdateGlobal(args) {
   const home = resolveGlobalHome(process.env);
   const claudeDir = claudeSkillsDir(process.env);
   if (!fs.existsSync(path.join(home, STAMP_FILE))) {
-    fail("no global ADD install at " + home + " (.add-version not found) — run `init --global` first");
+    fail("no_global_home: no global ADD install at " + home + " (.add-version not found) — run `init --global` first");
   }
+  acquireUpdateLock(home);   // exclusive; EEXIST -> update_in_progress; released on process exit
   // Read the registry BEFORE refreshing the home — a corrupt registry fails closed with ZERO
   // writes (never a silent empty-list no-op), leaving the file for the user to fix or delete.
   let reg;
   try { reg = readRegistry(home); }
-  catch (_e) { fail("global registry " + registryPath(home) + " is corrupt — fix or delete it; not propagating"); }
+  catch (_e) { fail("registry_corrupt: global registry " + registryPath(home) + " is corrupt — fix or delete it; not propagating"); }
+  // PRE-SCAN (security): a NON-ABSOLUTE entry is the traversal vector -> abort with zero mutations.
+  for (const p of reg) {
+    if (!path.isAbsolute(p)) {
+      fail("unsafe_registry_path: registered project '" + p + "' is not an absolute path — fix or remove it in " + registryPath(home) + "; not propagating");
+    }
+  }
   try { reconcileGlobal(home, claudeDir, args.noSkill); }
   catch (e) { fail("cannot write global home " + home + " — " + (e && e.message ? e.message : e)); }
   const version = pkgVersion();
   writeStamp(home, version, "global");
   const kept = [];
-  let pruned = 0;
+  let pruned = 0, dropped = 0;
   for (const p of reg) {
-    if (!fs.existsSync(p)) { log("  ⚠ registered project " + p + " not found — pruning"); pruned++; continue; }
-    reconcile(args, p, home);     // standard MANAGED map, sourced from the home mirror
+    const np = path.normalize(p);   // absolute (pre-scan) -> lexically normalized
+    if (!fs.existsSync(np)) { log("  ⚠ registered project " + np + " not found — pruning"); pruned++; continue; }
+    if (!validRegistryPath(np)) {   // exists but no .add/ -> NEVER reconcile managed files into it
+      log("  ⚠ registered path " + np + " is not an ADD project (no .add/) — dropping"); dropped++; continue;
+    }
+    reconcile(args, np, home);      // standard MANAGED map, sourced from the home mirror
+    seedGitignore(np);               // keep .add/.gitignore current too (parity: _installer.py)
     // re-persist an opted-in project (one that already has a snapshot); a vanished
     // project's snapshot is KEPT above (the backup outlives the dir).
-    if (fs.existsSync(path.join(home, "data", dataKey(p)))) persistData(home, p);
-    kept.push(p);
+    if (fs.existsSync(path.join(home, "data", dataKey(np)))) persistData(home, np);
+    kept.push(np);                  // store the NORMALIZED path (heals a bent legit entry)
   }
   writeRegistry(home, kept);
+  const bits = [];
+  if (pruned) bits.push(pruned + " pruned");
+  if (dropped) bits.push(dropped + " dropped");
   log("ADD " + version + " · global home + " + kept.length + " project(s) reconciled" +
-      (pruned ? " (" + pruned + " pruned)" : "") + ".");
+      (bits.length ? " (" + bits.join(", ") + ")" : "") + ".");
 }
 
 function cmdUpdate(args) {
@@ -974,7 +1179,10 @@ function cmdUpdate(args) {
   // same-version no-op ONLY when nothing is missing — a missing managed tree HEALS
   // even at the current version (heal-reconcile).
   const status = managedStatus(target);
-  const missing = MANAGED.some(([sub]) => status[sub] === "missing");
+  // An optional tree absent from BOTH the package and the project can't be healed, so it
+  // never counts as "missing" — otherwise a same-version update would never reach the no-op.
+  const missing = MANAGED.some(([sub]) => status[sub] === "missing"
+    && !(OPTIONAL.has(sub) && !fs.existsSync(path.join(PKG_ROOT, sub))));
   if (cur === version && !args.force && !missing) {
     log("ADD already at " + version + " — nothing to update (use --force to re-materialize).");
     return;
@@ -984,12 +1192,13 @@ function cmdUpdate(args) {
   if (fs.existsSync(stateFile)) {
     fs.copyFileSync(stateFile, path.join(addDir, "pre-update-state.bak.json"));
   }
-  reconcile(args, target);
+  const roll = reconcile(args, target);
   seedSoulMd(target);   // pip parity: re-seed a missing user-owned SOUL.md (never clobber)
   seedGitignore(target);   // pip parity: seed/append-if-absent the engine-transient ignore lines
   writeStamp(addDir, version);
   log("ADD updated " + (cur || "(unstamped)") + " -> " + version +
-      " · managed layer reconciled · your project state untouched.");
+      " · managed layer reconciled (" + roll.restored + " restored · " + roll.refreshed +
+      " refreshed) · your project state untouched.");
 }
 
 async function main() {
@@ -1003,16 +1212,21 @@ async function main() {
     case "update":
       cmdUpdate(args);
       break;
+    case "prune-data":
+      cmdPruneData(args);
+      break;
     case "help":
     case "--help":
-      log("usage: npx @pilotspace/add <init|update> [targetDir] [--force] [--check] [--no-skill] [--global] [--yes|--non-interactive]");
+      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("          (--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("          (--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;
     default:
       fail("unknown command '" + cmd + "'. Try: npx @pilotspace/add init");

package/docs/02-the-flow.md

@@ -93,7 +93,7 @@ The flow runs in two directions under two rules that never conflict. **Backward
 | 6 Verify | own the residue (security · concurrency · architecture); approve when `conservative` | gather evidence; **auto-PASS on complete evidence** under `autonomy: auto` |
 | 7 Observe | read the signal; consolidate confirmed deltas into PROJECT.md | run behind a flag; emit lessons learned |
 
-**What the human sees when it is their turn — the decision arc.** Whenever the flow stops for the human — the baseline approval that ends setup, the contract-freeze decision point and an escalated verify gate within each task, and the wider decision points of the loop (intake · scope · milestone close · stage graduation) — the AI opens its report with the **decision arc**: three engine-sourced lines — `goal:` the milestone goal the work serves · `done:` the proven progress toward it · `plan:` what comes next. The arc renders first, above the report's summary, so the human confirms with sight of the whole trajectory rather than a local snapshot. Within that report the AI also presents the **DECISION** itself as a **guided choice** — one highlighted **recommended pick** (`▶ … (recommended)`) plus its real, described alternatives — so the human chooses with the recommendation and each option's consequence in view rather than a bare next-step line. Both are presentation only — they never add a gate or change an outcome, and the guided choice fires at human gates only. See [Appendix C](./appendix-c-glossary.md) and the `add` skill's `report-template.md` for the convention itself.
+**What the human sees when it is their turn — the decision banner and arc.** Whenever the flow stops for the human — the baseline approval that ends setup, the contract-freeze decision point and an escalated verify gate within each task, and the wider decision points of the loop (intake · scope · milestone close · stage graduation) — the AI opens its report with a **banner** (`PLAN · <title> · <gate> → APPROVE?` plus a file-path line) and the **decision arc**: three engine-sourced lines — `goal:` the milestone goal the work serves · `done:` the proven progress toward it · `plan:` what comes next. The arc renders above the report's summary, so the human confirms with sight of the whole trajectory rather than a local snapshot. Within that report the AI also presents **APPROVE** itself as a **guided choice** — one highlighted **recommended pick** (`▶ … (recommended)`) plus its real, described alternatives — so the human chooses with the recommendation and each option's consequence in view rather than a bare next-step line. Both are presentation only — they never add a gate or change an outcome, and the guided choice fires at human gates only. See [Appendix C](./appendix-c-glossary.md) and the `add` skill's `report-template.md` for the convention itself.
 
 ## What survives, and what is disposable
 

package/docs/03-step-1-specify.md

@@ -35,6 +35,10 @@ Four parts, kept short:
 
 Naming the errors matters. "Reject bad amounts" is an instruction to guess; `amount <= 0 -> "amount_invalid"` is a rule that produces a testable scenario and a defined contract response.
 
+### Rule IDs (optional — opt-in by usage)
+
+Give each Must a stable `M<n>:` ID; a Reject's own error code already IS its ID (referenced later as `R:<error_code>`). Once a task uses a tag anywhere in §2 SCENARIOS or §4 TESTS, `add.py check` starts asking that every Must/Reject be covered by a scenario tag or a test's `covers:` line — a task that never tags anything is never retro-flagged. See the template's own inline example for the exact grammar.
+
 ## Template
 
 ```

package/docs/04-step-2-scenarios.md

@@ -58,6 +58,10 @@ Scenario: not my account
 
 The `And no balance changes` line is doing real work: it specifies that a rejected transfer must leave the world untouched — a property the AI could easily violate by deducting before checking.
 
+### Tagging back to a rule ID (optional — opt-in by usage)
+
+If §1's Musts and Rejects carry stable IDs (`M1:`, and a Reject's own error code as `R:<error_code>`), tag each `Scenario:` line with the ID(s) it covers, e.g. `# M1, R:amount_invalid`. Once a task tags even one scenario this way, `add.py check` starts confirming every §1 ID is covered by a tag here or a `covers:` line in §4 TESTS — a task that never tags anything is left alone. See the template's own inline example for the exact grammar.
+
 ## Cover the edge cases
 
 The transfer above is one domain; the same gaps recur in every domain — an HR leave request, a marketing campaign send, a checkout. Beyond the spec's "Reject" rules, sweep the recurring gaps and add a scenario for each that applies (or rule it out on purpose): boundary, duplicate/idempotent, ownership, stale/out-of-order, partial failure, concurrency, malformed input, limits/volume.

package/docs/06-step-4-tests.md

@@ -50,6 +50,10 @@ def test_not_my_account():
 
 Run this now, with no implementation: all three fail. That is the correct, honest starting point for the build.
 
+### Declaring which rule a test covers (optional — opt-in by usage)
+
+If §1's Musts and Rejects carry stable IDs, add a trailing `covers: M1, R:amount_invalid` to a test-plan line to declare which ID(s) that test satisfies. Once any test in a task declares a `covers:` line (or any §2 scenario carries a tag), `add.py check` confirms every §1 ID is covered by a tag or a `covers:` line somewhere — a task that never uses either is left alone. See the template's own inline example for the exact grammar.
+
 ## The AI's role here
 
 The AI generates the test suite from the scenarios and contract. Your job is to confirm two things it cannot judge for itself: that each test asserts *behavior* rather than internal detail, and that none of them pass by accident before code exists. See `playbook/4_tests.md` in [Appendix B](./appendix-b-prompts.md).

package/docs/17-components.md

@@ -24,11 +24,11 @@ guess. You name them in `.add/components.toml`:
 ```toml
 [component.gateway]
 root      = "apps/gateway"
-green-bar = "pytest + pyright"
+green_bar = "pytest + pyright"
 
 [component.dashboard]
 root      = "apps/web"
-green-bar = "vitest + a11y"
+green_bar = "vitest + a11y"
 ```
 
 Each component owns a **root** (the source subtree it governs) and a
@@ -49,6 +49,13 @@ the right suite for the bound component; the gate checks the **right bar was
 cited** in the evidence. Two tasks, one milestone, two green bars — each held to
 its own.
 
+At the gate the engine also **surfaces** the bound component's `verify` command —
+the literal suite to run (e.g. `pytest -q`) — beside the expected green-bar, and
+records it in the §6 gate record so the ledger shows which suite backed the gate.
+It prints *what* to run; it never runs it (NO-EXEC). In the fast lane the same
+`component:` affordance is available, so a small task in a monorepo can bind a
+component and get its bar and `verify` surfaced too.
+
 ## Freeze a contract between components
 
 When one component produces an interface another consumes, that boundary needs a
@@ -83,6 +90,15 @@ frontend proceeds and pins it. The slice is **ordered by the frozen contract**,
 all inside one milestone — the FE stays downstream of the BE endpoint, not split
 into a later milestone.
 
+The hold checks more than existence. Even once a snapshot exists, if a live
+producer task has *re-opened or drifted* its §3 — the snapshot no longer matches
+a frozen producer — the consumer is held `producer_contract_stale` rather than
+pinning a shape that is mid-change (the freeze-recency guard). Outside the hold,
+`add.py check` surfaces the softer `contract_producer_stale` (a live producer
+drifted past a pinned consumer) and `contract_snapshot_hashless` (a snapshot
+carrying no hash to verify against) as **never-red warnings** — measured and
+reported, never blocking.
+
 ## Across repositories: federation
 
 Components in separate repositories work the same way; only the
@@ -99,9 +115,11 @@ pin    = "v1"        # optional — the version this repo expects
 matching id, a hash, and — if `pin` is set — a matching version), and lands a
 **byte-for-byte copy** at the local `.add/contracts/gateway-api.json`. From
 there, the consuming repo's task holds and pins exactly as in a monorepo. The
-pull is **fail-loud by design**: an unknown id, an unreadable source, an invalid
-snapshot, or a version mismatch each HARD-STOPS and lands nothing — federation
-never builds an FE against a guessed or stale endpoint. The producer's snapshot
+pull is **fail-loud by design**: an unknown id, an unreadable source, a `source`
+that **escapes the consumer repo's allowlist** (`federation_source_escapes` — the
+path is confined to a sibling of the repo root, so a `../../etc`-style traversal
+lands nothing), an invalid snapshot, or a version mismatch each HARD-STOPS — federation
+never builds an FE against a guessed, out-of-tree, or stale endpoint. The producer's snapshot
 is the published artifact; "publishing" is committing that file in the producer
 repo. Each repo keeps its own git-native `state.json`; federation transports only
 the immutable frozen shape, never shared mutable state.

package/docs/18-personas.md

@@ -0,0 +1,80 @@
+# 18 · Personas — the project-fit learning loop
+
+[← 17 Components](./17-components.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)
+
+---
+
+A **persona** is a project-fit requirements lens the agent adopts so its work matches *this*
+codebase's standards instead of a generic default. It is not a chat costume: a persona is a small,
+versioned file under `.add/personas/<slug>.md` with three machine-readable parts —
+
+- **Identity** — the stance the worker takes (e.g. *a payments engineer who treats money as exact*).
+- **Critical Rules** — the constraints that must hold (the non-negotiables for this domain).
+- **Success Metrics** — the measurable done-bar (what "good" looks like, in numbers where it can).
+
+The **persona loop** is how those files come to exist, improve, and get used: **seed → grow →
+apply**. The loop is opt-in and additive — a project with no personas behaves exactly as before.
+
+## Where personas come from — the teacher
+
+ADD does not invent personas from nothing. It learns them from a **teacher**: a corpus of worked
+agent definitions that ADD ships as a vendored local library at `.add/personas-teacher/`.
+The teacher is read **off-build**, by the AI, while drafting a persona — it is a *source of ideas*,
+**never a runtime dependency**: nothing in the engine imports it, fetches it, or needs it present to
+run. You distil a teacher entry down to the three-part shape above and commit the result; from then
+on the project owns that persona outright.
+
+## Seed — at setup
+
+The first personas are **seeded** during project setup, from the foundation (`PROJECT.md`'s domain
+and standards). Setup proposes a starter persona or two that fit the project's domain; the human
+confirms. Seeding writes `.add/personas/<slug>.md` and nothing else — no behaviour changes until a
+task actually applies one.
+
+## Grow — observe → delta → consolidate
+
+Personas are **living documents**: they improve through the same loop the foundation uses. In a
+task's **observe** phase the AI emits a **persona delta** — a one-line, tagged proposal to add or
+sharpen a critical-rule or success-metric, written `open` with evidence (just like a lesson learned).
+At a retrospective the human **consolidates** confirmed deltas into the persona file (the same
+`fold` step the foundation uses), bumping it forward. The consolidation is judgment-free
+transcription: the engine routes a confirmed delta into the named
+persona's `## Critical Rules` or `## Success Metrics` section and **never clobbers** existing content.
+So a persona gets *more* accurate every milestone instead of drifting.
+
+## Apply — three surfaces
+
+A seeded, grown persona earns its keep when work adopts it. Three surfaces apply a persona, and all
+three treat it the same way — as **advice**, never authority:
+
+- **UDD (design).** At the design-definition loop a persona frames the requirements lens: which
+  rules and metrics a UI/UX slice must satisfy for this project's users.
+- **advisor / streams (delegation).** When you delegate a piece of your plan to a subagent, its
+  `<persona>` block **selects** the best-fit `.add/personas/<slug>.md` and the returned verdict
+  **records** which persona did the work. The independent earned-green refute-read selects a
+  **Code-Reviewer** persona whose findings carry severity markers — 🔴 blocker · 🟡 concern · 💭 note.
+  The same canonical persona body rides every runner (Claude, Cursor, Copilot, Codex), so a
+  **cross-runner subagent** behaves identically wherever it is spawned.
+- **build (overlay).** While building, the orchestrating agent may load the active persona as a
+  domain identity **overlay** layered on `SOUL.md`: SOUL is the voice and trust rules; the persona is
+  the domain stance. The overlay **never rewrites** SOUL.md (it is human-owned) and never overrides a
+  trust rule.
+
+## The non-negotiable — a persona never lowers a gate
+
+A persona changes *how carefully* the work is done; it never changes *what passes*. This is the one
+hard rule across every surface:
+
+- A **security** finding is always a **HARD-STOP**, whatever persona was adopted.
+- High-risk scope still escalates to the human; a stronger persona never buys back a gate.
+- The engine stays **NO-EXEC** throughout: it never spawns a subagent, never runs a persona, never
+  reads one on the build path. Selecting, loading, and applying a persona is the orchestrating
+  agent's judgment — the engine only records what was used (for the audit trail) and measures that
+  the record is present; it never auto-passes on a persona's say-so.
+
+In short: a persona makes the agent *fit the project*. Direction, freezing, evidence, and the gate
+are exactly as strict as they were before — the loop adds expertise, not permission.
+
+---
+
+[← 17 Components](./17-components.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)