From 2361246fb7c08420b18a16b79974eff06ef09487 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 20 Jul 2026 15:01:25 +0000
Subject: [PATCH] refactor(cli): split the run() god-function into a dispatch
 table (H3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The former ~2,420-line run() (a flat 44-branch `if (cmd === …)` chain, 97% of
src/cli.js) is now a ~44-line dispatcher: it looks the command up in a HANDLERS
map and delegates. Each command is a module-scope `async (argv, cmd)` handler —
independently navigable and mergeable, ending the merge-conflict-magnet problem.

Behavior is byte-identical: same argv in, same stdout/stderr/exit-code out. The
pre-dispatch middleware (--help interception, first-run hint, cortex-mcp), the
unknown-command fallback, the process.exitCode error model, and the main-module
import guard are all preserved. Handler signatures are trimmed to the params each
body actually uses, so no unused-parameter warnings are introduced.

Verified: full spawn-based suite 1069 pass / 0 fail / 2 skip, biome 0 errors,
tsc 0 errors, `docs check` green, and importing the package root still does not
execute the CLI.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C7htTiesXKLvAUtv6ET2jz
---
 CHANGELOG.md |   11 +
 src/cli.js   | 4267 +++++++++++++++++++++++++-------------------------
 2 files changed, 2144 insertions(+), 2134 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 89c7a4e..b6b5d69 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,17 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Changed
+
+- **Split the `run()` god-function in `src/cli.js` into a dispatch table (H3).** The former
+  ~2,420-line `run()` (a flat 44-branch `if (cmd === …)` chain) is now a ~44-line dispatcher
+  that looks the command up in a `HANDLERS` map; each command is an independently navigable,
+  independently mergeable module-scope `async` handler. Behavior is byte-identical — the same
+  argv in, the same stdout/stderr/exit-code out (the full spawn-based suite is unchanged and
+  green) — the pre-dispatch middleware (`--help` interception, first-run hint, `cortex-mcp`),
+  the unknown-command fallback, `process.exitCode` error model, and the main-module import
+  guard are all preserved.
+
 ## [0.26.0] - 2026-07-20
 
 ### Added
diff --git a/src/cli.js b/src/cli.js
index 40e3ad6..5ea44f2 100755
--- a/src/cli.js
+++ b/src/cli.js
@@ -62,6 +62,11 @@ function printHelp() {
   console.log(`Run \`${BRAND.cli} <command> --help\` for details.`);
 }
 
+// Command dispatch table: name → async handler `(argv, cmd) => …`. Populated at module
+// load by the per-command handler declarations below. run() looks a command up here.
+/** @type {Record<string, (argv: string[], cmd: string) => unknown>} */
+const HANDLERS = {};
+
 async function run(argv) {
   const [cmd] = argv;
   // Top-level help/version — flag AND word forms (`forge help`, `forge version`).
@@ -89,189 +94,179 @@ async function run(argv) {
     serve();
     return;
   }
-  if (cmd === "brand") {
-    const { brand, cli, pkg, version, layers } = BRAND;
-    return console.log(JSON.stringify({ brand, cli, pkg, version, layers }, null, 2));
-  }
-  if (cmd === "init") {
-    const { init } = await import("./init.js");
-    const noSettings = argv.includes("--no-settings");
-    // Test/plumbing override of the merge target — not user-facing surface.
-    const settingsPath = process.env.FORGE_SETTINGS_PATH || undefined;
-    // RA-11: the settings merge touches GLOBAL state — say so before reporting it,
-    // on merged AND unchanged runs, with the opt-out and the reversal path.
-    const consentLine = (path) =>
-      console.log(
-        `  settings: merging ${BRAND.brand} hooks into ${path} (GLOBAL — affects all repos). ` +
-          `Skip with --no-settings; reverse with \`${BRAND.cli} init --remove-settings\`.`,
-      );
-    // --remove-settings: reverse the merge (RA-17) — strip every template-shaped hook,
-    // permission, statusline, and the _forge marker; user-owned entries stay untouched.
-    if (argv.includes("--remove-settings")) {
-      const { removeForgeSettings } = await import("./init.js");
-      const r = removeForgeSettings({ settingsPath });
-      heading(`${BRAND.brand} init — remove managed settings\n`);
-      if (r.action === "removed") {
-        console.log(`  settings: removed ${r.removed.join(", ")} from ${r.path}`);
-        console.log(`            backup: ${r.backup}`);
-      } else if (r.action === "noop") {
-        console.log(`  settings: nothing to remove (${r.reason})`);
-      } else {
-        console.error(`  settings: NOT modified — ${r.path}: ${r.reason}`);
-        process.exitCode = 1;
-      }
-      return;
-    }
-    // --settings-only: wire hooks + permissions into ~/.claude/settings.json ONLY (the
-    // idempotent, marker-guarded merge install.sh calls) — no repo emit, no AGENTS.md.
-    if (argv.includes("--settings-only")) {
-      // ME-22: heading + disclosure precede the merge — onSettingsNotice fires inside init
-      // BEFORE mergeSettings touches the file, never after.
-      heading(`${BRAND.brand} init — settings merge only\n`);
-      const { settings } = init({
-        settingsOnly: true,
-        noSettings,
-        settingsPath,
-        onSettingsNotice: consentLine,
-      });
-      if (
-        (settings?.action === "merged" || settings?.action === "created") &&
-        "added" in settings
-      ) {
-        const verb = settings.action === "created" ? "created" : "merged";
-        const what = settings.added.length ? settings.added.join(", ") : "defaults";
-        console.log(`  settings: ${verb} ${what} into ${settings.path}`);
-      } else if (settings?.action === "unchanged" && "path" in settings) {
-        console.log(`  settings: already up to date (${settings.path})`);
-      } else if (settings?.action === "skipped") {
-        console.log("  settings: skipped (--no-settings)");
-      } else if (settings?.action === "error") {
-        // RA-04: a refused/failed merge must FAIL the command, not silently exit 0 —
-        // install.sh keys its "install incomplete" path off this exit code.
-        console.error(`  settings: FAILED — ${settings.path}: ${settings.reason}`);
-        process.exitCode = 1;
-      }
-      return;
-    }
-    const profileIdx = argv.indexOf("--profile");
-    const profile = profileIdx >= 0 ? argv[profileIdx + 1] : undefined;
-    // ME-22: emit the GLOBAL-settings disclosure BEFORE the merge mutates the file. init
-    // forwards `onSettingsNotice` to mergeSettings, which fires it right before touching
-    // ~/.claude/settings.json — so the notice always precedes the mutation it describes.
-    heading(`${BRAND.brand} init — this repo now speaks every AI tool from one source.\n`);
-    const {
-      report,
-      bytes,
-      settings,
-      detected,
-      profile: profileResult,
-    } = /** @type {any} */ (
-      init({
-        targetRoot: process.cwd(),
-        noSettings,
-        profile,
-        settingsPath,
-        onSettingsNotice: consentLine,
-      })
+  // Dispatch table: migrated commands resolve here; run() is the thin dispatcher.
+  const handler = HANDLERS[cmd];
+  if (handler) return handler(argv, cmd);
+  if (!(cmd in COMMANDS)) {
+    const near = suggest(cmd, Object.keys(COMMANDS));
+    console.error(
+      `Unknown command: ${cmd}${near ? ` — did you mean \`${BRAND.cli} ${near}\`?` : ""}\n` +
+        `Run \`${BRAND.cli} --help\` to see commands.`,
     );
-    if (profileResult?.error) {
-      console.error(`  ${profileResult.error}`);
-      process.exitCode = 1;
-      return;
-    }
-    const wrote = report.filter((r) => r.action === "written").map((r) => r.target);
-    console.log(`  emitted:  ${wrote.length ? wrote.join(", ") : "(all up to date)"}`);
+    process.exitCode = 1;
+    return;
+  }
+  // A command is registered in COMMANDS but has no handler wired yet. Exit non-zero
+  // so scripts (and CI) treat "recognized but unimplemented" as a failure, not success.
+  console.error(`${BRAND.cli} ${cmd}: not wired yet — coming in a later build phase.`);
+  process.exitCode = 1;
+}
+
+// ─────────────────────────── command handlers ───────────────────────────────
+// One async function per command, registered into HANDLERS above; run() dispatches
+// to them. Each is independently navigable and mergeable (was one 2.4k-line run()).
+
+HANDLERS.brand = async () => {
+  const { brand, cli, pkg, version, layers } = BRAND;
+  return console.log(JSON.stringify({ brand, cli, pkg, version, layers }, null, 2));
+};
+HANDLERS.init = async (argv) => {
+  const { init } = await import("./init.js");
+  const noSettings = argv.includes("--no-settings");
+  // Test/plumbing override of the merge target — not user-facing surface.
+  const settingsPath = process.env.FORGE_SETTINGS_PATH || undefined;
+  // RA-11: the settings merge touches GLOBAL state — say so before reporting it,
+  // on merged AND unchanged runs, with the opt-out and the reversal path.
+  const consentLine = (path) =>
     console.log(
-      `  source:   AGENTS.md (${bytes} B) — edit rules in source/, re-run \`${BRAND.cli} sync\``,
+      `  settings: merging ${BRAND.brand} hooks into ${path} (GLOBAL — affects all repos). ` +
+        `Skip with --no-settings; reverse with \`${BRAND.cli} init --remove-settings\`.`,
     );
-    // ME-19: sync is non-transactional — if a target failed mid-emit, say so instead of
-    // implying every tool is ready, and fail the command.
-    const failedTargets = report.filter((r) => r.action === "error");
-    if (failedTargets.length) {
-      console.error(
-        `  status:   PARTIAL — ${failedTargets.length} target(s) failed: ${failedTargets
-          .map((r) => r.tool)
-          .join(", ")} (re-run \`${BRAND.cli} sync\` after fixing)`,
-      );
+  // --remove-settings: reverse the merge (RA-17) — strip every template-shaped hook,
+  // permission, statusline, and the _forge marker; user-owned entries stay untouched.
+  if (argv.includes("--remove-settings")) {
+    const { removeForgeSettings } = await import("./init.js");
+    const r = removeForgeSettings({ settingsPath });
+    heading(`${BRAND.brand} init — remove managed settings\n`);
+    if (r.action === "removed") {
+      console.log(`  settings: removed ${r.removed.join(", ")} from ${r.path}`);
+      console.log(`            backup: ${r.backup}`);
+    } else if (r.action === "noop") {
+      console.log(`  settings: nothing to remove (${r.reason})`);
+    } else {
+      console.error(`  settings: NOT modified — ${r.path}: ${r.reason}`);
       process.exitCode = 1;
     }
-    if (profileResult?.profile) {
-      console.log(`  profile:  ${profileResult.profile} → .forge/forge.config.json`);
-      if (profileResult.deprecated) {
-        console.error(
-          `  warning:  profile "${profileResult.deprecated}" is deprecated — treated as "${profileResult.profile}"`,
-        );
-      }
-    }
+    return;
+  }
+  // --settings-only: wire hooks + permissions into ~/.claude/settings.json ONLY (the
+  // idempotent, marker-guarded merge install.sh calls) — no repo emit, no AGENTS.md.
+  if (argv.includes("--settings-only")) {
+    // ME-22: heading + disclosure precede the merge — onSettingsNotice fires inside init
+    // BEFORE mergeSettings touches the file, never after.
+    heading(`${BRAND.brand} init — settings merge only\n`);
+    const { settings } = init({
+      settingsOnly: true,
+      noSettings,
+      settingsPath,
+      onSettingsNotice: consentLine,
+    });
     if ((settings?.action === "merged" || settings?.action === "created") && "added" in settings) {
       const verb = settings.action === "created" ? "created" : "merged";
       const what = settings.added.length ? settings.added.join(", ") : "defaults";
       console.log(`  settings: ${verb} ${what} into ${settings.path}`);
-      if ("backup" in settings && settings.backup)
-        console.log(`            backup: ${settings.backup}`);
     } else if (settings?.action === "unchanged" && "path" in settings) {
       console.log(`  settings: already up to date (${settings.path})`);
     } else if (settings?.action === "skipped") {
       console.log("  settings: skipped (--no-settings)");
     } else if (settings?.action === "error") {
-      // RA-04: repo files above were still emitted, but the settings merge FAILED —
-      // surface it on stderr and fail the command instead of a quiet exit 0.
-      console.error(`  settings: FAILED — ${settings.reason} (repo files were still emitted)`);
+      // RA-04: a refused/failed merge must FAIL the command, not silently exit 0 —
+      // install.sh keys its "install incomplete" path off this exit code.
+      console.error(`  settings: FAILED — ${settings.path}: ${settings.reason}`);
       process.exitCode = 1;
     }
-    if (detected) {
-      console.log(`  provider: auto-detected ${detected.name} from ${detected.source}`);
-    } else {
-      console.log(
-        `  provider: none detected — set ANTHROPIC_API_KEY, OPENROUTER_API_KEY, or LITELLM_BASE_URL`,
-      );
-    }
-    console.log(`  active:   tools · crew · guards  →  \`${BRAND.cli} catalog\``);
-    console.log(`  verify:   \`${BRAND.cli} doctor\``);
     return;
   }
-  if (cmd === "update") {
-    const { applyUpdate, applyUpdateTo, updateStatus } = await import("./update.js");
-    const json = argv.includes("--json");
-    const toIdx = argv.indexOf("--to");
-    if (toIdx !== -1) {
-      const r = applyUpdateTo(argv[toIdx + 1], {});
-      if (json) return console.log(JSON.stringify(r, null, 2));
-      heading(`${BRAND.brand} update — pin\n`);
-      if (r.ok)
-        console.log(
-          r.changed
-            ? `  pinned ${r.before} → ${r.after} (${r.tag}). ${r.note}`
-            : `  already at ${r.tag}. ${r.note}`,
-        );
-      else if (r.instruction) console.log(`  ${r.reason}:\n    ${r.instruction}`);
-      else {
-        console.log(`  ${r.reason}`);
-        process.exitCode = 1;
-      }
-      return;
-    }
-    if (argv.includes("--check")) {
-      const s = updateStatus({});
-      if (json) return console.log(JSON.stringify(s, null, 2));
-      heading(`${BRAND.brand} update — check\n`);
-      if (s.unknown)
-        console.log(
-          `  on v${s.current} (${s.mode}) — can't compare to upstream${s.network === "offline" ? " (offline)" : ""}; update with your installer.`,
-        );
-      else if (s.behind > 0)
-        console.log(`  ${s.behind} commit(s) behind ${s.upstream} — run \`${BRAND.cli} update\`.`);
-      else console.log(`  up to date (v${s.current}).`);
-      return;
+  const profileIdx = argv.indexOf("--profile");
+  const profile = profileIdx >= 0 ? argv[profileIdx + 1] : undefined;
+  // ME-22: emit the GLOBAL-settings disclosure BEFORE the merge mutates the file. init
+  // forwards `onSettingsNotice` to mergeSettings, which fires it right before touching
+  // ~/.claude/settings.json — so the notice always precedes the mutation it describes.
+  heading(`${BRAND.brand} init — this repo now speaks every AI tool from one source.\n`);
+  const {
+    report,
+    bytes,
+    settings,
+    detected,
+    profile: profileResult,
+  } = /** @type {any} */ (
+    init({
+      targetRoot: process.cwd(),
+      noSettings,
+      profile,
+      settingsPath,
+      onSettingsNotice: consentLine,
+    })
+  );
+  if (profileResult?.error) {
+    console.error(`  ${profileResult.error}`);
+    process.exitCode = 1;
+    return;
+  }
+  const wrote = report.filter((r) => r.action === "written").map((r) => r.target);
+  console.log(`  emitted:  ${wrote.length ? wrote.join(", ") : "(all up to date)"}`);
+  console.log(
+    `  source:   AGENTS.md (${bytes} B) — edit rules in source/, re-run \`${BRAND.cli} sync\``,
+  );
+  // ME-19: sync is non-transactional — if a target failed mid-emit, say so instead of
+  // implying every tool is ready, and fail the command.
+  const failedTargets = report.filter((r) => r.action === "error");
+  if (failedTargets.length) {
+    console.error(
+      `  status:   PARTIAL — ${failedTargets.length} target(s) failed: ${failedTargets
+        .map((r) => r.tool)
+        .join(", ")} (re-run \`${BRAND.cli} sync\` after fixing)`,
+    );
+    process.exitCode = 1;
+  }
+  if (profileResult?.profile) {
+    console.log(`  profile:  ${profileResult.profile} → .forge/forge.config.json`);
+    if (profileResult.deprecated) {
+      console.error(
+        `  warning:  profile "${profileResult.deprecated}" is deprecated — treated as "${profileResult.profile}"`,
+      );
     }
-    const r = applyUpdate({});
+  }
+  if ((settings?.action === "merged" || settings?.action === "created") && "added" in settings) {
+    const verb = settings.action === "created" ? "created" : "merged";
+    const what = settings.added.length ? settings.added.join(", ") : "defaults";
+    console.log(`  settings: ${verb} ${what} into ${settings.path}`);
+    if ("backup" in settings && settings.backup)
+      console.log(`            backup: ${settings.backup}`);
+  } else if (settings?.action === "unchanged" && "path" in settings) {
+    console.log(`  settings: already up to date (${settings.path})`);
+  } else if (settings?.action === "skipped") {
+    console.log("  settings: skipped (--no-settings)");
+  } else if (settings?.action === "error") {
+    // RA-04: repo files above were still emitted, but the settings merge FAILED —
+    // surface it on stderr and fail the command instead of a quiet exit 0.
+    console.error(`  settings: FAILED — ${settings.reason} (repo files were still emitted)`);
+    process.exitCode = 1;
+  }
+  if (detected) {
+    console.log(`  provider: auto-detected ${detected.name} from ${detected.source}`);
+  } else {
+    console.log(
+      `  provider: none detected — set ANTHROPIC_API_KEY, OPENROUTER_API_KEY, or LITELLM_BASE_URL`,
+    );
+  }
+  console.log(`  active:   tools · crew · guards  →  \`${BRAND.cli} catalog\``);
+  console.log(`  verify:   \`${BRAND.cli} doctor\``);
+  return;
+};
+HANDLERS.update = async (argv) => {
+  const { applyUpdate, applyUpdateTo, updateStatus } = await import("./update.js");
+  const json = argv.includes("--json");
+  const toIdx = argv.indexOf("--to");
+  if (toIdx !== -1) {
+    const r = applyUpdateTo(argv[toIdx + 1], {});
     if (json) return console.log(JSON.stringify(r, null, 2));
-    heading(`${BRAND.brand} update\n`);
+    heading(`${BRAND.brand} update — pin\n`);
     if (r.ok)
       console.log(
         r.changed
-          ? `  updated ${r.before} → ${r.after}. ${r.note}`
-          : `  already up to date (v${BRAND.version}).`,
+          ? `  pinned ${r.before} → ${r.after} (${r.tag}). ${r.note}`
+          : `  already at ${r.tag}. ${r.note}`,
       );
     else if (r.instruction) console.log(`  ${r.reason}:\n    ${r.instruction}`);
     else {
@@ -280,2214 +275,2218 @@ async function run(argv) {
     }
     return;
   }
-  if (cmd === "stack") {
-    // Dynamic: read THIS repo's manifests and report its real stack (not a static menu).
-    const { detectStack } = await import("./stack.js");
-    const s = detectStack(process.cwd());
-    if (argv.includes("--json")) return console.log(JSON.stringify(s, null, 2));
-    heading(`${BRAND.brand} stack — detected from this repo's manifests\n`);
-    const row = (label, arr) =>
-      arr.length ? console.log(`  ${`${label}:`.padEnd(11)} ${arr.join(", ")}`) : undefined;
-    if (!s.languages.length) {
-      console.log("  no known stack detected (no package.json/go.mod/Cargo.toml/… found).");
-      return;
+  if (argv.includes("--check")) {
+    const s = updateStatus({});
+    if (json) return console.log(JSON.stringify(s, null, 2));
+    heading(`${BRAND.brand} update — check\n`);
+    if (s.unknown)
+      console.log(
+        `  on v${s.current} (${s.mode}) — can't compare to upstream${s.network === "offline" ? " (offline)" : ""}; update with your installer.`,
+      );
+    else if (s.behind > 0)
+      console.log(`  ${s.behind} commit(s) behind ${s.upstream} — run \`${BRAND.cli} update\`.`);
+    else console.log(`  up to date (v${s.current}).`);
+    return;
+  }
+  const r = applyUpdate({});
+  if (json) return console.log(JSON.stringify(r, null, 2));
+  heading(`${BRAND.brand} update\n`);
+  if (r.ok)
+    console.log(
+      r.changed
+        ? `  updated ${r.before} → ${r.after}. ${r.note}`
+        : `  already up to date (v${BRAND.version}).`,
+    );
+  else if (r.instruction) console.log(`  ${r.reason}:\n    ${r.instruction}`);
+  else {
+    console.log(`  ${r.reason}`);
+    process.exitCode = 1;
+  }
+  return;
+};
+HANDLERS.stack = async (argv) => {
+  // Dynamic: read THIS repo's manifests and report its real stack (not a static menu).
+  const { detectStack } = await import("./stack.js");
+  const s = detectStack(process.cwd());
+  if (argv.includes("--json")) return console.log(JSON.stringify(s, null, 2));
+  heading(`${BRAND.brand} stack — detected from this repo's manifests\n`);
+  const row = (label, arr) =>
+    arr.length ? console.log(`  ${`${label}:`.padEnd(11)} ${arr.join(", ")}`) : undefined;
+  if (!s.languages.length) {
+    console.log("  no known stack detected (no package.json/go.mod/Cargo.toml/… found).");
+    return;
+  }
+  row("languages", s.languages);
+  row("frameworks", s.frameworks);
+  row("pkg mgrs", s.packageManagers);
+  row("test", s.testCommands);
+  row("tools", s.tools);
+  row("notes", s.notes);
+  console.log(`  ${"evidence:".padEnd(11)} ${s.evidence.join(", ")}`);
+  return;
+};
+HANDLERS.radar = async (argv) => {
+  // Dependency-currency rings from live registry evidence (mizan — every ring ships its
+  // evidence; missing evidence never upgrades a dep). Injectable/cached/offline-honest.
+  const { radarScan } = await import("./radar.js");
+  const offline = argv.includes("--offline");
+  const refresh = argv.includes("--refresh");
+  const r = await radarScan(process.cwd(), { offline, refresh });
+  if (argv.includes("--json")) return console.log(JSON.stringify(r, null, 2));
+  if (!r.ok) {
+    console.log(`${BRAND.brand} radar — ${r.reason}`);
+    process.exitCode = 1;
+    return;
+  }
+  heading(`${BRAND.brand} radar — dependency currency (rings from registry evidence)\n`);
+  const deps = r.deps ?? {};
+  const names = Object.keys(deps);
+  if (!names.length) {
+    console.log("  no Node dependencies to probe (no package.json deps found).");
+  } else {
+    const roleFor = (ring) =>
+      ring === "adopt" ? "ok" : ring === "trial" ? "accent" : ring === "hold" ? "err" : "warn";
+    // Order by ring severity, then by usage (stakes), then name — the risky, load-bearing first.
+    const rank = { hold: 0, assess: 1, trial: 2, adopt: 3 };
+    names.sort(
+      (a, b) =>
+        (rank[deps[a].ring] ?? 9) - (rank[deps[b].ring] ?? 9) ||
+        (deps[b].usage ?? 0) - (deps[a].usage ?? 0) ||
+        (a < b ? -1 : 1),
+    );
+    const rows = names.map((n) => {
+      const d = deps[n];
+      return [
+        paint(d.ring, roleFor(d.ring)),
+        n,
+        `${d.installed ?? "?"}→${d.latest ?? "?"}`,
+        bar(d.score ?? 0),
+        (d.reasons ?? []).slice(0, 2).join("; ") || paint("no risk signals", "dim"),
+      ];
+    });
+    console.log(table(rows));
+  }
+  if (r.stale)
+    console.log(
+      `\n  ${paint(`served from cache (${Math.round(r.ageH)}h old) — ${offline ? "--offline" : "registry unreachable"}`, "dim")}`,
+    );
+  else if (r.source === "cache")
+    console.log(`\n  ${paint("served from cache (within TTL)", "dim")}`);
+  for (const s of r.skipped ?? []) console.log(`  ${paint(`${s.language}: ${s.reason}`, "dim")}`);
+  return;
+};
+HANDLERS.catalog = async () => {
+  const { catalog } = await import("./init.js");
+  const c = catalog();
+  heading(`${BRAND.brand} catalog — Start Here\n`);
+  console.log("  TOOLS (model-invoked skills)");
+  for (const t of c.tools) console.log(`    ${t.name.padEnd(18)} ${t.why.slice(0, 66)}`);
+  console.log(`\n  CREW (isolated sub-agents)   ${c.crew.join(" · ")}`);
+  console.log(`  GUARDS (enforced hooks)      ${c.guards.join(" · ")}`);
+  if (c.taste?.length)
+    console.log(
+      `  TASTE (design directions)    ${c.taste.join(" · ")}  →  \`${BRAND.cli} taste <style>\``,
+    );
+  if (c.cortex) console.log(`\n  CORTEX (self-correcting memory)  ${c.cortex}`);
+  if (c.preflight) console.log(`  PREFLIGHT (before you spend tokens)  ${c.preflight}`);
+  console.log(`\n  Full detail: ARCHITECTURE.md · per-tool config: \`${BRAND.cli} sync\``);
+  return;
+};
+HANDLERS.taste = async (argv) => {
+  const t = await import("./taste.js");
+  const style = argv[1];
+  if (!style) {
+    console.log(
+      `${BRAND.brand} taste — pick ONE visual direction per repo (every tool then follows it):\n`,
+    );
+    for (const s of t.list()) console.log(`  ${s}`);
+    console.log(`\n  apply: \`${BRAND.cli} taste <style>\`  (writes a managed DESIGN.md)`);
+    return;
+  }
+  const res = t.apply(style, process.cwd());
+  if (res.ok) {
+    console.log(
+      `  DESIGN.md ${res.action} → taste: ${res.style}. Every AI tool now builds in this direction.`,
+    );
+  } else {
+    console.error(`  ${res.reason}`);
+    process.exitCode = 1;
+  }
+  return;
+};
+HANDLERS.sync = async () => {
+  const { sync } = await import("./sync.js");
+  const { report, warnings, bytes, partial, status } = sync({
+    targetRoot: process.cwd(),
+  });
+  heading(`${BRAND.brand} sync — one source → every tool\n`);
+  for (const r of report) {
+    console.log(
+      `  ${r.action.padEnd(16)} ${String(r.target).padEnd(22)} ${r.tool}${r.note ? `  · ${r.note}` : ""}`,
+    );
+  }
+  for (const w of warnings) console.warn(`  ! ${w}`);
+  const written = report.filter((r) => r.action === "written").length;
+  console.log(`\n${written} file(s) written · canonical ${bytes} B · status: ${status}`);
+  // ME-19: a mid-way target failure must NOT exit 0 as if every tool were configured.
+  if (partial) {
+    const failed = report.filter((r) => r.action === "error");
+    console.error(
+      `  ! PARTIAL sync — ${failed.length} target(s) failed: ${failed.map((r) => r.tool).join(", ")}`,
+    );
+    process.exitCode = 1;
+  }
+  return;
+};
+HANDLERS.doctor = async (argv) => {
+  const { doctor } = await import("./doctor.js");
+  const fix = argv.includes("--fix");
+  const { results, failed, repairs, health } = doctor({
+    targetRoot: process.cwd(),
+    fix,
+  });
+  if (argv.includes("--json")) {
+    console.log(JSON.stringify({ results, failed, repairs, health }, null, 2));
+    if (failed) process.exitCode = 1;
+    return;
+  }
+  const icon = {
+    ok: paint("✓", "ok"),
+    warn: paint("!", "warn"),
+    fail: paint("✗", "err"),
+    na: paint("–", "dim"), // not built/applicable — neutral, never a failure
+  };
+  heading(`${BRAND.brand} doctor\n`);
+  if (fix) {
+    if (repairs.length) {
+      console.log("  repairs:");
+      for (const rep of repairs)
+        console.log(
+          `  ${rep.ok ? paint("✓", "ok") : paint("✗", "err")} ${rep.label}${rep.ok ? "" : ` — ${rep.error}`}`,
+        );
+      console.log("");
+    } else {
+      console.log(`  ${paint("✓", "ok")} nothing to repair\n`);
     }
-    row("languages", s.languages);
-    row("frameworks", s.frameworks);
-    row("pkg mgrs", s.packageManagers);
-    row("test", s.testCommands);
-    row("tools", s.tools);
-    row("notes", s.notes);
-    console.log(`  ${"evidence:".padEnd(11)} ${s.evidence.join(", ")}`);
-    return;
-  }
-  if (cmd === "radar") {
-    // Dependency-currency rings from live registry evidence (mizan — every ring ships its
-    // evidence; missing evidence never upgrades a dep). Injectable/cached/offline-honest.
-    const { radarScan } = await import("./radar.js");
-    const offline = argv.includes("--offline");
-    const refresh = argv.includes("--refresh");
-    const r = await radarScan(process.cwd(), { offline, refresh });
-    if (argv.includes("--json")) return console.log(JSON.stringify(r, null, 2));
-    if (!r.ok) {
-      console.log(`${BRAND.brand} radar — ${r.reason}`);
+  }
+  for (const r of results) console.log(`  ${icon[r.status]} ${r.label.padEnd(16)} ${r.note}`);
+  // Subsystem health in the standard vocabulary (P1-06) — a degraded control stays visible.
+  const healthLine = Object.entries(health)
+    .map(([k, v]) => `${k}=${v}`)
+    .join("  ");
+  console.log(`\n  health: ${healthLine}`);
+  console.log(
+    `\n${failed === 0 ? paint("all clear", "ok") : paint(`${failed} problem(s)`, "err")}`,
+  );
+  if (failed) process.exitCode = 1;
+  return;
+};
+HANDLERS.docs = async (argv) => {
+  const json = argv.includes("--json");
+  const sub = argv.slice(1).filter((a) => !a.startsWith("--"))[0] || "check";
+  // `sync` sweeps THIS repo's diff for stale doc mentions (advisory by default —
+  // it runs mid-repair from the completion gate's checklist; --strict for CI).
+  if (sub === "sync") {
+    const { docsSyncReport, renderDocsSync } = await import("./docs_sync.js");
+    const baseIdx = argv.indexOf("--base");
+    const r = docsSyncReport(process.cwd(), {
+      base: baseIdx >= 0 ? argv[baseIdx + 1] : undefined,
+    });
+    if (json) console.log(JSON.stringify(r, null, 2));
+    else console.log(renderDocsSync(r));
+    if (r.error || (argv.includes("--strict") && r.stale.length)) process.exitCode = 1;
+    return;
+  }
+  // `impact` — reusable documentation-impact graph: which documented surfaces
+  // reference the entities THIS diff changed (advisory; --strict exits 1).
+  if (sub === "impact") {
+    const { docsImpact, renderDocsImpact } = await import("./docs_impact.js");
+    const { newestBaseline } = await import("./docs_sync.js");
+    const staged = argv.includes("--staged");
+    const sinceIdx = argv.indexOf("--since");
+    const base = sinceIdx >= 0 ? argv[sinceIdx + 1] : newestBaseline(process.cwd()) || undefined;
+    const mcIdx = argv.indexOf("--min-confidence");
+    const minConfidence = mcIdx >= 0 ? Number(argv[mcIdx + 1]) : 0;
+    const r = docsImpact(process.cwd(), { base, staged, minConfidence });
+    if (json) console.log(JSON.stringify(r, null, 2));
+    else console.log(renderDocsImpact(r));
+    if (argv.includes("--strict") && r.impacted.length) process.exitCode = 1;
+    return;
+  }
+  // `check` — self-check of the forge package's own docs against its code (commands
+  // table, env reads, MCP registry, CHANGELOG).
+  const { docsCheck } = await import("./docs_check.js");
+  const r = docsCheck();
+  if (json) {
+    console.log(JSON.stringify(r, null, 2));
+    if (!r.ok) process.exitCode = 1;
+    return;
+  }
+  heading(`${BRAND.brand} docs check — docs↔code drift\n`);
+  if (!r.issues.length) console.log(`  ✓ docs and code agree (${r.checked.join(", ")})`);
+  for (const i of r.issues)
+    console.log(`  ${i.severity === "error" ? "✗" : "!"} [${i.check}] ${i.detail}`);
+  if (!r.ok) {
+    console.log(`\n${r.issues.filter((i) => i.severity === "error").length} problem(s)`);
+    process.exitCode = 1;
+  }
+  // Advisory: if the working tree changed a documented entity, point at the impacted
+  // prose. Never fails the check (fail-open); best-effort, so a git-less tree is silent.
+  try {
+    const { docsImpact } = await import("./docs_impact.js");
+    const imp = docsImpact(process.cwd());
+    if (imp.impacted.length)
+      console.log(
+        `\n  ! ${imp.summary.impactedFiles} doc file(s) may be stale from this diff — run \`${BRAND.cli} docs impact\` to review`,
+      );
+  } catch {}
+  return;
+};
+HANDLERS.integrations = async (argv) => {
+  const { listIntegrations, planIntegration, addIntegration, removeIntegration } = await import(
+    "./integrations.js"
+  );
+  const sub = argv[1];
+  if (sub === "add") {
+    const name = argv[2];
+    const plan = planIntegration(name);
+    if (!plan.ok) {
+      console.error(plan.reason);
       process.exitCode = 1;
       return;
     }
-    heading(`${BRAND.brand} radar — dependency currency (rings from registry evidence)\n`);
-    const deps = r.deps ?? {};
-    const names = Object.keys(deps);
-    if (!names.length) {
-      console.log("  no Node dependencies to probe (no package.json deps found).");
-    } else {
-      const roleFor = (ring) =>
-        ring === "adopt" ? "ok" : ring === "trial" ? "accent" : ring === "hold" ? "err" : "warn";
-      // Order by ring severity, then by usage (stakes), then name — the risky, load-bearing first.
-      const rank = { hold: 0, assess: 1, trial: 2, adopt: 3 };
-      names.sort(
-        (a, b) =>
-          (rank[deps[a].ring] ?? 9) - (rank[deps[b].ring] ?? 9) ||
-          (deps[b].usage ?? 0) - (deps[a].usage ?? 0) ||
-          (a < b ? -1 : 1),
-      );
-      const rows = names.map((n) => {
-        const d = deps[n];
-        return [
-          paint(d.ring, roleFor(d.ring)),
-          n,
-          `${d.installed ?? "?"}→${d.latest ?? "?"}`,
-          bar(d.score ?? 0),
-          (d.reasons ?? []).slice(0, 2).join("; ") || paint("no risk signals", "dim"),
-        ];
-      });
-      console.log(table(rows));
-    }
-    if (r.stale)
+    if (!argv.includes("--yes")) {
+      heading(`${BRAND.brand} integrations — add ${name}\n`);
+      console.log(`  This adds a THIRD-PARTY MCP server to every detected tool's config:`);
+      console.log(`    package: ${plan.pkg}`);
+      console.log(`    network: ${plan.network}`);
+      console.log(`    purpose: ${plan.why}`);
+      console.log(`    writes:  .mcp.json, .cursor/mcp.json, .gemini/…, .codex/…, .continue/…`);
+      console.log(`    records: .forge/forge.config.json (mcp.integrations — the managed set)`);
       console.log(
-        `\n  ${paint(`served from cache (${Math.round(r.ageH)}h old) — ${offline ? "--offline" : "registry unreachable"}`, "dim")}`,
+        `\n  Not installed. Re-run with --yes to apply:  ${BRAND.cli} integrations add ${name} --yes`,
       );
-    else if (r.source === "cache")
-      console.log(`\n  ${paint("served from cache (within TTL)", "dim")}`);
-    for (const s of r.skipped ?? []) console.log(`  ${paint(`${s.language}: ${s.reason}`, "dim")}`);
-    return;
-  }
-  if (cmd === "catalog") {
-    const { catalog } = await import("./init.js");
-    const c = catalog();
-    heading(`${BRAND.brand} catalog — Start Here\n`);
-    console.log("  TOOLS (model-invoked skills)");
-    for (const t of c.tools) console.log(`    ${t.name.padEnd(18)} ${t.why.slice(0, 66)}`);
-    console.log(`\n  CREW (isolated sub-agents)   ${c.crew.join(" · ")}`);
-    console.log(`  GUARDS (enforced hooks)      ${c.guards.join(" · ")}`);
-    if (c.taste?.length)
       console.log(
-        `  TASTE (design directions)    ${c.taste.join(" · ")}  →  \`${BRAND.cli} taste <style>\``,
+        `  A same-name server you configured yourself is never overwritten unless you also pass --adopt.`,
       );
-    if (c.cortex) console.log(`\n  CORTEX (self-correcting memory)  ${c.cortex}`);
-    if (c.preflight) console.log(`  PREFLIGHT (before you spend tokens)  ${c.preflight}`);
-    console.log(`\n  Full detail: ARCHITECTURE.md · per-tool config: \`${BRAND.cli} sync\``);
+      return;
+    }
+    const res = addIntegration(name, {
+      targetRoot: process.cwd(),
+      adopt: argv.includes("--adopt"),
+    });
+    heading(`${BRAND.brand} integrations — add ${name}\n`);
+    if (res.ok === false) {
+      console.error(`  ${res.reason}`);
+      process.exitCode = 1;
+      return;
+    }
+    const wrote = res.rows.filter((x) => x.action === "written").map((x) => x.target);
+    console.log(`  added ${name} → ${wrote.length ? wrote.join(", ") : "(all up to date)"}`);
+    for (const r of res.rows.filter((x) => x.action === "skipped"))
+      console.log(`  ! ${r.target}: ${r.note}`);
     return;
   }
-  if (cmd === "taste") {
-    const t = await import("./taste.js");
-    const style = argv[1];
-    if (!style) {
-      console.log(
-        `${BRAND.brand} taste — pick ONE visual direction per repo (every tool then follows it):\n`,
-      );
-      for (const s of t.list()) console.log(`  ${s}`);
-      console.log(`\n  apply: \`${BRAND.cli} taste <style>\`  (writes a managed DESIGN.md)`);
+  if (sub === "remove") {
+    const name = argv[2];
+    const res = removeIntegration(name, { targetRoot: process.cwd() });
+    heading(`${BRAND.brand} integrations — remove ${name}\n`);
+    if (res.ok === false) {
+      console.error(`  ${res.reason}`);
+      process.exitCode = 1;
       return;
     }
-    const res = t.apply(style, process.cwd());
-    if (res.ok) {
-      console.log(
-        `  DESIGN.md ${res.action} → taste: ${res.style}. Every AI tool now builds in this direction.`,
-      );
-    } else {
-      console.error(`  ${res.reason}`);
+    if (!res.removed) {
+      console.log(`  ${name} is not installed — nothing to remove`);
+      return;
+    }
+    const wrote = res.rows.filter((x) => x.action === "written").map((x) => x.target);
+    console.log(`  removed ${name} → ${wrote.length ? wrote.join(", ") : "(nothing on disk)"}`);
+    for (const r of res.rows.filter((x) => x.action === "skipped"))
+      console.log(`  ! ${r.target}: ${r.note}`);
+    return;
+  }
+  // Default: list what's available.
+  heading(`${BRAND.brand} integrations — opt-in third-party MCP servers\n`);
+  for (const it of listIntegrations()) {
+    console.log(`  ${it.name.padEnd(12)} ${it.why}  (${it.pkg})`);
+  }
+  console.log(`\n  Add one with:     ${BRAND.cli} integrations add <name>`);
+  console.log(`  Remove one with:  ${BRAND.cli} integrations remove <name>`);
+  return;
+};
+HANDLERS.recall = async (argv) => {
+  const r = await import("./recall.js");
+  const store = r.defaultStore();
+  const sub = argv[1] || "list";
+  if (sub === "list") {
+    const items = r.list(store);
+    console.log(items.length ? items.map((s) => `  - ${s}`).join("\n") : "  (no memories yet)");
+  } else if (sub === "add") {
+    const name = argv[2];
+    const body = argv.slice(3).join(" ");
+    if (!name || !body) {
+      console.error('usage: forge recall add "<name>" "<fact>"');
       process.exitCode = 1;
+      return;
+    }
+    const res = r.add(store, name, body);
+    if (res.ok) {
+      // Shadow the fact into the PERSONAL ledger beside the global store (repo
+      // promotion stays an explicit act — docs/plans/substrate-v2/02-team-memory.md §3).
+      // Best-effort INCLUDING the imports: a broken bridge module must never turn an
+      // already-persisted fact into a CLI failure.
+      try {
+        const { join } = await import("node:path");
+        const { shadowFact } = await import("./ledger_bridge.js");
+        shadowFact(join(store, "ledger"), name, body);
+      } catch {}
+      // Re-index after the shadow so a ledger-only store's MEMORY.md includes the fact
+      // (its only copy now lives in the ledger, written just above).
+      r.reindex(store);
     }
+    console.log(res.ok ? `  saved: ${res.slug}` : `  ${res.reason}`);
+    if (!res.ok) process.exitCode = 1;
+  } else if (sub === "consolidate") {
+    const { removed, kept } = r.consolidate(store);
+    try {
+      // Deleted duplicates must not survive as live claims in the shadow ledger.
+      const { join } = await import("node:path");
+      const { reconcileFacts } = await import("./ledger_bridge.js");
+      reconcileFacts(store, join(store, "ledger"));
+    } catch {}
+    console.log(`  consolidated: ${removed} duplicate(s) removed, ${kept} kept`);
+  } else {
+    console.error(`recall: unknown subcommand "${sub}" (list | add | consolidate)`);
+    process.exitCode = 1;
+  }
+  return;
+};
+HANDLERS.ledger = async (argv) => {
+  const ls = await import("./ledger_store.js");
+  const { epochDay, gitAuthor } = await import("./util.js");
+  const root = process.cwd();
+  // --personal targets the ledger beside the global recall store (~/.forge/recall/
+  // ledger) — otherwise facts shadowed by `forge recall add` would be write-only,
+  // with no command able to inspect or verify them.
+  const personal = argv.includes("--personal");
+  const args = argv.filter((a) => a !== "--json" && a !== "--personal");
+  const dir = personal
+    ? (await import("node:path")).join((await import("./recall.js")).defaultStore(), "ledger")
+    : ls.repoLedger(root);
+  const sub = args[1] || "stats";
+  const json = argv.includes("--json");
+  const nowDay = epochDay();
+  if (sub === "stats") {
+    const s = ls.stats(dir, nowDay);
+    if (json) return console.log(JSON.stringify(s, null, 2));
+    heading(`${BRAND.brand} ledger — proof-carrying memory\n`);
+    console.log(`  claims: ${s.total}  (tombstoned ${s.tombstoned})`);
+    for (const [kind, n] of Object.entries(s.byKind)) console.log(`    ${kind}: ${n}`);
+    console.log(
+      `  val: ${paint(`trusted ${s.val.trusted}`, "ok")} · ${paint(`uncertain ${s.val.uncertain}`, "warn")} · ${paint(`dormant ${s.val.dormant}`, "dim")}`,
+    );
+    console.log(
+      paint("\n  stored in .forge/ledger/ (git-committable, conflict-free merge)", "dim"),
+    );
     return;
   }
-  if (cmd === "sync") {
-    const { sync } = await import("./sync.js");
-    const { report, warnings, bytes, partial, status } = sync({
-      targetRoot: process.cwd(),
-    });
-    heading(`${BRAND.brand} sync — one source → every tool\n`);
-    for (const r of report) {
-      console.log(
-        `  ${r.action.padEnd(16)} ${String(r.target).padEnd(22)} ${r.tool}${r.note ? `  · ${r.note}` : ""}`,
+  if (sub === "verify") {
+    const r = ls.verify(dir);
+    if (json) return console.log(JSON.stringify(r, null, 2));
+    console.log(`  ${r.ok ? "OK" : "ISSUES"} — ${r.claims} claim(s), ${r.outcomes} outcome(s)`);
+    for (const i of r.issues) console.log(`    - ${i}`);
+    if (!r.ok) process.exitCode = 1;
+    return;
+  }
+  if (sub === "show") {
+    const id = args[2];
+    const hit = id && id.length >= 2 ? ls.getClaimByPrefix(dir, id) : null;
+    if (!hit) {
+      console.error(
+        id ? `  no claim matching ${id}` : "usage: forge ledger show <id-prefix (≥2 chars)>",
       );
+      process.exitCode = 1;
+      return;
     }
-    for (const w of warnings) console.warn(`  ! ${w}`);
-    const written = report.filter((r) => r.action === "written").length;
-    console.log(`\n${written} file(s) written · canonical ${bytes} B · status: ${status}`);
-    // ME-19: a mid-way target failure must NOT exit 0 as if every tool were configured.
-    if (partial) {
-      const failed = report.filter((r) => r.action === "error");
+    const { val } = await import("./ledger.js");
+    return console.log(JSON.stringify({ ...hit, val: val(hit, nowDay) }, null, 2));
+  }
+  if (sub === "merge") {
+    const src = args[2];
+    const { existsSync } = await import("node:fs");
+    if (!src || !existsSync(src)) {
       console.error(
-        `  ! PARTIAL sync — ${failed.length} target(s) failed: ${failed.map((r) => r.tool).join(", ")}`,
+        src
+          ? `  no ledger at ${src}`
+          : "usage: forge ledger merge <path-to-ledger-dir>  (a teammate's checkout, a backup, a worktree)",
       );
       process.exitCode = 1;
+      return;
     }
+    const r = ls.mergeDirs(dir, src);
+    if (json) return console.log(JSON.stringify(r, null, 2));
+    console.log(`  merged: ${r.claims} new claim(s), ${r.records} new record(s) — conflict-free`);
+    if (r.quarantined)
+      console.log(
+        `  quarantined: ${r.quarantined} invalid record(s) (forged hash or unresolvable ref — see quarantine/ in the ledger dir)`,
+      );
     return;
   }
-  if (cmd === "doctor") {
-    const { doctor } = await import("./doctor.js");
-    const fix = argv.includes("--fix");
-    const { results, failed, repairs, health } = doctor({
-      targetRoot: process.cwd(),
-      fix,
-    });
-    if (argv.includes("--json")) {
-      console.log(JSON.stringify({ results, failed, repairs, health }, null, 2));
-      if (failed) process.exitCode = 1;
+  if (sub === "blame") {
+    const b = args[2] && args[2].length >= 2 ? ls.blame(dir, args[2], nowDay) : null;
+    if (!b) {
+      console.error(
+        args[2] ? `  no claim matching ${args[2]}` : "usage: forge ledger blame <id-prefix>",
+      );
+      process.exitCode = 1;
       return;
     }
-    const icon = {
-      ok: paint("✓", "ok"),
-      warn: paint("!", "warn"),
-      fail: paint("✗", "err"),
-      na: paint("–", "dim"), // not built/applicable — neutral, never a failure
-    };
-    heading(`${BRAND.brand} doctor\n`);
-    if (fix) {
-      if (repairs.length) {
-        console.log("  repairs:");
-        for (const rep of repairs)
-          console.log(
-            `  ${rep.ok ? paint("✓", "ok") : paint("✗", "err")} ${rep.label}${rep.ok ? "" : ` — ${rep.error}`}`,
-          );
-        console.log("");
-      } else {
-        console.log(`  ${paint("✓", "ok")} nothing to repair\n`);
-      }
-    }
-    for (const r of results) console.log(`  ${icon[r.status]} ${r.label.padEnd(16)} ${r.note}`);
-    // Subsystem health in the standard vocabulary (P1-06) — a degraded control stays visible.
-    const healthLine = Object.entries(health)
-      .map(([k, v]) => `${k}=${v}`)
-      .join("  ");
-    console.log(`\n  health: ${healthLine}`);
+    if (json) return console.log(JSON.stringify(b, null, 2));
+    heading(`${BRAND.brand} ledger blame — ${b.kind} ${b.id.slice(0, 12)}\n`);
     console.log(
-      `\n${failed === 0 ? paint("all clear", "ok") : paint(`${failed} problem(s)`, "err")}`,
+      `  val ${bar(b.val)} ${b.val.toFixed(2)} (trust-weighted ${b.valTrustWeighted.toFixed(2)})`,
     );
-    if (failed) process.exitCode = 1;
+    for (const p of b.minted)
+      console.log(
+        `  minted  day ${p.t}  by ${p.author || "(unknown)"}${p.agent ? ` · ${p.agent}` : ""}`,
+      );
+    for (const e of b.evidence)
+      console.log(
+        `  ${e.result === "confirm" ? paint("confirm ", "ok") : paint("contradic", "err")}  day ${e.t}  ${e.oracle} → ${e.ref}${e.author ? `  by ${e.author}` : ""}`,
+      );
+    for (const t of b.tombstones)
+      console.log(
+        paint(`  retract  day ${t.t}  ${t.reason}${t.author ? `  by ${t.author}` : ""}`, "dim"),
+      );
+    const trusts = Object.entries(b.trust);
+    if (trusts.length) {
+      console.log("\n  author trust (earned from oracle outcomes on their claims):");
+      for (const [a, u] of trusts) console.log(`    ${u.toFixed(2)}  ${a}`);
+    }
     return;
   }
-  if (cmd === "docs") {
-    const json = argv.includes("--json");
-    const sub = argv.slice(1).filter((a) => !a.startsWith("--"))[0] || "check";
-    // `sync` sweeps THIS repo's diff for stale doc mentions (advisory by default —
-    // it runs mid-repair from the completion gate's checklist; --strict for CI).
-    if (sub === "sync") {
-      const { docsSyncReport, renderDocsSync } = await import("./docs_sync.js");
-      const baseIdx = argv.indexOf("--base");
-      const r = docsSyncReport(process.cwd(), {
-        base: baseIdx >= 0 ? argv[baseIdx + 1] : undefined,
-      });
-      if (json) console.log(JSON.stringify(r, null, 2));
-      else console.log(renderDocsSync(r));
-      if (r.error || (argv.includes("--strict") && r.stale.length)) process.exitCode = 1;
+  // The two writes (08-dashboard-ux.md §2) — CLI twins of the dashboard's POSTs, so
+  // the dashboard stays a convenience, never a requirement. Both append-only.
+  if (sub === "ratify") {
+    const id = args[2];
+    if (!id || id.length < 2) {
+      console.error("usage: forge ledger ratify <id-prefix (≥2 chars)>");
+      process.exitCode = 1;
       return;
     }
-    // `impact` — reusable documentation-impact graph: which documented surfaces
-    // reference the entities THIS diff changed (advisory; --strict exits 1).
-    if (sub === "impact") {
-      const { docsImpact, renderDocsImpact } = await import("./docs_impact.js");
-      const { newestBaseline } = await import("./docs_sync.js");
-      const staged = argv.includes("--staged");
-      const sinceIdx = argv.indexOf("--since");
-      const base = sinceIdx >= 0 ? argv[sinceIdx + 1] : newestBaseline(process.cwd()) || undefined;
-      const mcIdx = argv.indexOf("--min-confidence");
-      const minConfidence = mcIdx >= 0 ? Number(argv[mcIdx + 1]) : 0;
-      const r = docsImpact(process.cwd(), { base, staged, minConfidence });
-      if (json) console.log(JSON.stringify(r, null, 2));
-      else console.log(renderDocsImpact(r));
-      if (argv.includes("--strict") && r.impacted.length) process.exitCode = 1;
+    // Human-only promotion: the author is YOUR git identity, minted as a decision claim.
+    const r = ls.ratify(dir, id, { author: gitAuthor(), t: nowDay });
+    if (!r.ok) {
+      console.error(`  ${r.reason}`);
+      process.exitCode = 1;
       return;
     }
-    // `check` — self-check of the forge package's own docs against its code (commands
-    // table, env reads, MCP registry, CHANGELOG).
-    const { docsCheck } = await import("./docs_check.js");
-    const r = docsCheck();
-    if (json) {
-      console.log(JSON.stringify(r, null, 2));
-      if (!r.ok) process.exitCode = 1;
+    if (json) return console.log(JSON.stringify(r, null, 2));
+    console.log(
+      `  ratified ${r.ratifies.slice(0, 12)} → decision ${r.decisionId.slice(0, 12)}${r.existed ? " (already ratified — same decision)" : ""}`,
+    );
+    return;
+  }
+  if (sub === "retract") {
+    const id = args[2];
+    const ri = args.indexOf("--reason");
+    const reason = ri >= 0 ? (args[ri + 1] ?? "") : "";
+    if (!id || id.length < 2 || id === "--reason" || !reason) {
+      console.error('usage: forge ledger retract <id-prefix> --reason "<why>"');
+      process.exitCode = 1;
+      return;
+    }
+    const hit = ls.getClaimByPrefix(dir, id);
+    if (!hit) {
+      console.error(`  no claim matching ${id}`);
+      process.exitCode = 1;
       return;
     }
-    heading(`${BRAND.brand} docs check — docs↔code drift\n`);
-    if (!r.issues.length) console.log(`  ✓ docs and code agree (${r.checked.join(", ")})`);
-    for (const i of r.issues)
-      console.log(`  ${i.severity === "error" ? "✗" : "!"} [${i.check}] ${i.detail}`);
+    const r = ls.tombstone(dir, hit.id, {
+      author: gitAuthor(),
+      reason,
+      t: nowDay,
+    });
     if (!r.ok) {
-      console.log(`\n${r.issues.filter((i) => i.severity === "error").length} problem(s)`);
+      console.error(`  ${r.reason}`);
       process.exitCode = 1;
+      return;
     }
-    // Advisory: if the working tree changed a documented entity, point at the impacted
-    // prose. Never fails the check (fail-open); best-effort, so a git-less tree is silent.
-    try {
-      const { docsImpact } = await import("./docs_impact.js");
-      const imp = docsImpact(process.cwd());
-      if (imp.impacted.length)
-        console.log(
-          `\n  ! ${imp.summary.impactedFiles} doc file(s) may be stale from this diff — run \`${BRAND.cli} docs impact\` to review`,
-        );
-    } catch {}
+    if (json) return console.log(JSON.stringify({ ...r, id: hit.id }, null, 2));
+    console.log(
+      `  retracted ${hit.id.slice(0, 12)} — ${reason}${r.deduped ? " (already retracted with this record)" : ""}`,
+    );
     return;
   }
-  if (cmd === "integrations") {
-    const { listIntegrations, planIntegration, addIntegration, removeIntegration } = await import(
-      "./integrations.js"
-    );
-    const sub = argv[1];
-    if (sub === "add") {
-      const name = argv[2];
-      const plan = planIntegration(name);
-      if (!plan.ok) {
-        console.error(plan.reason);
-        process.exitCode = 1;
-        return;
-      }
-      if (!argv.includes("--yes")) {
-        heading(`${BRAND.brand} integrations — add ${name}\n`);
-        console.log(`  This adds a THIRD-PARTY MCP server to every detected tool's config:`);
-        console.log(`    package: ${plan.pkg}`);
-        console.log(`    network: ${plan.network}`);
-        console.log(`    purpose: ${plan.why}`);
-        console.log(`    writes:  .mcp.json, .cursor/mcp.json, .gemini/…, .codex/…, .continue/…`);
-        console.log(`    records: .forge/forge.config.json (mcp.integrations — the managed set)`);
-        console.log(
-          `\n  Not installed. Re-run with --yes to apply:  ${BRAND.cli} integrations add ${name} --yes`,
-        );
-        console.log(
-          `  A same-name server you configured yourself is never overwritten unless you also pass --adopt.`,
-        );
-        return;
-      }
-      const res = addIntegration(name, {
-        targetRoot: process.cwd(),
-        adopt: argv.includes("--adopt"),
-      });
-      heading(`${BRAND.brand} integrations — add ${name}\n`);
-      if (res.ok === false) {
-        console.error(`  ${res.reason}`);
-        process.exitCode = 1;
-        return;
-      }
-      const wrote = res.rows.filter((x) => x.action === "written").map((x) => x.target);
-      console.log(`  added ${name} → ${wrote.length ? wrote.join(", ") : "(all up to date)"}`);
-      for (const r of res.rows.filter((x) => x.action === "skipped"))
-        console.log(`  ! ${r.target}: ${r.note}`);
-      return;
-    }
-    if (sub === "remove") {
-      const name = argv[2];
-      const res = removeIntegration(name, { targetRoot: process.cwd() });
-      heading(`${BRAND.brand} integrations — remove ${name}\n`);
-      if (res.ok === false) {
-        console.error(`  ${res.reason}`);
-        process.exitCode = 1;
-        return;
-      }
-      if (!res.removed) {
-        console.log(`  ${name} is not installed — nothing to remove`);
-        return;
-      }
-      const wrote = res.rows.filter((x) => x.action === "written").map((x) => x.target);
-      console.log(`  removed ${name} → ${wrote.length ? wrote.join(", ") : "(nothing on disk)"}`);
-      for (const r of res.rows.filter((x) => x.action === "skipped"))
-        console.log(`  ! ${r.target}: ${r.note}`);
-      return;
-    }
-    // Default: list what's available.
-    heading(`${BRAND.brand} integrations — opt-in third-party MCP servers\n`);
-    for (const it of listIntegrations()) {
-      console.log(`  ${it.name.padEnd(12)} ${it.why}  (${it.pkg})`);
-    }
-    console.log(`\n  Add one with:     ${BRAND.cli} integrations add <name>`);
-    console.log(`  Remove one with:  ${BRAND.cli} integrations remove <name>`);
-    return;
-  }
-  if (cmd === "recall") {
-    const r = await import("./recall.js");
-    const store = r.defaultStore();
-    const sub = argv[1] || "list";
-    if (sub === "list") {
-      const items = r.list(store);
-      console.log(items.length ? items.map((s) => `  - ${s}`).join("\n") : "  (no memories yet)");
-    } else if (sub === "add") {
-      const name = argv[2];
-      const body = argv.slice(3).join(" ");
-      if (!name || !body) {
-        console.error('usage: forge recall add "<name>" "<fact>"');
-        process.exitCode = 1;
-        return;
-      }
-      const res = r.add(store, name, body);
-      if (res.ok) {
-        // Shadow the fact into the PERSONAL ledger beside the global store (repo
-        // promotion stays an explicit act — docs/plans/substrate-v2/02-team-memory.md §3).
-        // Best-effort INCLUDING the imports: a broken bridge module must never turn an
-        // already-persisted fact into a CLI failure.
-        try {
-          const { join } = await import("node:path");
-          const { shadowFact } = await import("./ledger_bridge.js");
-          shadowFact(join(store, "ledger"), name, body);
-        } catch {}
-        // Re-index after the shadow so a ledger-only store's MEMORY.md includes the fact
-        // (its only copy now lives in the ledger, written just above).
-        r.reindex(store);
-      }
-      console.log(res.ok ? `  saved: ${res.slug}` : `  ${res.reason}`);
-      if (!res.ok) process.exitCode = 1;
-    } else if (sub === "consolidate") {
-      const { removed, kept } = r.consolidate(store);
-      try {
-        // Deleted duplicates must not survive as live claims in the shadow ledger.
-        const { join } = await import("node:path");
-        const { reconcileFacts } = await import("./ledger_bridge.js");
-        reconcileFacts(store, join(store, "ledger"));
-      } catch {}
-      console.log(`  consolidated: ${removed} duplicate(s) removed, ${kept} kept`);
-    } else {
-      console.error(`recall: unknown subcommand "${sub}" (list | add | consolidate)`);
+  if (sub === "query") {
+    const q = args.slice(2).join(" ");
+    if (!q) {
+      console.error('usage: forge ledger query "<what you are about to do>"');
       process.exitCode = 1;
-    }
-    return;
-  }
-  if (cmd === "ledger") {
-    const ls = await import("./ledger_store.js");
-    const { epochDay, gitAuthor } = await import("./util.js");
-    const root = process.cwd();
-    // --personal targets the ledger beside the global recall store (~/.forge/recall/
-    // ledger) — otherwise facts shadowed by `forge recall add` would be write-only,
-    // with no command able to inspect or verify them.
-    const personal = argv.includes("--personal");
-    const args = argv.filter((a) => a !== "--json" && a !== "--personal");
-    const dir = personal
-      ? (await import("node:path")).join((await import("./recall.js")).defaultStore(), "ledger")
-      : ls.repoLedger(root);
-    const sub = args[1] || "stats";
-    const json = argv.includes("--json");
-    const nowDay = epochDay();
-    if (sub === "stats") {
-      const s = ls.stats(dir, nowDay);
-      if (json) return console.log(JSON.stringify(s, null, 2));
-      heading(`${BRAND.brand} ledger — proof-carrying memory\n`);
-      console.log(`  claims: ${s.total}  (tombstoned ${s.tombstoned})`);
-      for (const [kind, n] of Object.entries(s.byKind)) console.log(`    ${kind}: ${n}`);
-      console.log(
-        `  val: ${paint(`trusted ${s.val.trusted}`, "ok")} · ${paint(`uncertain ${s.val.uncertain}`, "warn")} · ${paint(`dormant ${s.val.dormant}`, "dim")}`,
-      );
-      console.log(
-        paint("\n  stored in .forge/ledger/ (git-committable, conflict-free merge)", "dim"),
-      );
-      return;
-    }
-    if (sub === "verify") {
-      const r = ls.verify(dir);
-      if (json) return console.log(JSON.stringify(r, null, 2));
-      console.log(`  ${r.ok ? "OK" : "ISSUES"} — ${r.claims} claim(s), ${r.outcomes} outcome(s)`);
-      for (const i of r.issues) console.log(`    - ${i}`);
-      if (!r.ok) process.exitCode = 1;
-      return;
-    }
-    if (sub === "show") {
-      const id = args[2];
-      const hit = id && id.length >= 2 ? ls.getClaimByPrefix(dir, id) : null;
-      if (!hit) {
-        console.error(
-          id ? `  no claim matching ${id}` : "usage: forge ledger show <id-prefix (≥2 chars)>",
-        );
-        process.exitCode = 1;
-        return;
-      }
-      const { val } = await import("./ledger.js");
-      return console.log(JSON.stringify({ ...hit, val: val(hit, nowDay) }, null, 2));
-    }
-    if (sub === "merge") {
-      const src = args[2];
-      const { existsSync } = await import("node:fs");
-      if (!src || !existsSync(src)) {
-        console.error(
-          src
-            ? `  no ledger at ${src}`
-            : "usage: forge ledger merge <path-to-ledger-dir>  (a teammate's checkout, a backup, a worktree)",
-        );
-        process.exitCode = 1;
-        return;
-      }
-      const r = ls.mergeDirs(dir, src);
-      if (json) return console.log(JSON.stringify(r, null, 2));
-      console.log(`  merged: ${r.claims} new claim(s), ${r.records} new record(s) — conflict-free`);
-      if (r.quarantined)
-        console.log(
-          `  quarantined: ${r.quarantined} invalid record(s) (forged hash or unresolvable ref — see quarantine/ in the ledger dir)`,
-        );
       return;
     }
-    if (sub === "blame") {
-      const b = args[2] && args[2].length >= 2 ? ls.blame(dir, args[2], nowDay) : null;
-      if (!b) {
-        console.error(
-          args[2] ? `  no claim matching ${args[2]}` : "usage: forge ledger blame <id-prefix>",
-        );
-        process.exitCode = 1;
-        return;
-      }
-      if (json) return console.log(JSON.stringify(b, null, 2));
-      heading(`${BRAND.brand} ledger blame — ${b.kind} ${b.id.slice(0, 12)}\n`);
+    const { retrieve, claimText } = await import("./ledger.js");
+    // The embeddings tier (ADR-0005) is assembled HERE, not in ledger.js — the pure
+    // core stays provider-free. No FORGE_EMBED (or a failing provider) → sim is
+    // null and retrieval is the stock MinHash path.
+    const { claimSim, simLabel } = await import("./embed.js");
+    const claims = ls.loadClaims(dir);
+    const sim = claimSim(root, q, claims, claimText);
+    const ranked = retrieve(q, claims, { nowDay, budget: 8, sim });
+    if (json)
+      return console.log(
+        JSON.stringify(
+          {
+            sim: simLabel(sim),
+            results: ranked.map((r) => ({
+              id: r.claim.id,
+              kind: r.claim.kind,
+              score: r.score,
+            })),
+          },
+          null,
+          2,
+        ),
+      );
+    console.log(paint(`  sim: ${simLabel(sim)}`, "dim"));
+    if (!ranked.length) return console.log("  no matching live claims");
+    for (const r of ranked)
       console.log(
-        `  val ${bar(b.val)} ${b.val.toFixed(2)} (trust-weighted ${b.valTrustWeighted.toFixed(2)})`,
+        `  ${bar(r.score, 8)} ${r.score.toFixed(3)}  ${paint(r.claim.kind.padEnd(9), "accent")} ${paint(r.claim.id.slice(0, 8), "dim")}  ${claimText(r.claim).slice(0, 90)}`,
       );
-      for (const p of b.minted)
-        console.log(
-          `  minted  day ${p.t}  by ${p.author || "(unknown)"}${p.agent ? ` · ${p.agent}` : ""}`,
-        );
-      for (const e of b.evidence)
-        console.log(
-          `  ${e.result === "confirm" ? paint("confirm ", "ok") : paint("contradic", "err")}  day ${e.t}  ${e.oracle} → ${e.ref}${e.author ? `  by ${e.author}` : ""}`,
-        );
-      for (const t of b.tombstones)
-        console.log(
-          paint(`  retract  day ${t.t}  ${t.reason}${t.author ? `  by ${t.author}` : ""}`, "dim"),
-        );
-      const trusts = Object.entries(b.trust);
-      if (trusts.length) {
-        console.log("\n  author trust (earned from oracle outcomes on their claims):");
-        for (const [a, u] of trusts) console.log(`    ${u.toFixed(2)}  ${a}`);
-      }
+    return;
+  }
+  if (sub === "sync") {
+    const { ledgerSync, defaultRef } = await import("./ledger_sync.js");
+    const di = args.indexOf("--dir");
+    const re = args.indexOf("--remote");
+    const rf = args.indexOf("--ref");
+    const r = ledgerSync({
+      dir,
+      root,
+      personal,
+      dirTarget: di >= 0 ? args[di + 1] : undefined,
+      remote: re >= 0 ? args[re + 1] : undefined,
+      ref: rf >= 0 ? args[rf + 1] : undefined,
+    });
+    if (json) return console.log(JSON.stringify(r, null, 2));
+    heading(`${BRAND.brand} ledger sync\n`);
+    if (!r.ok) {
+      console.error(`  ${paint(r.reason ?? "sync failed", "err")}`);
+      process.exitCode = 1;
       return;
     }
-    // The two writes (08-dashboard-ux.md §2) — CLI twins of the dashboard's POSTs, so
-    // the dashboard stays a convenience, never a requirement. Both append-only.
-    if (sub === "ratify") {
-      const id = args[2];
-      if (!id || id.length < 2) {
-        console.error("usage: forge ledger ratify <id-prefix (≥2 chars)>");
-        process.exitCode = 1;
-        return;
-      }
-      // Human-only promotion: the author is YOUR git identity, minted as a decision claim.
-      const r = ls.ratify(dir, id, { author: gitAuthor(), t: nowDay });
-      if (!r.ok) {
-        console.error(`  ${r.reason}`);
-        process.exitCode = 1;
-        return;
-      }
-      if (json) return console.log(JSON.stringify(r, null, 2));
+    if (r.mode === "dir") {
       console.log(
-        `  ratified ${r.ratifies.slice(0, 12)} → decision ${r.decisionId.slice(0, 12)}${r.existed ? " (already ratified — same decision)" : ""}`,
+        table([
+          [paint("target", "dim"), r.dir],
+          [paint("pulled", "dim"), `${r.pulled.claims} claim(s), ${r.pulled.records} record(s)`],
+          [paint("pushed", "dim"), `${r.pushed.claims} claim(s), ${r.pushed.records} record(s)`],
+        ]),
       );
-      return;
-    }
-    if (sub === "retract") {
-      const id = args[2];
-      const ri = args.indexOf("--reason");
-      const reason = ri >= 0 ? (args[ri + 1] ?? "") : "";
-      if (!id || id.length < 2 || id === "--reason" || !reason) {
-        console.error('usage: forge ledger retract <id-prefix> --reason "<why>"');
-        process.exitCode = 1;
-        return;
-      }
-      const hit = ls.getClaimByPrefix(dir, id);
-      if (!hit) {
-        console.error(`  no claim matching ${id}`);
-        process.exitCode = 1;
-        return;
-      }
-      const r = ls.tombstone(dir, hit.id, {
-        author: gitAuthor(),
-        reason,
-        t: nowDay,
-      });
-      if (!r.ok) {
-        console.error(`  ${r.reason}`);
-        process.exitCode = 1;
-        return;
-      }
-      if (json) return console.log(JSON.stringify({ ...r, id: hit.id }, null, 2));
+    } else {
       console.log(
-        `  retracted ${hit.id.slice(0, 12)} — ${reason}${r.deduped ? " (already retracted with this record)" : ""}`,
+        table([
+          [paint("ref", "dim"), `${r.remote} ${r.ref}`],
+          [paint("pulled", "dim"), `${r.pulled.claims} claim(s), ${r.pulled.records} record(s)`],
+          [
+            paint("pushed", "dim"),
+            r.upToDate
+              ? paint("up to date — nothing to push", "dim")
+              : `yes (retries ${r.retries})`,
+          ],
+        ]),
       );
-      return;
     }
-    if (sub === "query") {
-      const q = args.slice(2).join(" ");
-      if (!q) {
-        console.error('usage: forge ledger query "<what you are about to do>"');
-        process.exitCode = 1;
-        return;
-      }
-      const { retrieve, claimText } = await import("./ledger.js");
-      // The embeddings tier (ADR-0005) is assembled HERE, not in ledger.js — the pure
-      // core stays provider-free. No FORGE_EMBED (or a failing provider) → sim is
-      // null and retrieval is the stock MinHash path.
-      const { claimSim, simLabel } = await import("./embed.js");
-      const claims = ls.loadClaims(dir);
-      const sim = claimSim(root, q, claims, claimText);
-      const ranked = retrieve(q, claims, { nowDay, budget: 8, sim });
-      if (json)
-        return console.log(
-          JSON.stringify(
-            {
-              sim: simLabel(sim),
-              results: ranked.map((r) => ({
-                id: r.claim.id,
-                kind: r.claim.kind,
-                score: r.score,
-              })),
-            },
-            null,
-            2,
-          ),
-        );
-      console.log(paint(`  sim: ${simLabel(sim)}`, "dim"));
-      if (!ranked.length) return console.log("  no matching live claims");
-      for (const r of ranked)
-        console.log(
-          `  ${bar(r.score, 8)} ${r.score.toFixed(3)}  ${paint(r.claim.kind.padEnd(9), "accent")} ${paint(r.claim.id.slice(0, 8), "dim")}  ${claimText(r.claim).slice(0, 90)}`,
-        );
-      return;
-    }
-    if (sub === "sync") {
-      const { ledgerSync, defaultRef } = await import("./ledger_sync.js");
-      const di = args.indexOf("--dir");
-      const re = args.indexOf("--remote");
-      const rf = args.indexOf("--ref");
-      const r = ledgerSync({
-        dir,
-        root,
-        personal,
-        dirTarget: di >= 0 ? args[di + 1] : undefined,
-        remote: re >= 0 ? args[re + 1] : undefined,
-        ref: rf >= 0 ? args[rf + 1] : undefined,
+    for (const n of r.notes ?? []) console.log(paint(`  note: ${n}`, "warn"));
+    if (r.mode === "ref" && r.ref === defaultRef(personal))
+      console.log(paint("\n  synced through a git ref — CRDT, converges in any order", "dim"));
+    return;
+  }
+  if (sub === "import") {
+    const b = await import("./ledger_bridge.js");
+    let r;
+    if (personal) {
+      // Personal import: facts from the global recall store into the personal ledger.
+      const { defaultStore } = await import("./recall.js");
+      r = {
+        lessons: 0,
+        outcomes: 0,
+        ...b.importFacts(defaultStore(), dir, nowDay),
+      };
+    } else {
+      const { brainStore } = await import("./brain.js");
+      r = b.importLegacy(root, {
+        recallStore: brainStore(root),
+        recallLedger: dir,
+        nowDay,
       });
-      if (json) return console.log(JSON.stringify(r, null, 2));
-      heading(`${BRAND.brand} ledger sync\n`);
-      if (!r.ok) {
-        console.error(`  ${paint(r.reason ?? "sync failed", "err")}`);
-        process.exitCode = 1;
-        return;
-      }
-      if (r.mode === "dir") {
-        console.log(
-          table([
-            [paint("target", "dim"), r.dir],
-            [paint("pulled", "dim"), `${r.pulled.claims} claim(s), ${r.pulled.records} record(s)`],
-            [paint("pushed", "dim"), `${r.pushed.claims} claim(s), ${r.pushed.records} record(s)`],
-          ]),
-        );
-      } else {
-        console.log(
-          table([
-            [paint("ref", "dim"), `${r.remote} ${r.ref}`],
-            [paint("pulled", "dim"), `${r.pulled.claims} claim(s), ${r.pulled.records} record(s)`],
-            [
-              paint("pushed", "dim"),
-              r.upToDate
-                ? paint("up to date — nothing to push", "dim")
-                : `yes (retries ${r.retries})`,
-            ],
-          ]),
-        );
-      }
-      for (const n of r.notes ?? []) console.log(paint(`  note: ${n}`, "warn"));
-      if (r.mode === "ref" && r.ref === defaultRef(personal))
-        console.log(paint("\n  synced through a git ref — CRDT, converges in any order", "dim"));
-      return;
     }
-    if (sub === "import") {
-      const b = await import("./ledger_bridge.js");
-      let r;
-      if (personal) {
-        // Personal import: facts from the global recall store into the personal ledger.
-        const { defaultStore } = await import("./recall.js");
-        r = {
-          lessons: 0,
-          outcomes: 0,
-          ...b.importFacts(defaultStore(), dir, nowDay),
-        };
-      } else {
-        const { brainStore } = await import("./brain.js");
-        r = b.importLegacy(root, {
-          recallStore: brainStore(root),
-          recallLedger: dir,
-          nowDay,
-        });
-      }
-      if (json) return console.log(JSON.stringify(r, null, 2));
-      console.log(
-        `  imported: ${r.lessons} lesson(s), ${r.facts} fact(s), ${r.outcomes} outcome(s)`,
-      );
-      for (const x of r.refused) console.log(`    refused: ${x}`);
-      return;
-    }
-    console.error(
-      `ledger: unknown subcommand "${sub}" (stats | verify | show <id> | blame <id> | query <text> | ratify <id> | retract <id> --reason "<why>" | merge <path> | sync [--dir <path>|--remote <name>|--ref <ref>] | import) [--personal] [--json]`,
-    );
-    process.exitCode = 1;
+    if (json) return console.log(JSON.stringify(r, null, 2));
+    console.log(`  imported: ${r.lessons} lesson(s), ${r.facts} fact(s), ${r.outcomes} outcome(s)`);
+    for (const x of r.refused) console.log(`    refused: ${x}`);
     return;
   }
-  if (cmd === "reuse") {
-    const ru = await import("./reuse.js");
-    const { load: loadAtlas } = await import("./atlas.js");
-    const { epochDay } = await import("./util.js");
-    const root = process.cwd();
-    const nowDay = epochDay();
-    const json = argv.includes("--json");
-    const flagVal = (name) => {
-      const i = argv.indexOf(name);
-      return i >= 0 ? argv[i + 1] : undefined;
-    };
-    const args = argv.filter(
-      (a, i) => !a.startsWith("--") && argv[i - 1] !== "--file" && argv[i - 1] !== "--ref",
-    );
-    const sub = args[1] || "stats";
-    if (sub === "query") {
-      const spec = args.slice(2).join(" ");
-      if (!spec) {
-        console.error('usage: forge reuse query "<what you are about to build>" [--json]');
-        process.exitCode = 1;
-        return;
-      }
-      const r = ru.reuseQuery(root, spec, { atlas: loadAtlas(root), nowDay });
-      if (json)
-        return console.log(
-          JSON.stringify(
-            {
-              tier: r.tier,
-              artifact: r.artifact?.id,
-              jaccard: r.jaccard,
-              similarity: r.similarity,
-              sim: r.sim,
-              reasons: r.reasons,
-            },
-            null,
-            2,
-          ),
-        );
-      console.log(`  sim: ${r.sim}`);
-      if (r.tier === "miss") {
-        console.log("  miss — nothing verified matches; generate, then `forge reuse mint` it");
-      } else {
-        const a = r.artifact;
-        console.log(
-          `  ${r.tier.toUpperCase()} hit (similarity ${(r.similarity ?? r.jaccard ?? 1).toFixed(2)}) — ${a.body.form}${a.body.code?.path ? ` at ${a.body.code.path}` : ""}`,
-        );
-        console.log(
-          `    claim ${a.id.slice(0, 12)} — \`forge ledger blame ${a.id.slice(0, 8)}\` for its proof`,
-        );
-        if (r.tier === "adapt")
-          console.log(
-            "    adapt tier: inject as a verified starting point, generate only the delta",
-          );
-      }
-      for (const why of r.reasons) console.log(`    note: ${why}`);
+  console.error(
+    `ledger: unknown subcommand "${sub}" (stats | verify | show <id> | blame <id> | query <text> | ratify <id> | retract <id> --reason "<why>" | merge <path> | sync [--dir <path>|--remote <name>|--ref <ref>] | import) [--personal] [--json]`,
+  );
+  process.exitCode = 1;
+  return;
+};
+HANDLERS.reuse = async (argv) => {
+  const ru = await import("./reuse.js");
+  const { load: loadAtlas } = await import("./atlas.js");
+  const { epochDay } = await import("./util.js");
+  const root = process.cwd();
+  const nowDay = epochDay();
+  const json = argv.includes("--json");
+  const flagVal = (name) => {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+  };
+  const args = argv.filter(
+    (a, i) => !a.startsWith("--") && argv[i - 1] !== "--file" && argv[i - 1] !== "--ref",
+  );
+  const sub = args[1] || "stats";
+  if (sub === "query") {
+    const spec = args.slice(2).join(" ");
+    if (!spec) {
+      console.error('usage: forge reuse query "<what you are about to build>" [--json]');
+      process.exitCode = 1;
       return;
     }
-    if (sub === "mint") {
-      const spec = args.slice(2).join(" ");
-      const file = flagVal("--file");
-      const ref = flagVal("--ref");
-      if (!spec || !file) {
-        console.error(
-          'usage: forge reuse mint "<task the code solves>" --file <path> [--ref <test-run/commit>] [--json]',
-        );
-        process.exitCode = 1;
-        return;
-      }
-      const { repoLedger } = await import("./ledger_store.js");
-      const desc = ru.describeFile(root, file);
-      const r = ru.mintArtifact(
-        repoLedger(root),
-        { spec, form: "module", ...desc },
-        ref
-          ? {
-              evidence: { oracle: "test.run", result: "confirm", ref },
-              t: nowDay,
-            }
-          : { t: nowDay },
+    const r = ru.reuseQuery(root, spec, { atlas: loadAtlas(root), nowDay });
+    if (json)
+      return console.log(
+        JSON.stringify(
+          {
+            tier: r.tier,
+            artifact: r.artifact?.id,
+            jaccard: r.jaccard,
+            similarity: r.similarity,
+            sim: r.sim,
+            reasons: r.reasons,
+          },
+          null,
+          2,
+        ),
       );
-      if (json) return console.log(JSON.stringify(r, null, 2));
-      if (!r.ok) {
-        console.error(`  ${r.reason}`);
-        process.exitCode = 1;
-        return;
-      }
+    console.log(`  sim: ${r.sim}`);
+    if (r.tier === "miss") {
+      console.log("  miss — nothing verified matches; generate, then `forge reuse mint` it");
+    } else {
+      const a = r.artifact;
       console.log(
-        `  minted: ${r.id.slice(0, 12)} (${desc.iface.length} export(s), ${desc.deps.length} dep(s))`,
+        `  ${r.tier.toUpperCase()} hit (similarity ${(r.similarity ?? r.jaccard ?? 1).toFixed(2)}) — ${a.body.form}${a.body.code?.path ? ` at ${a.body.code.path}` : ""}`,
       );
       console.log(
-        r.serves
-          ? "  serving: yes — verification evidence attached"
-          : "  serving: NOT YET — no evidence; attach a verified test/commit ref (--ref) or it stays at the 0.5 prior",
+        `    claim ${a.id.slice(0, 12)} — \`forge ledger blame ${a.id.slice(0, 8)}\` for its proof`,
       );
-      return;
+      if (r.tier === "adapt")
+        console.log("    adapt tier: inject as a verified starting point, generate only the delta");
     }
-    if (sub === "stats") {
-      const { summarize } = await import("./metrics.js");
-      const s = summarize(root).cache ?? {
-        events: 0,
-        byOutcome: {},
-        savedEstimate: 0,
-      };
-      if (json) return console.log(JSON.stringify(s, null, 2));
-      heading(`${BRAND.brand} reuse — proof-carrying code cache\n`);
-      console.log(`  lookups: ${s.events}`);
-      for (const [o, n] of Object.entries(s.byOutcome)) console.log(`    ${o}: ${n}`);
-      console.log(`  est. tokens saved: ${s.savedEstimate}`);
-      return;
-    }
-    console.error(
-      `reuse: unknown subcommand "${sub}" (query <spec> | mint <spec> --file <path> | stats)`,
-    );
-    process.exitCode = 1;
+    for (const why of r.reasons) console.log(`    note: ${why}`);
     return;
   }
-  if (cmd === "context") {
-    const { assemble, renderContext } = await import("./context.js");
-    const { load: loadAtlas } = await import("./atlas.js");
-    const { epochDay } = await import("./util.js");
-    const json = argv.includes("--json");
-    const bi = argv.indexOf("--budget");
-    const budget = bi >= 0 ? Number(argv[bi + 1]) || undefined : undefined;
-    const task = argv
-      .filter((a, i) => i > 0 && !a.startsWith("--") && argv[i - 1] !== "--budget")
-      .join(" ");
-    if (!task) {
-      console.error('usage: forge context "<task>" [--budget <tokens>] [--json]');
+  if (sub === "mint") {
+    const spec = args.slice(2).join(" ");
+    const file = flagVal("--file");
+    const ref = flagVal("--ref");
+    if (!spec || !file) {
+      console.error(
+        'usage: forge reuse mint "<task the code solves>" --file <path> [--ref <test-run/commit>] [--json]',
+      );
       process.exitCode = 1;
       return;
     }
-    const r = assemble(process.cwd(), task, {
-      atlas: loadAtlas(process.cwd()),
-      nowDay: epochDay(),
-      ...(budget ? { budget } : {}),
-    });
-    if (json) {
-      const { block, ...rest } = r;
-      return console.log(JSON.stringify(rest, null, 2));
+    const { repoLedger } = await import("./ledger_store.js");
+    const desc = ru.describeFile(root, file);
+    const r = ru.mintArtifact(
+      repoLedger(root),
+      { spec, form: "module", ...desc },
+      ref
+        ? {
+            evidence: { oracle: "test.run", result: "confirm", ref },
+            t: nowDay,
+          }
+        : { t: nowDay },
+    );
+    if (json) return console.log(JSON.stringify(r, null, 2));
+    if (!r.ok) {
+      console.error(`  ${r.reason}`);
+      process.exitCode = 1;
+      return;
     }
-    console.log(renderContext(r));
-    if (!r.ok) process.exitCode = 1;
+    console.log(
+      `  minted: ${r.id.slice(0, 12)} (${desc.iface.length} export(s), ${desc.deps.length} dep(s))`,
+    );
+    console.log(
+      r.serves
+        ? "  serving: yes — verification evidence attached"
+        : "  serving: NOT YET — no evidence; attach a verified test/commit ref (--ref) or it stays at the 0.5 prior",
+    );
     return;
   }
-  if (cmd === "atlas") {
-    const a = await import("./atlas.js");
-    const sub = argv[1] || "build";
-    const need = () => {
-      if (a.load()) return a.load();
-      console.error("  no index — run `forge atlas build` first");
-      process.exitCode = 1;
-      return null;
+  if (sub === "stats") {
+    const { summarize } = await import("./metrics.js");
+    const s = summarize(root).cache ?? {
+      events: 0,
+      byOutcome: {},
+      savedEstimate: 0,
     };
-    if (sub === "build") {
-      const at = a.build({ root: process.cwd() });
-      console.log(
-        `  indexed ${at.symbols.length} symbols in ${at.files} files → .forge/atlas.json${at.capped ? " (capped)" : ""}`,
-      );
-    } else if (sub === "query") {
-      const at = need();
-      if (!at) return;
-      const hits = a.query(at, argv.slice(2).join(" "));
-      console.log(
-        hits.length
-          ? hits
-              .slice(0, 30)
-              .map((s) => `  ${s.file}:${s.line}  ${s.kind} ${s.name}`)
-              .join("\n")
-          : "  no match",
-      );
-    } else if (sub === "has") {
-      const at = need();
-      if (!at) return;
-      const name = argv[2];
-      const yes = a.has(at, name);
-      console.log(`  ${yes ? "✓ defined" : "✗ not found (possible hallucinated symbol)"}: ${name}`);
-      if (!yes) process.exitCode = 1;
-    } else {
-      console.error(`atlas: unknown subcommand "${sub}" (build | query | has)`);
-      process.exitCode = 1;
-    }
+    if (json) return console.log(JSON.stringify(s, null, 2));
+    heading(`${BRAND.brand} reuse — proof-carrying code cache\n`);
+    console.log(`  lookups: ${s.events}`);
+    for (const [o, n] of Object.entries(s.byOutcome)) console.log(`    ${o}: ${n}`);
+    console.log(`  est. tokens saved: ${s.savedEstimate}`);
     return;
   }
-  if (cmd === "scan") {
-    const { scan } = await import("./skillgate.js");
-    const target = argv[1];
-    if (!target) {
-      console.error("usage: forge scan <SKILL.md | .mcp.json | path>");
-      process.exitCode = 1;
-      return;
-    }
-    const r = scan(target);
-    heading(`${BRAND.brand} scan — skill-gate (${r.scanner})\n`);
-    if (r.findings?.length) {
-      for (const f of r.findings) console.log(`  [${f.sev}] ${f.msg}`);
-    } else if (r.raw) {
-      console.log(`  ${r.raw.trim().split("\n").slice(-6).join("\n  ")}`);
-    } else {
-      console.log("  no obvious red flags");
-    }
+  console.error(
+    `reuse: unknown subcommand "${sub}" (query <spec> | mint <spec> --file <path> | stats)`,
+  );
+  process.exitCode = 1;
+  return;
+};
+HANDLERS.context = async (argv) => {
+  const { assemble, renderContext } = await import("./context.js");
+  const { load: loadAtlas } = await import("./atlas.js");
+  const { epochDay } = await import("./util.js");
+  const json = argv.includes("--json");
+  const bi = argv.indexOf("--budget");
+  const budget = bi >= 0 ? Number(argv[bi + 1]) || undefined : undefined;
+  const task = argv
+    .filter((a, i) => i > 0 && !a.startsWith("--") && argv[i - 1] !== "--budget")
+    .join(" ");
+  if (!task) {
+    console.error('usage: forge context "<task>" [--budget <tokens>] [--json]');
+    process.exitCode = 1;
+    return;
+  }
+  const r = assemble(process.cwd(), task, {
+    atlas: loadAtlas(process.cwd()),
+    nowDay: epochDay(),
+    ...(budget ? { budget } : {}),
+  });
+  if (json) {
+    const { block, ...rest } = r;
+    return console.log(JSON.stringify(rest, null, 2));
+  }
+  console.log(renderContext(r));
+  if (!r.ok) process.exitCode = 1;
+  return;
+};
+HANDLERS.atlas = async (argv) => {
+  const a = await import("./atlas.js");
+  const sub = argv[1] || "build";
+  const need = () => {
+    if (a.load()) return a.load();
+    console.error("  no index — run `forge atlas build` first");
+    process.exitCode = 1;
+    return null;
+  };
+  if (sub === "build") {
+    const at = a.build({ root: process.cwd() });
     console.log(
-      `\n  ${r.verdict || (r.critical ? "BLOCKED — critical finding" : "no critical signature detected — not a safety certification")}`,
+      `  indexed ${at.symbols.length} symbols in ${at.files} files → .forge/atlas.json${at.capped ? " (capped)" : ""}`,
     );
-    if (r.critical) process.exitCode = 1;
+  } else if (sub === "query") {
+    const at = need();
+    if (!at) return;
+    const hits = a.query(at, argv.slice(2).join(" "));
+    console.log(
+      hits.length
+        ? hits
+            .slice(0, 30)
+            .map((s) => `  ${s.file}:${s.line}  ${s.kind} ${s.name}`)
+            .join("\n")
+        : "  no match",
+    );
+  } else if (sub === "has") {
+    const at = need();
+    if (!at) return;
+    const name = argv[2];
+    const yes = a.has(at, name);
+    console.log(`  ${yes ? "✓ defined" : "✗ not found (possible hallucinated symbol)"}: ${name}`);
+    if (!yes) process.exitCode = 1;
+  } else {
+    console.error(`atlas: unknown subcommand "${sub}" (build | query | has)`);
+    process.exitCode = 1;
+  }
+  return;
+};
+HANDLERS.scan = async (argv) => {
+  const { scan } = await import("./skillgate.js");
+  const target = argv[1];
+  if (!target) {
+    console.error("usage: forge scan <SKILL.md | .mcp.json | path>");
+    process.exitCode = 1;
     return;
   }
-  if (cmd === "verify") {
-    const json = argv.includes("--json");
-    if (argv.includes("--deep")) {
-      const { verifyDeep, LENSES } = await import("./consensus.js");
-      // `--llm` opts the reviewer panel in for this run; otherwise FORGE_LLM decides.
-      const r = verifyDeep({
-        targetRoot: process.cwd(),
-        llm: argv.includes("--llm") ? true : undefined,
-      });
-      if (json) {
-        console.log(JSON.stringify(r, null, 2));
-        if (!r.ok) process.exitCode = 1;
-        return;
-      }
-      heading(`${BRAND.brand} verify --deep — multi-lens consensus\n`);
-      console.log(
-        table(
-          r.lenses.map((l) => {
-            const meta = LENSES[l.lens];
-            const state =
-              l.ran === false
-                ? paint("— skipped", "dim")
-                : l.s > 0
-                  ? paint("● finding", meta.solo ? "err" : "warn")
-                  : paint("✓ clean", "ok");
-            return [l.lens, meta.family, `w=${meta.weight}`, state];
-          }),
-        ),
-      );
-      if (r.findings.length) {
-        console.log();
-        for (const f of r.findings) console.log(`  ! ${f}`);
-      }
-      console.log(
-        `\n  defectRiskScore:  ${bar(r.p)} ${r.p.toFixed(2)} (heuristic, not a calibrated probability)${
-          r.families.length ? `  (families: ${r.families.join(", ")})` : ""
-        }`,
-      );
-      console.log(
-        `  remainingUncheckedWeight: ${r.residual.toFixed(3)} — Theorem-D silent-miss bound (heuristic)`,
-      );
-      // The core tests state, spelled out — deep ok REQUIRES a passing core, so the
-      // reader must see whether a verifier actually ran (RA-01).
-      const t = r.tests ?? /** @type {import("./verify.js").VerifyTests} */ ({ ran: false });
-      console.log(
-        `  tests:            ${t.status ?? "unknown"}${t.runner ? ` (${t.runner})` : ""}${
-          !t.runner && t.detected?.length ? ` (detected: ${t.detected.join(", ")})` : ""
-        }`,
-      );
-      if (t.executed?.length)
-        console.log(
-          `  suites ran:       ${t.executed.map((s) => `${s.label}=${s.status}`).join(", ")}`,
-        );
-      if (t.notExecuted?.length)
-        console.log(`  suites skipped:   ${t.notExecuted.join(", ")} (no built-in executor)`);
-      const detail = t.output || (t.detected ?? []).join(", ");
-      const verdictLine =
-        r.status === "PASS"
-          ? paint("PASS", "ok")
-          : r.status === "NOT_CONFIGURED"
-            ? paint("NOT VERIFIED — no test runner configured (NOT_CONFIGURED)", "warn")
-            : r.status === "INCOMPLETE"
-              ? paint(`NOT VERIFIED — tests incomplete${detail ? ` (${detail})` : ""}`, "warn")
-              : paint("BLOCKED — cross-family consensus says defect", "err");
-      console.log(`\n  ${verdictLine}`);
-      if (!r.ok) process.exitCode = 1;
-      return;
-    }
-    const { verify } = await import("./verify.js");
-    const r = verify({ targetRoot: process.cwd() });
+  const r = scan(target);
+  heading(`${BRAND.brand} scan — skill-gate (${r.scanner})\n`);
+  if (r.findings?.length) {
+    for (const f of r.findings) console.log(`  [${f.sev}] ${f.msg}`);
+  } else if (r.raw) {
+    console.log(`  ${r.raw.trim().split("\n").slice(-6).join("\n  ")}`);
+  } else {
+    console.log("  no obvious red flags");
+  }
+  console.log(
+    `\n  ${r.verdict || (r.critical ? "BLOCKED — critical finding" : "no critical signature detected — not a safety certification")}`,
+  );
+  if (r.critical) process.exitCode = 1;
+  return;
+};
+HANDLERS.verify = async (argv) => {
+  const json = argv.includes("--json");
+  if (argv.includes("--deep")) {
+    const { verifyDeep, LENSES } = await import("./consensus.js");
+    // `--llm` opts the reviewer panel in for this run; otherwise FORGE_LLM decides.
+    const r = verifyDeep({
+      targetRoot: process.cwd(),
+      llm: argv.includes("--llm") ? true : undefined,
+    });
     if (json) {
       console.log(JSON.stringify(r, null, 2));
       if (!r.ok) process.exitCode = 1;
       return;
     }
-    heading(`${BRAND.brand} verify\n`);
-    console.log(`  changed files:    ${r.changedFiles.length}`);
-    // Honest four-state tests line (RA-09): "nothing ran" is never dressed up as a pass,
-    // and a real run names the runner that actually executed.
-    const t = r.tests;
-    const testsLine =
-      t.status === "PASS"
-        ? `✓ pass (${t.runner ?? "project suite"})`
-        : t.status === "FAIL"
-          ? `✗ FAIL (${t.runner ?? "project suite"})`
-          : t.status === "INCOMPLETE"
-            ? `— INCOMPLETE: ${t.output || (t.detected ?? []).join(", ") || "test run did not complete"}`
-            : "— NOT CONFIGURED (no test runner detected)";
-    console.log(`  tests:            ${testsLine}`);
-    // Per-suite honesty (HI-01): a polyglot repo runs every executable suite; name which
-    // ones ran with what verdict, and which were detected but never executed.
+    heading(`${BRAND.brand} verify --deep — multi-lens consensus\n`);
+    console.log(
+      table(
+        r.lenses.map((l) => {
+          const meta = LENSES[l.lens];
+          const state =
+            l.ran === false
+              ? paint("— skipped", "dim")
+              : l.s > 0
+                ? paint("● finding", meta.solo ? "err" : "warn")
+                : paint("✓ clean", "ok");
+          return [l.lens, meta.family, `w=${meta.weight}`, state];
+        }),
+      ),
+    );
+    if (r.findings.length) {
+      console.log();
+      for (const f of r.findings) console.log(`  ! ${f}`);
+    }
+    console.log(
+      `\n  defectRiskScore:  ${bar(r.p)} ${r.p.toFixed(2)} (heuristic, not a calibrated probability)${
+        r.families.length ? `  (families: ${r.families.join(", ")})` : ""
+      }`,
+    );
+    console.log(
+      `  remainingUncheckedWeight: ${r.residual.toFixed(3)} — Theorem-D silent-miss bound (heuristic)`,
+    );
+    // The core tests state, spelled out — deep ok REQUIRES a passing core, so the
+    // reader must see whether a verifier actually ran (RA-01).
+    const t = r.tests ?? /** @type {import("./verify.js").VerifyTests} */ ({ ran: false });
+    console.log(
+      `  tests:            ${t.status ?? "unknown"}${t.runner ? ` (${t.runner})` : ""}${
+        !t.runner && t.detected?.length ? ` (detected: ${t.detected.join(", ")})` : ""
+      }`,
+    );
     if (t.executed?.length)
       console.log(
         `  suites ran:       ${t.executed.map((s) => `${s.label}=${s.status}`).join(", ")}`,
       );
     if (t.notExecuted?.length)
       console.log(`  suites skipped:   ${t.notExecuted.join(", ")} (no built-in executor)`);
-    console.log(`  symbols checked:  ${r.provenance.symbolsChecked}`);
-    if (r.unknown.length)
-      console.log(
-        `  ! not in codebase (possible hallucination): ${r.unknown.slice(0, 12).join(", ")}`,
-      );
-    console.log(`  provenance:       .forge/provenance.json`);
-    // BLOCKED is reserved for a runner that actually FAILED; anything that never ran
-    // to completion is NOT VERIFIED (still exit 1 — unverified is not a pass).
-    const verdict = r.ok
-      ? "PASS"
-      : t.status === "FAIL"
-        ? "BLOCKED — tests failing"
-        : `NOT VERIFIED — ${t.status}`;
-    console.log(`\n  ${verdict}`);
+    const detail = t.output || (t.detected ?? []).join(", ");
+    const verdictLine =
+      r.status === "PASS"
+        ? paint("PASS", "ok")
+        : r.status === "NOT_CONFIGURED"
+          ? paint("NOT VERIFIED — no test runner configured (NOT_CONFIGURED)", "warn")
+          : r.status === "INCOMPLETE"
+            ? paint(`NOT VERIFIED — tests incomplete${detail ? ` (${detail})` : ""}`, "warn")
+            : paint("BLOCKED — cross-family consensus says defect", "err");
+    console.log(`\n  ${verdictLine}`);
     if (!r.ok) process.exitCode = 1;
     return;
   }
-  if (cmd === "remember") {
-    const b = await import("./brain.js");
-    const name = argv[1];
-    const body = argv.slice(2).join(" ");
-    if (!name || !body) {
-      console.error('usage: forge remember "<name>" "<fact>"');
-      process.exitCode = 1;
-      return;
-    }
-    const res = b.remember(b.brainStore(process.cwd()), name, body);
-    if (res.ok) {
-      // Brain is repo-scoped and git-committable → shadow into the REPO ledger.
-      try {
-        const { shadowFact } = await import("./ledger_bridge.js");
-        const { repoLedger } = await import("./ledger_store.js");
-        shadowFact(repoLedger(process.cwd()), name, body);
-      } catch {}
-      // Rebuild the inlined index after the shadow so a ledger-only brain's
-      // AGENTS.brain.md includes the fact (its only copy now lives in the ledger).
-      b.buildIndex(b.brainStore(process.cwd()));
-    }
-    console.log(
-      res.ok
-        ? `  remembered: ${res.slug} — run \`forge sync\` to inline it into every tool`
-        : `  ${res.reason}`,
-    );
-    if (!res.ok) process.exitCode = 1;
+  const { verify } = await import("./verify.js");
+  const r = verify({ targetRoot: process.cwd() });
+  if (json) {
+    console.log(JSON.stringify(r, null, 2));
+    if (!r.ok) process.exitCode = 1;
     return;
   }
-  if (cmd === "brain") {
-    const b = await import("./brain.js");
-    const store = b.brainStore(process.cwd());
-    const idx = b.buildIndex(store);
-    const items = b.list(store);
-    heading(`${BRAND.brand} brain — portable project memory\n`);
+  heading(`${BRAND.brand} verify\n`);
+  console.log(`  changed files:    ${r.changedFiles.length}`);
+  // Honest four-state tests line (RA-09): "nothing ran" is never dressed up as a pass,
+  // and a real run names the runner that actually executed.
+  const t = r.tests;
+  const testsLine =
+    t.status === "PASS"
+      ? `✓ pass (${t.runner ?? "project suite"})`
+      : t.status === "FAIL"
+        ? `✗ FAIL (${t.runner ?? "project suite"})`
+        : t.status === "INCOMPLETE"
+          ? `— INCOMPLETE: ${t.output || (t.detected ?? []).join(", ") || "test run did not complete"}`
+          : "— NOT CONFIGURED (no test runner detected)";
+  console.log(`  tests:            ${testsLine}`);
+  // Per-suite honesty (HI-01): a polyglot repo runs every executable suite; name which
+  // ones ran with what verdict, and which were detected but never executed.
+  if (t.executed?.length)
     console.log(
-      items.length
-        ? items.map((s) => `  - ${s}`).join("\n")
-        : '  (no facts yet — forge remember "<name>" "<fact>")',
+      `  suites ran:       ${t.executed.map((s) => `${s.label}=${s.status}`).join(", ")}`,
     );
+  if (t.notExecuted?.length)
+    console.log(`  suites skipped:   ${t.notExecuted.join(", ")} (no built-in executor)`);
+  console.log(`  symbols checked:  ${r.provenance.symbolsChecked}`);
+  if (r.unknown.length)
     console.log(
-      `\n  ${idx.indexed} inlined into AGENTS.md${idx.overflow ? `, ${idx.overflow} in overflow` : ""} · stored in .forge/brain/`,
+      `  ! not in codebase (possible hallucination): ${r.unknown.slice(0, 12).join(", ")}`,
     );
+  console.log(`  provenance:       .forge/provenance.json`);
+  // BLOCKED is reserved for a runner that actually FAILED; anything that never ran
+  // to completion is NOT VERIFIED (still exit 1 — unverified is not a pass).
+  const verdict = r.ok
+    ? "PASS"
+    : t.status === "FAIL"
+      ? "BLOCKED — tests failing"
+      : `NOT VERIFIED — ${t.status}`;
+  console.log(`\n  ${verdict}`);
+  if (!r.ok) process.exitCode = 1;
+  return;
+};
+HANDLERS.remember = async (argv) => {
+  const b = await import("./brain.js");
+  const name = argv[1];
+  const body = argv.slice(2).join(" ");
+  if (!name || !body) {
+    console.error('usage: forge remember "<name>" "<fact>"');
+    process.exitCode = 1;
     return;
   }
-  if (cmd === "cost") {
-    // `--stages` is the P8 measured report (per-stage factors from .forge/metrics.jsonl);
-    // the default path stays the ccusage per-day spend view, untouched.
-    if (argv.includes("--stages")) {
-      const { renderCostReport, report } = await import("./cost_report.js");
-      const r = report(process.cwd());
-      console.log(argv.includes("--json") ? JSON.stringify(r, null, 2) : renderCostReport(r));
-      return;
-    }
-    const { execFileSync } = await import("node:child_process");
-    const run = (bin, args) => execFileSync(bin, args, { encoding: "utf8", stdio: "pipe" });
-    heading(`${BRAND.brand} cost — real per-day spend (ccusage)\n`);
+  const res = b.remember(b.brainStore(process.cwd()), name, body);
+  if (res.ok) {
+    // Brain is repo-scoped and git-committable → shadow into the REPO ledger.
     try {
-      let out;
-      try {
-        out = run("ccusage", ["daily"]);
-      } catch {
-        // Pinned (verified 2026-07-05) — never @latest for code we execute; re-verify via dev-radar.
-        out = run("npx", ["-y", "ccusage@20.0.14", "daily"]);
-      }
-      console.log(out.trim());
-    } catch {
-      const { estimateSpendFromLogs } = await import("./cost_report.js");
-      const est = estimateSpendFromLogs();
-      if (est && est.totalCost > 0) {
-        console.log(
-          `  $${est.totalCost.toFixed(2)} estimated from Claude session logs (${est.sessions} session(s))`,
-        );
-        if (est.byModel.length) {
-          for (const m of est.byModel)
-            console.log(
-              `    ${m.model.padEnd(30)} $${m.cost.toFixed(4)}  (${m.inTokens} in / ${m.outTokens} out)`,
-            );
-        }
-        console.log(paint("\n  install ccusage for precise tracking: npm i -g ccusage", "dim"));
-      } else {
-        console.log(
-          "  ccusage not found. Install for real spend (reads local JSONL, nothing leaves your machine):\n    npm i -g ccusage    # then: forge cost",
-        );
-      }
-    }
-    console.log(
-      paint(
-        `\n  ceiling: FORGE_COST_CEILING (default $10) — the cost-budget guard warns when a day exceeds it.`,
-        "dim",
-      ),
-    );
+      const { shadowFact } = await import("./ledger_bridge.js");
+      const { repoLedger } = await import("./ledger_store.js");
+      shadowFact(repoLedger(process.cwd()), name, body);
+    } catch {}
+    // Rebuild the inlined index after the shadow so a ledger-only brain's
+    // AGENTS.brain.md includes the fact (its only copy now lives in the ledger).
+    b.buildIndex(b.brainStore(process.cwd()));
+  }
+  console.log(
+    res.ok
+      ? `  remembered: ${res.slug} — run \`forge sync\` to inline it into every tool`
+      : `  ${res.reason}`,
+  );
+  if (!res.ok) process.exitCode = 1;
+  return;
+};
+HANDLERS.brain = async () => {
+  const b = await import("./brain.js");
+  const store = b.brainStore(process.cwd());
+  const idx = b.buildIndex(store);
+  const items = b.list(store);
+  heading(`${BRAND.brand} brain — portable project memory\n`);
+  console.log(
+    items.length
+      ? items.map((s) => `  - ${s}`).join("\n")
+      : '  (no facts yet — forge remember "<name>" "<fact>")',
+  );
+  console.log(
+    `\n  ${idx.indexed} inlined into AGENTS.md${idx.overflow ? `, ${idx.overflow} in overflow` : ""} · stored in .forge/brain/`,
+  );
+  return;
+};
+HANDLERS.cost = async (argv) => {
+  // `--stages` is the P8 measured report (per-stage factors from .forge/metrics.jsonl);
+  // the default path stays the ccusage per-day spend view, untouched.
+  if (argv.includes("--stages")) {
+    const { renderCostReport, report } = await import("./cost_report.js");
+    const r = report(process.cwd());
+    console.log(argv.includes("--json") ? JSON.stringify(r, null, 2) : renderCostReport(r));
     return;
   }
-  if (cmd === "spec") {
-    const s = await import("./speclock.js");
-    const sub = argv[1] || "check";
-    if (sub === "init") {
-      const { execFileSync } = await import("node:child_process");
-      try {
-        // Pinned (verified 2026-07-05) — never @latest for code we execute; re-verify via dev-radar.
-        execFileSync("npx", ["-y", "@fission-ai/openspec@1.5.0", "init"], {
-          stdio: "inherit",
-        });
-      } catch {
-        console.log(
-          "  OpenSpec not run. Scaffold spec-driven dev:\n    npx -y @fission-ai/openspec init   # lightweight (default)\n    # or GitHub Spec Kit for heavier/governed projects",
-        );
+  const { execFileSync } = await import("node:child_process");
+  const run = (bin, args) => execFileSync(bin, args, { encoding: "utf8", stdio: "pipe" });
+  heading(`${BRAND.brand} cost — real per-day spend (ccusage)\n`);
+  try {
+    let out;
+    try {
+      out = run("ccusage", ["daily"]);
+    } catch {
+      // Pinned (verified 2026-07-05) — never @latest for code we execute; re-verify via dev-radar.
+      out = run("npx", ["-y", "ccusage@20.0.14", "daily"]);
+    }
+    console.log(out.trim());
+  } catch {
+    const { estimateSpendFromLogs } = await import("./cost_report.js");
+    const est = estimateSpendFromLogs();
+    if (est && est.totalCost > 0) {
+      console.log(
+        `  $${est.totalCost.toFixed(2)} estimated from Claude session logs (${est.sessions} session(s))`,
+      );
+      if (est.byModel.length) {
+        for (const m of est.byModel)
+          console.log(
+            `    ${m.model.padEnd(30)} $${m.cost.toFixed(4)}  (${m.inTokens} in / ${m.outTokens} out)`,
+          );
       }
-      return;
+      console.log(paint("\n  install ccusage for precise tracking: npm i -g ccusage", "dim"));
+    } else {
+      console.log(
+        "  ccusage not found. Install for real spend (reads local JSONL, nothing leaves your machine):\n    npm i -g ccusage    # then: forge cost",
+      );
     }
-    if (sub === "lock") {
-      const { count } = s.snapshot(process.cwd());
-      console.log(`  spec-lock: snapshotted ${count} spec(s) → .forge/spec-lock.json`);
-      return;
+  }
+  console.log(
+    paint(
+      `\n  ceiling: FORGE_COST_CEILING (default $10) — the cost-budget guard warns when a day exceeds it.`,
+      "dim",
+    ),
+  );
+  return;
+};
+HANDLERS.spec = async (argv) => {
+  const s = await import("./speclock.js");
+  const sub = argv[1] || "check";
+  if (sub === "init") {
+    const { execFileSync } = await import("node:child_process");
+    try {
+      // Pinned (verified 2026-07-05) — never @latest for code we execute; re-verify via dev-radar.
+      execFileSync("npx", ["-y", "@fission-ai/openspec@1.5.0", "init"], {
+        stdio: "inherit",
+      });
+    } catch {
+      console.log(
+        "  OpenSpec not run. Scaffold spec-driven dev:\n    npx -y @fission-ai/openspec init   # lightweight (default)\n    # or GitHub Spec Kit for heavier/governed projects",
+      );
     }
-    const r = s.check(process.cwd());
-    heading(`${BRAND.brand} spec check\n`);
-    if (r.note) console.log(`  ${r.note}`);
-    else if (r.drift.length) {
-      for (const d of r.drift) {
-        console.log(`  ✗ ${d.spec} claims \`${d.symbol}\` — no longer defined in the code`);
-      }
-    } else console.log("  ✓ no drift — every claimed symbol still exists");
-    console.log(`\n  ${r.ok ? "PASS" : "DRIFT — update the spec or restore the symbol"}`);
-    if (!r.ok) process.exitCode = 1;
     return;
   }
-  if (cmd === "harden") {
-    const { harden } = await import("./harden.js");
-    const r = harden({ targetRoot: process.cwd() });
-    heading(`${BRAND.brand} harden\n`);
-    console.log(`  gitleaks:            ${r.gitleaks}`);
-    console.log(`  pre-commit gate:     ${r.precommit}`);
-    console.log(
-      `  sandbox settings:    ${r.sandbox} — merge into ~/.claude/settings.json to enable (84% fewer prompts)`,
-    );
+  if (sub === "lock") {
+    const { count } = s.snapshot(process.cwd());
+    console.log(`  spec-lock: snapshotted ${count} spec(s) → .forge/spec-lock.json`);
     return;
   }
-  if (cmd === "precommit") {
-    // The commit-level rung of the gate lattice (turn ⊂ commit ⊂ PR): the harden-installed
-    // pre-commit hook execs this, and it can be run by hand before committing. Exit code
-    // carries the decision (1 = refuse the commit); fail-open inside commitGate.
-    const { commitGate, renderCommitGate } = await import("./commit_gate.js");
-    const r = commitGate(process.cwd());
-    if (argv.includes("--json")) {
-      console.log(JSON.stringify(r, null, 2));
-      if (!r.allow) process.exitCode = 1;
-      return;
-    }
-    heading(`${BRAND.brand} precommit — commit-level completeness + secret gate\n`);
-    console.log(renderCommitGate(r));
+  const r = s.check(process.cwd());
+  heading(`${BRAND.brand} spec check\n`);
+  if (r.note) console.log(`  ${r.note}`);
+  else if (r.drift.length) {
+    for (const d of r.drift) {
+      console.log(`  ✗ ${d.spec} claims \`${d.symbol}\` — no longer defined in the code`);
+    }
+  } else console.log("  ✓ no drift — every claimed symbol still exists");
+  console.log(`\n  ${r.ok ? "PASS" : "DRIFT — update the spec or restore the symbol"}`);
+  if (!r.ok) process.exitCode = 1;
+  return;
+};
+HANDLERS.harden = async () => {
+  const { harden } = await import("./harden.js");
+  const r = harden({ targetRoot: process.cwd() });
+  heading(`${BRAND.brand} harden\n`);
+  console.log(`  gitleaks:            ${r.gitleaks}`);
+  console.log(`  pre-commit gate:     ${r.precommit}`);
+  console.log(
+    `  sandbox settings:    ${r.sandbox} — merge into ~/.claude/settings.json to enable (84% fewer prompts)`,
+  );
+  return;
+};
+HANDLERS.precommit = async (argv) => {
+  // The commit-level rung of the gate lattice (turn ⊂ commit ⊂ PR): the harden-installed
+  // pre-commit hook execs this, and it can be run by hand before committing. Exit code
+  // carries the decision (1 = refuse the commit); fail-open inside commitGate.
+  const { commitGate, renderCommitGate } = await import("./commit_gate.js");
+  const r = commitGate(process.cwd());
+  if (argv.includes("--json")) {
+    console.log(JSON.stringify(r, null, 2));
     if (!r.allow) process.exitCode = 1;
     return;
   }
-  if (cmd === "cortex") {
-    const c = await import("./cortex.js");
-    const root = process.cwd();
-    const nowDay = Math.floor(Date.now() / 86400000);
-    const sub = argv[1] || "status";
-    if (sub === "why") {
-      const key = argv[2];
-      if (!key) {
-        console.error("usage: forge cortex why <symbol|file>");
-        process.exitCode = 1;
-        return;
-      }
-      const { block, selected } = c.lessonsForContext(
-        root,
-        { symbols: [key], files: [key], keywords: [key] },
-        { nowDay },
-      );
-      console.log(selected.length ? block : `  no lessons for ${key} yet`);
-      return;
-    }
-    const s = c.summary(root, nowDay);
-    heading(`${BRAND.brand} cortex — self-correcting project memory\n`);
-    console.log(
-      `  lessons: ${s.total}  (active ${s.active} · candidate ${s.candidate} · quarantined ${s.quarantined} · retired ${s.retired})`,
-    );
-    if (s.topActive.length) {
-      console.log("\n  top active (by confidence):");
-      for (const t of s.topActive)
-        console.log(`    ${bar(t.confidence, 8)} ${t.confidence.toFixed(2)}  ${t.id}`);
-    } else {
-      console.log("\n  (no active lessons yet — Cortex learns from corrections as you work)");
-    }
-    console.log(paint("\n  stored in .forge/lessons/ (git-committable, auditable)", "dim"));
-    return;
-  }
-  if (cmd === "deja") {
-    const { dejaFromLedger } = await import("./deja.js");
-    const { claimText, val } = await import("./ledger.js");
-    const { epochDay } = await import("./util.js");
-    const json = argv.includes("--json");
-    const task = argv
-      .slice(1)
-      .filter((a) => a !== "--json")
-      .join(" ");
-    if (!task) {
-      console.error('usage: forge deja "<task you are about to start>" [--json]');
+  heading(`${BRAND.brand} precommit — commit-level completeness + secret gate\n`);
+  console.log(renderCommitGate(r));
+  if (!r.allow) process.exitCode = 1;
+  return;
+};
+HANDLERS.cortex = async (argv) => {
+  const c = await import("./cortex.js");
+  const root = process.cwd();
+  const nowDay = Math.floor(Date.now() / 86400000);
+  const sub = argv[1] || "status";
+  if (sub === "why") {
+    const key = argv[2];
+    if (!key) {
+      console.error("usage: forge cortex why <symbol|file>");
       process.exitCode = 1;
       return;
     }
-    const nowDay = epochDay();
-    const hits = dejaFromLedger(process.cwd(), task, { nowDay, budget: 8 });
-    if (json)
-      return console.log(
-        JSON.stringify(
-          hits.map((h) => ({
-            id: h.claim.id,
-            kind: h.claim.kind,
-            score: h.score,
-            verified: val(h.claim, nowDay) > 0.5,
-            day: h.claim.provenance?.t ?? 0,
-            gist: claimText(h.claim).slice(0, 120),
-          })),
-          null,
-          2,
-        ),
-      );
-    heading(`${BRAND.brand} déjà vu — have you done this before?\n`);
-    if (!hits.length) return console.log("  no similar prior task in memory — this looks new.");
-    for (const h of hits) {
-      const verified = val(h.claim, nowDay) > 0.5;
-      console.log(
-        `  ${bar(h.score, 8)} ${h.score.toFixed(3)}  ${paint(h.claim.kind.padEnd(9), "accent")} ${verified ? paint("verified", "ok") : paint("attempted", "warn")}  day ${h.claim.provenance?.t ?? 0}  ${claimText(h.claim).replace(/\s+/g, " ").trim().slice(0, 80)}`,
-      );
-    }
+    const { block, selected } = c.lessonsForContext(
+      root,
+      { symbols: [key], files: [key], keywords: [key] },
+      { nowDay },
+    );
+    console.log(selected.length ? block : `  no lessons for ${key} yet`);
     return;
   }
-  if (cmd === "preflight") {
-    const { preflightRepo, clarifyBlock } = await import("./preflight.js");
-    const json = argv.includes("--json");
-    const task = argv
-      .slice(1)
-      .filter((a) => a !== "--json")
-      .join(" ");
-    if (!task) {
-      console.error('usage: forge preflight "<task description>" [--json]');
-      process.exitCode = 1;
-      return;
-    }
-    const r = preflightRepo(process.cwd(), task);
-    if (json) {
-      console.log(JSON.stringify(r, null, 2));
-      return;
-    }
-    heading(`${BRAND.brand} preflight — assumption check\n`);
+  const s = c.summary(root, nowDay);
+  heading(`${BRAND.brand} cortex — self-correcting project memory\n`);
+  console.log(
+    `  lessons: ${s.total}  (active ${s.active} · candidate ${s.candidate} · quarantined ${s.quarantined} · retired ${s.retired})`,
+  );
+  if (s.topActive.length) {
+    console.log("\n  top active (by confidence):");
+    for (const t of s.topActive)
+      console.log(`    ${bar(t.confidence, 8)} ${t.confidence.toFixed(2)}  ${t.id}`);
+  } else {
+    console.log("\n  (no active lessons yet — Cortex learns from corrections as you work)");
+  }
+  console.log(paint("\n  stored in .forge/lessons/ (git-committable, auditable)", "dim"));
+  return;
+};
+HANDLERS.deja = async (argv) => {
+  const { dejaFromLedger } = await import("./deja.js");
+  const { claimText, val } = await import("./ledger.js");
+  const { epochDay } = await import("./util.js");
+  const json = argv.includes("--json");
+  const task = argv
+    .slice(1)
+    .filter((a) => a !== "--json")
+    .join(" ");
+  if (!task) {
+    console.error('usage: forge deja "<task you are about to start>" [--json]');
+    process.exitCode = 1;
+    return;
+  }
+  const nowDay = epochDay();
+  const hits = dejaFromLedger(process.cwd(), task, { nowDay, budget: 8 });
+  if (json)
+    return console.log(
+      JSON.stringify(
+        hits.map((h) => ({
+          id: h.claim.id,
+          kind: h.claim.kind,
+          score: h.score,
+          verified: val(h.claim, nowDay) > 0.5,
+          day: h.claim.provenance?.t ?? 0,
+          gist: claimText(h.claim).slice(0, 120),
+        })),
+        null,
+        2,
+      ),
+    );
+  heading(`${BRAND.brand} déjà vu — have you done this before?\n`);
+  if (!hits.length) return console.log("  no similar prior task in memory — this looks new.");
+  for (const h of hits) {
+    const verified = val(h.claim, nowDay) > 0.5;
     console.log(
-      `  info-gap: ${r.gap.toFixed(2)}  · completeness ${r.assumption.completeness.toFixed(2)}  (referenced ${r.entities.symbols.length} symbol(s), ${r.entities.files.length} file(s))`,
+      `  ${bar(h.score, 8)} ${h.score.toFixed(3)}  ${paint(h.claim.kind.padEnd(9), "accent")} ${verified ? paint("verified", "ok") : paint("attempted", "warn")}  day ${h.claim.provenance?.t ?? 0}  ${claimText(h.claim).replace(/\s+/g, " ").trim().slice(0, 80)}`,
     );
-    const block = clarifyBlock(r);
+  }
+  return;
+};
+HANDLERS.preflight = async (argv) => {
+  const { preflightRepo, clarifyBlock } = await import("./preflight.js");
+  const json = argv.includes("--json");
+  const task = argv
+    .slice(1)
+    .filter((a) => a !== "--json")
+    .join(" ");
+  if (!task) {
+    console.error('usage: forge preflight "<task description>" [--json]');
+    process.exitCode = 1;
+    return;
+  }
+  const r = preflightRepo(process.cwd(), task);
+  if (json) {
+    console.log(JSON.stringify(r, null, 2));
+    return;
+  }
+  heading(`${BRAND.brand} preflight — assumption check\n`);
+  console.log(
+    `  info-gap: ${r.gap.toFixed(2)}  · completeness ${r.assumption.completeness.toFixed(2)}  (referenced ${r.entities.symbols.length} symbol(s), ${r.entities.files.length} file(s))`,
+  );
+  const block = clarifyBlock(r);
+  console.log(
+    block ? `\n${block}` : "\n  ✓ everything this task names is grounded in the codebase.",
+  );
+  return;
+};
+HANDLERS.impact = async (argv) => {
+  const { predictImpact } = await import("./substrate.js");
+  const json = argv.includes("--json");
+  const target = argv
+    .slice(1)
+    .filter((a) => a !== "--json")
+    .join(" ");
+  if (!target) {
+    console.error("usage: forge impact <symbol|file> [--json]");
+    process.exitCode = 1;
+    return;
+  }
+  const r = predictImpact(process.cwd(), target);
+  if (json) {
+    console.log(JSON.stringify(r, null, 2));
+    return;
+  }
+  heading(`${BRAND.brand} impact — blast radius\n`);
+  console.log(`  target: ${target}  ${r.found ? "✓ found" : "not found"}`);
+  console.log(`  impacted files: ${r.impactedFiles.length}`);
+  for (const file of r.impactedFiles.slice(0, 20)) console.log(`    - ${file}`);
+  if (r.impactedFiles.length > 20) console.log(`    … ${r.impactedFiles.length - 20} more`);
+  return;
+};
+HANDLERS.substrate = async (argv) => {
+  const { renderSubstrate, substrateCheck } = await import("./substrate.js");
+  const json = argv.includes("--json");
+  const task = argv
+    .slice(1)
+    .filter((a) => a !== "--json")
+    .join(" ");
+  if (!task) {
+    console.error('usage: forge substrate "<task>" [--json]');
+    process.exitCode = 1;
+    return;
+  }
+  const r = substrateCheck(process.cwd(), task);
+  console.log(json ? JSON.stringify(r, null, 2) : renderSubstrate(r));
+  return;
+};
+HANDLERS.config = async (argv) => {
+  const sub = argv[1] || "show";
+  const { loadProviders, activeProvider, setProvider, addProvider, listProviders, applyRoute } =
+    await import("./providers.js");
+  const json = argv.includes("--json");
+  if (sub === "show") {
+    const prov = activeProvider(process.cwd());
+    const config = loadProviders(process.cwd());
+    if (json)
+      return console.log(JSON.stringify({ active: config.active, provider: prov }, null, 2));
+    heading(`${BRAND.brand} config\n`);
+    console.log(`  provider:  ${prov.name} (${prov.label || prov.name})`);
+    if (prov._autoDetected) console.log(`  detected:  auto (from ${prov._source})`);
+    console.log(`  base URL:  ${prov.baseUrl}`);
     console.log(
-      block ? `\n${block}` : "\n  ✓ everything this task names is grounded in the codebase.",
+      `  env key:   ${prov.envKey || "(none)"}${prov.envKey ? (process.env[prov.envKey] ? " ✓ set" : " ✗ not set") : ""}`,
     );
+    console.log(`  models:`);
+    for (const [tier, id] of Object.entries(prov.models || {}))
+      console.log(`    ${tier.padEnd(8)} ${id}`);
     return;
   }
-  if (cmd === "impact") {
-    const { predictImpact } = await import("./substrate.js");
-    const json = argv.includes("--json");
-    const target = argv
-      .slice(1)
-      .filter((a) => a !== "--json")
-      .join(" ");
-    if (!target) {
-      console.error("usage: forge impact <symbol|file> [--json]");
-      process.exitCode = 1;
-      return;
-    }
-    const r = predictImpact(process.cwd(), target);
-    if (json) {
-      console.log(JSON.stringify(r, null, 2));
-      return;
-    }
-    heading(`${BRAND.brand} impact — blast radius\n`);
-    console.log(`  target: ${target}  ${r.found ? "✓ found" : "not found"}`);
-    console.log(`  impacted files: ${r.impactedFiles.length}`);
-    for (const file of r.impactedFiles.slice(0, 20)) console.log(`    - ${file}`);
-    if (r.impactedFiles.length > 20) console.log(`    … ${r.impactedFiles.length - 20} more`);
-    return;
-  }
-  if (cmd === "substrate") {
-    const { renderSubstrate, substrateCheck } = await import("./substrate.js");
-    const json = argv.includes("--json");
-    const task = argv
-      .slice(1)
-      .filter((a) => a !== "--json")
-      .join(" ");
-    if (!task) {
-      console.error('usage: forge substrate "<task>" [--json]');
-      process.exitCode = 1;
-      return;
-    }
-    const r = substrateCheck(process.cwd(), task);
-    console.log(json ? JSON.stringify(r, null, 2) : renderSubstrate(r));
-    return;
-  }
-  if (cmd === "config") {
-    const sub = argv[1] || "show";
-    const { loadProviders, activeProvider, setProvider, addProvider, listProviders, applyRoute } =
-      await import("./providers.js");
-    const json = argv.includes("--json");
-    if (sub === "show") {
-      const prov = activeProvider(process.cwd());
-      const config = loadProviders(process.cwd());
-      if (json)
-        return console.log(JSON.stringify({ active: config.active, provider: prov }, null, 2));
-      heading(`${BRAND.brand} config\n`);
-      console.log(`  provider:  ${prov.name} (${prov.label || prov.name})`);
-      if (prov._autoDetected) console.log(`  detected:  auto (from ${prov._source})`);
-      console.log(`  base URL:  ${prov.baseUrl}`);
+  if (sub === "providers") {
+    const list = listProviders(process.cwd());
+    if (json) return console.log(JSON.stringify(list, null, 2));
+    heading(`${BRAND.brand} config providers\n`);
+    for (const p of list)
       console.log(
-        `  env key:   ${prov.envKey || "(none)"}${prov.envKey ? (process.env[prov.envKey] ? " ✓ set" : " ✗ not set") : ""}`,
+        `  ${p.active ? "▸" : " "} ${p.name.padEnd(14)} ${p.label.padEnd(20)} ${p.envKey ? (p.hasKey ? "✓ key set" : "✗ key missing") : ""}`,
       );
-      console.log(`  models:`);
-      for (const [tier, id] of Object.entries(prov.models || {}))
-        console.log(`    ${tier.padEnd(8)} ${id}`);
-      return;
-    }
-    if (sub === "providers") {
-      const list = listProviders(process.cwd());
-      if (json) return console.log(JSON.stringify(list, null, 2));
-      heading(`${BRAND.brand} config providers\n`);
-      for (const p of list)
-        console.log(
-          `  ${p.active ? "▸" : " "} ${p.name.padEnd(14)} ${p.label.padEnd(20)} ${p.envKey ? (p.hasKey ? "✓ key set" : "✗ key missing") : ""}`,
-        );
-      console.log(`\n  switch: \`${BRAND.cli} config provider <name>\``);
+    console.log(`\n  switch: \`${BRAND.cli} config provider <name>\``);
+    return;
+  }
+  if (sub === "provider") {
+    const name = argv[2];
+    if (!name) {
+      console.error(
+        `usage: ${BRAND.cli} config provider <name>   |   ${BRAND.cli} config provider add <name> --base-url <url> [--key-env <VAR>]`,
+      );
+      process.exitCode = 1;
       return;
     }
-    if (sub === "provider") {
-      const name = argv[2];
-      if (!name) {
-        console.error(
-          `usage: ${BRAND.cli} config provider <name>   |   ${BRAND.cli} config provider add <name> --base-url <url> [--key-env <VAR>]`,
-        );
-        process.exitCode = 1;
-        return;
-      }
-      if (name === "add") {
-        const addName = argv[3];
-        const flagVal = (f) => {
-          const i = argv.indexOf(f);
-          return i >= 0 ? argv[i + 1] : undefined;
-        };
-        const baseUrl = flagVal("--base-url");
-        const envKey = flagVal("--key-env");
-        const label = flagVal("--label");
-        const r = addProvider(process.cwd(), addName, {
-          baseUrl,
-          envKey,
-          label,
-        });
-        if (!r.ok) {
-          console.error(`  ${r.reason}`);
-          process.exitCode = 1;
-          return;
-        }
-        console.log(`  added provider "${addName}" → ${r.provider.baseUrl}`);
-        return;
-      }
-      const r = setProvider(process.cwd(), name);
+    if (name === "add") {
+      const addName = argv[3];
+      const flagVal = (f) => {
+        const i = argv.indexOf(f);
+        return i >= 0 ? argv[i + 1] : undefined;
+      };
+      const baseUrl = flagVal("--base-url");
+      const envKey = flagVal("--key-env");
+      const label = flagVal("--label");
+      const r = addProvider(process.cwd(), addName, {
+        baseUrl,
+        envKey,
+        label,
+      });
       if (!r.ok) {
         console.error(`  ${r.reason}`);
         process.exitCode = 1;
         return;
       }
-      console.log(`  switched to provider "${name}" (${r.provider.label || name})`);
+      console.log(`  added provider "${addName}" → ${r.provider.baseUrl}`);
       return;
     }
-    if (sub === "model") {
-      const tier = argv[2];
-      if (!tier) {
-        console.error(`usage: ${BRAND.cli} config model <haiku|sonnet|opus|fable>`);
-        process.exitCode = 1;
-        return;
-      }
-      const r = applyRoute(tier);
-      if (!r.ok) {
-        console.error(`  ${r.reason}`);
-        process.exitCode = 1;
-        return;
-      }
-      console.log(`  model set to ${r.model} (${r.modelId})${r.prev ? ` — was: ${r.prev}` : ""}`);
-      console.log(`  written to ${r.path}`);
+    const r = setProvider(process.cwd(), name);
+    if (!r.ok) {
+      console.error(`  ${r.reason}`);
+      process.exitCode = 1;
       return;
     }
-    if (sub === "gateway") {
-      const { emitGatewayConfig } = await import("./route.js");
-      const result = emitGatewayConfig(process.cwd());
-      if (typeof result === "object" && !result.ok) {
-        console.log(`  ${result.reason}`);
-        return;
-      }
-      console.log(`  wrote ${result}`);
-      console.log(`\n  setup LiteLLM gateway:`);
-      console.log(`    1. pip install "litellm[proxy]"    # pin an exact verified version`);
-      console.log(`    2. litellm --config litellm.config.yaml`);
-      console.log(`    3. export ANTHROPIC_BASE_URL=http://localhost:4000`);
-      console.log(`\n  then switch to the gateway provider:`);
-      console.log(`    ${BRAND.cli} config provider litellm`);
-      console.log(`\n  routing flows through: forge route → tier alias → LiteLLM → model`);
+    console.log(`  switched to provider "${name}" (${r.provider.label || name})`);
+    return;
+  }
+  if (sub === "model") {
+    const tier = argv[2];
+    if (!tier) {
+      console.error(`usage: ${BRAND.cli} config model <haiku|sonnet|opus|fable>`);
+      process.exitCode = 1;
       return;
     }
-    if (sub === "setup") {
-      const { providerStatus, listDetectedProviders } = await import("./providers.js");
-      const prov = activeProvider(process.cwd());
-      const status = providerStatus(process.cwd());
-      const detected = listDetectedProviders();
-      heading(`${BRAND.brand} config setup\n`);
-      console.log(`  active provider: ${prov.name} (${prov.label || prov.name})`);
-      if (prov._autoDetected) console.log(`  source: auto-detected from ${prov._source}`);
-      console.log();
-      for (const c of status.checks) {
-        console.log(`  ${c.ok ? "✓" : "✗"} ${c.detail}`);
-      }
-      console.log(`\n  environment:`);
-      for (const e of status.envScan) {
-        console.log(`  ${e.set ? "✓" : "·"} ${e.key}${e.set ? " (set)" : ""}`);
-      }
-      if (detected.length) {
-        console.log(`\n  available providers (auto-detected):`);
-        for (const d of detected) {
-          console.log(`    ${d.name.padEnd(18)} ${d.label.padEnd(24)} via ${d.source}`);
-        }
-      }
-      console.log(`\n  Anthropic Console API key:`);
-      console.log(`    1. Go to console.anthropic.com/settings/keys`);
-      console.log(`    2. Create a key, then:  export ANTHROPIC_API_KEY=sk-ant-...`);
-      console.log(`\n  OpenRouter API key:`);
-      console.log(`    1. Go to openrouter.ai/keys`);
-      console.log(`    2. Create a key, then:  export OPENROUTER_API_KEY=sk-or-...`);
-      console.log(`\n  LiteLLM hosted gateway (no admin access needed):`);
-      console.log(`    export LITELLM_BASE_URL=https://your-gateway.example.com`);
-      console.log(`    export LITELLM_API_KEY=sk-...    # or uses ANTHROPIC_API_KEY`);
-      console.log(`\n  LiteLLM self-hosted gateway:`);
-      console.log(`    ${BRAND.cli} config gateway    # emit litellm.config.yaml`);
-      console.log(`    ${BRAND.cli} config provider litellm`);
-      console.log(`\n  quick start:`);
-      console.log(`    ${BRAND.cli} config provider anthropic     # direct Anthropic API`);
-      console.log(`    ${BRAND.cli} config provider openrouter    # OpenRouter multi-model`);
-      console.log(`    ${BRAND.cli} config provider litellm       # LiteLLM self-hosted`);
-      console.log(`    ${BRAND.cli} config model sonnet           # set default model tier`);
-      console.log(`    ${BRAND.cli} route "<task>" --apply        # route + apply model`);
+    const r = applyRoute(tier);
+    if (!r.ok) {
+      console.error(`  ${r.reason}`);
+      process.exitCode = 1;
       return;
     }
-    console.error(
-      `config: unknown subcommand "${sub}" (show | providers | provider <name> | model <tier> | gateway | setup)`,
-    );
-    process.exitCode = 1;
+    console.log(`  model set to ${r.model} (${r.modelId})${r.prev ? ` — was: ${r.prev}` : ""}`);
+    console.log(`  written to ${r.path}`);
     return;
   }
-  if (cmd === "route") {
-    const r = await import("./route.js");
-    if (argv[1] === "gateway") {
-      const result = r.emitGatewayConfig(process.cwd());
-      if (typeof result === "object" && !result.ok) {
-        console.log(`  ${result.reason}`);
-        return;
-      }
-      console.log(
-        `  wrote ${result} — LiteLLM tiers: forge-simple / forge-medium / forge-complex.`,
-      );
-      console.log("  next: pin+install litellm, run it, point ANTHROPIC_BASE_URL at it, then");
-      console.log(
-        "        REQUEST the tier `forge route` recommends (a plain claude-* request passes through).",
-      );
+  if (sub === "gateway") {
+    const { emitGatewayConfig } = await import("./route.js");
+    const result = emitGatewayConfig(process.cwd());
+    if (typeof result === "object" && !result.ok) {
+      console.log(`  ${result.reason}`);
+      return;
+    }
+    console.log(`  wrote ${result}`);
+    console.log(`\n  setup LiteLLM gateway:`);
+    console.log(`    1. pip install "litellm[proxy]"    # pin an exact verified version`);
+    console.log(`    2. litellm --config litellm.config.yaml`);
+    console.log(`    3. export ANTHROPIC_BASE_URL=http://localhost:4000`);
+    console.log(`\n  then switch to the gateway provider:`);
+    console.log(`    ${BRAND.cli} config provider litellm`);
+    console.log(`\n  routing flows through: forge route → tier alias → LiteLLM → model`);
+    return;
+  }
+  if (sub === "setup") {
+    const { providerStatus, listDetectedProviders } = await import("./providers.js");
+    const prov = activeProvider(process.cwd());
+    const status = providerStatus(process.cwd());
+    const detected = listDetectedProviders();
+    heading(`${BRAND.brand} config setup\n`);
+    console.log(`  active provider: ${prov.name} (${prov.label || prov.name})`);
+    if (prov._autoDetected) console.log(`  source: auto-detected from ${prov._source}`);
+    console.log();
+    for (const c of status.checks) {
+      console.log(`  ${c.ok ? "✓" : "✗"} ${c.detail}`);
+    }
+    console.log(`\n  environment:`);
+    for (const e of status.envScan) {
+      console.log(`  ${e.set ? "✓" : "·"} ${e.key}${e.set ? " (set)" : ""}`);
+    }
+    if (detected.length) {
+      console.log(`\n  available providers (auto-detected):`);
+      for (const d of detected) {
+        console.log(`    ${d.name.padEnd(18)} ${d.label.padEnd(24)} via ${d.source}`);
+      }
+    }
+    console.log(`\n  Anthropic Console API key:`);
+    console.log(`    1. Go to console.anthropic.com/settings/keys`);
+    console.log(`    2. Create a key, then:  export ANTHROPIC_API_KEY=sk-ant-...`);
+    console.log(`\n  OpenRouter API key:`);
+    console.log(`    1. Go to openrouter.ai/keys`);
+    console.log(`    2. Create a key, then:  export OPENROUTER_API_KEY=sk-or-...`);
+    console.log(`\n  LiteLLM hosted gateway (no admin access needed):`);
+    console.log(`    export LITELLM_BASE_URL=https://your-gateway.example.com`);
+    console.log(`    export LITELLM_API_KEY=sk-...    # or uses ANTHROPIC_API_KEY`);
+    console.log(`\n  LiteLLM self-hosted gateway:`);
+    console.log(`    ${BRAND.cli} config gateway    # emit litellm.config.yaml`);
+    console.log(`    ${BRAND.cli} config provider litellm`);
+    console.log(`\n  quick start:`);
+    console.log(`    ${BRAND.cli} config provider anthropic     # direct Anthropic API`);
+    console.log(`    ${BRAND.cli} config provider openrouter    # OpenRouter multi-model`);
+    console.log(`    ${BRAND.cli} config provider litellm       # LiteLLM self-hosted`);
+    console.log(`    ${BRAND.cli} config model sonnet           # set default model tier`);
+    console.log(`    ${BRAND.cli} route "<task>" --apply        # route + apply model`);
+    return;
+  }
+  console.error(
+    `config: unknown subcommand "${sub}" (show | providers | provider <name> | model <tier> | gateway | setup)`,
+  );
+  process.exitCode = 1;
+  return;
+};
+HANDLERS.route = async (argv) => {
+  const r = await import("./route.js");
+  if (argv[1] === "gateway") {
+    const result = r.emitGatewayConfig(process.cwd());
+    if (typeof result === "object" && !result.ok) {
+      console.log(`  ${result.reason}`);
       return;
     }
-    if (argv[1] === "calibrate") {
-      // Advisory → gated promotion (ROADMAP): measure whether an affine calibration of the
-      // routing rubric beats the raw rubric on the held-out fixture. Advisory — routing
-      // keeps the rubric unless the gate promotes AND a caller adopts the calibration.
-      const res = r.calibrateRouting();
-      if (argv.includes("--json")) return console.log(JSON.stringify(res, null, 2));
-      heading(`${BRAND.brand} route calibrate — outcome-calibrated routing (measured gate)\n`);
-      console.log(`  samples: ${res.n} labeled task(s)`);
-      if (res.baselineMetric !== undefined)
-        console.log(
-          `  held-out MAE: rubric ${res.baselineMetric} · calibrated ${res.candidateMetric}`,
-        );
-      console.log(
-        res.mode === "candidate"
-          ? `  → PROMOTE calibration — ${res.reason} (a=${res.model.a.toFixed(3)}, b=${res.model.b.toFixed(3)})`
-          : `  → keep the rubric — ${res.reason}`,
-      );
+    console.log(`  wrote ${result} — LiteLLM tiers: forge-simple / forge-medium / forge-complex.`);
+    console.log("  next: pin+install litellm, run it, point ANTHROPIC_BASE_URL at it, then");
+    console.log(
+      "        REQUEST the tier `forge route` recommends (a plain claude-* request passes through).",
+    );
+    return;
+  }
+  if (argv[1] === "calibrate") {
+    // Advisory → gated promotion (ROADMAP): measure whether an affine calibration of the
+    // routing rubric beats the raw rubric on the held-out fixture. Advisory — routing
+    // keeps the rubric unless the gate promotes AND a caller adopts the calibration.
+    const res = r.calibrateRouting();
+    if (argv.includes("--json")) return console.log(JSON.stringify(res, null, 2));
+    heading(`${BRAND.brand} route calibrate — outcome-calibrated routing (measured gate)\n`);
+    console.log(`  samples: ${res.n} labeled task(s)`);
+    if (res.baselineMetric !== undefined)
       console.log(
-        "\n  advisory — routing stays on the rubric until a promoted calibration is adopted",
-      );
-      return;
-    }
-    const json = argv.includes("--json");
-    const apply = argv.includes("--apply");
-    const providerIdx = argv.indexOf("--provider");
-    const providerName = providerIdx >= 0 ? argv[providerIdx + 1] : undefined;
-    const FLAGS = new Set(["--json", "--apply"]);
-    const task = argv
-      .slice(1)
-      .filter((a, i) => !FLAGS.has(a) && a !== "--provider" && argv[i] !== "--provider")
-      .join(" ");
-    if (!task) {
-      console.error(
-        'usage: forge route "<task>" [--apply] [--provider <name>] [--json]   |   forge route gateway',
+        `  held-out MAE: rubric ${res.baselineMetric} · calibrated ${res.candidateMetric}`,
       );
+    console.log(
+      res.mode === "candidate"
+        ? `  → PROMOTE calibration — ${res.reason} (a=${res.model.a.toFixed(3)}, b=${res.model.b.toFixed(3)})`
+        : `  → keep the rubric — ${res.reason}`,
+    );
+    console.log(
+      "\n  advisory — routing stays on the rubric until a promoted calibration is adopted",
+    );
+    return;
+  }
+  const json = argv.includes("--json");
+  const apply = argv.includes("--apply");
+  const providerIdx = argv.indexOf("--provider");
+  const providerName = providerIdx >= 0 ? argv[providerIdx + 1] : undefined;
+  const FLAGS = new Set(["--json", "--apply"]);
+  const task = argv
+    .slice(1)
+    .filter((a, i) => !FLAGS.has(a) && a !== "--provider" && argv[i] !== "--provider")
+    .join(" ");
+  if (!task) {
+    console.error(
+      'usage: forge route "<task>" [--apply] [--provider <name>] [--json]   |   forge route gateway',
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (providerName) {
+    const { setProvider } = await import("./providers.js");
+    const sr = setProvider(process.cwd(), providerName);
+    if (!sr.ok) {
+      console.error(`  ${sr.reason}`);
       process.exitCode = 1;
       return;
     }
-    if (providerName) {
-      const { setProvider } = await import("./providers.js");
-      const sr = setProvider(process.cwd(), providerName);
-      if (!sr.ok) {
-        console.error(`  ${sr.reason}`);
-        process.exitCode = 1;
-        return;
-      }
-    }
-    const rec = r.routeTask(process.cwd(), task);
-    r.meterRoute(process.cwd(), task, rec);
-    if (json) {
-      console.log(JSON.stringify(rec, null, 2));
+  }
+  const rec = r.routeTask(process.cwd(), task);
+  r.meterRoute(process.cwd(), task, rec);
+  if (json) {
+    console.log(JSON.stringify(rec, null, 2));
+  } else {
+    heading(`${BRAND.brand} route — cheapest capable model\n`);
+    const { priceOf } = await import("./model_tiers.js");
+    const price = priceOf(rec.key) || {
+      inCost: rec.model.inCost,
+      outCost: rec.model.outCost,
+    };
+    console.log(
+      `  → ${paint(rec.model.name, "accent")}  (${rec.tier}, $${price.inCost}/$${price.outCost} per M tok, current effective)`,
+    );
+    console.log(`    ${rec.model.use}`);
+    console.log(
+      `    complexity ${bar(rec.score, 8)} ${rec.score.toFixed(2)}${rec.reasons.length ? ` · driven by: ${rec.reasons.join(", ")}` : ""}`,
+    );
+    console.log(
+      `    signals: ${rec.signals.files} file(s), fan-out ${rec.signals.fanout}, churn ${rec.signals.churn}, past-mistakes ${rec.signals.pastMistakes}, ambiguity ${rec.signals.ambiguity.toFixed(2)}`,
+    );
+  }
+  if (apply) {
+    const { applyRoute } = await import("./providers.js");
+    const ar = applyRoute(rec.key);
+    if (ar.ok) {
+      if (!json) console.log(`\n  applied: model set to ${ar.model} (${ar.modelId}) in ${ar.path}`);
     } else {
-      heading(`${BRAND.brand} route — cheapest capable model\n`);
-      const { priceOf } = await import("./model_tiers.js");
-      const price = priceOf(rec.key) || {
-        inCost: rec.model.inCost,
-        outCost: rec.model.outCost,
-      };
-      console.log(
-        `  → ${paint(rec.model.name, "accent")}  (${rec.tier}, $${price.inCost}/$${price.outCost} per M tok, current effective)`,
-      );
-      console.log(`    ${rec.model.use}`);
-      console.log(
-        `    complexity ${bar(rec.score, 8)} ${rec.score.toFixed(2)}${rec.reasons.length ? ` · driven by: ${rec.reasons.join(", ")}` : ""}`,
-      );
-      console.log(
-        `    signals: ${rec.signals.files} file(s), fan-out ${rec.signals.fanout}, churn ${rec.signals.churn}, past-mistakes ${rec.signals.pastMistakes}, ambiguity ${rec.signals.ambiguity.toFixed(2)}`,
-      );
+      if (!json) console.error(`\n  apply failed: ${ar.reason}`);
+      process.exitCode = 1;
     }
-    if (apply) {
-      const { applyRoute } = await import("./providers.js");
-      const ar = applyRoute(rec.key);
-      if (ar.ok) {
-        if (!json)
-          console.log(`\n  applied: model set to ${ar.model} (${ar.modelId}) in ${ar.path}`);
-      } else {
-        if (!json) console.error(`\n  apply failed: ${ar.reason}`);
-        process.exitCode = 1;
-      }
-    } else if (!json) {
-      console.log(
-        `\n  advisory · apply: \`${BRAND.cli} route "<task>" --apply\` · gateway: \`${BRAND.cli} route gateway\``,
-      );
+  } else if (!json) {
+    console.log(
+      `\n  advisory · apply: \`${BRAND.cli} route "<task>" --apply\` · gateway: \`${BRAND.cli} route gateway\``,
+    );
+  }
+  return;
+};
+HANDLERS.anchor = async (argv) => {
+  const { goalDrift, renderAnchor } = await import("./anchor.js");
+  const { clearGoal, getGoal, setGoal } = await import("./goal.js");
+  const json = argv.includes("--json");
+  const args = argv.slice(1).filter((a) => a !== "--json");
+  const sub = args[0];
+  // Persistent goal management: `set` stores it, SessionStart re-injects it, and a
+  // bare `forge anchor` checks against it — the goal survives the session that set it.
+  if (sub === "set") {
+    const r = setGoal(process.cwd(), args.slice(1).join(" "));
+    if (!r.ok) {
+      console.error(`${BRAND.cli} anchor set: ${r.reason}`);
+      process.exitCode = 1;
+      return;
     }
+    console.log(
+      `goal set: ${r.goal}\n(injected each session start; \`forge anchor\` checks against it)`,
+    );
     return;
   }
-  if (cmd === "anchor") {
-    const { goalDrift, renderAnchor } = await import("./anchor.js");
-    const { clearGoal, getGoal, setGoal } = await import("./goal.js");
-    const json = argv.includes("--json");
-    const args = argv.slice(1).filter((a) => a !== "--json");
-    const sub = args[0];
-    // Persistent goal management: `set` stores it, SessionStart re-injects it, and a
-    // bare `forge anchor` checks against it — the goal survives the session that set it.
-    if (sub === "set") {
-      const r = setGoal(process.cwd(), args.slice(1).join(" "));
-      if (!r.ok) {
-        console.error(`${BRAND.cli} anchor set: ${r.reason}`);
-        process.exitCode = 1;
-        return;
-      }
+  if (sub === "show") {
+    const g = getGoal(process.cwd());
+    console.log(g ? `active goal: ${g}` : 'no active goal — set one: forge anchor set "<goal>"');
+    return;
+  }
+  if (sub === "clear") {
+    clearGoal(process.cwd());
+    console.log("goal cleared.");
+    return;
+  }
+  const goal = args.join(" ") || getGoal(process.cwd());
+  if (!goal) {
+    console.error(
+      `usage: ${BRAND.cli} anchor "<original goal>" [--json]\n       ${BRAND.cli} anchor set|show|clear — persist the goal across sessions`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const r = goalDrift(process.cwd(), goal);
+  console.log(json ? JSON.stringify(r, null, 2) : renderAnchor(r));
+  return; // advisory — never fails the process
+};
+HANDLERS.handoff = async (argv) => {
+  const { writeState } = await import("./handoff.js");
+  const json = argv.includes("--json");
+  const args = argv.slice(1).filter((a) => a !== "--json");
+  // Repeatable flags collect rows; positionals are "done" rows. Piped stdin (one row
+  // per line) covers agents that assemble the summary programmatically.
+  const fields = { done: [], next: [], gotchas: [], criteria: [] };
+  const FLAG = {
+    "--next": "next",
+    "--gotcha": "gotchas",
+    "--criteria": "criteria",
+  };
+  for (let i = 0; i < args.length; i += 1) {
+    if (FLAG[args[i]]) fields[FLAG[args[i]]].push(args[++i] ?? "");
+    else if (args[i] === "--phase") fields.phase = args[++i] ?? "";
+    else fields.done.push(args[i]);
+  }
+  if (!fields.done.length && !process.stdin.isTTY) {
+    try {
+      const { readFileSync } = await import("node:fs");
+      fields.done = readFileSync(0, "utf8").split("\n");
+    } catch {}
+  }
+  const r = writeState(process.cwd(), fields);
+  if (json) return console.log(JSON.stringify(r, null, 2));
+  if (!r.ok) {
+    console.error(
+      `${BRAND.cli} handoff: ${r.reason}\nusage: ${BRAND.cli} handoff "<done>" [--next "<step>"] [--gotcha "<trap>"] [--criteria "<check>"] [--phase <p>]`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  console.log(
+    `  state written: ${r.path} (${r.lines} lines)\n  (re-injected at every session start — the next session resumes instead of re-assuming)`,
+  );
+  return;
+};
+HANDLERS.decide = async (argv) => {
+  const { appendDecision, listDecisions } = await import("./decide.js");
+  const json = argv.includes("--json");
+  const text = argv
+    .slice(1)
+    .filter((a) => a !== "--json")
+    .join(" ");
+  if (!text) {
+    const rows = listDecisions(process.cwd(), { limit: 10 });
+    if (json) return console.log(JSON.stringify(rows, null, 2));
+    console.log(
+      rows.length
+        ? rows.map((d) => `  ${d.id} (${d.date}): ${d.text}`).join("\n")
+        : `  no decisions recorded — ${BRAND.cli} decide "<what was decided — why>"`,
+    );
+    return;
+  }
+  const r = appendDecision(process.cwd(), text);
+  if (json) return console.log(JSON.stringify(r, null, 2));
+  if (!r.ok) {
+    console.error(`${BRAND.cli} decide: ${r.reason}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`  recorded ${r.id}: ${r.text}`);
+  return;
+};
+HANDLERS.know = async (argv) => {
+  // A7 knowledge-router: total routing (T6) of a fact to its storage home — an unsure
+  // fact still lands (ledger fallback), it is never dropped.
+  const { HOMES, routeFact, storeFact } = await import("./knowledge_router.js");
+  const json = argv.includes("--json");
+  const dry = argv.includes("--dry-run");
+  const text = argv
+    .slice(1)
+    .filter((a) => a !== "--json" && a !== "--dry-run")
+    .join(" ");
+  if (!text) {
+    console.error(`usage: ${BRAND.cli} know "<fact>" [--dry-run] [--json]`);
+    process.exitCode = 1;
+    return;
+  }
+  const route = routeFact(text);
+  const r = storeFact(process.cwd(), text, {
+    mode: dry ? "advise" : "auto",
+    route,
+  });
+  if (json) return console.log(JSON.stringify({ ...route, ...r, dryRun: dry }, null, 2));
+  heading(`${BRAND.brand} know — knowledge routing (A7)\n`);
+  const why =
+    route.provenance === "fallback"
+      ? "fallback — resembles no exemplar; the ledger absorbs unsure placements"
+      : `confidence ${route.confidence}`;
+  console.log(`  home:     ${route.home} (${why}) → ${HOMES[route.home].where}`);
+  const near = route.neighbors[0];
+  if (near) console.log(`  nearest:  "${near.text}" (${near.sim.toFixed(3)})`);
+  if (!r.ok) {
+    console.error(`  ${r.reason}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (r.stored) console.log(`  stored:   ${r.ref}`);
+  else if (dry) console.log("  (dry-run — nothing written)");
+  if (r.advice) console.log(`  advice:   ${r.advice}`);
+  return;
+};
+HANDLERS.diagnose = async (argv) => {
+  const { diagnose, THRASH_K } = await import("./diagnose.js");
+  const json = argv.includes("--json");
+  const flagVal = (name) => {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+  };
+  const args = argv.filter(
+    (a, i) => !a.startsWith("--") && argv[i - 1] !== "--file" && argv[i - 1] !== "--symbol",
+  );
+  const errorText = args.slice(1).join(" ");
+  if (!errorText) {
+    console.error('usage: forge diagnose "<error text>" [--file f] [--symbol s] [--json]');
+    process.exitCode = 1;
+    return;
+  }
+  const r = diagnose(process.cwd(), {
+    errorText,
+    file: flagVal("--file"),
+    symbol: flagVal("--symbol"),
+  });
+  if (json) return console.log(JSON.stringify(r, null, 2));
+  heading(`${BRAND.brand} diagnose — doom-loop check\n`);
+  console.log(
+    `  signature: ${r.signature.slice(0, 12)} · seen ${r.count}× in the recent failure window`,
+  );
+  if (r.thrash) {
+    if (r.claimId)
       console.log(
-        `goal set: ${r.goal}\n(injected each session start; \`forge anchor\` checks against it)`,
+        `  diagnosis claim: ${r.claimId.slice(0, 12)}  (\`forge ledger show ${r.claimId.slice(0, 8)}\`)`,
       );
-      return;
-    }
-    if (sub === "show") {
-      const g = getGoal(process.cwd());
-      console.log(g ? `active goal: ${g}` : 'no active goal — set one: forge anchor set "<goal>"');
-      return;
-    }
-    if (sub === "clear") {
-      clearGoal(process.cwd());
-      console.log("goal cleared.");
-      return;
-    }
-    const goal = args.join(" ") || getGoal(process.cwd());
-    if (!goal) {
+    console.log(`\n  ${r.escalate ?? r.reason}`);
+  } else {
+    console.log(`  below the thrash threshold (${THRASH_K}) — recorded; keep going.`);
+  }
+  return; // advisory — halting the retry loop is the AGENT's move, not an exit code
+};
+HANDLERS.imagine = async (argv) => {
+  const { dryRun, imagineTask, renderImagine } = await import("./imagine.js");
+  const json = argv.includes("--json");
+  const doRun = argv.includes("--run");
+  const allowDirty = argv.includes("--allow-dirty");
+  const FLAGS = new Set(["--json", "--run", "--allow-dirty"]);
+  const task = argv
+    .slice(1)
+    .filter((a) => !FLAGS.has(a))
+    .join(" ");
+  if (!task) {
+    console.error('usage: forge imagine "<task>" [--run] [--allow-dirty] [--json]');
+    process.exitCode = 1;
+    return;
+  }
+  const root = process.cwd();
+  const r = imagineTask(root, task);
+  if (!doRun) {
+    console.log(json ? JSON.stringify(r, null, 2) : renderImagine(r));
+    return;
+  }
+  // --run: the static prediction first (always), then the measured half. The sandbox
+  // is a git worktree of HEAD — uncommitted changes are INVISIBLE to it — so a dirty
+  // tree is refused by default rather than silently dry-running the wrong code.
+  if (!json) console.log(renderImagine(r, { footer: false }));
+  if (!allowDirty) {
+    let dirty = "";
+    try {
+      const { execFileSync } = await import("node:child_process");
+      dirty = execFileSync("git", ["status", "--porcelain"], {
+        cwd: root,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+    } catch {} // not a repo / no git → dryRun reports its own precondition failure
+    if (dirty) {
       console.error(
-        `usage: ${BRAND.cli} anchor "<original goal>" [--json]\n       ${BRAND.cli} anchor set|show|clear — persist the goal across sessions`,
+        "\n  imagine --run refused: the working tree is dirty and the sandbox runs HEAD,\n" +
+          "  so your uncommitted changes would NOT be in the dry-run. Commit or stash them,\n" +
+          "  or pass --allow-dirty to knowingly measure the last commit instead.",
       );
       process.exitCode = 1;
       return;
     }
-    const r = goalDrift(process.cwd(), goal);
-    console.log(json ? JSON.stringify(r, null, 2) : renderAnchor(r));
-    return; // advisory — never fails the process
-  }
-  if (cmd === "handoff") {
-    const { writeState } = await import("./handoff.js");
-    const json = argv.includes("--json");
-    const args = argv.slice(1).filter((a) => a !== "--json");
-    // Repeatable flags collect rows; positionals are "done" rows. Piped stdin (one row
-    // per line) covers agents that assemble the summary programmatically.
-    const fields = { done: [], next: [], gotchas: [], criteria: [] };
-    const FLAG = {
-      "--next": "next",
-      "--gotcha": "gotchas",
-      "--criteria": "criteria",
-    };
-    for (let i = 0; i < args.length; i += 1) {
-      if (FLAG[args[i]]) fields[FLAG[args[i]]].push(args[++i] ?? "");
-      else if (args[i] === "--phase") fields.phase = args[++i] ?? "";
-      else fields.done.push(args[i]);
-    }
-    if (!fields.done.length && !process.stdin.isTTY) {
-      try {
-        const { readFileSync } = await import("node:fs");
-        fields.done = readFileSync(0, "utf8").split("\n");
-      } catch {}
-    }
-    const r = writeState(process.cwd(), fields);
-    if (json) return console.log(JSON.stringify(r, null, 2));
-    if (!r.ok) {
-      console.error(
-        `${BRAND.cli} handoff: ${r.reason}\nusage: ${BRAND.cli} handoff "<done>" [--next "<step>"] [--gotcha "<trap>"] [--criteria "<check>"] [--phase <p>]`,
-      );
-      process.exitCode = 1;
-      return;
+  }
+  const d = dryRun(root, { tests: r.tests });
+  // Metrics are best-effort telemetry (05-cost-model.md) — never let recording
+  // failure break the verdict. Only a run that happened is worth counting.
+  try {
+    if (d.durationMs !== undefined) {
+      const { record } = await import("./metrics.js");
+      record(root, {
+        stage: "imagine",
+        outcome: d.ok && d.failed === 0 ? "clean" : "breaks",
+        ref: task.slice(0, 120),
+        durationMs: d.durationMs,
+      });
     }
+  } catch {}
+  if (json) {
+    console.log(JSON.stringify({ ...r, dryRun: d }, null, 2));
+    return;
+  }
+  if (!d.ok) {
+    console.log(`\n  dry-run: did not produce a verdict — ${d.reason}`);
+    if (d.output) console.log(`\n${d.output.replace(/^/gm, "    ")}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`\n  dry-run (sandboxed worktree of HEAD · ${d.runner}):`);
+  console.log(
+    `    pass ${d.passed} · fail ${d.failed} · ${d.durationMs}ms · worktree ${d.worktree}`,
+  );
+  if (d.perFile)
+    for (const [t, s] of Object.entries(d.perFile))
+      console.log(`    ${s === "pass" ? "ok  " : "FAIL"} ${t}`);
+  if (d.failed > 0) {
+    console.log("\n  measured consequence: the selected suite BREAKS at HEAD — output tail:");
+    console.log(`\n${(d.output || "").replace(/^/gm, "    ")}`);
+  } else {
+    console.log("\n  measured consequence: the selected suite is green at HEAD.");
+  }
+  return;
+};
+HANDLERS.lean = async (argv) => {
+  const { leanRepo, renderLean } = await import("./lean.js");
+  const json = argv.includes("--json");
+  const task = argv
+    .slice(1)
+    .filter((a) => a !== "--json")
+    .join(" ");
+  if (!task) {
+    console.error('usage: forge lean "<task>" [--json]   (measures the working diff vs the task)');
+    process.exitCode = 1;
+    return;
+  }
+  const r = leanRepo(process.cwd(), task);
+  console.log(json ? JSON.stringify(r, null, 2) : renderLean(r));
+  return; // advisory — never fails the process
+};
+HANDLERS.scope = async (argv) => {
+  const { decompose } = await import("./scope.js");
+  const json = argv.includes("--json");
+  const files = argv.slice(1).filter((a) => a !== "--json");
+  if (!files.length) {
+    console.error("usage: forge scope <file> [file...] [--json]");
+    process.exitCode = 1;
+    return;
+  }
+  const d = decompose(process.cwd(), files);
+  if (json) {
+    console.log(JSON.stringify(d, null, 2));
+    return;
+  }
+  heading(`${BRAND.brand} scope — task decomposition\n`);
+  if (d.independentGroups > 1) {
     console.log(
-      `  state written: ${r.path} (${r.lines} lines)\n  (re-injected at every session start — the next session resumes instead of re-assuming)`,
+      `  ${d.independentGroups} independent groups → consider a separate session per group:\n`,
     );
-    return;
   }
-  if (cmd === "decide") {
-    const { appendDecision, listDecisions } = await import("./decide.js");
-    const json = argv.includes("--json");
-    const text = argv
-      .slice(1)
-      .filter((a) => a !== "--json")
-      .join(" ");
-    if (!text) {
-      const rows = listDecisions(process.cwd(), { limit: 10 });
-      if (json) return console.log(JSON.stringify(rows, null, 2));
+  d.clusters.forEach((c, i) => {
+    console.log(`  [${i + 1}] ${c.touched.join(", ")}`);
+    if (c.coupled.length) {
+      const shown = c.coupled.slice(0, 8).join(", ");
       console.log(
-        rows.length
-          ? rows.map((d) => `  ${d.id} (${d.date}): ${d.text}`).join("\n")
-          : `  no decisions recorded — ${BRAND.cli} decide "<what was decided — why>"`,
+        `      ! also coupled (you didn't name): ${shown}${c.coupled.length > 8 ? " …" : ""}`,
       );
-      return;
-    }
-    const r = appendDecision(process.cwd(), text);
-    if (json) return console.log(JSON.stringify(r, null, 2));
-    if (!r.ok) {
-      console.error(`${BRAND.cli} decide: ${r.reason}`);
-      process.exitCode = 1;
-      return;
     }
-    console.log(`  recorded ${r.id}: ${r.text}`);
-    return;
-  }
-  if (cmd === "know") {
-    // A7 knowledge-router: total routing (T6) of a fact to its storage home — an unsure
-    // fact still lands (ledger fallback), it is never dropped.
-    const { HOMES, routeFact, storeFact } = await import("./knowledge_router.js");
-    const json = argv.includes("--json");
-    const dry = argv.includes("--dry-run");
-    const text = argv
-      .slice(1)
-      .filter((a) => a !== "--json" && a !== "--dry-run")
-      .join(" ");
-    if (!text) {
-      console.error(`usage: ${BRAND.cli} know "<fact>" [--dry-run] [--json]`);
+  });
+  if (d.independentGroups === 1) console.log("\n  all coupled — keep as one change.");
+  return;
+};
+HANDLERS.uicheck = async (argv) => {
+  const sub = argv[1];
+  if (sub === "visual") {
+    // The Playwright visual loop (spec §5): render in a real browser, fingerprint
+    // the COMPUTED styles, run the same design gate. Playwright is an optional
+    // tier (ADR-0005) — its absence is a note and exit 0, never a failure.
+    const { visualGate } = await import("./uivisual.js");
+    const args = argv.slice(2);
+    const tasteIdx = args.indexOf("--taste");
+    const tasteArg = tasteIdx >= 0 ? (args.splice(tasteIdx, 2)[1] ?? null) : null;
+    const json = args.includes("--json");
+    const remote = args.includes("--remote");
+    const targets = args.filter((a) => !a.startsWith("--"));
+    if (targets.length !== 1 || (tasteIdx >= 0 && !tasteArg)) {
+      console.error(
+        `usage: ${BRAND.cli} uicheck visual <file-or-url> [--taste <name>] [--json] [--remote]`,
+      );
       process.exitCode = 1;
       return;
     }
-    const route = routeFact(text);
-    const r = storeFact(process.cwd(), text, {
-      mode: dry ? "advise" : "auto",
-      route,
+    const r = await visualGate(targets[0], {
+      taste: tasteArg,
+      remote,
+      root: process.cwd(),
     });
-    if (json) return console.log(JSON.stringify({ ...route, ...r, dryRun: dry }, null, 2));
-    heading(`${BRAND.brand} know — knowledge routing (A7)\n`);
-    const why =
-      route.provenance === "fallback"
-        ? "fallback — resembles no exemplar; the ledger absorbs unsure placements"
-        : `confidence ${route.confidence}`;
-    console.log(`  home:     ${route.home} (${why}) → ${HOMES[route.home].where}`);
-    const near = route.neighbors[0];
-    if (near) console.log(`  nearest:  "${near.text}" (${near.sim.toFixed(3)})`);
     if (!r.ok) {
-      console.error(`  ${r.reason}`);
+      const reason = "reason" in r ? r.reason : "visual gate failed";
+      if ("skipped" in r && r.skipped) {
+        // Graceful absence (ADR-0005): a missing optional tier is not a failure.
+        if (json) console.log(JSON.stringify({ skipped: true, reason }, null, 2));
+        else {
+          heading(`${BRAND.brand} uicheck visual — skipped (no browser runtime)\n`);
+          console.log(`  ${reason}`);
+          console.log(
+            "  enable it: npm i -D playwright-core   (or point FORGE_PLAYWRIGHT at an existing install, e.g. FORGE_PLAYWRIGHT=/path/to/node_modules/playwright-core)",
+          );
+        }
+        return; // exit 0 — the static gate still stands
+      }
+      console.error(reason);
       process.exitCode = 1;
       return;
     }
-    if (r.stored) console.log(`  stored:   ${r.ref}`);
-    else if (dry) console.log("  (dry-run — nothing written)");
-    if (r.advice) console.log(`  advice:   ${r.advice}`);
+    if (json) {
+      const { ok: _ok, fail: _fail, ...body } = r;
+      console.log(JSON.stringify(body, null, 2));
+    } else {
+      heading(`${BRAND.brand} uicheck visual — rendered fingerprint + design gate\n`);
+      console.log(`  rendered:      ${r.url} (${r.elements} visible element style(s))`);
+      console.log(`  screenshots:   ${r.screenshots.join(", ")}`);
+      if (r.taste) console.log(`  taste:         ${r.taste} (thresholds from its profile)`);
+      console.log(
+        `  slop distance: ${r.slop}  (need ≥ ${r.tauSlop} — farther from generic is better)`,
+      );
+      console.log(
+        r.hasProjectFingerprint
+          ? `  conformance:   ${r.conform}  (need ≤ ${r.tauConform} — closer to the project system is better)`
+          : `  conformance:   (no project fingerprint claim — slop-only; mint one: \`${BRAND.cli} uicheck fingerprint <ui files> --mint\`)`,
+      );
+      for (const v of r.violations) console.log(`\n  ✗ ${v.detail}\n    fix: ${v.hint}`);
+      console.log("");
+      for (const c of r.checks)
+        console.log(
+          `  ${c.pass ? "✓" : "✗"} ${c.id}: ${c.detail}${c.pass || !c.hint ? "" : `\n    fix: ${c.hint}`}`,
+        );
+      console.log(`\n  ${r.fail ? "✗ FAIL" : "✓ PASS"}`);
+    }
+    if (r.fail) process.exitCode = 1;
     return;
   }
-  if (cmd === "diagnose") {
-    const { diagnose, THRASH_K } = await import("./diagnose.js");
-    const json = argv.includes("--json");
-    const flagVal = (name) => {
-      const i = argv.indexOf(name);
-      return i >= 0 ? argv[i + 1] : undefined;
-    };
-    const args = argv.filter(
-      (a, i) => !a.startsWith("--") && argv[i - 1] !== "--file" && argv[i - 1] !== "--symbol",
-    );
-    const errorText = args.slice(1).join(" ");
-    if (!errorText) {
-      console.error('usage: forge diagnose "<error text>" [--file f] [--symbol s] [--json]');
+  if (sub === "interact") {
+    // The Playwright interaction loop (ROADMAP "Next"): drive the page and check what
+    // it DOES — keyboard reach, a visible focus ring, console cleanliness, reduced-
+    // motion honesty. Advisory by default (the `behavioral` oracle is cross-family-
+    // gated); --enforce or FORGE_ENFORCE=1 turns a fail into a non-zero exit. Playwright
+    // is an optional tier (ADR-0005) — its absence is a note and exit 0, never a failure.
+    const { runInteractions, recordInteraction } = await import("./uiinteract.js");
+    const args = argv.slice(2);
+    const json = args.includes("--json");
+    const remote = args.includes("--remote");
+    const record = args.includes("--record");
+    const enforce = args.includes("--enforce") || process.env.FORGE_ENFORCE === "1";
+    const targets = args.filter((a) => !a.startsWith("--"));
+    if (targets.length !== 1) {
+      console.error(
+        `usage: ${BRAND.cli} uicheck interact <file-or-url> [--record] [--enforce] [--json] [--remote]`,
+      );
       process.exitCode = 1;
       return;
     }
-    const r = diagnose(process.cwd(), {
-      errorText,
-      file: flagVal("--file"),
-      symbol: flagVal("--symbol"),
+    const r = await runInteractions(targets[0], {
+      remote,
+      cwd: process.cwd(),
     });
-    if (json) return console.log(JSON.stringify(r, null, 2));
-    heading(`${BRAND.brand} diagnose — doom-loop check\n`);
-    console.log(
-      `  signature: ${r.signature.slice(0, 12)} · seen ${r.count}× in the recent failure window`,
-    );
-    if (r.thrash) {
-      if (r.claimId)
-        console.log(
-          `  diagnosis claim: ${r.claimId.slice(0, 12)}  (\`forge ledger show ${r.claimId.slice(0, 8)}\`)`,
-        );
-      console.log(`\n  ${r.escalate ?? r.reason}`);
-    } else {
-      console.log(`  below the thrash threshold (${THRASH_K}) — recorded; keep going.`);
-    }
-    return; // advisory — halting the retry loop is the AGENT's move, not an exit code
-  }
-  if (cmd === "imagine") {
-    const { dryRun, imagineTask, renderImagine } = await import("./imagine.js");
-    const json = argv.includes("--json");
-    const doRun = argv.includes("--run");
-    const allowDirty = argv.includes("--allow-dirty");
-    const FLAGS = new Set(["--json", "--run", "--allow-dirty"]);
-    const task = argv
-      .slice(1)
-      .filter((a) => !FLAGS.has(a))
-      .join(" ");
-    if (!task) {
-      console.error('usage: forge imagine "<task>" [--run] [--allow-dirty] [--json]');
-      process.exitCode = 1;
-      return;
-    }
-    const root = process.cwd();
-    const r = imagineTask(root, task);
-    if (!doRun) {
-      console.log(json ? JSON.stringify(r, null, 2) : renderImagine(r));
-      return;
-    }
-    // --run: the static prediction first (always), then the measured half. The sandbox
-    // is a git worktree of HEAD — uncommitted changes are INVISIBLE to it — so a dirty
-    // tree is refused by default rather than silently dry-running the wrong code.
-    if (!json) console.log(renderImagine(r, { footer: false }));
-    if (!allowDirty) {
-      let dirty = "";
-      try {
-        const { execFileSync } = await import("node:child_process");
-        dirty = execFileSync("git", ["status", "--porcelain"], {
-          cwd: root,
-          encoding: "utf8",
-          stdio: ["ignore", "pipe", "ignore"],
-        }).trim();
-      } catch {} // not a repo / no git → dryRun reports its own precondition failure
-      if (dirty) {
-        console.error(
-          "\n  imagine --run refused: the working tree is dirty and the sandbox runs HEAD,\n" +
-            "  so your uncommitted changes would NOT be in the dry-run. Commit or stash them,\n" +
-            "  or pass --allow-dirty to knowingly measure the last commit instead.",
-        );
-        process.exitCode = 1;
-        return;
-      }
-    }
-    const d = dryRun(root, { tests: r.tests });
-    // Metrics are best-effort telemetry (05-cost-model.md) — never let recording
-    // failure break the verdict. Only a run that happened is worth counting.
-    try {
-      if (d.durationMs !== undefined) {
-        const { record } = await import("./metrics.js");
-        record(root, {
-          stage: "imagine",
-          outcome: d.ok && d.failed === 0 ? "clean" : "breaks",
-          ref: task.slice(0, 120),
-          durationMs: d.durationMs,
-        });
+    if (!r.ok) {
+      const reason = "reason" in r ? r.reason : "interaction run failed";
+      if ("skipped" in r && r.skipped) {
+        // Graceful absence (ADR-0005): a missing optional tier is not a failure.
+        if (json) console.log(JSON.stringify({ skipped: true, reason }, null, 2));
+        else {
+          heading(`${BRAND.brand} uicheck interact — skipped (no browser runtime)\n`);
+          console.log(`  ${reason}`);
+          console.log(
+            "  enable it: npm i -D playwright-core   (or point FORGE_PLAYWRIGHT at an existing install)",
+          );
+        }
+        return; // exit 0 — the advisory tier is absent
       }
-    } catch {}
-    if (json) {
-      console.log(JSON.stringify({ ...r, dryRun: d }, null, 2));
-      return;
-    }
-    if (!d.ok) {
-      console.log(`\n  dry-run: did not produce a verdict — ${d.reason}`);
-      if (d.output) console.log(`\n${d.output.replace(/^/gm, "    ")}`);
+      console.error(reason);
       process.exitCode = 1;
       return;
     }
-    console.log(`\n  dry-run (sandboxed worktree of HEAD · ${d.runner}):`);
-    console.log(
-      `    pass ${d.passed} · fail ${d.failed} · ${d.durationMs}ms · worktree ${d.worktree}`,
-    );
-    if (d.perFile)
-      for (const [t, s] of Object.entries(d.perFile))
-        console.log(`    ${s === "pass" ? "ok  " : "FAIL"} ${t}`);
-    if (d.failed > 0) {
-      console.log("\n  measured consequence: the selected suite BREAKS at HEAD — output tail:");
-      console.log(`\n${(d.output || "").replace(/^/gm, "    ")}`);
+    const recorded = record ? recordInteraction(process.cwd(), r.url, r.verdict) : null;
+    if (json) {
+      console.log(JSON.stringify({ url: r.url, ...r.verdict, recorded }, null, 2));
     } else {
-      console.log("\n  measured consequence: the selected suite is green at HEAD.");
+      heading(`${BRAND.brand} uicheck interact — browser interaction checks\n`);
+      console.log(`  driven:        ${r.url} (headless, prefers-reduced-motion)`);
+      for (const c of r.verdict.checks) console.log(`  ${c.ok ? "✓" : "✗"} ${c.id}: ${c.detail}`);
+      console.log(`\n  ${r.verdict.pass ? "✓ PASS" : "✗ FAIL"}${enforce ? "" : "  (advisory)"}`);
+      if (recorded)
+        console.log(
+          recorded.recorded
+            ? `  recorded as behavioral evidence on design claim ${recorded.claimId.slice(0, 12)}`
+            : `  not recorded: ${recorded.reason}`,
+        );
     }
+    if (!r.verdict.pass && enforce) process.exitCode = 1;
     return;
   }
-  if (cmd === "lean") {
-    const { leanRepo, renderLean } = await import("./lean.js");
-    const json = argv.includes("--json");
-    const task = argv
-      .slice(1)
-      .filter((a) => a !== "--json")
-      .join(" ");
-    if (!task) {
+  if (sub === "fingerprint" || sub === "design") {
+    const ui = await import("./uifingerprint.js");
+    // `--taste <name>` (design only) takes a VALUE — splice it out before the
+    // file filter so the profile name is never mistaken for a file.
+    const args = argv.slice(2);
+    const tasteIdx = args.indexOf("--taste");
+    const tasteArg = tasteIdx >= 0 ? (args.splice(tasteIdx, 2)[1] ?? null) : null;
+    const json = args.includes("--json");
+    const files = args.filter((a) => !a.startsWith("--"));
+    if (!files.length || (tasteIdx >= 0 && !tasteArg)) {
       console.error(
-        'usage: forge lean "<task>" [--json]   (measures the working diff vs the task)',
+        `usage: ${BRAND.cli} uicheck ${sub} <file...> [--json]${sub === "fingerprint" ? " [--mint]" : " [--taste <name>]"}`,
       );
       process.exitCode = 1;
       return;
     }
-    const r = leanRepo(process.cwd(), task);
-    console.log(json ? JSON.stringify(r, null, 2) : renderLean(r));
-    return; // advisory — never fails the process
-  }
-  if (cmd === "scope") {
-    const { decompose } = await import("./scope.js");
-    const json = argv.includes("--json");
-    const files = argv.slice(1).filter((a) => a !== "--json");
-    if (!files.length) {
-      console.error("usage: forge scope <file> [file...] [--json]");
-      process.exitCode = 1;
-      return;
-    }
-    const d = decompose(process.cwd(), files);
-    if (json) {
-      console.log(JSON.stringify(d, null, 2));
-      return;
-    }
-    heading(`${BRAND.brand} scope — task decomposition\n`);
-    if (d.independentGroups > 1) {
-      console.log(
-        `  ${d.independentGroups} independent groups → consider a separate session per group:\n`,
-      );
-    }
-    d.clusters.forEach((c, i) => {
-      console.log(`  [${i + 1}] ${c.touched.join(", ")}`);
-      if (c.coupled.length) {
-        const shown = c.coupled.slice(0, 8).join(", ");
-        console.log(
-          `      ! also coupled (you didn't name): ${shown}${c.coupled.length > 8 ? " …" : ""}`,
-        );
-      }
-    });
-    if (d.independentGroups === 1) console.log("\n  all coupled — keep as one change.");
-    return;
-  }
-  if (cmd === "uicheck") {
-    const sub = argv[1];
-    if (sub === "visual") {
-      // The Playwright visual loop (spec §5): render in a real browser, fingerprint
-      // the COMPUTED styles, run the same design gate. Playwright is an optional
-      // tier (ADR-0005) — its absence is a note and exit 0, never a failure.
-      const { visualGate } = await import("./uivisual.js");
-      const args = argv.slice(2);
-      const tasteIdx = args.indexOf("--taste");
-      const tasteArg = tasteIdx >= 0 ? (args.splice(tasteIdx, 2)[1] ?? null) : null;
-      const json = args.includes("--json");
-      const remote = args.includes("--remote");
-      const targets = args.filter((a) => !a.startsWith("--"));
-      if (targets.length !== 1 || (tasteIdx >= 0 && !tasteArg)) {
-        console.error(
-          `usage: ${BRAND.cli} uicheck visual <file-or-url> [--taste <name>] [--json] [--remote]`,
-        );
-        process.exitCode = 1;
-        return;
-      }
-      const r = await visualGate(targets[0], {
-        taste: tasteArg,
-        remote,
-        root: process.cwd(),
-      });
-      if (!r.ok) {
-        const reason = "reason" in r ? r.reason : "visual gate failed";
-        if ("skipped" in r && r.skipped) {
-          // Graceful absence (ADR-0005): a missing optional tier is not a failure.
-          if (json) console.log(JSON.stringify({ skipped: true, reason }, null, 2));
-          else {
-            heading(`${BRAND.brand} uicheck visual — skipped (no browser runtime)\n`);
-            console.log(`  ${reason}`);
-            console.log(
-              "  enable it: npm i -D playwright-core   (or point FORGE_PLAYWRIGHT at an existing install, e.g. FORGE_PLAYWRIGHT=/path/to/node_modules/playwright-core)",
-            );
-          }
-          return; // exit 0 — the static gate still stands
-        }
-        console.error(reason);
-        process.exitCode = 1;
-        return;
+    const fp = ui.fingerprintFiles(process.cwd(), files);
+    if (sub === "fingerprint") {
+      let minted = null;
+      if (argv.includes("--mint")) {
+        const { epochDay } = await import("./util.js");
+        minted = ui.mintProjectFingerprint(process.cwd(), files, {
+          t: epochDay(),
+        });
       }
       if (json) {
-        const { ok: _ok, fail: _fail, ...body } = r;
-        console.log(JSON.stringify(body, null, 2));
+        console.log(JSON.stringify(minted ? { fingerprint: fp, minted } : fp, null, 2));
       } else {
-        heading(`${BRAND.brand} uicheck visual — rendered fingerprint + design gate\n`);
-        console.log(`  rendered:      ${r.url} (${r.elements} visible element style(s))`);
-        console.log(`  screenshots:   ${r.screenshots.join(", ")}`);
-        if (r.taste) console.log(`  taste:         ${r.taste} (thresholds from its profile)`);
+        heading(`${BRAND.brand} uicheck fingerprint — the design feature vector\n`);
         console.log(
-          `  slop distance: ${r.slop}  (need ≥ ${r.tauSlop} — farther from generic is better)`,
+          `  palette:  ${fp.paletteSize} color(s), hue bins [${fp.hueBuckets.join(" ")}]`,
         );
         console.log(
-          r.hasProjectFingerprint
-            ? `  conformance:   ${r.conform}  (need ≤ ${r.tauConform} — closer to the project system is better)`
-            : `  conformance:   (no project fingerprint claim — slop-only; mint one: \`${BRAND.cli} uicheck fingerprint <ui files> --mint\`)`,
+          `  spacing:  ${fp.spacing.join(", ") || "(none)"} px — base ${fp.spacingBase ?? "(none)"}, ${Math.round(fp.spacingOnScale * 100)}% on-scale`,
         );
-        for (const v of r.violations) console.log(`\n  ✗ ${v.detail}\n    fix: ${v.hint}`);
-        console.log("");
-        for (const c of r.checks)
-          console.log(
-            `  ${c.pass ? "✓" : "✗"} ${c.id}: ${c.detail}${c.pass || !c.hint ? "" : `\n    fix: ${c.hint}`}`,
-          );
-        console.log(`\n  ${r.fail ? "✗ FAIL" : "✓ PASS"}`);
-      }
-      if (r.fail) process.exitCode = 1;
-      return;
-    }
-    if (sub === "interact") {
-      // The Playwright interaction loop (ROADMAP "Next"): drive the page and check what
-      // it DOES — keyboard reach, a visible focus ring, console cleanliness, reduced-
-      // motion honesty. Advisory by default (the `behavioral` oracle is cross-family-
-      // gated); --enforce or FORGE_ENFORCE=1 turns a fail into a non-zero exit. Playwright
-      // is an optional tier (ADR-0005) — its absence is a note and exit 0, never a failure.
-      const { runInteractions, recordInteraction } = await import("./uiinteract.js");
-      const args = argv.slice(2);
-      const json = args.includes("--json");
-      const remote = args.includes("--remote");
-      const record = args.includes("--record");
-      const enforce = args.includes("--enforce") || process.env.FORGE_ENFORCE === "1";
-      const targets = args.filter((a) => !a.startsWith("--"));
-      if (targets.length !== 1) {
-        console.error(
-          `usage: ${BRAND.cli} uicheck interact <file-or-url> [--record] [--enforce] [--json] [--remote]`,
+        console.log(`  type:     ${fp.fontFamilies.join(", ") || "(none)"}`);
+        console.log(
+          `  shape:    radii ${fp.radii.join(", ") || "(none)"} (${fp.radiusLevels} level(s)) · ${fp.shadowLevels} shadow level(s)`,
         );
-        process.exitCode = 1;
-        return;
-      }
-      const r = await runInteractions(targets[0], {
-        remote,
-        cwd: process.cwd(),
-      });
-      if (!r.ok) {
-        const reason = "reason" in r ? r.reason : "interaction run failed";
-        if ("skipped" in r && r.skipped) {
-          // Graceful absence (ADR-0005): a missing optional tier is not a failure.
-          if (json) console.log(JSON.stringify({ skipped: true, reason }, null, 2));
-          else {
-            heading(`${BRAND.brand} uicheck interact — skipped (no browser runtime)\n`);
-            console.log(`  ${reason}`);
+        if (minted) {
+          if (minted.ok)
             console.log(
-              "  enable it: npm i -D playwright-core   (or point FORGE_PLAYWRIGHT at an existing install)",
+              `\n  minted fingerprint claim ${minted.id.slice(0, 12)}${minted.existed ? " (already in ledger)" : ""} — the gate's "home"`,
             );
-          }
-          return; // exit 0 — the advisory tier is absent
+          else console.error(`\n  mint failed: ${"reason" in minted ? minted.reason : ""}`);
         }
-        console.error(reason);
-        process.exitCode = 1;
-        return;
-      }
-      const recorded = record ? recordInteraction(process.cwd(), r.url, r.verdict) : null;
-      if (json) {
-        console.log(JSON.stringify({ url: r.url, ...r.verdict, recorded }, null, 2));
-      } else {
-        heading(`${BRAND.brand} uicheck interact — browser interaction checks\n`);
-        console.log(`  driven:        ${r.url} (headless, prefers-reduced-motion)`);
-        for (const c of r.verdict.checks) console.log(`  ${c.ok ? "✓" : "✗"} ${c.id}: ${c.detail}`);
-        console.log(`\n  ${r.verdict.pass ? "✓ PASS" : "✗ FAIL"}${enforce ? "" : "  (advisory)"}`);
-        if (recorded)
-          console.log(
-            recorded.recorded
-              ? `  recorded as behavioral evidence on design claim ${recorded.claimId.slice(0, 12)}`
-              : `  not recorded: ${recorded.reason}`,
-          );
       }
-      if (!r.verdict.pass && enforce) process.exitCode = 1;
+      if (minted && !minted.ok) process.exitCode = 1;
       return;
     }
-    if (sub === "fingerprint" || sub === "design") {
-      const ui = await import("./uifingerprint.js");
-      // `--taste <name>` (design only) takes a VALUE — splice it out before the
-      // file filter so the profile name is never mistaken for a file.
-      const args = argv.slice(2);
-      const tasteIdx = args.indexOf("--taste");
-      const tasteArg = tasteIdx >= 0 ? (args.splice(tasteIdx, 2)[1] ?? null) : null;
-      const json = args.includes("--json");
-      const files = args.filter((a) => !a.startsWith("--"));
-      if (!files.length || (tasteIdx >= 0 && !tasteArg)) {
-        console.error(
-          `usage: ${BRAND.cli} uicheck ${sub} <file...> [--json]${sub === "fingerprint" ? " [--mint]" : " [--taste <name>]"}`,
-        );
-        process.exitCode = 1;
-        return;
-      }
-      const fp = ui.fingerprintFiles(process.cwd(), files);
-      if (sub === "fingerprint") {
-        let minted = null;
-        if (argv.includes("--mint")) {
-          const { epochDay } = await import("./util.js");
-          minted = ui.mintProjectFingerprint(process.cwd(), files, {
-            t: epochDay(),
-          });
-        }
-        if (json) {
-          console.log(JSON.stringify(minted ? { fingerprint: fp, minted } : fp, null, 2));
-        } else {
-          heading(`${BRAND.brand} uicheck fingerprint — the design feature vector\n`);
-          console.log(
-            `  palette:  ${fp.paletteSize} color(s), hue bins [${fp.hueBuckets.join(" ")}]`,
-          );
-          console.log(
-            `  spacing:  ${fp.spacing.join(", ") || "(none)"} px — base ${fp.spacingBase ?? "(none)"}, ${Math.round(fp.spacingOnScale * 100)}% on-scale`,
-          );
-          console.log(`  type:     ${fp.fontFamilies.join(", ") || "(none)"}`);
-          console.log(
-            `  shape:    radii ${fp.radii.join(", ") || "(none)"} (${fp.radiusLevels} level(s)) · ${fp.shadowLevels} shadow level(s)`,
-          );
-          if (minted) {
-            if (minted.ok)
-              console.log(
-                `\n  minted fingerprint claim ${minted.id.slice(0, 12)}${minted.existed ? " (already in ledger)" : ""} — the gate's "home"`,
-              );
-            else console.error(`\n  mint failed: ${"reason" in minted ? minted.reason : ""}`);
-          }
-        }
-        if (minted && !minted.ok) process.exitCode = 1;
-        return;
-      }
-      // design — the two-sided gate: fail when too close to generic OR (when the
-      // project has minted its fingerprint) too far from the project's own system.
-      // A taste profile (explicit --taste, else the style pinned by a
-      // `forge taste`-managed DESIGN.md) overrides thresholds + adds its checks.
-      const tasteName = tasteArg ?? ui.activeTasteStyle(process.cwd());
-      const profile = tasteName ? ui.loadTasteProfile(tasteName) : null;
-      if (tasteArg && !profile) {
-        // Explicit --taste must exist; an auto-picked style without a JSON sibling
-        // silently falls back to defaults (custom prose styles stay legal).
-        console.error(
-          `unknown taste profile "${tasteArg}" — run \`${BRAND.cli} taste\` to list styles`,
-        );
-        process.exitCode = 1;
-        return;
-      }
-      const projectFp = ui.loadProjectFingerprint(process.cwd());
-      const tauSlop = profile?.gate?.tau_slop ?? ui.UI_GATE_DEFAULTS.tauSlop;
-      const tauConform = profile?.gate?.tau_conform ?? ui.UI_GATE_DEFAULTS.tauConform;
-      const gate = ui.uiGate(fp, { projectFp, tauSlop, tauConform });
-      const checks = [...ui.scaleChecks(fp), ...(profile ? ui.profileChecks(fp, profile) : [])];
-      const fail = !gate.pass || checks.some((c) => !c.pass);
-      if (json) {
-        console.log(
-          JSON.stringify(
-            {
-              ...gate,
-              checks,
-              hasProjectFingerprint: !!projectFp,
-              taste: profile ? tasteName : null,
-              tauSlop,
-              tauConform,
-            },
-            null,
-            2,
-          ),
-        );
-      } else {
-        heading(`${BRAND.brand} uicheck design — slop distance + project conformance\n`);
-        if (profile) console.log(`  taste:         ${tasteName} (thresholds from its profile)`);
-        console.log(
-          `  slop distance: ${gate.slop}  (need ≥ ${tauSlop} — farther from generic is better)`,
-        );
-        console.log(
-          projectFp
-            ? `  conformance:   ${gate.conform}  (need ≤ ${tauConform} — closer to the project system is better)`
-            : `  conformance:   (no project fingerprint claim — slop-only; mint one: \`${BRAND.cli} uicheck fingerprint <ui files> --mint\`)`,
-        );
-        for (const v of gate.violations) console.log(`\n  ✗ ${v.detail}\n    fix: ${v.hint}`);
-        console.log("");
-        for (const c of checks)
-          console.log(
-            `  ${c.pass ? "✓" : "✗"} ${c.id}: ${c.detail}${c.pass || !c.hint ? "" : `\n    fix: ${c.hint}`}`,
-          );
-        console.log(`\n  ${fail ? "✗ FAIL" : "✓ PASS"}`);
-      }
-      if (fail) process.exitCode = 1;
+    // design — the two-sided gate: fail when too close to generic OR (when the
+    // project has minted its fingerprint) too far from the project's own system.
+    // A taste profile (explicit --taste, else the style pinned by a
+    // `forge taste`-managed DESIGN.md) overrides thresholds + adds its checks.
+    const tasteName = tasteArg ?? ui.activeTasteStyle(process.cwd());
+    const profile = tasteName ? ui.loadTasteProfile(tasteName) : null;
+    if (tasteArg && !profile) {
+      // Explicit --taste must exist; an auto-picked style without a JSON sibling
+      // silently falls back to defaults (custom prose styles stay legal).
+      console.error(
+        `unknown taste profile "${tasteArg}" — run \`${BRAND.cli} taste\` to list styles`,
+      );
+      process.exitCode = 1;
       return;
     }
-    const { contrastRatio, wcagLevel, ASSERTABLE_CHECKS, ADVISORY_ONLY } = await import(
-      "./uicheck.js"
-    );
-    // `uicheck contrast <fg> <bg>` is the named form; bare `uicheck <fg> <bg>` stays
-    // supported (it predates the subcommands and hooks already call it).
-    const [fg, bg] = sub === "contrast" ? [argv[2], argv[3]] : [argv[1], argv[2]];
-    heading(`${BRAND.brand} uicheck — deterministic UI review\n`);
-    if (fg && bg) {
-      try {
-        const g = wcagLevel(contrastRatio(fg, bg));
+    const projectFp = ui.loadProjectFingerprint(process.cwd());
+    const tauSlop = profile?.gate?.tau_slop ?? ui.UI_GATE_DEFAULTS.tauSlop;
+    const tauConform = profile?.gate?.tau_conform ?? ui.UI_GATE_DEFAULTS.tauConform;
+    const gate = ui.uiGate(fp, { projectFp, tauSlop, tauConform });
+    const checks = [...ui.scaleChecks(fp), ...(profile ? ui.profileChecks(fp, profile) : [])];
+    const fail = !gate.pass || checks.some((c) => !c.pass);
+    if (json) {
+      console.log(
+        JSON.stringify(
+          {
+            ...gate,
+            checks,
+            hasProjectFingerprint: !!projectFp,
+            taste: profile ? tasteName : null,
+            tauSlop,
+            tauConform,
+          },
+          null,
+          2,
+        ),
+      );
+    } else {
+      heading(`${BRAND.brand} uicheck design — slop distance + project conformance\n`);
+      if (profile) console.log(`  taste:         ${tasteName} (thresholds from its profile)`);
+      console.log(
+        `  slop distance: ${gate.slop}  (need ≥ ${tauSlop} — farther from generic is better)`,
+      );
+      console.log(
+        projectFp
+          ? `  conformance:   ${gate.conform}  (need ≤ ${tauConform} — closer to the project system is better)`
+          : `  conformance:   (no project fingerprint claim — slop-only; mint one: \`${BRAND.cli} uicheck fingerprint <ui files> --mint\`)`,
+      );
+      for (const v of gate.violations) console.log(`\n  ✗ ${v.detail}\n    fix: ${v.hint}`);
+      console.log("");
+      for (const c of checks)
         console.log(
-          `  contrast ${fg} on ${bg}: ${g.ratio}:1  →  ${g.level}${g.passesAA ? " (passes AA)" : " (FAILS AA)"}`,
+          `  ${c.pass ? "✓" : "✗"} ${c.id}: ${c.detail}${c.pass || !c.hint ? "" : `\n    fix: ${c.hint}`}`,
         );
-      } catch (e) {
-        console.error(`  ${e.message}`);
-        process.exitCode = 1;
-        return;
-      }
-    }
-    console.log(`\n  ASSERT (deterministic): ${ASSERTABLE_CHECKS.map((c) => c.id).join(", ")}`);
-    console.log(`  ADVISE (subjective, human-only): ${ADVISORY_ONLY.slice(0, 4).join(", ")} …`);
-    return;
-  }
-  if (cmd === "report") {
-    // Static twin of `dash`: emit ONE self-contained HTML file (no server, opens
-    // offline) instead of serving a live localhost lens. `--out <path>` overrides the
-    // default `.forge/report.html`.
-    const { renderReport, writeReport } = await import("./report.js");
-    const oi = argv.indexOf("--out");
-    heading(`${BRAND.brand} report — static snapshot of .forge/\n`);
-    if (oi >= 0) {
-      const out = argv[oi + 1];
-      if (!out) {
-        console.error("usage: forge report [--out <path>]");
-        process.exitCode = 1;
-        return;
-      }
-      const { writeFileSync } = await import("node:fs");
-      writeFileSync(out, renderReport(process.cwd()));
-      console.log(`  wrote ${out}`);
-      return;
+      console.log(`\n  ${fail ? "✗ FAIL" : "✓ PASS"}`);
     }
-    const path = writeReport(process.cwd());
-    console.log(`  wrote ${path}`);
-    console.log("  open it in a browser — fully offline, no server needed.");
+    if (fail) process.exitCode = 1;
     return;
   }
-  if (cmd === "dash") {
-    const { serve } = await import("./dash.js");
-    const i = argv.indexOf("--port");
-    const port = i >= 0 ? Number(argv[i + 1]) : 4242;
-    if (!Number.isInteger(port) || port < 0 || port > 65535) {
-      console.error("usage: forge dash [--port N]");
-      process.exitCode = 1;
-      return;
-    }
-    const server = serve(process.cwd(), { port });
-    server.on("listening", () => {
-      const addr = /** @type {import("node:net").AddressInfo} */ (server.address());
-      heading(`${BRAND.brand} dash — read-only lens on .forge/\n`);
-      console.log(`  http://127.0.0.1:${addr.port}  (localhost-only · Ctrl-C to stop)`);
-    });
-    server.on("error", (err) => {
-      console.error(`  ${err.message}`);
-      process.exitCode = 1;
-    });
-    return; // the process stays alive serving — that's the command
-  }
-  if (cmd === "tools") {
-    const { resolvePrimaryTool, applyPrimaryTool, clearRepoConfig, KNOWN_TOOLS } = await import(
-      "./repo_config.js"
-    );
-    const { removeGitignoreBlock, readGitignoreBlock } = await import("./gitignore.js");
-    const root = process.cwd();
-    const json = argv.includes("--json");
-
-    if (argv.includes("--reset")) {
-      const cleared = clearRepoConfig(root);
-      const gi = removeGitignoreBlock(root);
-      if (json)
-        return console.log(
-          JSON.stringify({ reset: true, config: cleared.cleared, gitignore: gi.action }, null, 2),
-        );
-      heading(`${BRAND.brand} tools — reset\n`);
+  const { contrastRatio, wcagLevel, ASSERTABLE_CHECKS, ADVISORY_ONLY } = await import(
+    "./uicheck.js"
+  );
+  // `uicheck contrast <fg> <bg>` is the named form; bare `uicheck <fg> <bg>` stays
+  // supported (it predates the subcommands and hooks already call it).
+  const [fg, bg] = sub === "contrast" ? [argv[2], argv[3]] : [argv[1], argv[2]];
+  heading(`${BRAND.brand} uicheck — deterministic UI review\n`);
+  if (fg && bg) {
+    try {
+      const g = wcagLevel(contrastRatio(fg, bg));
       console.log(
-        `  primary-tool config ${cleared.cleared ? "cleared" : "was unset"} · .gitignore block ${gi.action}`,
+        `  contrast ${fg} on ${bg}: ${g.ratio}:1  →  ${g.level}${g.passesAA ? " (passes AA)" : " (FAILS AA)"}`,
       );
+    } catch (e) {
+      console.error(`  ${e.message}`);
+      process.exitCode = 1;
       return;
     }
-
-    const name = argv.slice(1).find((a) => !a.startsWith("--"));
-    if (name) {
-      if (!KNOWN_TOOLS.includes(name)) {
-        console.error(`Unknown tool: ${name}\nKnown tools: ${KNOWN_TOOLS.join(", ")}`);
-        process.exitCode = 1;
-        return;
-      }
-      // Inject the sync runner from here (the orchestration layer) so repo_config —
-      // a config-leaf module — no longer reaches back into the sync compiler.
-      const { sync } = await import("./sync.js");
-      const r = await applyPrimaryTool(root, name, {
-        syncFn: (r2) => sync({ targetRoot: r2 }),
-      });
-      if (json) return console.log(JSON.stringify(r, null, 2));
-      heading(`${BRAND.brand} tools — primary set\n`);
-      console.log(`  primary tool   ${paint(r.primaryTool, "ok")}`);
-      console.log(
-        `  gitignored     ${r.targets.length ? r.targets.join(", ") : "none"}  (block ${r.gitignore})`,
-      );
-      console.log(`\n  ${BRAND.cli} tools --reset  to undo`);
+  }
+  console.log(`\n  ASSERT (deterministic): ${ASSERTABLE_CHECKS.map((c) => c.id).join(", ")}`);
+  console.log(`  ADVISE (subjective, human-only): ${ADVISORY_ONLY.slice(0, 4).join(", ")} …`);
+  return;
+};
+HANDLERS.report = async (argv) => {
+  // Static twin of `dash`: emit ONE self-contained HTML file (no server, opens
+  // offline) instead of serving a live localhost lens. `--out <path>` overrides the
+  // default `.forge/report.html`.
+  const { renderReport, writeReport } = await import("./report.js");
+  const oi = argv.indexOf("--out");
+  heading(`${BRAND.brand} report — static snapshot of .forge/\n`);
+  if (oi >= 0) {
+    const out = argv[oi + 1];
+    if (!out) {
+      console.error("usage: forge report [--out <path>]");
+      process.exitCode = 1;
       return;
     }
+    const { writeFileSync } = await import("node:fs");
+    writeFileSync(out, renderReport(process.cwd()));
+    console.log(`  wrote ${out}`);
+    return;
+  }
+  const path = writeReport(process.cwd());
+  console.log(`  wrote ${path}`);
+  console.log("  open it in a browser — fully offline, no server needed.");
+  return;
+};
+HANDLERS.dash = async (argv) => {
+  const { serve } = await import("./dash.js");
+  const i = argv.indexOf("--port");
+  const port = i >= 0 ? Number(argv[i + 1]) : 4242;
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    console.error("usage: forge dash [--port N]");
+    process.exitCode = 1;
+    return;
+  }
+  const server = serve(process.cwd(), { port });
+  server.on("listening", () => {
+    const addr = /** @type {import("node:net").AddressInfo} */ (server.address());
+    heading(`${BRAND.brand} dash — read-only lens on .forge/\n`);
+    console.log(`  http://127.0.0.1:${addr.port}  (localhost-only · Ctrl-C to stop)`);
+  });
+  server.on("error", (err) => {
+    console.error(`  ${err.message}`);
+    process.exitCode = 1;
+  });
+  return; // the process stays alive serving — that's the command
+};
+HANDLERS.tools = async (argv) => {
+  const { resolvePrimaryTool, applyPrimaryTool, clearRepoConfig, KNOWN_TOOLS } = await import(
+    "./repo_config.js"
+  );
+  const { removeGitignoreBlock, readGitignoreBlock } = await import("./gitignore.js");
+  const root = process.cwd();
+  const json = argv.includes("--json");
 
-    const { tool, source } = resolvePrimaryTool(root);
-    const ignored = readGitignoreBlock(root);
+  if (argv.includes("--reset")) {
+    const cleared = clearRepoConfig(root);
+    const gi = removeGitignoreBlock(root);
     if (json)
       return console.log(
-        JSON.stringify({ primaryTool: tool, source, gitignored: ignored }, null, 2),
+        JSON.stringify({ reset: true, config: cleared.cleared, gitignore: gi.action }, null, 2),
       );
-    const origin =
-      source === "config"
-        ? "from config"
-        : source === "auto-detect"
-          ? "auto-detected"
-          : "unset — emitting all tools";
-    heading(`${BRAND.brand} tools — agent-tool config\n`);
-    console.log(`  primary tool   ${tool ? paint(tool, "ok") : "none"} (${origin})`);
-    console.log(`  gitignored     ${ignored.length ? ignored.join(", ") : "none"}`);
-    console.log(`\n  Set primary:   ${BRAND.cli} tools <name>   (${KNOWN_TOOLS.join(" | ")})`);
-    console.log(`  Clear:         ${BRAND.cli} tools --reset`);
+    heading(`${BRAND.brand} tools — reset\n`);
+    console.log(
+      `  primary-tool config ${cleared.cleared ? "cleared" : "was unset"} · .gitignore block ${gi.action}`,
+    );
     return;
   }
-  if (!(cmd in COMMANDS)) {
-    const near = suggest(cmd, Object.keys(COMMANDS));
-    console.error(
-      `Unknown command: ${cmd}${near ? ` — did you mean \`${BRAND.cli} ${near}\`?` : ""}\n` +
-        `Run \`${BRAND.cli} --help\` to see commands.`,
+
+  const name = argv.slice(1).find((a) => !a.startsWith("--"));
+  if (name) {
+    if (!KNOWN_TOOLS.includes(name)) {
+      console.error(`Unknown tool: ${name}\nKnown tools: ${KNOWN_TOOLS.join(", ")}`);
+      process.exitCode = 1;
+      return;
+    }
+    // Inject the sync runner from here (the orchestration layer) so repo_config —
+    // a config-leaf module — no longer reaches back into the sync compiler.
+    const { sync } = await import("./sync.js");
+    const r = await applyPrimaryTool(root, name, {
+      syncFn: (r2) => sync({ targetRoot: r2 }),
+    });
+    if (json) return console.log(JSON.stringify(r, null, 2));
+    heading(`${BRAND.brand} tools — primary set\n`);
+    console.log(`  primary tool   ${paint(r.primaryTool, "ok")}`);
+    console.log(
+      `  gitignored     ${r.targets.length ? r.targets.join(", ") : "none"}  (block ${r.gitignore})`,
     );
-    process.exitCode = 1;
+    console.log(`\n  ${BRAND.cli} tools --reset  to undo`);
     return;
   }
-  // A command is registered in COMMANDS but has no handler wired yet. Exit non-zero
-  // so scripts (and CI) treat "recognized but unimplemented" as a failure, not success.
-  console.error(`${BRAND.cli} ${cmd}: not wired yet — coming in a later build phase.`);
-  process.exitCode = 1;
-}
+
+  const { tool, source } = resolvePrimaryTool(root);
+  const ignored = readGitignoreBlock(root);
+  if (json)
+    return console.log(JSON.stringify({ primaryTool: tool, source, gitignored: ignored }, null, 2));
+  const origin =
+    source === "config"
+      ? "from config"
+      : source === "auto-detect"
+        ? "auto-detected"
+        : "unset — emitting all tools";
+  heading(`${BRAND.brand} tools — agent-tool config\n`);
+  console.log(`  primary tool   ${tool ? paint(tool, "ok") : "none"} (${origin})`);
+  console.log(`  gitignored     ${ignored.length ? ignored.join(", ") : "none"}`);
+  console.log(`\n  Set primary:   ${BRAND.cli} tools <name>   (${KNOWN_TOOLS.join(" | ")})`);
+  console.log(`  Clear:         ${BRAND.cli} tools --reset`);
+  return;
+};
 
 // Auto-run only as the CLI entry (npm/global bin, install.sh symlink, `node src/cli.js`).
 // realpathSync resolves the bin symlink so the global `forge` still runs; importing the