@pilotspace/add 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -6,6 +6,96 @@ All notable changes to the ADD method (`@pilotspace/add` on npm,
 
 ## [Unreleased]
 
+## [1.14.0] — 2026-06-29
+
+Two milestones round out lanes that shipped partially in earlier releases: the
+**global-home / installer** lane gets its missing inverse + safety, and the
+**component** pillar closes its remaining gaps and hardens its cross-repo edges.
+Installer- and engine-pin-neutral — the ADD engine is byte-identical (ENGINE_MD5
+unchanged); all changes live in the installer twins and the component validator.
+Backward-compatible throughout.
+
+### Added (installer-polish — complete the global lane)
+- **Restore the global home.** `init --from-global-data` (and an `init` that detects a
+  matching `<home>/data/<key>`) rehydrates a project's user-data from the global home on
+  a fresh clone — the non-destructive inverse of the one-way backup. Fill-gaps by default;
+  `--force` writes a `<name>.bak` sidecar before overwriting.
+- **`prune-data` orphan cleanup.** A new `prune-data` command removes home snapshots with
+  no live registry owner — dry-run by default, `--force` to delete. Both installer twins
+  (pip + npm) carry the behavior, byte-for-byte.
+- **`update --global` made safe.** An O_EXCL home lock (`<home>/.update.lock`) serializes
+  concurrent runs **cross-twin** (a pip-held lock blocks an npm run and vice-versa), and
+  every registered path is validated before any write — a relative/traversal entry aborts
+  the whole run loud (`unsafe_registry_path`), a directory without `.add/` is dropped.
+- **Reconcile roll-up.** Every reconcile now reports a file-level `N restored · M refreshed`
+  summary, so a partially-gutted-but-present managed tree's heal is finally visible (it
+  healed silently before). Pure observation — copy semantics are unchanged.
+
+### Added (component-polish — close the pillar gaps + harden the edges)
+- **`add.py components` reader + validator.** A `components.toml` schema-lint surfaces
+  `component_unknown_key` / `component_type_mismatch` / `component_unknown_table` — all
+  measure-not-block warnings at `check`.
+- **Federation hardening.** `federate pull` path-confines the manifest `source` to a
+  sibling-repo allowlist with a fail-closed HARD-STOP (`federation_source_escapes`) before
+  any read; a stale leftover contract snapshot that no longer admits a consumer is surfaced
+  (`producer_contract_stale`, never red).
+- **Registry fill + a worked example.** The component registry round-trips completely, and
+  a full worked example threads the component flow end-to-end in the book.
+
+### Changed
+- Five version sources bump in lockstep to **1.14.0** (`package.json`, `package-lock.json`
+  ×2, `pyproject.toml`, `.claude-plugin/plugin.json`, `add_method.__version__`).
+
+## [1.13.0] — 2026-06-28
+
+Two method milestones make ADD's loop more **self-auditing** and more **honest**:
+the observe step now harvests a decision record automatically, and every flow gate
+is either mechanically enforced or plainly disclosed where it is not. Plus the npm
+release pipeline moves to tokenless **Trusted Publishing**. Backward-compatible
+throughout; nothing retro-changes an existing task or milestone record.
+
+### Added (adr-at-observe — a decision record, harvested not hand-written)
+- **`### Decisions (ADR)` harvested at the gate.** On `add.py gate PASS`, the engine
+  harvests a §7 Architecture-Decision-Record block from §1/§3/§5/§6 — one
+  actor-tagged line per decision (`[AI] specify · [human] freeze · [AI] build ·
+  [human] verify`), refilled only while the placeholder stands (never hand-edited).
+- **`add.py audit` checks the ADR at done.** A done task whose §7 ADR block is unfilled
+  is surfaced — presence-only, never a semantic judgment of the decisions themselves.
+- **Strategy write-back.** The §6 GATE RECORD is stamped with the git actor + date, and
+  the §5 "Strategy actually used" line is harvested into the ADR as the `[AI] build` row.
+
+### Added (flow-honesty — every gate engine-true or honestly disclosed)
+- **Two structural holes became real, forceable gates.** A **universal freeze gate**
+  (`contract_not_frozen` fires for every task at tests→build, with a recorded
+  `--skip-freeze` escape) and a **delta-drain release floor**
+  (`release_build_in_flight`, `--force`-able but loud) — the two places the method
+  promised enforcement and now delivers it.
+- **Four honor-system edges became plain disclosures + measure-not-block lints.**
+  `add.py audit` now surfaces `shallow_deep_check`, `risk_unset`, and
+  `refute_unrecorded` (presence-only, never blocking); the guides + book state plainly
+  that a *missed* security finding is invisible to the engine (a human spot-audit is
+  the only backstop under `auto`); reject-code names read honestly
+  (`release_tests_red`→`release_build_in_flight`).
+- **The earned-green refute-read is now a recorded verdict.** Under `auto`, the §6
+  `### Refute-read verdict` block records `EARNED | NOT-EARNED`; the engine measures it
+  is filled but never spawns the read — the resolver still does the judging.
+- **Stale guidance synced to the shipped engine.** The 5-build "scope gate deferred"
+  note is gone (the scope gate enforces today); the auto-PASS precondition list is now
+  identical across `run.md`, `6-verify.md`, and the book.
+
+### Added (loose tasks)
+- **`/add --todo` flag** (`skill-todo-flag`) — capture/list/close backlog todos.
+- **§5 Strategy fed into spawns** (`build-strategy-solutions` · `streams-strategy-pull`)
+  — the planned build order + known-problem fixes flow into subagent prompts.
+- **`<strategy>` softened** (`strategy-soft-not-hard`) — §5 is the *preferred* plan; the
+  builder may self-improve during build and reports the strategy actually used for audit.
+
+### Changed (release infrastructure)
+- **npm Trusted Publishing (OIDC).** `publish.yml` drops the stored npm token (no more
+  ~90-day rotation), publishes via OIDC (`id-token: write`, Node 24 + npm ≥ 11.5.1),
+  and generates provenance automatically (`--provenance` no longer needed). A guard test
+  locks the tokenless shape. PyPI already used OIDC.
+
 ## [1.12.0] — 2026-06-26
 
 Multi-milestone polish release — the intake/roadmap front grows a real **queue**,

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;
@@ -694,12 +698,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 -----------
@@ -712,6 +727,7 @@ const MANAGED = [
   ["docs", [".add", "docs"], false],
 ];
 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 +748,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,6 +781,9 @@ 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" };
@@ -771,8 +812,11 @@ function reconcile(args, target, srcRoot) {
     }
   }
   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 +824,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 ----
@@ -851,7 +896,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 +947,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 +1058,82 @@ 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
     // 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) {
@@ -984,12 +1166,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 +1186,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/03-step-1-specify.md

@@ -3,7 +3,7 @@
 [← 02 The flow](./02-the-flow.md) · [Contents](./README.md) · Next: [04 Step 2 Scenarios →](./04-step-2-scenarios.md)
 
 > **Purpose:** state, in plain language, what the feature must do and what it must reject, with no ambiguity left for the AI to resolve by guessing.
-> **Produces:** `SPEC.md` for the feature.
+> **Produces:** the **§1 SPECIFY** block of the task's `TASK.md` (one file per task — what this chapter is the *why* behind; historically a separate `SPEC.md`).
 > **How it works — co-specification:** AI and human **brainstorm the shape together**; the AI drafts; the **human validates, with the AI's advice.** The decisive advice is a *lowest-confidence flag* — the AI names the one or two things most likely to be wrong, so the human's attention lands where it matters. The human owns the decision; the AI owns surfacing what it does not yet know.
 
 ---

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

@@ -3,7 +3,7 @@
 [← 03 Step 1 Specify](./03-step-1-specify.md) · [Contents](./README.md) · Next: [05 Step 3 Contract →](./05-step-3-contract.md)
 
 > **Purpose:** rewrite each rule from the spec as a concrete, pass-or-fail scenario.
-> **Produces:** `features/<name>.feature`.
+> **Produces:** the **§2 SCENARIOS** block of the task's `TASK.md` (one file per task — what this chapter is the *why* behind; historically a separate `features/<name>.feature`).
 > **Person's job:** decide what "correct" looks like in concrete situations. **AI's job:** draft the scenarios.
 
 > **Part of the specification bundle (v7).** In the default flow these scenarios are drafted by the AI alongside the spec, contract, and failing tests as **one bundle**, approved by a person **once** (the one approval), at the contract freeze — not signed off step by step. This chapter is how to get the scenarios *right*; [05 Contract](./05-step-3-contract.md) is where the bundle is frozen. See [11 Governance](./11-governance.md).

package/docs/08-step-6-verify.md

@@ -18,7 +18,7 @@ This needs care, because it is easy to misread. "Not by inspection" does not mea
 
 Verify can be resolved two ways, set per task by the `autonomy:` header (see [governance](./11-governance.md) and the autonomy level):
 
-- **Auto (the default).** When `autonomy: auto`, the run resolves the gate on **evidence** rather than waiting for a person — but only when *all* of these hold: every test green, coverage not decreased, no test weakened and no contract edited, the convergence loops dry, and **no residue** (security, concurrency, or architecture). It records `PASS` as *auto-resolved*, naming the run as the accountable owner — an explicit pass, not a skip. This is principle 7: a gate may be resolved by evidence when that evidence is sufficient and the result is logged.
+- **Auto (the default).** When `autonomy: auto`, the run resolves the gate on **evidence** rather than waiting for a person — but only when *all* of these hold — the **same canonical list run.md owns**: every test green, coverage not decreased, no test weakened and no contract edited, the convergence loops dry, the completeness-critic clean, the deep check filled, the earned-green refute-read verdict recorded (the §6 `### Refute-read verdict` field, under auto), and **no residue** (security, concurrency, or architecture). It records `PASS` as *auto-resolved*, naming the run as the accountable owner — an explicit pass, not a skip. This is principle 7: a gate may be resolved by evidence when that evidence is sufficient and the result is logged.
 - **Human.** When `autonomy: conservative`, or whenever the run finds residue it cannot judge, the gate stops for a person; the two parts below are theirs.
 
 **Security is always a `HARD-STOP` and is never auto-passed, at any autonomy level.** The two parts that follow — confirm the evidence, then check the non-functional risks — are what *either* resolver works through; the only question is whether a person or the recorded run signs the outcome.
@@ -40,7 +40,7 @@ Automated tests are excellent at behavior on defined inputs and poor at a few sp
 
 - **Concurrency and timing.** Is the operation correct when two of them happen at once? Tests usually run serially and miss races.
   - ▶ *Example: the balance update must be one atomic transaction. Confirm that two simultaneous transfers from the same account cannot both pass the balance check and overdraw it.* This is the single most important check for this feature, and it is the reason the build prompt named atomicity explicitly.
-- **Security.** Are there exposed secrets, injection openings, or unexpected dependencies? AI-generated code is known to hardcode secrets and to pull in packages by plausible-but-wrong names.
+- **Security.** Are there exposed secrets, injection openings, or unexpected dependencies? AI-generated code is known to hardcode secrets and to pull in packages by plausible-but-wrong names. A security finding is always a `HARD-STOP`, never a waiver — and it escalates only if it is *written down*: `add.py audit`'s `unescalated_security_note` check fires on a **marked** note that slipped through as an auto-gate PASS, but a finding you **never marked** is invisible to the engine, escalated to no one. That is the honest limit of the auto-gate: under `auto`, a human **spot-audit** (reading the diff) is the only backstop for a *missed* security finding — the same backstop named for an unrecorded earned-green refute-read.
 - **Architecture conformance.** Does the change respect the layering and dependency rules in `CONVENTIONS.md`? Speed with no architectural check produces a fast-growing tangle that becomes unmaintainable within months.
 
 ## Part three — the deep check (do not skim)
@@ -59,6 +59,8 @@ Passing tests say the code satisfies the cases you wrote down. They do not say i
 
 A green suite proves the tests pass — not that the build EARNED them. Three judgment cheats pass the unchanged suite without earning it: src overfit to the test fixtures (special-cased to the literal inputs, not the general behavior §1 asked for), vacuous asserts (tautological — green even against an empty implementation), and real logic stubbed away (the function returns a constant the tests happen to accept). These cheats are invisible to the mechanical tamper tripwire, which only sees edited files. Score them with an adversarial refute-read: an independent reviewer — a subagent under `autonomy: auto` is recommended, the engine never spawns one — prompted to argue the green was NOT earned from outside the build context. This is the verify-gate, whole-suite specialization of run.md's adversarial verify (see run.md), not a new discipline. A confirmed earned-green failure is HARD-STOP-class: never auto-passed, never RISK-ACCEPTED — but a first cheat is a chance to redo: a confirmed cheat (mechanical tamper or a reported earned-green failure) enters the bounded self-heal loop — it returns to build for an honest redo, and only after the loop's cap does it HARD-STOP to the human (the loop lives in run.md).
 
+Under `autonomy: auto` there is no human at the gate to confirm the refute-read happened, so the verdict is **recorded** — a `### Refute-read verdict` field in §6 (`Verdict: EARNED | NOT-EARNED`, plus who read it and what they adversarially probed). This closes an honesty gap the auto-gate would otherwise leave open: the method *says* an auto-PASS rests on an earned-green check, but nothing made that check visible. Now `add.py audit` surfaces a verify-or-later task whose verdict block is still a placeholder as `refute_unrecorded` — a **measure, not a gate**: it never blocks the run (a hard gate on this universal completion path would break far too much to justify it, and the engine cannot read whether a self-graded `EARNED` is *true* anyway — only whether it was written). The honest backstop is the same one named for a missed security finding: a human **spot-audit** reading the diff. A `NOT-EARNED` verdict is not a dead end — it routes through `add.py heal` for an honest redo, never an auto-PASS. The discipline this records is simple: under auto, you are the accountable owner of the gate, so you leave the trace of the check you owe.
+
 ## Recording the outcome
 
 Every verification ends with exactly one recorded outcome, with an accountable owner — never a silent pass:

package/docs/09-the-loop.md

@@ -33,6 +33,10 @@ Every defect, surprise, or new need is written up as a change to the specificati
 
 This is also where the AI returns to a useful role: summarizing telemetry, clustering errors into themes, and drafting the proposed spec delta for a person to review. But the production decisions — what to roll back, what to prioritize — remain human.
 
+## The decision record (ADR)
+
+Observe is also where the loop's **decisions** become durable. At the gate the engine harvests §7's **Decisions (ADR)** block from the stamps the task already carries — the §1 framing it chose (and the alternatives it rejected), the §3 contract a person froze, the §5 strategy it actually used, and the §6 gate outcome — tagging each line `[human]` or `[AI]`. It is *harvested, not authored*: the engine writes no decision of its own, only what the task already recorded, so the trail can never drift from what actually happened. The result is one consolidated, auditable record of who decided what — and `add.py audit` flags a done task whose block never harvested (`adr_record_missing`), so the record cannot silently go missing.
+
 ## Lessons learned and the retrospective consolidation
 
 A spec delta feeds the *next feature*. But a loop also teaches the **method itself** — that the domain model missed a boundary, that a whole class of scenario was never tested, that a build convention helped or hurt. AIDD captures those as **lessons learned**: a single tagged learning, written in the Observe step, marking which of the five competencies it sharpens.

package/docs/11-governance.md

@@ -23,7 +23,7 @@ The **per-scope default is auto-with-evidence behind a one-approval decision poi
 
 The engine expresses this per task as an explicit three-rung level — `autonomy: manual | conservative | auto`, an ordered ladder `manual < conservative < auto` declared in the `TASK.md` header and reviewed at the freeze. `auto` is auto-with-evidence behind the one approval (the seeded default); `conservative` is the deliberate lowering that keeps a person at the verify gate; `manual` is the strict floor where the human owns the gate and nothing auto-resolves. A high-risk or method-defining scope refuses an unguarded `auto` (`unguarded_high_risk_auto`) — it must be lowered to `conservative` or `manual`. The prose here and that engine token are one rule: prose ≡ enforcement.
 
-**Autonomy is earned by goal-clarity — the auto-ready goal.** The autonomy level decides *who* resolves Verify; an **auto-ready goal** decides whether a self-verifying run is even *meaningful*. A milestone goal is *auto-ready* when **every exit criterion cites a verifier** — `(verify: <test | command | metric>)` — so the engine can check the result against the goal without human judgment. `add.py check` raises a `goal_not_auto_ready` WARN (never red, the active milestone only) while the goal has criteria not all cited, and `status` surfaces a `goal-ready:` line every session, so the goal-clarity gap stays visible. The WARN *measures*, it never blocks: it changes neither the freeze gate nor the autonomy level — clarifying the goal is the prerequisite that *earns* trust, not a new gate (a zero-criteria goal reads not-auto-ready and is milestone-shaping's nudge, not this one's). The lint raises the floor — a citation slot per criterion — but cannot prove the citation is honest: a human can still write `(verify: it works)`, and closing that is a person's judgment, not the engine's.
+**Autonomy is earned by goal-clarity — the auto-ready goal.** The autonomy level decides *who* resolves Verify; an **auto-ready goal** decides whether a self-verifying run is even *meaningful*. A milestone goal is *auto-ready* when **every exit criterion cites a verifier** — `(verify: <test | command | metric>)` — so the engine can check the result against the goal without human judgment. `add.py check` raises a `goal_not_auto_ready` WARN (never red, the active milestone only) while the goal has criteria not all cited, and `status` surfaces a `goal-ready:` line every session, so the goal-clarity gap stays visible. The WARN *measures citation presence*, it never blocks: it changes neither the freeze gate nor the autonomy level — clarifying the goal is the prerequisite for a meaningful self-verifying run, not a new gate (a zero-criteria goal reads not-auto-ready and is milestone-shaping's nudge, not this one's). The lint raises the floor — a citation slot per criterion — but cannot prove the citation is honest: a human can still write `(verify: it works)`, and closing that is a person's judgment, not the engine's.
 
 ## The gate-fail protocol and the three reports
 

package/docs/16-releasing.md

@@ -86,7 +86,7 @@ refusing with a non-zero exit and leaving every file byte-unchanged on any of fo
 
 - `release_security_open` — an open security `HARD-STOP` exists. This is the non-negotiable one: a
   security finding is never shipped. Resolve it first, as a change request back to Specify.
-- `release_tests_red` — the suite is not green. A release ships on evidence, not on a plausible diff.
+- `release_build_in_flight` — a build is in flight: a task sits in build/verify with no recorded green gate. A release ships on evidence, not on a plausible diff.
 - `release_no_closed_milestone` — nothing new since the last release. The cut would be a no-op; do not
   bump a version to mark time.
 - `release_undisclosed_waiver` — a `RISK-ACCEPTED` waiver rides into the release but is missing from the

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.