@pilotspace/add 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -6,6 +6,46 @@ 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**:

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/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/appendix-c-glossary.md

@@ -16,11 +16,11 @@
 
 **Co-specification** — how a spec is made in ADD: the AI and the human **brainstorm the shape together** (diverge), the AI **drafts** it, and the human **validates with the AI's advice** (validate). The AI's decisive advice is the *lowest-confidence flag*. It replaces dictation-by-one-side — the human owns the decision, the AI owns surfacing what it does not yet know. See [03 Specify](./03-step-1-specify.md).
 
-**Component** — a declared part of a multi-part codebase that owns a source `root` and its own `green-bar` (suite + checks), named in `.add/components.toml` under `[component.<name>]`. A task binds to one with a `component:` header line, which adds that root to its §5 Scope and holds it to that component's green bar at verify. Declared, never inferred; a project with no components is byte-identical to a single-codebase project. See [17 Components](./17-components.md).
+**Component** — a declared part of a multi-part codebase that owns a source `root` and its own `green-bar` (suite + checks), named in `.add/components.toml` under `[component.<name>]`. A task binds to one with a `component:` header line, which adds that root to its §5 Scope and holds it to that component's green bar at verify. At the gate the engine also **surfaces** the component's `verify` command (the literal suite to run, e.g. `pytest -q`) and records it — NO-EXEC, the operator runs it; the fast lane carries the same `component:` affordance. Declared, never inferred; a project with no components is byte-identical to a single-codebase project. See [17 Components](./17-components.md).
 
-**Cross-component contract** — the frozen, machine-checkable interface between a producer component and its consumers, declared under `[contract.<id>]` (producer + consumers). A task names its role with a `produces: <id>` or `consumes: <id>` header. On the producer's freeze the engine writes an immutable snapshot at `.add/contracts/<id>.json`; a consumer pins its hash and is flagged `contract_consumer_stale` if the producer later re-freezes a changed shape. Inside one milestone a `consumes:` task is HELD from writing its §3 until the producer's snapshot exists — the intra-milestone BE→FE ordering. See [17 Components](./17-components.md).
+**Cross-component contract** — the frozen, machine-checkable interface between a producer component and its consumers, declared under `[contract.<id>]` (producer + consumers). A task names its role with a `produces: <id>` or `consumes: <id>` header. On the producer's freeze the engine writes an immutable snapshot at `.add/contracts/<id>.json`; a consumer pins its hash and is flagged `contract_consumer_stale` if the producer later re-freezes a changed shape. Inside one milestone a `consumes:` task is HELD from writing its §3 until the producer's snapshot exists — the intra-milestone BE→FE ordering. Freeze-recency: the consumer is also held `producer_contract_stale` if a *live* producer task has re-opened or drifted its §3 (the snapshot no longer matches a frozen producer); `add.py check` surfaces the softer `contract_producer_stale` and `contract_snapshot_hashless` (a snapshot with no hash to verify) as never-red warnings. See [17 Components](./17-components.md).
 
-**Federation (multi-repo)** — the transport that carries a frozen cross-component contract between separate repositories. A consumer repo declares `[federation.<id>]` with a `source` (and optional `pin`); `add.py federate pull <id>` validates the producer repo's published snapshot and lands a byte-for-byte copy locally, where it behaves exactly as in a monorepo. Fail-loud: an unknown id, unreadable source, invalid snapshot, or version mismatch HARD-STOPS and lands nothing. Each repo keeps its own git-native `state.json`; only the immutable snapshot crosses. See [17 Components](./17-components.md).
+**Federation (multi-repo)** — the transport that carries a frozen cross-component contract between separate repositories. A consumer repo declares `[federation.<id>]` with a `source` (and optional `pin`); `add.py federate pull <id>` validates the producer repo's published snapshot and lands a byte-for-byte copy locally, where it behaves exactly as in a monorepo. Fail-loud: an unknown id, unreadable source, a `source` that escapes the repo's allowlist (`federation_source_escapes` — the path is confined to a sibling of the repo root), invalid snapshot, or version mismatch HARD-STOPS and lands nothing. Each repo keeps its own git-native `state.json`; only the immutable snapshot crosses. See [17 Components](./17-components.md).
 
 **Disposable code** — the view that code is one regenerable implementation of the artifacts, not a durable asset to be preserved.
 

package/docs/appendix-d-worked-example.md

@@ -150,3 +150,82 @@ A week later, telemetry shows an unexpectedly high `forbidden` rate. The `6_obse
 ---
 
 This is the whole method in one feature: four artifacts written in order, an AI build bounded by them, a verification grounded in evidence plus the one check tests miss, and a loop that turns production reality into the next specification.
+
+---
+
+## Multi-component, end to end
+
+The example above is a single codebase with one green bar. Real slices often cross components — a backend endpoint and the frontend that calls it. ADD ships that slice *inside one milestone* using the component pillar (chapter 17). Here is the same flow, now spanning two components: a `gateway` backend that **produces** an `orders` contract, and a `web` frontend that **consumes** it.
+
+### Declare the components
+
+The two parts and the boundary between them are declared in `.add/components.toml` — never inferred:
+
+```toml
+[component.gateway]
+root      = "apps/gateway"
+green_bar = "pytest + pyright"
+verify    = "pytest -q apps/gateway"
+
+[component.web]
+root      = "apps/web"
+green_bar = "vitest + a11y"
+verify    = "pnpm -C apps/web test"
+
+[contract.orders]
+producer  = "gateway"
+consumers = ["web"]
+```
+
+One milestone, **list-orders slice**, holds two tasks: `orders-api` (the BE, `produces: orders`) and `orders-list` (the FE, `consumes: orders`).
+
+### The backend freezes first → an immutable snapshot
+
+`orders-api` carries a `component: gateway` and a `produces: orders` header. It runs the normal flow — specify, scenarios, contract — and the human freezes its §3:
+
+```
+GET /orders?status=  ->  200 { orders: [{ id, status, total, placedAt }], nextCursor }
+                          400 { error: "bad_status" }
+Status: FROZEN @ v1 — approved by the tech lead
+```
+
+The moment that contract freezes and the task crosses contract→tests, the engine writes an immutable snapshot — `.add/contracts/orders.json` — recording the id, producer, version, frozen date, and a hash over the frozen §3 shape. That file *is* the published interface.
+
+### The frontend is held until the backend freezes
+
+`orders-list` (`component: web`, `consumes: orders`) was started in the same milestone, but it must not commit to a shape the backend has not frozen. When it tries to advance scenarios→contract before the snapshot exists, the engine refuses:
+
+```
+$ python3 .add/tooling/add.py advance
+add: error: producer_contract_unfrozen: orders-list consumes 'orders' but no frozen producer snapshot exists yet — the FE is held until gateway freezes
+```
+
+Once `orders.json` exists, the same `advance` succeeds: the FE writes its §3 against the frozen shape and **pins that snapshot's hash**. The slice is ordered by the contract, not by splitting BE and FE across two milestones.
+
+If the backend later *re-opens* its §3 to change the shape, the engine holds the consumer `producer_contract_stale` rather than letting it pin a shape that is mid-change — and `add.py check` separately surfaces `contract_producer_stale` / `contract_snapshot_hashless` as never-red warnings. Freeze-recency, not just existence.
+
+### Each task verifies against its own green bar
+
+At the gate, the engine holds each task to *its* component. `orders-api` must cite `pytest + pyright` in its §6 evidence; `orders-list` must cite `vitest + a11y` — cite the wrong bar (or none) and the gate refuses `component_green_bar_uncited`. The engine never runs either suite; it **surfaces** the component's `verify` command so the operator sees exactly what to run:
+
+```
+$ python3 .add/tooling/add.py gate PASS
+task 'orders-api' gate -> PASS
+component: gateway · expected green-bar: pytest + pyright · verify: pytest -q apps/gateway   # run this suite — the engine does not (NO-EXEC)
+```
+
+Two tasks, one milestone, two green bars — each held to its own, each suite run by you.
+
+### Across repositories — federation
+
+When `gateway` and `web` live in *separate* repos, only the snapshot transport changes. The `web` repo declares where the producer publishes:
+
+```toml
+[federation.orders]
+source = "../gateway/.add/contracts/orders.json"
+pin    = "v1"
+```
+
+`add.py federate pull orders` validates the producer repo's published snapshot (valid JSON, matching id, a hash, matching version) and lands a byte-for-byte copy locally — from there the FE holds and pins exactly as in a monorepo. The pull is fail-loud: an unknown id, an unreadable source, a `source` that escapes the repo's allowlist (`federation_source_escapes`), an invalid snapshot, or a version mismatch each HARD-STOPS and lands nothing. Federation never builds the FE against a guessed, out-of-tree, or stale endpoint.
+
+That is the component pillar in one slice: declare the parts, freeze the boundary, hold the consumer behind the producer, verify each part on its own bar, and carry the frozen contract across repos — all within the same six-step flow and its single contract-freeze approval.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "ADD (AI-Driven Development). One skill. Eight steps. Five disciplines. Every feature ships through the loop — a minimal, state-tracked Claude Code skill that ships the AIDD book as its trust layer.",
   "bin": {
     "add": "bin/cli.js"

package/skill/add/components.md

@@ -1,10 +1,8 @@
 # Components — monorepo and multi-repo slices
 
-Opt-in pillar for a milestone that spans **more than one green bar** — a backend
-and its frontend, a shared lib and two apps, services across repos. A project
-that declares no components is byte-identical to a single-codebase project. Reach
-for this only when one milestone genuinely crosses components. Full narrative:
-book chapter `17-components.md`.
+Opt-in pillar for a milestone spanning **more than one green bar** — a BE + its
+FE, a shared lib + two apps, services across repos. No components declared =
+byte-identical to a single-codebase project. Full narrative: `17-components.md`.
 
 ## Declare (never inferred)
 
@@ -13,21 +11,21 @@ book chapter `17-components.md`.
 ```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"
 ```
 
-A task binds with a `component: <name>` header line → that root joins its §5
-Scope, and verify holds it to that component's green-bar.
+A task binds with a `component: <name>` header → that root joins its §5 Scope,
+and verify holds it to that component's green-bar.
 
 ## The loop
 
-1. **Per-component verify.** A bound task must CITE its component's green-bar in
-   the §6 Build-expectations evidence, or the gate refuses
-   `component_green_bar_uncited`. The engine never runs the suite — you run the
-   right one; the gate checks the right bar was cited.
+1. **Per-component verify.** A bound task must CITE its green-bar in §6 evidence
+   or the gate refuses `component_green_bar_uncited`. The engine never runs the
+   suite — it **surfaces** the component's `verify` command (and records it in §6);
+   you run it (NO-EXEC). The fast lane carries the same `component:` affordance.
 2. **Freeze a cross-component contract.** Declare `[contract.<id>]`
    (producer + consumers). A task names its role `produces: <id>` / `consumes: <id>`.
    The producer's freeze (contract→tests) writes the immutable snapshot
@@ -35,20 +33,20 @@ Scope, and verify holds it to that component's green-bar.
    flags consumers `contract_consumer_stale`; a missing/malformed snapshot
    HARD-STOPS — never build against an unfrozen shape.
 3. **One milestone, full slice.** A `consumes:` task is HELD from advancing
-   scenarios→contract (`producer_contract_unfrozen`) until the producer's
-   snapshot exists. The FE stays downstream of the frozen BE endpoint, in one
-   milestone.
+   scenarios→contract (`producer_contract_unfrozen`) until the producer's snapshot
+   exists — and `producer_contract_stale` if a live producer re-opened/drifted its
+   §3 (freeze-recency). The FE stays downstream of the frozen BE, in one milestone.
 4. **Across repos — federate.** A consumer repo declares `[federation.<id>]`
    (`source` + optional `pin`); `add.py federate pull <id>` validates and lands a
-   byte-for-byte copy of the producer repo's published snapshot locally, where it
-   behaves as in a monorepo. Fail-loud: unknown id / unreadable source / invalid
+   byte-for-byte copy of the producer's snapshot locally. Fail-loud:
+   unknown id / unreadable source / a `source` escaping the repo's allowlist
+   (`federation_source_escapes`, confined to a repo-root sibling) / invalid
    snapshot / version mismatch each HARD-STOPS and lands nothing.
 
 ## Hold the line
 
 - **Declared, not inferred** — no scanning `apps/*`.
-- **No central server / no shared mutable state** — federation copies an
-  immutable snapshot; each repo keeps its own git-native `state.json`.
-- **No new approval** — these are engine-enforced gates on the existing six-step
-  flow, not extra human checkpoints. Ownership/autonomy per component is the
-  identity story (`streams.md`, governance), layered on this graph.
+- **No central server / no shared mutable state** — federation copies an immutable
+  snapshot; each repo keeps its own `state.json`.
+- **No new approval** — engine-enforced gates on the six-step flow, not extra human
+  checkpoints. Per-component ownership/autonomy is the identity story (`streams.md`).

package/tooling/add.py

@@ -228,11 +228,18 @@ def _stamp_gate_record(root: Path, state: dict, slug: str, outcome: str) -> None
     new = text
     for pat, repl in rules:
         new = re.sub(pat, repl, new, count=1)
-    # component-aware-add (per-component-verify): record WHICH green-bar a bound task gated
-    # against, right after the Outcome line. Unbound / no green_bar -> no line (byte-identical).
+    # component-aware-add (per-component-verify) + component-registry-fill: record WHICH green-bar
+    # the bound task gated against AND the component's verify COMMAND, right after the Outcome line.
+    # Unbound / neither declared -> no line (byte-identical). green-bar-only output is unchanged.
     _bar = _task_green_bar(root, slug)
-    if _bar:
-        _line = f"component: {_task_component(root, slug)} · expected green-bar: {_bar}"
+    _vfy = _task_verify(root, slug)
+    if _bar or _vfy:
+        _parts = [f"component: {_task_component(root, slug)}"]
+        if _bar:
+            _parts.append(f"expected green-bar: {_bar}")
+        if _vfy:
+            _parts.append(f"verify: {_vfy}")
+        _line = " · ".join(_parts)        # deterministic per task -> idempotent on re-stamp
         if _line not in new:
             new = re.sub(r"(?m)^(Outcome:.*$)", lambda m: m.group(1) + "\n" + _line, new, count=1)
     if new != text:                              # no-op = no write (mtime stable)
@@ -835,6 +842,10 @@ def cmd_phase(args: argparse.Namespace) -> None:
     # loop sets phase=build directly (never via cmd_phase) and so stays exempt.
     if args.phase == "build":
         _build_entry(root, state, slug, skip_freeze=getattr(args, "skip_freeze", False))
+    # cross-component-recency: the `phase contract` override runs the SAME consumer HOLD `advance`
+    # runs (existence + recency), so it is not a backdoor around producer_contract_unfrozen/_stale.
+    if args.phase == "contract":
+        _consumer_contract_hold(root, state, slug)
     state["tasks"][slug]["phase"] = args.phase
     state["tasks"][slug]["updated"] = _now()
     save_state(root, state)                    # F12: durable state FIRST (source of truth) — may _die
@@ -863,12 +874,10 @@ def cmd_advance(args: argparse.Namespace) -> None:
     # the HARD-STOP precedes the phase bump, so the task stays at `scenarios`. Undeclared id / no
     # `consumes:` header -> no hold (byte-identical; a typo'd id is a cmd_check registry finding).
     if nxt == "contract":
-        _cid = _task_consumes(root, slug)
-        _cmap = _contracts(root)
-        if _cid and _cid in _cmap and not _contract_snapshot(root, _cid).exists():
-            _die(f"producer_contract_unfrozen: the producer '{_cmap[_cid].get('producer', '?')}' of "
-                 f"contract '{_cid}' must freeze its contract before you write §3 — wait for "
-                 f".add/contracts/{_cid}.json")
+        # existence + RECENCY (cross-component-recency): a missing snapshot HARD-STOPs
+        # producer_contract_unfrozen; a present-but-stale leftover (live producer drifted/unfroze)
+        # HARD-STOPs producer_contract_stale. Shared with cmd_phase so the override is no backdoor.
+        _consumer_contract_hold(root, state, slug)
     # flag-first freeze guard (task unflagged-freeze): a FROZEN §3 may not cross
     # into build without a WELL-FORMED lowest-confidence flag. On pass, stamp the
     # verified marker so `audit` enforces the flag on THIS record only (open/new
@@ -1067,6 +1076,9 @@ def cmd_gate(args: argparse.Namespace) -> None:
     _gbar = _task_green_bar(root, slug)                   # per-component-verify: surface the bound bar
     if _gbar:
         print(f"component: {_task_component(root, slug)} · expected green-bar: {_gbar}")
+    _vfy = _task_verify(root, slug)                       # component-registry-fill: surface the verify command
+    if _vfy:
+        print(f"verify: {_vfy}   # run this suite — the engine does not (NO-EXEC)")
     # the engine-sourced next step (next-footer-engine): a completing gate hands off to the
     # state arm; HARD-STOP routes to "resolve HARD-STOP …" — converging the old bespoke line.
     print(_next_footer(root, state))
@@ -2179,12 +2191,25 @@ def _missing_captures(root: Path) -> list[str]:
             if not any((cap_dir / f"{n}.{ext}").is_file() for ext in _CAPTURE_EXTS)]
 
 
+def _federation_source_confined(root: Path, source: str) -> bool:
+    """True iff a federation manifest `source` resolves INSIDE the sibling-repo allowlist — the
+    workspace dir (root.parent.parent) that holds this project and its sibling checkouts. A legit
+    cross-repo source is one level up + down (`../<repo>/…`); an absolute path or a `../../` escape
+    resolves OUTSIDE and returns False. PURE + TOTAL — never raises (every error, incl. an embedded
+    NUL, → False, fail-closed), so cmd_federate can gate on it BEFORE any read (federation-harden)."""
+    try:
+        allow = root.parent.parent.resolve()
+        return _confined(root.parent / source, allow)
+    except (OSError, ValueError):
+        return False
+
+
 def cmd_federate(args: argparse.Namespace) -> None:
     """Multi-repo federation: pull a producer repo's published, immutable contract snapshot into
     this repo. Mono vs multi-repo differ ONLY in snapshot-transport — this lands the byte-copy at
     the SAME local `.add/contracts/<id>.json` the monorepo path (tasks 3/4) already reads, so a
-    `consumes: <id>` task then holds/pins identically. Designed-for-failure: unknown / missing /
-    invalid / version-mismatched sources HARD-STOP and land NOTHING (never build blind)."""
+    `consumes: <id>` task then holds/pins identically. Designed-for-failure: unknown / escaping /
+    missing / invalid / version-mismatched sources HARD-STOP and land NOTHING (never build blind)."""
     root = find_root()
     if root is None:
         _die("no_project")
@@ -2193,6 +2218,13 @@ def cmd_federate(args: argparse.Namespace) -> None:
     if fid not in fed:
         _die(f"federation_unknown: no [federation.{fid}] in components.toml — declare the producer "
              f"repo's published snapshot source before pulling")
+    # federation-harden: confine the source to the sibling-repo allowlist BEFORE any read — an
+    # absolute path or a `../../` traversal must HARD-STOP and land nothing (never read a path
+    # that escapes the project's sibling repos). Checked after the id lookup, before read_bytes.
+    if not _federation_source_confined(root, fed[fid]["source"]):
+        _die(f"federation_source_escapes: the source '{fed[fid]['source']}' for '{fid}' resolves "
+             f"outside the sibling-repo allowlist (the workspace dir) — refusing to read a path "
+             f"that escapes the project's sibling repos")
     source = (root.parent / fed[fid]["source"])
     try:
         raw = source.read_bytes()       # bytes — the landed snapshot must be a byte-for-byte copy
@@ -2214,6 +2246,47 @@ def cmd_federate(args: argparse.Namespace) -> None:
     print(f"federated '{fid}' {snap.get('version', '?')} {snap['hash']} from {fed[fid]['source']}")
 
 
+def cmd_components(args: argparse.Namespace) -> None:
+    """Read-only: print + validate the component registry (.add/components.toml).
+
+    Opt-in — with no registry this is a friendly single-component no-op (exit 0). Prints
+    the parsed components/contracts/federation, then the existing RED integrity findings
+    (_component_findings + _contract_findings), then the new schema-lint WARNs
+    (_component_schema_findings); exits 1 IFF a RED finding exists (a typo/WARN never fails).
+    NO-EXEC — `verify` is shown as data, never run. Reads no docs/ chapter."""
+    root = find_root()
+    if root is None:
+        _die("no_project")
+    if not (root / "components.toml").exists():
+        print("single-component project (no components.toml) — nothing to validate")
+        return
+    comps, cons, feds = _components(root), _contracts(root), _federation(root)
+    for name in sorted(comps):
+        c = comps[name]
+        print(f"component {name}  root={c['root']}  verify={c.get('verify') or '-'}  "
+              f"green_bar={c.get('green_bar') or '-'}  language={c.get('language') or '-'}")
+    for cid in sorted(cons):
+        c = cons[cid]
+        print(f"contract {cid}  producer={c['producer']}  consumers={c['consumers']}")
+    for fid in sorted(feds):
+        f = feds[fid]
+        print(f"federation {fid}  source={f['source']}  pin={f.get('pin') or '-'}")
+    reds = sorted(_component_findings(root) + _contract_findings(root))
+    warns = sorted(_component_schema_findings(root))
+    for code, detail in reds:
+        print(f"ERROR {code}: {detail}")
+    for code, detail in warns:
+        print(f"WARN {code}: {detail}")
+    head = f"components: {len(comps)} · contracts: {len(cons)} · federation: {len(feds)}"
+    if reds or warns:
+        seg = ([f"{len(reds)} error(s)"] if reds else []) + ([f"{len(warns)} warning(s)"] if warns else [])
+        print(f"{head} — {', '.join(seg)}")
+    else:
+        print(f"{head} — valid")
+    if reds:
+        raise SystemExit(1)
+
+
 def cmd_check(args: argparse.Namespace) -> None:
     """Read-only integrity check of the .add project. Exit 1 if anything fails."""
     as_json = getattr(args, "json", False)
@@ -2290,6 +2363,28 @@ def cmd_check(args: argparse.Namespace) -> None:
                 warnings.append((f"task '{slug}'", f"contract_consumer_stale — pinned contract "
                                  f"'{_pin.get('id')}' changed shape since pin; re-pin (re-cross contract→tests) "
                                  "after reviewing the producer's new frozen shape"))
+        # cross-component-recency: a consumer whose landed snapshot's LIVE producer drifted/unfroze
+        # since the snapshot — surfaced EARLY (never red) before the consumer re-enters §3, the
+        # check twin of the producer_contract_stale advance HARD-STOP. Degrade-safe.
+        _ccons = _task_consumes(root, slug)
+        if _ccons and _ccons in _contracts(root):
+            _csnap = _contract_snapshot(root, _ccons)
+            if _csnap.exists():
+                try:
+                    _chash = json.loads(_csnap.read_text(encoding="utf-8")).get("hash")
+                except (OSError, ValueError, AttributeError):
+                    _chash = None
+                if _chash is None:
+                    # cross-component-recency R1: a present-but-hash-less snapshot degrades the
+                    # recency check to existence-only (frozen behavior) — SURFACE the blind spot
+                    # (never red) so a hand-tampered/hash-stripped snapshot is not silently trusted.
+                    warnings.append((f"task '{slug}'", f"contract_snapshot_hashless — the landed "
+                                     f"snapshot for '{_ccons}' carries no hash; recency cannot be "
+                                     "verified (re-publish the producer contract / re-cross contract→tests)"))
+                elif _producer_snapshot_stale(root, _ccons, _chash):
+                    warnings.append((f"task '{slug}'", f"contract_producer_stale — the live producer "
+                                     f"of '{_ccons}' changed or re-opened its §3 since the landed "
+                                     "snapshot; re-cross the producer contract→tests, then re-enter"))
         for dep in t.get("depends_on") or []:
             checks.append((dep in tasks or dep in archived_slugs,
                            f"task '{slug}' dep '{dep}' resolves", "unknown task"))
@@ -2417,11 +2512,23 @@ def cmd_check(args: argparse.Namespace) -> None:
     # is a BROKEN JOIN — surface it EARLY as a WARN (never red alone; `federate pull` is where it
     # HARD-STOPs). Silent when no federation is declared (opt-in / byte-identical).
     for _fid, _fspec in _federation(root).items():
-        if not (root.parent / _fspec["source"]).is_file():
+        if not _federation_source_confined(root, _fspec["source"]):
+            # federation-harden: an out-of-allowlist source surfaced EARLY as a never-red WARN
+            # (escape takes precedence over unreadable — a real /etc/passwd passes is_file()).
+            warnings.append((f"federation '{_fid}'",
+                             f"federation_source_escapes — '{_fspec['source']}' resolves outside the "
+                             f"sibling-repo allowlist; `federate pull {_fid}` will HARD-STOP"))
+        elif not (root.parent / _fspec["source"]).is_file():
             warnings.append((f"federation '{_fid}'",
                              f"federation_source_unreadable — the producer snapshot at "
                              f"'{_fspec['source']}' is missing/unreadable; `federate pull {_fid}` "
                              "will hard-stop until the producer repo publishes it"))
+    # components-validator: the schema-lint (typo'd/unknown key · wrong-type value · unknown
+    # table) is a never-red WARN — measure-not-block, forward-compat-safe. Rides `warnings`,
+    # NEVER `checks`/`failed`. Silent when no components.toml. `add.py components` is the
+    # richer surface; this catches the same typos EARLY in CI without failing the build.
+    for _scode, _sdetail in _component_schema_findings(root):
+        warnings.append((_scode, _sdetail))
 
     # UDD foundation (udd-check-lint): lint a project's named set under .add/design/ —
     # composes the token + catalog/tree validators + the cross-file prop-token resolution.
@@ -3572,6 +3679,16 @@ def _task_green_bar(root: Path, slug: str) -> str | None:
     return (_components(root).get(comp) or {}).get("green_bar") or None
 
 
+def _task_verify(root: Path, slug: str) -> str | None:
+    """The `verify` COMMAND of the task's bound component (component-registry-fill) — the literal
+    suite the operator runs at the gate. Twin of _task_green_bar: unbound / "?" / no verify
+    declared all yield None. PURE. SURFACED as data only — the engine NEVER executes it (NO-EXEC)."""
+    comp = _task_component(root, slug)
+    if not comp or comp == "?":
+        return None
+    return (_components(root).get(comp) or {}).get("verify") or None
+
+
 def _component_findings(root: Path) -> list[tuple[str, str]]:
     """The loud gate surface for the registry — the codes a degrade-safe read passes
     over silently. Consumed by cmd_check (the scope_violation surface). [] when clean."""
@@ -3624,6 +3741,64 @@ def _task_consumes(root: Path, slug: str) -> str | None:
     return m.group(1).strip() if m else None
 
 
+def _producer_snapshot_stale(root: Path, cid: str, snap_hash: str | None) -> bool:
+    """True IFF a LIVE producer task backs `cid` (some task under root/tasks/ whose header carries
+    `produces: cid`) AND that producer's current §3 is NOT frozen, OR its frozen body-hash differs
+    from `snap_hash` (the landed snapshot's hash) — i.e. the producer re-opened/changed its contract
+    since the snapshot was written (cross-component-recency). No live producer task (archived in a
+    prior milestone, or a federation/external snapshot) -> False = existence-only, recency is the
+    producer repo's job via the federation version pin. snap_hash None / unreadable §3 -> False (not
+    confirmable here). PURE + TOTAL — never raises (a read error is a non-confirmation, not a block)."""
+    if snap_hash is None:
+        return False
+    tasks_dir = root / "tasks"
+    if not tasks_dir.is_dir():
+        return False
+    try:
+        producers = sorted(td.name for td in tasks_dir.iterdir() if td.is_dir())
+    except OSError:
+        return False
+    for pslug in producers:
+        if _task_produces(root, pslug) != cid:
+            continue
+        raw3 = _raw_phase_bodies(root, pslug).get(3, "")
+        if "FROZEN @" not in raw3:
+            return True                                  # live producer exists but its §3 is not frozen
+        return _contract_body_hash(raw3) != snap_hash    # frozen but drifted from the landed snapshot
+    return False                                         # no live producer backs cid -> existence-only
+
+
+def _consumer_contract_hold(root: Path, state: dict, slug: str) -> None:
+    """The cross-component consumer HOLD at the §3 boundary, shared by cmd_advance (nxt=="contract")
+    and cmd_phase (phase=="contract") so the admin override is not a backdoor (mirrors the
+    phase build -> _build_entry precedent). A `consumes: <cid>` task targeting a DECLARED contract:
+    a MISSING snapshot HARD-STOPs `producer_contract_unfrozen` (producer hasn't frozen); a PRESENT
+    snapshot whose live producer has drifted/unfrozen HARD-STOPs `producer_contract_stale`
+    (cross-component-recency — a stale leftover must not admit a consumer). No consumes / undeclared
+    id -> return (byte-identical; a typo'd id is a cmd_check finding). `state` is accepted for call-site
+    symmetry with _build_entry (unused here — the hold reads the task + contract files). Validate-
+    then-write: every _die precedes the caller's phase bump, so a refused task does not move."""
+    cid = _task_consumes(root, slug)
+    if not cid:
+        return
+    cmap = _contracts(root)
+    if cid not in cmap:
+        return
+    snap = _contract_snapshot(root, cid)
+    if not snap.exists():
+        _die(f"producer_contract_unfrozen: the producer '{cmap[cid].get('producer', '?')}' of "
+             f"contract '{cid}' must freeze its contract before you write §3 — wait for "
+             f".add/contracts/{cid}.json")
+    try:
+        snap_hash = json.loads(snap.read_text(encoding="utf-8")).get("hash")
+    except (OSError, ValueError, AttributeError):
+        snap_hash = None
+    if _producer_snapshot_stale(root, cid, snap_hash):
+        _die(f"producer_contract_stale: the live producer of contract '{cid}' changed or re-opened "
+             f"its §3 since the landed .add/contracts/{cid}.json — re-cross the producer "
+             "contract->tests to refresh the snapshot, then re-enter (never build against a stale shape)")
+
+
 def _contract_body_hash(raw3: str) -> str:
     """md5 of the §3 contract SHAPE — the first ```fenced``` block, whitespace-normalized. The
     version stamp + freeze flags are excluded (fallback strips Status:/flag/change-request lines)
@@ -3644,6 +3819,67 @@ def _contract_findings(root: Path) -> list[tuple[str, str]]:
     return findings
 
 
+# ── components.toml schema-lint (components-validator) ─────────────────────────────────
+# The SOFT typo surface: the keys/tables a DEGRADE-SAFE read silently drops. All three
+# codes are WARN-severity (measure-not-block) — forward-compat-safe (an older engine
+# reading a newer file flags, never fails). Surfaced at `check` (as warnings) AND by
+# `add.py components`. PURE · DEGRADE-SAFE · NO-EXEC: reads only .add/components.toml,
+# never raises, never executes `verify`. A parse break is _component_findings' RED job.
+_SCHEMA_KNOWN_KEYS: dict[str, tuple[str, ...]] = {
+    "component": ("root", "verify", "green_bar", "language"),
+    "contract": ("producer", "consumers"),
+    "federation": ("source", "pin"),
+}
+_SCHEMA_KEY_TYPES: dict[str, dict[str, type]] = {
+    # `root` is intentionally absent — a missing/non-str root is already RED `components_malformed`
+    "component": {"verify": str, "green_bar": str, "language": str},
+    "contract": {"producer": str, "consumers": list},
+    "federation": {"source": str, "pin": str},
+}
+_SCHEMA_TYPENAME = {str: "a string", list: "a list"}
+
+
+def _component_schema_findings(root: Path) -> list[tuple[str, str]]:
+    """Schema-lint the components.toml registry for typos a degrade-safe read drops:
+    an unknown/misspelled key, a wrong-type value on a known key, or an unrecognized
+    top-level table. Returns [(code, detail)] (deterministic file order); [] when the
+    file is absent / opted-out / unparseable (no double-report with the RED surface).
+    All codes WARN: component_unknown_key · component_type_mismatch · component_unknown_table."""
+    if tomllib is None:
+        return []
+    try:
+        data = tomllib.loads((root / "components.toml").read_bytes().decode("utf-8"))
+    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError, ValueError):
+        return []                       # a parse break is _component_findings' RED job
+    if not isinstance(data, dict):
+        return []
+    out: list[tuple[str, str]] = []
+    for top in data:                    # 1. unrecognized top-level tables/keys
+        if top not in _SCHEMA_KNOWN_KEYS:
+            out.append(("component_unknown_table",
+                        f"top-level [{top}] is not a known table "
+                        f"(expected one of: {', '.join(_SCHEMA_KNOWN_KEYS)})"))
+    for table, known in _SCHEMA_KNOWN_KEYS.items():     # 2/3. per-entry keys + value types
+        entries = data.get(table)
+        if not isinstance(entries, dict):
+            continue
+        types = _SCHEMA_KEY_TYPES[table]
+        for name, spec in entries.items():
+            if not isinstance(spec, dict):
+                continue                # a non-table entry is the RED surface's job
+            for key, val in spec.items():
+                if key not in known:
+                    out.append(("component_unknown_key",
+                                f"[{table}.{name}] has unknown key {key!r} "
+                                f"(known: {', '.join(known)})"))
+                elif key in types and not isinstance(val, types[key]):
+                    out.append(("component_type_mismatch",
+                                f"[{table}.{name}].{key} should be "
+                                f"{_SCHEMA_TYPENAME.get(types[key], types[key].__name__)}, "
+                                f"got {type(val).__name__}"))
+    return out
+
+
 def _declared_scope(root: Path, slug: str) -> list[str] | None:
     """Resolve the §5 'Scope (may touch):' declaration to project-root-relative
     strings (directory tokens keep a trailing '/'). The frozen scope-decl-template
@@ -5998,6 +6234,11 @@ def build_parser() -> argparse.ArgumentParser:
     pck.add_argument("--json", action="store_true", help="machine-readable JSON output")
     pck.set_defaults(func=cmd_check)
 
+    pcomp = sub.add_parser("components",
+                           help="read-only: print + validate the component registry "
+                                "(.add/components.toml) — RED integrity errors + schema-lint typo warnings")
+    pcomp.set_defaults(func=cmd_components)
+
     pfed = sub.add_parser("federate", help="multi-repo: pull a producer repo's published, immutable "
                                            "contract snapshot into this repo (fail-loud)")
     pfedsub = pfed.add_subparsers(dest="action", required=True)

package/tooling/templates/TASK.fast.md.tmpl

@@ -1,7 +1,7 @@
 # TASK: {{title}}
 
 slug: {{slug}} · created: {{date}} · stage: {{stage}}
-autonomy: {{autonomy}}
+autonomy: {{autonomy}}   <!-- Multi-component repo? add a `component: <name>` line (declared in .add/components.toml) to bind this fast task to a component — its root joins §5 Scope and its green-bar/verify surface at the gate. Omit for single-component projects. -->
 phase: ground   <!-- fast lane: ground -> specify -> contract -> tests -> build -> verify -> observe -> done -->
 fast: true   <!-- the fast lane: a small task, collapsed flow + minimal template. Omit --fast for full rigor. -->