@pilotspace/add 1.5.0 → 1.7.0

package/bin/cli.js

@@ -4,7 +4,7 @@
 /**
  * @pilotspace/add installer.
  *
- *   npx @pilotspace/add init [targetDir] [--force] [--stage <stage>] [--name <name>]
+ *   npx @pilotspace/add init [targetDir] [--force] [--stage <stage>] [--name <name>] [--yes|--non-interactive]
  *
  * Installs the ADD skill + tooling + book into a target project:
  *   <target>/.claude/skills/add/   (the skill Claude loads)
@@ -15,12 +15,18 @@
  * to a CLI user. A pre-run plain init would grandfather-lock the gate before `/add` runs
  * AND consume the brownfield signal in the terminal, where the AI never sees it.
  *
- * Zero npm dependencies, no Python needed at install time. Designed for failure:
- * verifies sources exist before copying, never clobbers an existing skill.
+ * One lazy, optional dependency (@clack/prompts) powers the interactive flow on a real
+ * terminal; it is dynamic-import()ed ONLY on that path, so a non-interactive / CI run
+ * (and the `--yes` / `--non-interactive` path) never loads it and degrades to plain text
+ * if it is missing. No Python needed at install time. Designed for failure: verifies
+ * sources exist before copying, never clobbers an existing skill, never throws on a
+ * non-TTY or a failed clack import.
  */
 
 const fs = require("fs");
 const path = require("path");
+const os = require("os");
+const crypto = require("crypto");
 
 const PKG_ROOT = path.resolve(__dirname, "..");
 
@@ -32,11 +38,26 @@ function parseArgs(argv) {
   // stage/name stay null unless EXPLICITLY passed — the engine's own `init`
   // 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, stage: null, name: null };
+  const args = { _: [], force: false, check: false, noSkill: false, stage: null, name: null,
+                 yes: false, nonInteractive: false, global: false, globalData: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--force") args.force = true;
     else if (a === "--check") args.check = true;
+    // --global: ALSO install the managed layer to a shared home + register this project
+    // (the per-project self-contained drop still runs). update --global refreshes all.
+    else if (a === "--global") args.global = true;
+    // --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;
+    // --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;
+    else if (a === "--non-interactive") args.nonInteractive = true;
+    // --no-skill: drop the engine + book 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.
+    else if (a === "--no-skill") args.noSkill = true;
     else if (a === "--stage" || a === "--name") {
       const v = argv[++i];
       // fail loudly on a trailing/abutting flag — never silently drop a value
@@ -50,64 +71,217 @@ function parseArgs(argv) {
   return args;
 }
 
-function copyDir(src, dest, { skipIfExists, cleanReplace } = {}) {
-  if (!fs.existsSync(src)) fail("missing packaged source: " + src);
-  if (skipIfExists && fs.existsSync(dest)) {
-    warn(dest + " exists — leaving it untouched");
-    return;
-  }
-  // Clean replace: drop a stale dest before copying so a `--force` re-install can
-  // never leave orphaned files from a previous version behind. fs.cpSync merges
-  // (it never removes), so without this `--force` is a merge, not a replace. Mirrors
-  // _installer.py's `shutil.rmtree(skill_dest)` so npm and pip behave identically.
-  if (cleanReplace && fs.existsSync(dest)) {
-    fs.rmSync(dest, { recursive: true, force: true });
+// --- agent detection: which coding agent is invoking the installer -----------
+// ORDERED registry; detectAgent walks it top->bottom, first match wins, `generic` is
+// the fallback. Mirror of _installer.py:AGENT_PROFILES. The per-agent env SIGNAL is
+// best-effort (a mis-detect degrades to generic + is overridable in the clack confirm)
+// — refine via a SPEC delta, never a hard fail.
+const GENERIC_NEXT =
+  "open your AI Agent CLI (like Claude Code, Codex, etc.), then run `/add`, and " +
+  "say what you want to build — the agent sets up the foundation, sizes it into a " +
+  "milestone, and drives the build with you; you sign off once, at the lock-down.";
+
+const AGENT_PROFILES = [
+  { id: "claude", label: "Claude Code / Claude app", integration_file: "CLAUDE.md",
+    env: ["CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT"], envPrefix: null,
+    next_step: "Open Claude Code and run `/add` — the skill drives intake -> milestone -> build." },
+  { id: "codex", label: "Codex", integration_file: "AGENTS.md",
+    env: ["CODEX_HOME"], envPrefix: "CODEX_",
+    next_step: "Open Codex — it reads AGENTS.md; run `/add` or say what you want to build." },
+  { id: "opencode", label: "OpenCode", integration_file: "AGENTS.md",
+    env: ["OPENCODE"], envPrefix: "OPENCODE",
+    next_step: "Open OpenCode — it reads AGENTS.md; say what you want to build." },
+  { id: "generic", label: "your AI agent", integration_file: "AGENTS.md",
+    env: [], envPrefix: null, next_step: GENERIC_NEXT },
+];
+
+// The SAME markers add.py:sync-guidelines uses, so init's sync-guidelines REPLACES this
+// drop-time pointer in place (one block, never a duplicate).
+const GUIDE_BEGIN = "<!-- ADD:BEGIN — managed by `add.py sync-guidelines`; do not edit inside -->";
+const GUIDE_END = "<!-- ADD:END -->";
+
+function profileMatches(profile, env) {
+  for (const key of profile.env) { if (env[key]) return true; }
+  if (profile.envPrefix) {
+    for (const k of Object.keys(env)) {
+      if (env[k] && k.startsWith(profile.envPrefix)) return true;
+    }
   }
-  fs.mkdirSync(path.dirname(dest), { recursive: true });
-  fs.cpSync(src, dest, { recursive: true });
+  return false;
 }
 
-function cmdInit(args) {
-  const target = path.resolve(args._[0] || ".");
-  if (!fs.existsSync(target)) fail("target directory does not exist: " + target);
-  log("Installing ADD into " + target);
+// Pure, total, deterministic: same env -> same profile; never throws. Generic is last.
+function detectAgent(env) {
+  const generic = AGENT_PROFILES[AGENT_PROFILES.length - 1];
+  for (const profile of AGENT_PROFILES.slice(0, -1)) {
+    if (profileMatches(profile, env)) return profile;
+  }
+  return generic;
+}
 
-  // 1. skill -> .claude/skills/add
-  copyDir(
-    path.join(PKG_ROOT, "skill", "add"),
-    path.join(target, ".claude", "skills", "add"),
-    { skipIfExists: !args.force, cleanReplace: args.force }
+function agentPointerBlock(profile) {
+  return (
+    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" +
+    "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" +
+    profile.next_step + "\n" +
+    "\n" +
+    "This pointer is replaced by the full guideline block when `add.py sync-guidelines`\n" +
+    "runs (at `/add`->init). Edit outside the markers, not inside.\n" +
+    GUIDE_END
   );
-  log("  ✓ skill      -> .claude/skills/add/");
-
-  // 2. tooling -> .add/tooling  (exclude tests from the installed copy)
-  const toolingDest = path.join(target, ".add", "tooling");
-  copyDir(path.join(PKG_ROOT, "tooling"), toolingDest, { skipIfExists: false });
-  // installed copy is runtime-only: drop ALL test files and any compiled cache
-  // (glob test_*.py — not just test_add.py — so no test leaks into installs)
-  fs.rmSync(path.join(toolingDest, "__pycache__"), { recursive: true, force: true });
-  for (const entry of fs.readdirSync(toolingDest)) {
-    if (/^test_.*\.py$/.test(entry)) {
-      fs.rmSync(path.join(toolingDest, entry), { force: true });
+}
+
+// Inject the ADD pointer into <target>/<integration_file>, mirroring add.py:_inject_block.
+// created|updated|unchanged|skipped. Only the marked region is (re)written; content outside
+// the markers is preserved; a real change backs up <file>.bak first. Fail-soft (warn+skip).
+function writeAgentPointer(target, profile) {
+  const dest = path.join(target, profile.integration_file);
+  const block = agentPointerBlock(profile);
+  try {
+    if (fs.existsSync(dest)) {
+      const current = fs.readFileSync(dest, "utf8");
+      const begin = current.indexOf(GUIDE_BEGIN);
+      let next;
+      if (begin !== -1) {
+        const endIdx = current.indexOf(GUIDE_END, begin);
+        if (endIdx !== -1) {
+          next = current.slice(0, begin) + block + current.slice(endIdx + GUIDE_END.length);
+        } else {                       // begin with no end: corrupt — append fresh
+          next = current.replace(/\n+$/, "") + "\n\n" + block + "\n";
+        }
+      } else {                         // no block yet — append, keep user content
+        next = current.replace(/\n+$/, "") + "\n\n" + block + "\n";
+      }
+      if (next === current) return "unchanged";
+      fs.writeFileSync(dest + ".bak", current);   // rollback path before mutate
+      fs.writeFileSync(dest, next);
+      return "updated";
     }
+    fs.writeFileSync(dest, block + "\n");
+    return "created";
+  } catch (e) {
+    warn("could not write " + profile.integration_file + " — " +
+         (e && e.message ? e.message : e) + "; skipped");
+    return "skipped";
   }
-  log("  ✓ tooling    -> .add/tooling/add.py (+ templates)");
+}
 
-  // 3. docs (the book / trust layer) -> .add/docs
-  copyDir(path.join(PKG_ROOT, "docs"), path.join(target, ".add", "docs"),
-    { skipIfExists: false });
-  log("  ✓ trust docs -> .add/docs/ (the AIDD book)");
+// --- interactive layer (clack on a real TTY; plain text everywhere else) -----
+// Designed-for-failure: any doubt (non-TTY, CI, --yes, a failed import, an
+// un-promptable stream) degrades to the EXACT plain-text path below. The clack
+// import is dynamic + lazy (clack 1.x is ESM-only) so a non-interactive / CI run
+// never loads it. A test seam (ADD_INSTALLER_FORCE_INTERACTIVE) reaches the branch
+// without a PTY: "1" forces interactive, "fail" forces it but throws on import.
+
+function interactive(args) {
+  if (args.yes || args.nonInteractive) return false;       // explicit opt-out wins
+  const seam = process.env.ADD_INSTALLER_FORCE_INTERACTIVE;
+  if (seam === "1" || seam === "fail") return true;        // documented test seam
+  return Boolean(process.stdout.isTTY && process.stdin.isTTY) && !process.env.CI;
+}
+
+async function loadClack() {
+  // honors the "fail" seam so the clack_unavailable fallback is testable without
+  // uninstalling the dependency.
+  if (process.env.ADD_INSTALLER_FORCE_INTERACTIVE === "fail") {
+    throw new Error("forced clack import failure (test seam)");
+  }
+  return import("@clack/prompts");
+}
+
+// Returns { cancelled, target }. A cancel happens BEFORE any file is written, so a
+// cancelled run leaves the target untouched. Without a real TTY to read (the forced
+// test seam), we cannot prompt — abort safely rather than hang.
+async function runClackPreamble(clack, target, detected) {
+  clack.intro("ADD — AI-Driven Development");
+  if (!process.stdin.isTTY) return { cancelled: true, target: target };
+  const chosen = await clack.text({
+    message: "Install ADD into which directory?",
+    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?" });
+  if (clack.isCancel(ok) || !ok) return { cancelled: true, target: target };
+  // agent-detect STEP (seeded delta: a STEP in THIS flow, via the clack ui layer) — the
+  // user confirms or overrides the detected agent before any file is written.
+  const picked = await clack.select({
+    message: "Set up for which agent? (detected: " + detected.label + ")",
+    options: AGENT_PROFILES.map((p) => ({ value: p.id, label: p.label })),
+    initialValue: detected.id,
+  });
+  if (clack.isCancel(picked)) return { cancelled: true, target: target };
+  const profile = AGENT_PROFILES.find((p) => p.id === picked) || detected;
+  return { cancelled: false, target: String(chosen || target), profile: profile };
+}
+
+// The drop — now a RECONCILE: restore missing managed trees + refresh present ones
+// (sweep orphans) + report per-tree status. Byte-compatible handoff with the prior
+// installer. The interactive path resolves a target then calls straight into this.
+function dropFiles(args, target, profile) {
+  profile = profile || detectAgent(process.env);
+  log("Installing ADD into " + target);
+  reconcile(args, target);
+
+  // Agent detection: write THE detected agent's integration file (a marker-delimited
+  // pointer init's sync-guidelines later supersedes) + tailor the closing next-step.
+  // Best-effort + fail-soft — never aborts the successful drop above.
+  writeAgentPointer(target, profile);
 
   // 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. The `add` skill + tooling are installed (no project state yet — that's intentional).");
-  log("Next:  open your AI Agent CLI (like Claude Code, Codex, etc.), then run `/add`, and say what you want to build — the agent");
-  log("       sets up the foundation, sizes it into a milestone, and drives the build with you;");
-  log("       you sign off once, at the lock-down.");
+  log("\nDone. " + (args.noSkill ? "The engine + book are" : "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
+    log("Next:  open your AI Agent CLI (like Claude Code, Codex, etc.), then run `/add`, and say what you want to build — the agent");
+    log("       sets up the foundation, sizes it into a milestone, and drives the build with you;");
+    log("       you sign off once, at the lock-down.");
+  } else {
+    log("Detected " + profile.label + ".");
+    log("Next:  " + profile.next_step);
+  }
   log("");
 }
 
+async function cmdInit(args) {
+  const target = path.resolve(args._[0] || ".");
+  if (!fs.existsSync(target)) fail("target directory does not exist: " + target);
+
+  let chosenTarget = target;
+  let profile = detectAgent(process.env);     // default: non-interactive / fallback
+  if (interactive(args)) {
+    let clack = null;
+    try { clack = await loadClack(); }
+    catch (_e) { warn("clack unavailable — falling back to plain-text install"); }
+    if (clack) {
+      const outcome = await runClackPreamble(clack, target, profile);
+      if (outcome.cancelled) {
+        // the exit code IS the contract; a closed-pipe stdout (EPIPE) must not
+        // mask the cancel — guard the courtesy message, never let it throw.
+        try { clack.cancel("Installation cancelled — nothing was written."); }
+        catch (_e) { /* stdout unavailable (e.g. closed pipe) — exit code carries it */ }
+        process.exit(130);                // user_cancelled: nothing written
+      }
+      chosenTarget = path.resolve(outcome.target);
+      if (!fs.existsSync(chosenTarget)) fail("target directory does not exist: " + chosenTarget);
+      if (outcome.profile) profile = outcome.profile;   // honor the user's override
+    }
+  }
+  if (args.globalData) args.global = true;   // --global-data implies --global (need a home)
+  // 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);
+  // OPT-IN data persist, AFTER the drop (one-way snapshot of existing user-data).
+  if (args.globalData) installGlobalData(chosenTarget);
+}
+
 // --- update: re-materialize the managed layer without a re-install -----------
 // The managed trees (ship-controlled). `update` clean-replaces each, so a file removed
 // upstream leaves no orphan — and never touches .add/state.json, PROJECT.md, milestones,
@@ -130,11 +304,11 @@ function readStamp(addDir) {
   try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch (_e) { return null; }
 }
 
-function writeStamp(addDir, version) {
+function writeStamp(addDir, version, channel) {
   fs.mkdirSync(addDir, { recursive: true });
   fs.writeFileSync(
     path.join(addDir, STAMP_FILE),
-    JSON.stringify({ version: version, channel: "npm", installed_at: new Date().toISOString() }, null, 2) + "\n"
+    JSON.stringify({ version: version, channel: channel || "npm", installed_at: new Date().toISOString() }, null, 2) + "\n"
   );
 }
 
@@ -151,7 +325,217 @@ function cleanReplaceTree(src, dest, stripTests) {
   }
 }
 
+const TREE_LABEL = { "skill/add": "skill", "tooling": "tooling", "docs": "docs" };
+
+// Per managed tree: "missing" (dest absent OR empty) or "present".
+function managedStatus(target) {
+  const status = {};
+  for (const [sub, destParts] of MANAGED) {
+    const dest = path.join(target, ...destParts);
+    const present = fs.existsSync(dest) && fs.readdirSync(dest).length > 0;
+    status[sub] = present ? "present" : "missing";
+  }
+  return status;
+}
+
+// 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:
+// 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));
+  for (const [sub] of trees) {
+    if (!fs.existsSync(path.join(srcRoot, sub))) {
+      fail("missing packaged source: " + path.join(srcRoot, sub));
+    }
+  }
+  const status = managedStatus(target);
+  for (const [sub, destParts, stripTests] of trees) {
+    cleanReplaceTree(path.join(srcRoot, sub), path.join(target, ...destParts), stripTests);
+    const dest = destParts.join("/");
+    if (status[sub] === "missing") {
+      log("  ✓ restored  " + TREE_LABEL[sub].padEnd(8) + "-> " + dest + "  (was missing)");
+    } else {
+      log("  ✓ refreshed " + TREE_LABEL[sub].padEnd(8) + "-> " + dest);
+    }
+  }
+  return status;
+}
+
+// --- global home: an OPT-IN shared install (engine+book+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) {
+  // ADD_HOME (set, non-empty) -> else XDG_DATA_HOME/add -> else <HOME>/.add. Reads HOME from
+  // the env mapping (never $HOME directly) so tests can inject a hermetic home.
+  env = env || process.env;
+  if (env.ADD_HOME) return path.resolve(env.ADD_HOME);
+  if (env.XDG_DATA_HOME) return path.join(path.resolve(env.XDG_DATA_HOME), "add");
+  return path.join(env.HOME || os.homedir(), ".add");
+}
+
+function claudeSkillsDir(env) {
+  env = env || process.env;
+  return path.join(env.HOME || os.homedir(), ".claude", "skills", "add");
+}
+
+function registryPath(home) { return path.join(home, "registry.json"); }
+
+// [] when ABSENT; THROWS on present-but-corrupt so the caller fails LOUD (never a silent
+// empty-list no-op that quietly skips every registered project).
+function readRegistry(home) {
+  const p = registryPath(home);
+  if (!fs.existsSync(p)) return [];
+  let data;
+  try { data = JSON.parse(fs.readFileSync(p, "utf8")); }
+  catch (_e) { throw new Error("registry_corrupt"); }
+  if (!Array.isArray(data)) throw new Error("registry_corrupt");
+  return data;
+}
+
+// ATOMIC (temp + rename), de-duplicated preserving first-seen order.
+function writeRegistry(home, paths) {
+  fs.mkdirSync(home, { recursive: true });
+  const seen = [];
+  for (const p of paths) { if (!seen.includes(p)) seen.push(p); }
+  const target = registryPath(home);
+  const tmp = target + ".tmp";
+  fs.writeFileSync(tmp, JSON.stringify(seen, null, 2) + "\n");
+  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 package ships) so reconcile(args, project, home) reuses MANAGED unchanged.
+const GLOBAL_TREES = [
+  ["skill/add", ["skill", "add"], false],
+  ["tooling", ["tooling"], true],
+  ["docs", ["docs"], 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) {
+    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) {
+    cleanReplaceTree(path.join(PKG_ROOT, sub), path.join(home, ...destParts), stripTests);
+  }
+  if (!noSkill) cleanReplaceTree(path.join(home, "skill", "add"), claudeDir, false);
+}
+
+// --- 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
+
+// data_key twin: <sanitized-basename>-<sha1(abspath_utf8)[:12]>. Pure · total · separator-free.
+function dataKey(projectAbspath) {
+  const p = String(projectAbspath);
+  const digest = crypto.createHash("sha1").update(p, "utf8").digest("hex").slice(0, 12);
+  const base = (path.basename(p) || "root").replace(/[^A-Za-z0-9._-]/g, "_");
+  return base + "-" + digest;
+}
+
+// A top-level .add/ entry is user-data unless it is a managed tree or a transient artifact.
+function isUserData(name) {
+  if (DATA_EXCLUDE.includes(name)) return false;
+  if (name.startsWith("scope-snapshot")) return false;
+  if (name.includes("pre-archive-bak")) return false;
+  if (name.endsWith(".bak.json")) return false;
+  return true;
+}
+
+// Clean-replace a project's USER-DATA into <home>/data/<key>. true=persisted, false=skipped
+// (no .add or no user-data — an honest skip). Throws if the data dir can't be written.
+function persistData(home, projectAbspath) {
+  const addDir = path.join(projectAbspath, ".add");
+  if (!fs.existsSync(addDir)) return false;
+  const entries = fs.readdirSync(addDir).filter(isUserData);
+  if (entries.length === 0) return false;
+  const dest = path.join(home, "data", dataKey(projectAbspath));
+  if (fs.existsSync(dest)) fs.rmSync(dest, { recursive: true, force: true });
+  fs.mkdirSync(dest, { recursive: true });
+  for (const e of entries) {
+    fs.cpSync(path.join(addDir, e), path.join(dest, e), { recursive: true });
+  }
+  return true;
+}
+
+// init --global-data: persist this project's user-data after the per-project drop. Resolves the
+// SAME realpath the registry uses (so the key matches). Skip+notice when empty; fail on unwritable.
+function installGlobalData(chosenTarget) {
+  const home = resolveGlobalHome(process.env);
+  let resolved = chosenTarget;
+  try { resolved = fs.realpathSync(chosenTarget); } catch (_e) { /* fall back to the abspath */ }
+  let persisted;
+  try { persisted = persistData(home, resolved); }
+  catch (e) {
+    fail("cannot write global data " + path.join(home, "data", dataKey(resolved)) +
+         " — " + (e && e.message ? e.message : e));
+  }
+  if (persisted) log("  ✓ persisted data -> " + path.join(home, "data", dataKey(resolved)));
+  else log("  (no project data to persist yet — run /add to create one, then re-run --global-data)");
+}
+
+// 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) {
+  const home = resolveGlobalHome(process.env);
+  const claudeDir = claudeSkillsDir(process.env);
+  try { reconcileGlobal(home, claudeDir, args.noSkill); }                 // home_unwritable
+  catch (e) { fail("cannot write global home " + home + " — " + (e && e.message ? e.message : e)); }
+  writeStamp(home, pkgVersion(), "global");
+  let reg;
+  try { reg = readRegistry(home); }                                        // registry_corrupt
+  catch (_e) { fail("global registry " + registryPath(home) + " is corrupt — fix or delete it; not registering"); }
+  let resolved = chosenTarget;
+  try { resolved = fs.realpathSync(chosenTarget); } catch (_e) { /* fall back to the abspath */ }
+  reg.push(resolved);
+  try { writeRegistry(home, reg); }                                        // atomic + dedup
+  catch (e) { fail("cannot write global registry " + registryPath(home) + " — " + (e && e.message ? e.message : e)); }
+  log("  ✓ global home ready at " + home);
+  log("  ✓ registered " + resolved + " (registry: " + readRegistry(home).length + ")");
+}
+
+// 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.
+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");
+  }
+  // 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"); }
+  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;
+  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
+    // 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);
+  }
+  writeRegistry(home, kept);
+  log("ADD " + version + " · global home + " + kept.length + " project(s) reconciled" +
+      (pruned ? " (" + pruned + " pruned)" : "") + ".");
+}
+
 function cmdUpdate(args) {
+  if (args.global) return cmdUpdateGlobal(args);
   const target = path.resolve(args._[0] || ".");
   const addDir = path.join(target, ".add");
   if (!fs.existsSync(path.join(addDir, "tooling")) && !fs.existsSync(path.join(addDir, "state.json"))) {
@@ -167,7 +551,11 @@ function cmdUpdate(args) {
     else log("ADD update available: project on " + cur + ", package is " + version + ". Run `update`.");
     return;
   }
-  if (cur === version && !args.force) {
+  // 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");
+  if (cur === version && !args.force && !missing) {
     log("ADD already at " + version + " — nothing to update (use --force to re-materialize).");
     return;
   }
@@ -176,34 +564,37 @@ function cmdUpdate(args) {
   if (fs.existsSync(stateFile)) {
     fs.copyFileSync(stateFile, path.join(addDir, "pre-update-state.bak.json"));
   }
-  for (const [sub, destParts, stripTests] of MANAGED) {
-    cleanReplaceTree(path.join(PKG_ROOT, sub), path.join(target, ...destParts), stripTests);
-  }
+  reconcile(args, target);
   writeStamp(addDir, version);
   log("ADD updated " + (cur || "(unstamped)") + " -> " + version +
-      " · skill · tooling · docs refreshed · your project state untouched.");
+      " · managed layer reconciled · your project state untouched.");
 }
 
-function main() {
+async function main() {
   const argv = process.argv.slice(2);
   const cmd = argv[0] && !argv[0].startsWith("--") ? argv.shift() : "init";
   const args = parseArgs(argv);
   switch (cmd) {
     case "init":
-      cmdInit(args);
+      await cmdInit(args);
       break;
     case "update":
       cmdUpdate(args);
       break;
     case "help":
     case "--help":
-      log("usage: npx @pilotspace/add <init|update> [targetDir] [--force] [--check]");
+      log("usage: npx @pilotspace/add <init|update> [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("          (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)");
       break;
     default:
       fail("unknown command '" + cmd + "'. Try: npx @pilotspace/add init");
   }
 }
 
-main();
+main().catch((e) => fail(e && e.message ? e.message : String(e)));

package/docs/02-the-flow.md

@@ -83,7 +83,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. It is presentation only — it never adds a gate or changes an outcome. See [Appendix C](./appendix-c-glossary.md).
+**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 survives, and what is disposable
 

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.
 
+## 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.
+
 ## The AI's role here
 
 Hand the AI the spec and have it draft a scenario for each rule, including the rejection rules. Then read them as the person who owns the requirement: do they describe what you actually meant? Correct any that drift. See `playbook/2_scenarios.md` in [Appendix B](./appendix-b-prompts.md).
@@ -65,6 +69,7 @@ Hand the AI the spec and have it draft a scenario for each rule, including the r
 ## Common mistakes
 
 - **Only happy-path scenarios.** Every "Reject" rule in the spec needs its own scenario, or that rule will never be verified.
+- **Edge cases left to the build.** A boundary, a duplicate, or a partial failure with no scenario becomes whatever the AI happens to code. Sweep the categories above against the task's domain.
 - **Vague results.** "Then it works" is not checkable. The result must be a specific, observable fact ("A has 70").
 - **Forgetting the unchanged state.** For any rejection, assert that nothing changed; otherwise a partial, corrupting failure can pass.
 
@@ -72,6 +77,7 @@ Hand the AI the spec and have it draft a scenario for each rule, including the r
 
 - [ ] Every "Must" rule has at least one scenario.
 - [ ] Every "Reject" rule has at least one scenario.
+- [ ] The edge-case categories that apply to this task's domain have a scenario (or are ruled out on purpose).
 - [ ] Each scenario's result is a specific, observable fact.
 - [ ] Rejections assert what must stay unchanged.