@mutmutco/cli 3.40.0 → 3.42.0

package/dist/main.cjs

@@ -3410,8 +3410,8 @@ var program = new Command();
 
 // src/index.ts
 var import_promises7 = require("node:fs/promises");
-var import_node_fs28 = require("node:fs");
-var import_node_child_process12 = require("node:child_process");
+var import_node_fs29 = require("node:fs");
+var import_node_child_process13 = require("node:child_process");
 
 // src/cli-shared.ts
 var import_node_child_process3 = require("node:child_process");
@@ -8949,7 +8949,7 @@ function commandLadderHint() {
 }
 
 // src/index.ts
-var import_node_path25 = require("node:path");
+var import_node_path26 = require("node:path");
 
 // src/merge-ci-policy.ts
 function resolveMergeCiPolicy(input) {
@@ -15375,6 +15375,213 @@ function createDocsIndexDeps(repoRoot2) {
   };
 }
 
+// src/doc-refs-core.ts
+var import_node_child_process9 = require("node:child_process");
+var import_node_fs18 = require("node:fs");
+var import_node_path16 = require("node:path");
+var PIN_RE = /<!--\s*pinned by\s+([^:]+?)\s*:\s*"([^"]+)"[^"]*-->/;
+var PIN_MENTION_RE = /<!--\s*pinned by\b/;
+var REF_RE = /`([A-Za-z0-9_./-]+\.[A-Za-z0-9]+)(?::\d+)?`/g;
+var LINK_RE = /\]\(([^)#\s]+?\.md)(?:#[^)]*)?\)/g;
+var CMD_RE = /`mmi-cli ((?:[a-z][a-z-]*)(?: [a-z][a-z-]*){0,3})/g;
+var RETIRED_RE = /\b(retired|historical|removed|deleted|gone|no longer|superseded|legacy)\b/i;
+var ROOT_DOCS = ["README.md", "architecture.md"];
+var SKIP_WALK = ["docs/Archive/", "docs/incidents/"];
+var PINNED_DOCS = ["docs/Reference/runtime-contracts.md"];
+function stripFences(markdown) {
+  let inFence = false;
+  return markdown.split(/\r?\n/).map((line) => {
+    if (/^\s*```/.test(line)) {
+      inFence = !inFence;
+      return "";
+    }
+    return inFence ? "" : line;
+  });
+}
+function isRetiredLine(text) {
+  return RETIRED_RE.test(text);
+}
+function extractPins(markdown) {
+  const pins = [];
+  markdown.split(/\r?\n/).forEach((text, index) => {
+    const match = PIN_RE.exec(text);
+    if (match) {
+      pins.push({ file: match[1].trim(), phrase: match[2], line: index + 1 });
+    } else if (PIN_MENTION_RE.test(text.replace(/`[^`]*`/g, ""))) {
+      pins.push({ malformed: true, line: index + 1, text: text.trim() });
+    }
+  });
+  return pins;
+}
+function checkPins(root, readFile6) {
+  const findings = [];
+  for (const doc of PINNED_DOCS) {
+    const markdown = readFile6((0, import_node_path16.join)(root, doc));
+    if (markdown == null) {
+      findings.push({ kind: "missing-doc", doc, line: 0, detail: doc });
+      continue;
+    }
+    for (const pin of extractPins(markdown)) {
+      if ("malformed" in pin) {
+        findings.push({ kind: "malformed-pin", doc, line: pin.line, detail: pin.text });
+        continue;
+      }
+      const source = readFile6((0, import_node_path16.join)(root, pin.file));
+      if (source == null) {
+        findings.push({ kind: "missing-test", doc, line: pin.line, detail: pin.file });
+        continue;
+      }
+      if (!source.includes(pin.phrase)) {
+        findings.push({ kind: "unasserted-phrase", doc, line: pin.line, detail: pin.phrase });
+      }
+    }
+  }
+  return { ok: findings.length === 0, findings };
+}
+function isDomainLike(ref) {
+  const first = ref.split("/")[0];
+  return first.includes(".") && !first.startsWith(".");
+}
+function extractRefs(markdown) {
+  const lines = stripFences(markdown);
+  const refs = [];
+  lines.forEach((text, index) => {
+    if (isRetiredLine(text)) return;
+    for (const match of text.matchAll(REF_RE)) {
+      const ref = match[1];
+      if (!ref.includes("/")) continue;
+      if (ref.startsWith("/") || ref.startsWith(".git/")) continue;
+      if (isDomainLike(ref)) continue;
+      refs.push({ ref, line: index + 1 });
+    }
+  });
+  return refs;
+}
+function extractLinks(markdown) {
+  const lines = stripFences(markdown);
+  const links = [];
+  lines.forEach((text, index) => {
+    if (isRetiredLine(text)) return;
+    for (const match of text.matchAll(LINK_RE)) {
+      const target = match[1];
+      if (/^[a-z]+:/i.test(target)) continue;
+      links.push({ target, line: index + 1 });
+    }
+  });
+  return links;
+}
+function extractCommands(markdown) {
+  const lines = stripFences(markdown);
+  const commands = [];
+  lines.forEach((text, index) => {
+    if (isRetiredLine(text)) return;
+    for (const match of text.matchAll(CMD_RE)) {
+      commands.push({ command: match[1], line: index + 1 });
+    }
+  });
+  return commands;
+}
+function checkRefs(root, deps, docs2) {
+  const { exists, isIgnored = () => /* @__PURE__ */ new Set() } = deps;
+  const candidates = [];
+  for (const [doc, markdown] of Object.entries(docs2)) {
+    for (const { ref, line } of extractRefs(markdown)) {
+      const first = ref.split("/")[0];
+      if (!exists((0, import_node_path16.join)(root, first))) continue;
+      if (!exists((0, import_node_path16.join)(root, ref))) candidates.push({ kind: "missing-path", doc, line, detail: ref });
+    }
+    const docDir = import_node_path16.posix.dirname(doc);
+    for (const { target, line } of extractLinks(markdown)) {
+      const resolved = import_node_path16.posix.normalize(import_node_path16.posix.join(docDir === "." ? "" : docDir, target));
+      if (!exists((0, import_node_path16.join)(root, resolved))) {
+        candidates.push({ kind: "missing-link", doc, line, detail: target, resolved });
+      }
+    }
+  }
+  const ignored = candidates.length ? isIgnored(candidates.map((c) => c.kind === "missing-link" ? c.resolved : c.detail)) : /* @__PURE__ */ new Set();
+  const findings = candidates.filter((c) => !ignored.has(c.kind === "missing-link" ? c.resolved : c.detail)).map(({ resolved, ...finding }) => finding);
+  return { ok: findings.length === 0, findings };
+}
+function checkCommands(docs2, commandPaths) {
+  const findings = [];
+  const prefixesSome = (prefix) => {
+    for (const path2 of commandPaths) {
+      if (path2 === prefix || path2.startsWith(`${prefix} `)) return true;
+    }
+    return false;
+  };
+  for (const [doc, markdown] of Object.entries(docs2)) {
+    for (const { command, line } of extractCommands(markdown)) {
+      const tokens2 = command.split(" ");
+      for (let i = 1; i <= tokens2.length; i += 1) {
+        const prefix = tokens2.slice(0, i).join(" ");
+        if (prefixesSome(prefix)) continue;
+        const parent = tokens2.slice(0, i - 1).join(" ");
+        if (i > 1 && commandPaths.has(parent)) break;
+        findings.push({ kind: "unknown-command", doc, line, detail: `mmi-cli ${prefix}` });
+        break;
+      }
+    }
+  }
+  return { ok: findings.length === 0, findings };
+}
+function readFileOrNull(path2) {
+  return (0, import_node_fs18.existsSync)(path2) ? (0, import_node_fs18.readFileSync)(path2, "utf8") : null;
+}
+function walk(dir, root, out) {
+  for (const entry of (0, import_node_fs18.readdirSync)(dir)) {
+    const full = (0, import_node_path16.join)(dir, entry);
+    if ((0, import_node_fs18.statSync)(full).isDirectory()) walk(full, root, out);
+    else if (entry.endsWith(".md")) out.push(full.slice(root.length + 1).replaceAll("\\", "/"));
+  }
+  return out;
+}
+function defaultListDocs(root) {
+  const docsDir = (0, import_node_path16.join)(root, "docs");
+  const docs2 = ((0, import_node_fs18.existsSync)(docsDir) ? walk(docsDir, root, []) : []).filter(
+    (rel) => !SKIP_WALK.some((skip) => rel.startsWith(skip))
+  );
+  return [...ROOT_DOCS.filter((rel) => (0, import_node_fs18.existsSync)((0, import_node_path16.join)(root, rel))), ...docs2];
+}
+function defaultIsIgnored(root, relPaths, exec = import_node_child_process9.execFileSync) {
+  try {
+    const out = exec("git", ["check-ignore", "--stdin"], {
+      cwd: root,
+      input: relPaths.join("\n"),
+      encoding: "utf8"
+    });
+    return new Set(out.split(/\r?\n/).filter(Boolean));
+  } catch (error) {
+    if (error?.status === 1) return /* @__PURE__ */ new Set();
+    throw error;
+  }
+}
+function runDocRefs(root, deps = {}) {
+  const readFile6 = deps.readFile ?? readFileOrNull;
+  const exists = deps.exists ?? import_node_fs18.existsSync;
+  const listDocs = deps.listDocs ?? defaultListDocs;
+  const isIgnored = deps.isIgnored ?? ((paths) => defaultIsIgnored(root, paths));
+  const commandPaths = deps.commandPaths ?? null;
+  const docs2 = Object.fromEntries(
+    listDocs(root).map((rel) => [rel, readFile6((0, import_node_path16.join)(root, rel))]).filter(([, body]) => body != null)
+  );
+  const findings = [
+    ...checkPins(root, readFile6).findings,
+    ...checkRefs(root, { exists, isIgnored }, docs2).findings
+  ];
+  if (commandPaths == null) {
+    findings.push({
+      kind: "command-manifest-unavailable",
+      doc: "cli command manifest",
+      line: 0,
+      detail: "the CLI could not enumerate its own commands \u2014 command refs cannot be verified"
+    });
+  } else {
+    findings.push(...checkCommands(docs2, commandPaths).findings);
+  }
+  return { ok: findings.length === 0, findings, docCount: Object.keys(docs2).length };
+}
+
 // src/docs-audit-command.ts
 function serializeOutcome(outcome) {
   switch (outcome.kind) {
@@ -16298,8 +16505,8 @@ function writeError(res) {
 }
 
 // src/secrets-commands.ts
-var import_node_fs18 = require("node:fs");
-var import_node_path16 = require("node:path");
+var import_node_fs19 = require("node:fs");
+var import_node_path17 = require("node:path");
 var import_node_os5 = require("node:os");
 
 // src/project-runtime.ts
@@ -16423,18 +16630,18 @@ function collectMap(value, previous = []) {
   return [...previous, value];
 }
 async function decryptRailsCredentials(input) {
-  const appDir = (0, import_node_path16.resolve)(input.appDir ?? process.cwd());
+  const appDir = (0, import_node_path17.resolve)(input.appDir ?? process.cwd());
   const credentialsFile = input.credentialsFile ?? DEFAULT_RAILS_CREDENTIALS_FILE;
   const masterKeyFile = input.masterKeyFile ?? DEFAULT_RAILS_MASTER_KEY_FILE;
-  const credentialsPath = (0, import_node_path16.resolve)(appDir, credentialsFile);
-  const masterKeyPath = (0, import_node_path16.resolve)(appDir, masterKeyFile);
+  const credentialsPath = (0, import_node_path17.resolve)(appDir, credentialsFile);
+  const masterKeyPath = (0, import_node_path17.resolve)(appDir, masterKeyFile);
   const env = {
     ...process.env,
     MMI_RAILS_CREDENTIALS_FILE: credentialsPath,
     MMI_RAILS_MASTER_KEY_FILE: masterKeyPath
   };
-  if ((0, import_node_fs18.existsSync)(masterKeyPath)) {
-    env.RAILS_MASTER_KEY = (0, import_node_fs18.readFileSync)(masterKeyPath, "utf8").trim();
+  if ((0, import_node_fs19.existsSync)(masterKeyPath)) {
+    env.RAILS_MASTER_KEY = (0, import_node_fs19.readFileSync)(masterKeyPath, "utf8").trim();
   }
   const script = [
     'require "json"',
@@ -16444,9 +16651,9 @@ async function decryptRailsCredentials(input) {
     'config = ActiveSupport::EncryptedConfiguration.new(config_path: config_path, key_path: key_path, env_key: "RAILS_MASTER_KEY", raise_if_missing_key: true)',
     "puts JSON.generate(config.config)"
   ].join("\n");
-  const scriptDir = (0, import_node_fs18.mkdtempSync)((0, import_node_path16.join)((0, import_node_os5.tmpdir)(), "mmi-rails-decrypt-"));
-  const scriptPath = (0, import_node_path16.join)(scriptDir, "decrypt.rb");
-  (0, import_node_fs18.writeFileSync)(scriptPath, script, "utf8");
+  const scriptDir = (0, import_node_fs19.mkdtempSync)((0, import_node_path17.join)((0, import_node_os5.tmpdir)(), "mmi-rails-decrypt-"));
+  const scriptPath = (0, import_node_path17.join)(scriptDir, "decrypt.rb");
+  (0, import_node_fs19.writeFileSync)(scriptPath, script, "utf8");
   try {
     const args = ["exec", "ruby", scriptPath];
     const cmd = process.platform === "win32" ? "cmd.exe" : "bundle";
@@ -16458,7 +16665,7 @@ async function decryptRailsCredentials(input) {
     });
     return JSON.parse(stdout);
   } finally {
-    (0, import_node_fs18.rmSync)(scriptDir, { recursive: true, force: true });
+    (0, import_node_fs19.rmSync)(scriptDir, { recursive: true, force: true });
   }
 }
 async function readSecretStdin() {
@@ -16548,7 +16755,7 @@ function registerSecretsCommands(program3) {
     let body;
     if (o.file) {
       try {
-        body = (0, import_node_fs18.readFileSync)((0, import_node_path16.resolve)(o.file), "utf8");
+        body = (0, import_node_fs19.readFileSync)((0, import_node_path17.resolve)(o.file), "utf8");
       } catch (e) {
         return fail(`secrets org-catalog: cannot read --file ${o.file}: ${e.message}`);
       }
@@ -16653,7 +16860,7 @@ function registerSecretsCommands(program3) {
       {
         ...d,
         decryptRailsCredentials,
-        removeFile: (path2) => (0, import_node_fs18.unlinkSync)((0, import_node_path16.resolve)(o.appDir ?? process.cwd(), path2))
+        removeFile: (path2) => (0, import_node_fs19.unlinkSync)((0, import_node_path17.resolve)(o.appDir ?? process.cwd(), path2))
       },
       {
         repo: o.repo,
@@ -17028,7 +17235,7 @@ function registerBoxCommands(program3) {
 
 // src/schedules-commands.ts
 var import_promises2 = require("node:fs/promises");
-var import_node_child_process9 = require("node:child_process");
+var import_node_child_process10 = require("node:child_process");
 var import_node_util7 = require("node:util");
 
 // src/schedules.ts
@@ -17334,7 +17541,7 @@ function assembleReconciliation(githubEntries2, readRepos, registry2, activeWork
 }
 
 // src/schedules-commands.ts
-var execFileP5 = (0, import_node_util7.promisify)(import_node_child_process9.execFile);
+var execFileP5 = (0, import_node_util7.promisify)(import_node_child_process10.execFile);
 var AWS_REGION = "eu-central-1";
 var AWS_TIMEOUT_MS = 3e4;
 var AWS_RETRY_DELAY_MS = 1500;
@@ -17570,14 +17777,14 @@ function registerSchedulesCommands(program3) {
 
 // src/schedules-lift-command.ts
 var import_promises3 = require("node:fs/promises");
-var import_node_path17 = require("node:path");
+var import_node_path18 = require("node:path");
 
 // src/schedules-lift.ts
 var SCHEDULE_HEADER_FIELDS = ["schedule", "what", "owner", "cadence", "executor", "llm", "output", "breaks", "kill"];
 function parseScheduleHeader(yamlText) {
   const out = {};
   for (const rawLine of yamlText.split("\n")) {
-    const m = /^#\s*(schedule|what|owner|cadence|executor|llm|output|breaks|kill|target):\s*(.+?)\s*$/.exec(rawLine);
+    const m = /^#\s*(schedule|what|owner|cadence|executor|llm|output|breaks|kill|target|model):\s*(.+?)\s*$/.exec(rawLine);
     if (m && out[m[1]] === void 0) out[m[1]] = m[2].trim();
   }
   return out;
@@ -17614,6 +17821,10 @@ function scheduleRecordFromWorkflow(repo, workflowPath, yamlText) {
   if (target !== void 0 && !/^mmi-fleet-[A-Za-z0-9_-]{1,130}$/.test(target)) {
     throw new Error(`schedules lift: ${expectedId} header \`target: ${target}\` must be a bare lambda function name in the reserved fleet namespace \`mmi-fleet-*\` (allowed after the prefix: A-Z a-z 0-9 _ -; total max 140). The dispatcher can only invoke mmi-fleet-* functions.`);
   }
+  const model = header.model;
+  if (model !== void 0 && !/^[a-z][a-z0-9-]{0,30}$/.test(model)) {
+    throw new Error(`schedules lift: ${expectedId} header \`model: ${model}\` must be a model ROLE KEY (lowercase kebab, max 31 chars \u2014 e.g. janitor, arbiter), never a model id \u2014 ids resolve from the vault at dispatch.`);
+  }
   return {
     id: expectedId,
     what: h.what,
@@ -17626,7 +17837,8 @@ function scheduleRecordFromWorkflow(repo, workflowPath, yamlText) {
     kill: h.kill,
     repo,
     sourcePath: workflowPath,
-    ...target !== void 0 ? { target } : {}
+    ...target !== void 0 ? { target } : {},
+    ...model !== void 0 ? { model } : {}
   };
 }
 function scheduleRecordsFromWorkflows(repo, files) {
@@ -17671,7 +17883,7 @@ async function readWorkflowFiles(dir) {
   const files = [];
   for (const name of names.sort()) {
     if (!/\.ya?ml$/.test(name)) continue;
-    files.push({ path: `.github/workflows/${name}`, text: await (0, import_promises3.readFile)((0, import_node_path17.join)(dir, name), "utf8") });
+    files.push({ path: `.github/workflows/${name}`, text: await (0, import_promises3.readFile)((0, import_node_path18.join)(dir, name), "utf8") });
   }
   return files;
 }
@@ -18211,7 +18423,7 @@ function registerQueryCommands(program3) {
 }
 
 // src/bootstrap-commands.ts
-var import_node_fs19 = require("node:fs");
+var import_node_fs20 = require("node:fs");
 
 // src/bootstrap-verify.ts
 var TRAIN_BRANCHES2 = ["development", "rc", "main"];
@@ -18759,7 +18971,7 @@ function registerBootstrapCommands(program3) {
       client: defaultGitHubClient(),
       projectMeta: meta,
       deployModel: typeof meta?.deployModel === "string" ? meta.deployModel : void 0,
-      readLocalFile: (path2) => path2 === "projects.json" && apiProjects != null ? apiProjects : (0, import_node_fs19.existsSync)(path2) ? (0, import_node_fs19.readFileSync)(path2, "utf8") : null,
+      readLocalFile: (path2) => path2 === "projects.json" && apiProjects != null ? apiProjects : (0, import_node_fs20.existsSync)(path2) ? (0, import_node_fs20.readFileSync)(path2, "utf8") : null,
       // requiredGcpApis is stored as an array by a JSON write, but `org project set --var KEY=VALUE` stores a raw
       // comma-string — accept either so the seeded value verifies regardless of how it was written.
       requiredGcpApis: (() => {
@@ -18810,12 +19022,12 @@ function registerBootstrapCommands(program3) {
       return fail(`bootstrap apply: ${e.message}`);
     }
     const manifestPath = "skills/bootstrap/seeds/manifest.json";
-    if (!(0, import_node_fs19.existsSync)(manifestPath)) return fail(`bootstrap apply: ${manifestPath} not found; bootstrap runs from the MMI-Hub repo root by design \u2014 it stamps org-level resources (Project, Ruleset, secrets, access) through the GitHub App, which is only authorized from the Hub checkout`);
-    const manifest = loadBootstrapSeeds((0, import_node_fs19.readFileSync)(manifestPath, "utf8"));
+    if (!(0, import_node_fs20.existsSync)(manifestPath)) return fail(`bootstrap apply: ${manifestPath} not found; bootstrap runs from the MMI-Hub repo root by design \u2014 it stamps org-level resources (Project, Ruleset, secrets, access) through the GitHub App, which is only authorized from the Hub checkout`);
+    const manifest = loadBootstrapSeeds((0, import_node_fs20.readFileSync)(manifestPath, "utf8"));
     const baseBranch = o.class === "content" ? "main" : "development";
     const slug = parsedRepo.slug;
     const gh = async (args) => execFileP2("gh", args, { timeout: 2e4 });
-    const readFile6 = (p) => (0, import_node_fs19.existsSync)(p) ? (0, import_node_fs19.readFileSync)(p, "utf8") : null;
+    const readFile6 = (p) => (0, import_node_fs20.existsSync)(p) ? (0, import_node_fs20.readFileSync)(p, "utf8") : null;
     const enc = (p) => p.split("/").map(encodeURIComponent).join("/");
     const rawVars = {};
     for (const value of cmdOpts.var ?? []) {
@@ -19011,12 +19223,12 @@ LIVE apply to ${repo}:
 }
 
 // src/stage-commands.ts
-var import_node_fs21 = require("node:fs");
-var import_node_path19 = require("node:path");
+var import_node_fs22 = require("node:fs");
+var import_node_path20 = require("node:path");
 
 // src/port-registry.ts
-var import_node_fs20 = require("node:fs");
-var import_node_path18 = require("node:path");
+var import_node_fs21 = require("node:fs");
+var import_node_path19 = require("node:path");
 
 // ../infra/port-geometry.mjs
 var PORT_BLOCK = 100;
@@ -19030,8 +19242,8 @@ function nextPortBlock(registry2) {
   return [base, base + PORT_SPAN];
 }
 function loadPortRegistry(path2) {
-  if (!(0, import_node_fs20.existsSync)(path2)) return {};
-  const raw = JSON.parse((0, import_node_fs20.readFileSync)(path2, "utf8"));
+  if (!(0, import_node_fs21.existsSync)(path2)) return {};
+  const raw = JSON.parse((0, import_node_fs21.readFileSync)(path2, "utf8"));
   const out = {};
   for (const [key, value] of Object.entries(raw)) {
     if (Array.isArray(value) && value.length === 2 && value.every((n) => typeof n === "number")) {
@@ -19045,9 +19257,9 @@ function ensurePortRange(repo, path2) {
   const existing = registry2[repo];
   if (existing) return existing;
   const range = nextPortBlock(registry2);
-  const raw = (0, import_node_fs20.existsSync)(path2) ? JSON.parse((0, import_node_fs20.readFileSync)(path2, "utf8")) : {};
+  const raw = (0, import_node_fs21.existsSync)(path2) ? JSON.parse((0, import_node_fs21.readFileSync)(path2, "utf8")) : {};
   raw[repo] = range;
-  (0, import_node_fs20.writeFileSync)(path2, JSON.stringify(raw, null, 2) + "\n", "utf8");
+  (0, import_node_fs21.writeFileSync)(path2, JSON.stringify(raw, null, 2) + "\n", "utf8");
   return range;
 }
 function portCursorSeed(registry2) {
@@ -19069,22 +19281,22 @@ function existingPortRange(repo, registry2) {
   return registry2[repo] ?? null;
 }
 function portRangeInfraAt(root, source) {
-  const registryPath = (0, import_node_path18.join)(root, "infra", "port-ranges.json");
-  const ddbScriptPath = (0, import_node_path18.join)(root, "infra", "port-ddb.mjs");
-  if (!(0, import_node_fs20.existsSync)(registryPath) || !(0, import_node_fs20.existsSync)(ddbScriptPath)) return null;
+  const registryPath = (0, import_node_path19.join)(root, "infra", "port-ranges.json");
+  const ddbScriptPath = (0, import_node_path19.join)(root, "infra", "port-ddb.mjs");
+  if (!(0, import_node_fs21.existsSync)(registryPath) || !(0, import_node_fs21.existsSync)(ddbScriptPath)) return null;
   return { root, source, registryPath, ddbScriptPath };
 }
 function resolvePortRangeInfra(cwd, packageDir) {
   const direct = portRangeInfraAt(cwd, "cwd");
   if (direct) return direct;
-  for (let dir = cwd; ; dir = (0, import_node_path18.dirname)(dir)) {
-    const sibling = portRangeInfraAt((0, import_node_path18.join)(dir, "MMI-Hub"), "sibling-hub");
+  for (let dir = cwd; ; dir = (0, import_node_path19.dirname)(dir)) {
+    const sibling = portRangeInfraAt((0, import_node_path19.join)(dir, "MMI-Hub"), "sibling-hub");
     if (sibling) return sibling;
-    const parent = (0, import_node_path18.dirname)(dir);
+    const parent = (0, import_node_path19.dirname)(dir);
     if (parent === dir) break;
   }
   if (packageDir) {
-    const pkgRoot = (0, import_node_path18.join)(packageDir, "..", "..");
+    const pkgRoot = (0, import_node_path19.join)(packageDir, "..", "..");
     const pkgFrom = portRangeInfraAt(pkgRoot, "pkg-root");
     if (pkgFrom) return pkgFrom;
   }
@@ -19260,8 +19472,8 @@ function registerStageCommands(program3) {
     const portRange = portRangeMeta && typeof portRangeMeta.start === "number" && typeof portRangeMeta.end === "number" ? [portRangeMeta.start, portRangeMeta.end] : void 0;
     return decideStage({
       registry: { deployModel: project2?.deployModel, portRange, error: read.ok ? void 0 : read.error },
-      hasCompose: (0, import_node_fs21.existsSync)((0, import_node_path19.join)(process.cwd(), "docker-compose.yml")),
-      hasEnvExample: (0, import_node_fs21.existsSync)((0, import_node_path19.join)(process.cwd(), ".env.example"))
+      hasCompose: (0, import_node_fs22.existsSync)((0, import_node_path20.join)(process.cwd(), "docker-compose.yml")),
+      hasEnvExample: (0, import_node_fs22.existsSync)((0, import_node_path20.join)(process.cwd(), ".env.example"))
     });
   }
   async function fetchStageVaultEnvMerge() {
@@ -19696,9 +19908,9 @@ function registerBoardCommands(program3) {
 }
 
 // src/merge-cleanup.ts
-var import_node_fs22 = require("node:fs");
+var import_node_fs23 = require("node:fs");
 var import_promises5 = require("node:fs/promises");
-var import_node_child_process10 = require("node:child_process");
+var import_node_child_process11 = require("node:child_process");
 
 // src/board-advance.ts
 function repoOf2(ref) {
@@ -19784,7 +19996,7 @@ function boardAdvanceFailureMessage(result) {
 
 // src/deferred-registry-store.ts
 var import_promises4 = require("node:fs/promises");
-var import_node_path20 = require("node:path");
+var import_node_path21 = require("node:path");
 var sleep = (ms) => new Promise((resolve5) => setTimeout(resolve5, ms));
 async function atomicWrite(target, contents) {
   const tmp = `${target}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
@@ -19888,12 +20100,12 @@ function makeDeferredWorktreeStore(registryPath, lockOpts = {}) {
     },
     // Standalone atomic write — THROWS on failure (no best-effort swallow, #2846).
     write: async (entries) => {
-      await (0, import_promises4.mkdir)((0, import_node_path20.dirname)(registryPath), { recursive: true });
+      await (0, import_promises4.mkdir)((0, import_node_path21.dirname)(registryPath), { recursive: true });
       await atomicWrite(registryPath, serializeDeferredWorktrees(entries));
     },
     // Serialized read-modify-write under the repo-wide lock (#2846).
     update: async (mutate) => {
-      await (0, import_promises4.mkdir)((0, import_node_path20.dirname)(registryPath), { recursive: true });
+      await (0, import_promises4.mkdir)((0, import_node_path21.dirname)(registryPath), { recursive: true });
       const deadline = Date.now() + opts.maxWaitMs;
       for (; ; ) {
         const guard = await acquireLock(lockPath, opts, deadline);
@@ -20020,7 +20232,7 @@ async function applyGcPlan(plan, remote) {
       return cleanupPrMergeLocalBranch(branch.branch, {
         beforeWorktrees,
         startingPath: branch.worktreePath,
-        pathExists: (p) => (0, import_node_fs22.existsSync)(p),
+        pathExists: (p) => (0, import_node_fs23.existsSync)(p),
         execGit: async (args) => (await execFileP2("git", args, { timeout: GIT_TIMEOUT_MS })).stdout,
         teardownWorktreeStage,
         deferredStore,
@@ -20046,7 +20258,7 @@ async function applyGcPlan(plan, remote) {
   for (const wt of plan.worktreeDirs) {
     try {
       const cleanupTarget = resolveSafeSiblingWorktreeCleanupTarget(wt.path, siblingRoot, {
-        realpath: (path2) => (0, import_node_fs22.realpathSync)(path2)
+        realpath: (path2) => (0, import_node_fs23.realpathSync)(path2)
       });
       if (!cleanupTarget.ok) {
         result.failed.push(`${wt.path}: ${cleanupTarget.reason}`);
@@ -20159,7 +20371,7 @@ async function remoteBranchExists2(branch, options = {}) {
 }
 var COMPOSE_TIMEOUT_MS = 12e4;
 function spawnDeferredGcSweep() {
-  spawnDetachedSelf(["worktree", "gc", "sweep-deferred", "--quiet"], { spawn: import_node_child_process10.spawn, execPath: process.execPath, scriptPath: process.argv[1] });
+  spawnDetachedSelf(["worktree", "gc", "sweep-deferred", "--quiet"], { spawn: import_node_child_process11.spawn, execPath: process.execPath, scriptPath: process.argv[1] });
 }
 async function createDeferredWorktreeStore() {
   try {
@@ -20173,13 +20385,13 @@ var realWorktreeDirRemover = {
   probe: (p) => {
     let st;
     try {
-      st = (0, import_node_fs22.lstatSync)(p);
+      st = (0, import_node_fs23.lstatSync)(p);
     } catch {
       return null;
     }
     if (st.isSymbolicLink()) return "link";
     try {
-      (0, import_node_fs22.readlinkSync)(p);
+      (0, import_node_fs23.readlinkSync)(p);
       return "link";
     } catch {
     }
@@ -20187,7 +20399,7 @@ var realWorktreeDirRemover = {
   },
   readdir: (p) => {
     try {
-      return (0, import_node_fs22.readdirSync)(p);
+      return (0, import_node_fs23.readdirSync)(p);
     } catch {
       return [];
     }
@@ -20196,9 +20408,9 @@ var realWorktreeDirRemover = {
   // leaving the target); a file symlink with unlink. rmdir first, fall back to unlink.
   detachLink: (p) => {
     try {
-      (0, import_node_fs22.rmdirSync)(p);
+      (0, import_node_fs23.rmdirSync)(p);
     } catch {
-      (0, import_node_fs22.unlinkSync)(p);
+      (0, import_node_fs23.unlinkSync)(p);
     }
   },
   removeTree: (p) => (0, import_promises5.rm)(p, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 })
@@ -20231,9 +20443,9 @@ async function worktreeHasStageState(worktreePath) {
   }
 }
 function stageStateFileBelongsToWorktree(statePath, worktreePath) {
-  if (!(0, import_node_fs22.existsSync)(statePath)) return false;
+  if (!(0, import_node_fs23.existsSync)(statePath)) return false;
   try {
-    const state = JSON.parse((0, import_node_fs22.readFileSync)(statePath, "utf8"));
+    const state = JSON.parse((0, import_node_fs23.readFileSync)(statePath, "utf8"));
     const recordedCwd = typeof state.identity?.cwd === "string" ? state.identity.cwd : typeof state.cwd === "string" ? state.cwd : "";
     return Boolean(recordedCwd && isPathUnderDirectory(recordedCwd, worktreePath));
   } catch {
@@ -20361,8 +20573,8 @@ async function fetchRestCorePool(gh = defaultGhApi) {
 }
 
 // src/worktree-lifecycle-commands.ts
-var import_node_fs23 = require("node:fs");
-var import_node_path21 = require("node:path");
+var import_node_fs24 = require("node:fs");
+var import_node_path22 = require("node:path");
 var GH_TIMEOUT_MS = 2e4;
 var DEFAULT_BASE = "origin/development";
 var DEFAULT_REMOTE = "origin";
@@ -20499,13 +20711,13 @@ function registerWorktreeCommands(program3) {
       if (PROTECTED_BRANCHES2.has(branch)) {
         return fail(`worktree land: refusing to land protected branch '${branch}'`, { code: ERROR_CODES.ERR_BAD_ENUM });
       }
-      const gitFile = (0, import_node_path21.join)(wtPath, ".git");
-      const isLinked = (0, import_node_fs23.existsSync)(gitFile) && (0, import_node_fs23.statSync)(gitFile).isFile();
+      const gitFile = (0, import_node_path22.join)(wtPath, ".git");
+      const isLinked = (0, import_node_fs24.existsSync)(gitFile) && (0, import_node_fs24.statSync)(gitFile).isFile();
       if (apply && !isLinked) {
         return fail("worktree land: run from inside the linked worktree you want to land (this is the primary checkout)");
       }
       const commonDir = (await execFileP2("git", ["rev-parse", "--git-common-dir"], { timeout: GIT_TIMEOUT_MS }).catch(() => ({ stdout: "" }))).stdout.trim();
-      const primaryCheckout = commonDir ? (0, import_node_path21.dirname)(commonDir) : wtPath;
+      const primaryCheckout = commonDir ? (0, import_node_path22.dirname)(commonDir) : wtPath;
       const stageSummary = readStageSummary(wtPath);
       const hasStage = stageSummary != null;
       const steps = landSteps(branch, true, hasStage);
@@ -20617,10 +20829,10 @@ async function gatherWorktreeContext() {
   }
   const orphanDirs = [];
   const wtRoot = siblingMmiWorktreesRoot(repoRoot2);
-  if ((0, import_node_fs23.existsSync)(wtRoot)) {
+  if ((0, import_node_fs24.existsSync)(wtRoot)) {
     let entries = [];
     try {
-      entries = (0, import_node_fs23.readdirSync)(wtRoot, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => (0, import_node_path21.join)(wtRoot, e.name));
+      entries = (0, import_node_fs24.readdirSync)(wtRoot, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => (0, import_node_path22.join)(wtRoot, e.name));
     } catch {
     }
     const known = new Set(worktrees.map((w) => w.path));
@@ -20645,7 +20857,7 @@ async function bestEffortGit(args, cwd, step, timeoutMs = GIT_TIMEOUT_MS) {
 }
 
 // src/issue-commands.ts
-var import_node_fs24 = require("node:fs");
+var import_node_fs25 = require("node:fs");
 var import_node_crypto5 = require("node:crypto");
 var ghRunner = async (args, timeoutMs) => (await execFileP2("gh", args, { timeout: timeoutMs })).stdout;
 async function editIssue(client, options, deps = {}) {
@@ -20659,7 +20871,7 @@ async function editIssue(client, options, deps = {}) {
   if (options.body !== void 0 || options.bodyFile !== void 0) {
     let body;
     if (options.bodyFile) {
-      const td = deps.textDeps ?? { readFile: (p, e) => Promise.resolve((0, import_node_fs24.readFileSync)(p, e)), readStdin: () => Promise.resolve("") };
+      const td = deps.textDeps ?? { readFile: (p, e) => Promise.resolve((0, import_node_fs25.readFileSync)(p, e)), readStdin: () => Promise.resolve("") };
       body = await resolveIssueBody({ body: options.body, bodyFile: options.bodyFile }, td);
     } else {
       body = options.body ?? "";
@@ -21142,7 +21354,7 @@ function extendCreateCommand(issue2) {
     if (opts.batch) {
       let specs;
       try {
-        const raw = (0, import_node_fs24.readFileSync)(opts.batch, "utf8");
+        const raw = (0, import_node_fs25.readFileSync)(opts.batch, "utf8");
         specs = JSON.parse(raw);
         if (!Array.isArray(specs)) throw new Error("batch file must contain a JSON array");
       } catch (e) {
@@ -21186,12 +21398,12 @@ ${lines}`);
 }
 
 // src/train-commands.ts
-var import_node_fs26 = require("node:fs");
-var import_node_path23 = require("node:path");
+var import_node_fs27 = require("node:fs");
+var import_node_path24 = require("node:path");
 
 // src/plugin-guard-io.ts
-var import_node_fs25 = require("node:fs");
-var import_node_path22 = require("node:path");
+var import_node_fs26 = require("node:fs");
+var import_node_path23 = require("node:path");
 var import_node_os6 = require("node:os");
 
 // src/plugin-guard.ts
@@ -21321,11 +21533,11 @@ function runHostBin(bin, args, opts) {
 }
 var installedPluginsPath2 = (surface = detectSurface(process.env)) => {
   const homeDir = surface === "codex" ? ".codex" : ".claude";
-  return (0, import_node_path22.join)((0, import_node_os6.homedir)(), homeDir, "plugins", "installed_plugins.json");
+  return (0, import_node_path23.join)((0, import_node_os6.homedir)(), homeDir, "plugins", "installed_plugins.json");
 };
 function readInstalledPlugins(surface = detectSurface(process.env)) {
   try {
-    return JSON.parse((0, import_node_fs25.readFileSync)(installedPluginsPath2(surface), "utf8"));
+    return JSON.parse((0, import_node_fs26.readFileSync)(installedPluginsPath2(surface), "utf8"));
   } catch {
     return null;
   }
@@ -21333,13 +21545,13 @@ function readInstalledPlugins(surface = detectSurface(process.env)) {
 function marketplaceCloneCandidates(surface, home) {
   if (surface === "codex") {
     return [
-      (0, import_node_path22.join)(home, ".codex", ".tmp", "marketplaces", "mutmutco"),
-      (0, import_node_path22.join)(home, ".codex", "plugins", "marketplaces", "mutmutco")
+      (0, import_node_path23.join)(home, ".codex", ".tmp", "marketplaces", "mutmutco"),
+      (0, import_node_path23.join)(home, ".codex", "plugins", "marketplaces", "mutmutco")
     ];
   }
-  return [(0, import_node_path22.join)(home, ".claude", "plugins", "marketplaces", "mutmutco")];
+  return [(0, import_node_path23.join)(home, ".claude", "plugins", "marketplaces", "mutmutco")];
 }
-function marketplaceClonePresent(surface, home, exists = import_node_fs25.existsSync) {
+function marketplaceClonePresent(surface, home, exists = import_node_fs26.existsSync) {
   return marketplaceCloneCandidates(surface, home).some(exists);
 }
 async function fetchNpmReleasedVersion() {
@@ -21366,7 +21578,7 @@ function snapshotPluginGuardInput(surface = detectSurface(process.env), isOrgRep
     isOrgRepo,
     installRecordPresent: hasUserInstallRecord(installed, MMI_PLUGIN_ID) || hasProjectInstallRecord(installed, MMI_PLUGIN_ID, process.cwd()),
     marketplaceClonePresent: marketplaceClonePresent(surface, (0, import_node_os6.homedir)()),
-    pluginCachePresent: (0, import_node_fs25.existsSync)((0, import_node_path22.join)((0, import_node_os6.homedir)(), homeDir, "plugins", "cache", "mutmutco", "mmi"))
+    pluginCachePresent: (0, import_node_fs26.existsSync)((0, import_node_path23.join)((0, import_node_os6.homedir)(), homeDir, "plugins", "cache", "mutmutco", "mmi"))
   };
 }
 function claudePluginGuardState(isOrgRepo) {
@@ -21501,7 +21713,7 @@ function formatTrainStatus(r) {
 // src/train-commands.ts
 function readRepoVersion() {
   try {
-    return JSON.parse((0, import_node_fs26.readFileSync)((0, import_node_path23.join)(process.cwd(), ".claude-plugin", "plugin.json"), "utf8")).version || void 0;
+    return JSON.parse((0, import_node_fs27.readFileSync)((0, import_node_path24.join)(process.cwd(), ".claude-plugin", "plugin.json"), "utf8")).version || void 0;
   } catch {
     return void 0;
   }
@@ -22953,17 +23165,17 @@ async function runDoctorClean(opts, io, deps) {
 }
 
 // src/doctor-io.ts
-var import_node_fs27 = require("node:fs");
+var import_node_fs28 = require("node:fs");
 var import_node_os7 = require("node:os");
-var import_node_path24 = require("node:path");
-var import_node_child_process11 = require("node:child_process");
+var import_node_path25 = require("node:path");
+var import_node_child_process12 = require("node:child_process");
 var import_node_util8 = require("node:util");
-var execFileP6 = (0, import_node_util8.promisify)(import_node_child_process11.execFile);
+var execFileP6 = (0, import_node_util8.promisify)(import_node_child_process12.execFile);
 var MMI_PLUGIN_ID2 = "mmi@mutmutco";
 function installedClaudePluginVersion() {
   try {
     const file = JSON.parse(
-      (0, import_node_fs27.readFileSync)((0, import_node_path24.join)((0, import_node_os7.homedir)(), ".claude", "plugins", "installed_plugins.json"), "utf8")
+      (0, import_node_fs28.readFileSync)((0, import_node_path25.join)((0, import_node_os7.homedir)(), ".claude", "plugins", "installed_plugins.json"), "utf8")
     );
     const versions = (file.plugins?.[MMI_PLUGIN_ID2] ?? []).map((r) => r.version).filter((v) => Boolean(v));
     if (versions.length === 0) return void 0;
@@ -22974,7 +23186,7 @@ function installedClaudePluginVersion() {
 }
 function worktreeRootSync() {
   try {
-    const out = (0, import_node_child_process11.execFileSync)("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    const out = (0, import_node_child_process12.execFileSync)("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
     let root = out.endsWith("\n") ? out.slice(0, -1) : out;
     if (process.platform === "win32" && root.endsWith("\r")) root = root.slice(0, -1);
     return root || null;
@@ -22984,13 +23196,13 @@ function worktreeRootSync() {
 }
 var gitignorePath = () => {
   const root = worktreeRootSync();
-  return root === null ? null : (0, import_node_path24.join)(root, ".gitignore");
+  return root === null ? null : (0, import_node_path25.join)(root, ".gitignore");
 };
 function readGitignore() {
   const path2 = gitignorePath();
   if (path2 === null) return null;
   try {
-    return (0, import_node_fs27.readFileSync)(path2, "utf8");
+    return (0, import_node_fs28.readFileSync)(path2, "utf8");
   } catch {
     return null;
   }
@@ -22999,7 +23211,7 @@ function writeGitignore(content) {
   const path2 = gitignorePath();
   if (path2 === null) return false;
   try {
-    (0, import_node_fs27.writeFileSync)(path2, content, "utf8");
+    (0, import_node_fs28.writeFileSync)(path2, content, "utf8");
     return true;
   } catch {
     return false;
@@ -23023,7 +23235,7 @@ async function repoRoot() {
 }
 function hasRepoLocalWorktrees() {
   const root = worktreeRootSync();
-  return root !== null && (0, import_node_fs27.existsSync)((0, import_node_path24.join)(root, ".worktrees"));
+  return root !== null && (0, import_node_fs28.existsSync)((0, import_node_path25.join)(root, ".worktrees"));
 }
 
 // src/index.ts
@@ -23141,16 +23353,16 @@ var cachedLongFlags;
 function allLongFlags() {
   if (cachedLongFlags) return cachedLongFlags;
   const acc = /* @__PURE__ */ new Set();
-  const walk = (node) => {
+  const walk2 = (node) => {
     if (!isCanonicalSuggestion(node)) return;
     for (const opt of node.options) {
       if (opt.discovery) continue;
       const m = /--[\w-]+/.exec(opt.flags);
       if (m) acc.add(m[0]);
     }
-    for (const child2 of node.subcommands) walk(child2);
+    for (const child2 of node.subcommands) walk2(child2);
   };
-  walk(buildCommandManifest(program2).tree);
+  walk2(buildCommandManifest(program2).tree);
   cachedLongFlags = [...acc];
   return cachedLongFlags;
 }
@@ -23250,19 +23462,19 @@ program2.hook("preAction", async (_thisCommand, actionCommand) => {
 });
 var rules = program2.command("rules").description("org-managed .gitignore delivery");
 rules.command("gitignore").option("--write", "upsert the managed block into .gitignore (default: check only, non-zero exit on drift)").option("--json", "machine-readable output").description("verify (or --write) this repo's org-managed .gitignore block matches the SSOT").action((opts) => {
-  const path2 = (0, import_node_path25.join)(process.cwd(), ".gitignore");
-  const current = (0, import_node_fs28.existsSync)(path2) ? (0, import_node_fs28.readFileSync)(path2, "utf8") : null;
+  const path2 = (0, import_node_path26.join)(process.cwd(), ".gitignore");
+  const current = (0, import_node_fs29.existsSync)(path2) ? (0, import_node_fs29.readFileSync)(path2, "utf8") : null;
   const plan = planManagedGitignore(current);
   const drift = [...plan.added.map((l) => `+${l}`), ...plan.removed.map((l) => `-${l}`)].join(", ") || "block normalize";
   if (opts.json) {
-    if (opts.write && plan.changed) (0, import_node_fs28.writeFileSync)(path2, plan.content, "utf8");
+    if (opts.write && plan.changed) (0, import_node_fs29.writeFileSync)(path2, plan.content, "utf8");
     console.log(JSON.stringify(plan, null, 2));
     if (!opts.write && plan.changed) process.exitCode = 1;
     return;
   }
   if (opts.write) {
     if (plan.changed) {
-      (0, import_node_fs28.writeFileSync)(path2, plan.content, "utf8");
+      (0, import_node_fs29.writeFileSync)(path2, plan.content, "utf8");
       console.log(`mmi-cli org rules gitignore: updated .gitignore (${drift})`);
     } else {
       console.log("mmi-cli org rules gitignore: up to date");
@@ -23420,7 +23632,7 @@ function runWorktreeInstall(command, cwd, quiet) {
   const file = isWin2 ? "cmd.exe" : bin;
   const spawnArgs = isWin2 ? ["/c", bin, ...args] : args;
   return new Promise((resolve5, reject) => {
-    const child2 = (0, import_node_child_process12.spawn)(file, spawnArgs, { cwd, stdio: quiet ? "ignore" : "inherit", windowsHide: true });
+    const child2 = (0, import_node_child_process13.spawn)(file, spawnArgs, { cwd, stdio: quiet ? "ignore" : "inherit", windowsHide: true });
     const timer = setTimeout(() => {
       try {
         child2.kill();
@@ -23452,26 +23664,26 @@ function makeProvisionDeps(worktreeRoot, quiet, log) {
 function acquireWorktreeSetupLock(worktreeRoot) {
   const lockPath = repoRuntimeStatePath(worktreeRoot, "worktree-setup.lock");
   const take = () => {
-    const fd = (0, import_node_fs28.openSync)(lockPath, "wx");
+    const fd = (0, import_node_fs29.openSync)(lockPath, "wx");
     try {
-      (0, import_node_fs28.writeSync)(fd, String(Date.now()));
+      (0, import_node_fs29.writeSync)(fd, String(Date.now()));
     } finally {
-      (0, import_node_fs28.closeSync)(fd);
+      (0, import_node_fs29.closeSync)(fd);
     }
     return () => {
       try {
-        (0, import_node_fs28.rmSync)(lockPath, { force: true });
+        (0, import_node_fs29.rmSync)(lockPath, { force: true });
       } catch {
       }
     };
   };
   try {
-    (0, import_node_fs28.mkdirSync)((0, import_node_path25.dirname)(lockPath), { recursive: true });
+    (0, import_node_fs29.mkdirSync)((0, import_node_path26.dirname)(lockPath), { recursive: true });
     return take();
   } catch {
     try {
-      if (Date.now() - (0, import_node_fs28.statSync)(lockPath).mtimeMs > WORKTREE_SETUP_LOCK_TTL_MS) {
-        (0, import_node_fs28.rmSync)(lockPath, { force: true });
+      if (Date.now() - (0, import_node_fs29.statSync)(lockPath).mtimeMs > WORKTREE_SETUP_LOCK_TTL_MS) {
+        (0, import_node_fs29.rmSync)(lockPath, { force: true });
         return take();
       }
     } catch {
@@ -23651,7 +23863,7 @@ function scheduleRelatedDiscovery(o) {
   try {
     const args = ["issue", "discover-related", "--number", String(o.number), "--title", o.title, "--body", o.body, "--fail-soft"];
     if (o.repo) args.push("--repo", o.repo);
-    spawnDetachedSelf(args, { spawn: import_node_child_process12.spawn, execPath: process.execPath, scriptPath: process.argv[1] }, { cwd: process.cwd() });
+    spawnDetachedSelf(args, { spawn: import_node_child_process13.spawn, execPath: process.execPath, scriptPath: process.argv[1] }, { cwd: process.cwd() });
   } catch {
   }
 }
@@ -23677,6 +23889,27 @@ docs.command("index").description("regenerate docs/index.md from the docs/ tree
     await failGraceful(e.message);
   }
 });
+docs.command("refs").description("deterministic doc reference gate: every backticked repo path, relative .md link, `mmi-cli` command ref, and `<!-- pinned by \u2026 -->` comment across docs/** + README.md + architecture.md must resolve, or exit 1 (fleet-portable port of the Hub gate scripts/check-doc-refs.mjs, #3339)").option("--json", "machine-readable findings list: { ok, docCount, findings[] }").action(async (o) => {
+  try {
+    const root = await repoRoot();
+    const commandPaths = new Set(buildCommandManifest(program2).index.map((entry) => entry.path));
+    const result = runDocRefs(root, { commandPaths });
+    if (o.json) {
+      consoleIo.log(JSON.stringify({ ok: result.ok, docCount: result.docCount, findings: result.findings }, null, 2));
+      if (!result.ok) process.exitCode = 1;
+      return;
+    }
+    if (result.ok) {
+      console.log(`doc refs: ${result.docCount} docs, every reference resolves`);
+      return;
+    }
+    console.error("doc refs: unresolved references");
+    for (const f of result.findings) console.error(`- ${f.doc}:${f.line} [${f.kind}] ${f.detail}`);
+    process.exitCode = 1;
+  } catch (e) {
+    await failGraceful(e.message);
+  }
+});
 var docsAudit = program2.command("docs-audit").description("the docs janitor verdict ledger \u2014 record a dated run verdict, or read the dead-man status back");
 docsAudit.command("record").description("write a dated janitor verdict for one repo to the registry ledger (master-only server-side)").option("--repo <owner/name>", "the repo the verdict is for (default: the current repo)").option("--date <YYYY-MM-DD>", "the ISO day the run examined (default: today)").requiredOption("--sha-range <a..b>", "the git range the janitor read (e.g. <lastVerdictSha>..HEAD)").requiredOption("--outcome <kind>", "clean | refreshed | failed").option("--count <n>", "docs refreshed (required when --outcome refreshed)").option("--reason <text>", "why the run failed (required when --outcome failed)").requiredOption("--checker-vendor <vendor>", "which vendor's model actually ran the check").action(async (o) => {
   try {
@@ -23892,7 +24125,7 @@ project.command("set [owner/repo]").description("upsert project META (idempotent
   if (dupe) return fail(`org project set: KEY "${dupe}" was passed to both --var and --set; --set is an alias of --var, so pass each KEY once`);
   if (o.secretsFile) {
     try {
-      vars.push(`secrets=${(0, import_node_fs28.readFileSync)(o.secretsFile, "utf8")}`);
+      vars.push(`secrets=${(0, import_node_fs29.readFileSync)(o.secretsFile, "utf8")}`);
     } catch (e) {
       return fail(`org project set: cannot read --secrets-file ${o.secretsFile}: ${e.message}`);
     }
@@ -24527,11 +24760,11 @@ pr.command("view <number>").description("read a PR as structured JSON (merged st
   }
 });
 async function listCiWorkflowPaths(cwd = process.cwd()) {
-  const wfDir = (0, import_node_path25.join)(cwd, ".github", "workflows");
-  if (!(0, import_node_fs28.existsSync)(wfDir)) return [];
-  return (0, import_node_fs28.readdirSync)(wfDir).filter((name) => /\.(ya?ml)$/i.test(name)).filter((name) => {
+  const wfDir = (0, import_node_path26.join)(cwd, ".github", "workflows");
+  if (!(0, import_node_fs29.existsSync)(wfDir)) return [];
+  return (0, import_node_fs29.readdirSync)(wfDir).filter((name) => /\.(ya?ml)$/i.test(name)).filter((name) => {
     try {
-      return workflowReportsPrChecks((0, import_node_fs28.readFileSync)((0, import_node_path25.join)(wfDir, name), "utf8"));
+      return workflowReportsPrChecks((0, import_node_fs29.readFileSync)((0, import_node_path26.join)(wfDir, name), "utf8"));
     } catch {
       return true;
     }
@@ -24558,16 +24791,16 @@ function ciAuditDeps() {
     // gate re-seed step is skipped gracefully rather than failing mid-run.
     readSeedFile: (path2) => {
       if (!root) return null;
-      const fullPath = (0, import_node_path25.join)(root, path2);
-      return (0, import_node_fs28.existsSync)(fullPath) ? (0, import_node_fs28.readFileSync)(fullPath, "utf8") : null;
+      const fullPath = (0, import_node_path26.join)(root, path2);
+      return (0, import_node_fs29.existsSync)(fullPath) ? (0, import_node_fs29.readFileSync)(fullPath, "utf8") : null;
     }
   };
 }
 function hubRoot() {
-  const fromPkg = (0, import_node_path25.join)(__dirname, "..", "..");
+  const fromPkg = (0, import_node_path26.join)(__dirname, "..", "..");
   const marker = "skills/bootstrap/seeds/manifest.json";
-  if ((0, import_node_fs28.existsSync)((0, import_node_path25.join)(fromPkg, marker))) return fromPkg;
-  if ((0, import_node_fs28.existsSync)((0, import_node_path25.join)(process.cwd(), marker))) return process.cwd();
+  if ((0, import_node_fs29.existsSync)((0, import_node_path26.join)(fromPkg, marker))) return fromPkg;
+  if ((0, import_node_fs29.existsSync)((0, import_node_path26.join)(process.cwd(), marker))) return process.cwd();
   return null;
 }
 pr.command("ci-policy").description("report merge CI policy: wait-for-checks vs no-ci (for grind/build agents)").option("--json", "machine-readable output").option("--repo <owner/repo>", "target repo (defaults to the current checkout)").action(async (o) => {
@@ -24806,7 +25039,7 @@ pr.command("merge <number>").description("merge a PR (squash by default) and cle
     localCleanup = await cleanupPrMergeLocalBranch(headRef, {
       beforeWorktrees,
       startingPath,
-      pathExists: (p) => (0, import_node_fs28.existsSync)(p),
+      pathExists: (p) => (0, import_node_fs29.existsSync)(p),
       execGit: async (args) => (await execFileP2("git", args, { timeout: GIT_TIMEOUT_MS })).stdout,
       teardownWorktreeStage,
       deferredStore,
@@ -25146,10 +25379,10 @@ access.command("audit").description("audit collaborator roles + train-branch pus
     targets = resolution.targets;
   }
   const derivedMatrix = registryProjects ? accessMatrixFromProjects(registryProjects) : {};
-  const fileMatrix = (0, import_node_fs28.existsSync)("access-matrix.json") ? loadAccessMatrix((0, import_node_fs28.readFileSync)("access-matrix.json", "utf8")) : {};
+  const fileMatrix = (0, import_node_fs29.existsSync)("access-matrix.json") ? loadAccessMatrix((0, import_node_fs29.readFileSync)("access-matrix.json", "utf8")) : {};
   const matrix = mergeAccessMatrix(fileMatrix, derivedMatrix);
   const derivedContracts = registryProjects ? dataAccessContractsFromProjects(registryProjects) : { consumers: {} };
-  const fileContracts = (0, import_node_fs28.existsSync)("data-access-contracts.json") ? loadDataAccessContracts((0, import_node_fs28.readFileSync)("data-access-contracts.json", "utf8")) : { consumers: {} };
+  const fileContracts = (0, import_node_fs29.existsSync)("data-access-contracts.json") ? loadDataAccessContracts((0, import_node_fs29.readFileSync)("data-access-contracts.json", "utf8")) : { consumers: {} };
   const dataAccess = mergeDataAccessContracts(fileContracts, derivedContracts);
   const report = await auditOrgAccess(targets, deps, matrix, dataAccess);
   console.log(o.json ? JSON.stringify(report, null, 2) : renderAccessReport(report));
@@ -25182,16 +25415,16 @@ function directoryBytes(path2) {
   let total = 0;
   let entries;
   try {
-    entries = (0, import_node_fs28.readdirSync)(path2, { withFileTypes: true });
+    entries = (0, import_node_fs29.readdirSync)(path2, { withFileTypes: true });
   } catch {
     return 0;
   }
   for (const entry of entries) {
-    const child2 = (0, import_node_path25.join)(path2, entry.name);
+    const child2 = (0, import_node_path26.join)(path2, entry.name);
     if (entry.isDirectory()) total += directoryBytes(child2);
     else {
       try {
-        total += (0, import_node_fs28.statSync)(child2).size;
+        total += (0, import_node_fs29.statSync)(child2).size;
       } catch {
       }
     }
@@ -25199,25 +25432,25 @@ function directoryBytes(path2) {
   return total;
 }
 function listDirEntries(dir) {
-  return (0, import_node_fs28.readdirSync)(dir, { withFileTypes: true }).map((d) => ({ name: d.name, isDirectory: d.isDirectory() }));
+  return (0, import_node_fs29.readdirSync)(dir, { withFileTypes: true }).map((d) => ({ name: d.name, isDirectory: d.isDirectory() }));
 }
 function readInstalledPluginRefs(home) {
   const p = installedPluginsPath(home);
-  if (!(0, import_node_fs28.existsSync)(p)) return [];
+  if (!(0, import_node_fs29.existsSync)(p)) return [];
   try {
-    return installedPluginPaths((0, import_node_fs28.readFileSync)(p, "utf8"));
+    return installedPluginPaths((0, import_node_fs29.readFileSync)(p, "utf8"));
   } catch {
     return null;
   }
 }
 function pluginCacheFsDeps(home, dirBytes) {
   return {
-    exists: (p) => (0, import_node_fs28.existsSync)(p),
-    listVersionDirs: (root) => (0, import_node_fs28.readdirSync)(root, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name),
+    exists: (p) => (0, import_node_fs29.existsSync)(p),
+    listVersionDirs: (root) => (0, import_node_fs29.readdirSync)(root, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name),
     dirBytes,
-    listStagingDirs: (root) => (0, import_node_fs28.readdirSync)(root, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => {
+    listStagingDirs: (root) => (0, import_node_fs29.readdirSync)(root, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => {
       try {
-        return { name: d.name, mtimeMs: newestMtimeMs((0, import_node_path25.join)(root, d.name), listDirEntries, (p) => (0, import_node_fs28.statSync)(p).mtimeMs) };
+        return { name: d.name, mtimeMs: newestMtimeMs((0, import_node_path26.join)(root, d.name), listDirEntries, (p) => (0, import_node_fs29.statSync)(p).mtimeMs) };
       } catch {
         return { name: d.name, mtimeMs: Date.now() };
       }
@@ -25231,10 +25464,10 @@ function stagingApplyFsGuard(home) {
   return {
     referencedPaths: () => readInstalledPluginRefs(home),
     mtimeMs: (name) => {
-      const p = (0, import_node_path25.join)(stagingRoot, name);
-      if (!(0, import_node_fs28.existsSync)(p)) return null;
+      const p = (0, import_node_path26.join)(stagingRoot, name);
+      if (!(0, import_node_fs29.existsSync)(p)) return null;
       try {
-        return newestMtimeMs(p, listDirEntries, (q) => (0, import_node_fs28.statSync)(q).mtimeMs);
+        return newestMtimeMs(p, listDirEntries, (q) => (0, import_node_fs29.statSync)(q).mtimeMs);
       } catch {
         return null;
       }
@@ -25250,7 +25483,7 @@ program2.command("plugin-prune").description(`prune stale cached MMI plugin vers
     { withBytes: true }
   );
   const anythingToDelete = plan.prune.length > 0 || plan.staging.length > 0;
-  const result = o.apply && anythingToDelete ? applyPluginCachePlan(plan, (p) => (0, import_node_fs28.rmSync)(p, { recursive: true, force: true }), stagingApplyFsGuard((0, import_node_os8.homedir)())) : void 0;
+  const result = o.apply && anythingToDelete ? applyPluginCachePlan(plan, (p) => (0, import_node_fs29.rmSync)(p, { recursive: true, force: true }), stagingApplyFsGuard((0, import_node_os8.homedir)())) : void 0;
   const warnings = plan.prune.length > 0 ? [CONCURRENT_SESSION_WARNING] : [];
   if (o.json) console.log(JSON.stringify({ ...plan, warnings, applied: result ?? null }));
   else console.log(renderPluginCachePlan(plan, result));
@@ -25283,7 +25516,7 @@ program2.command("session-start").description("run the SessionStart verbs (whoam
       readBoard,
       // #1813: warm the slice cache out-of-band (detached) so the ~20s live read
       // never costs banner time and next session's glance renders instantly within budget.
-      scheduleRefresh: () => spawnDetachedSelf(["board", "slice-refresh", "--quiet"], { spawn: import_node_child_process12.spawn, execPath: process.execPath, scriptPath: process.argv[1] })
+      scheduleRefresh: () => spawnDetachedSelf(["board", "slice-refresh", "--quiet"], { spawn: import_node_child_process13.spawn, execPath: process.execPath, scriptPath: process.argv[1] })
     }),
     // command-ladder hint (#2609): compact gh→mmi-cli cheat sheet so agents reach for mmi-cli first,
     // not after a denied gh call. <1KB, pure in-memory — no network, no fs, fail-soft.
@@ -25314,7 +25547,7 @@ program2.command("session-start").description("run the SessionStart verbs (whoam
   for (const line of scratchGcLines(process.cwd())) consoleIo.log(line);
   const worktreeBanner = worktreeAutoProvisionBanner(process.cwd());
   if (worktreeBanner) {
-    spawnDetachedSelf(["worktree", "setup", "--quiet"], { spawn: import_node_child_process12.spawn, execPath: process.execPath, scriptPath: process.argv[1] });
+    spawnDetachedSelf(["worktree", "setup", "--quiet"], { spawn: import_node_child_process13.spawn, execPath: process.execPath, scriptPath: process.argv[1] });
     consoleIo.log(worktreeBanner);
   }
   appendHookActivity(process.cwd(), { event: "SessionStart", script: "session-start", outcome: "ran", action: "session-start hook completed" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "3.40.0",
+  "version": "3.42.0",
   "description": "MMI Future CLI — the org dev toolbox (board, registry, keyless secrets, release train, bootstrap, doctor) and the cross-IDE engine the plugin's session-start hook drives.",
   "type": "module",
   "license": "UNLICENSED",