@mutmutco/cli 3.89.0 → 3.91.0

package/dist/main.cjs

@@ -4040,6 +4040,56 @@ var execFileP2 = (file, args, options = {}) => (
   rawExecFileP2(file, args, { encoding: "utf8", windowsHide: true, timeout: DEFAULT_EXEC_TIMEOUT_MS, killSignal: "SIGTERM", ...options })
 );
 var GIT_TIMEOUT_MS = DEFAULT_EXEC_TIMEOUT_MS;
+var ExecDeadlineError = class extends Error {
+  constructor(step, timeoutMs, elapsedMs, killed) {
+    super(
+      `\`${step}\` did not finish within ${Math.round(timeoutMs / 1e3)}s (gave up after ${Math.round(elapsedMs / 1e3)}s). It stopped responding and did not exit when asked to, so the timeout alone could not end it; ${killed ? "its process tree was force-terminated" : "its process tree could NOT be terminated and may still be running"}.`
+    );
+    this.step = step;
+    this.timeoutMs = timeoutMs;
+    this.elapsedMs = elapsedMs;
+    this.killed = killed;
+    this.name = "ExecDeadlineError";
+  }
+  step;
+  timeoutMs;
+  elapsedMs;
+  killed;
+};
+function killProcessTree(pid) {
+  try {
+    if (process.platform === "win32") {
+      (0, import_node_child_process3.execFileSync)("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+    } else {
+      process.kill(pid, "SIGKILL");
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+function execFileHard(file, args, options) {
+  const { timeout, step, ...rest } = options;
+  const started = Date.now();
+  return new Promise((resolve5, reject) => {
+    const child2 = (0, import_node_child_process3.execFile)(file, args, { encoding: "utf8", windowsHide: true, ...rest, timeout: 0 }, (error, stdout, stderr) => {
+      clearTimeout(timer);
+      if (expired) return;
+      if (error) reject(error);
+      else resolve5({ stdout: String(stdout), stderr: String(stderr) });
+    });
+    let expired = false;
+    const timer = setTimeout(() => {
+      expired = true;
+      const killed = child2.pid ? killProcessTree(child2.pid) : false;
+      child2.stdout?.destroy();
+      child2.stderr?.destroy();
+      child2.unref();
+      reject(new ExecDeadlineError(step, timeout, Date.now() - started, killed));
+    }, timeout);
+    timer.unref?.();
+  });
+}
 var cachedGithubLogin;
 async function githubLogin() {
   cachedGithubLogin ??= execFileP2("gh", ["api", "user", "--jq", ".login"]).then(({ stdout }) => stdout.trim() || void 0).catch(() => void 0);
@@ -8872,7 +8922,11 @@ function hasUserInstallRecord(file, pluginId) {
 var CLAUDE_PLUGIN_TIMEOUT_MS = 12e4;
 var NPM_VIEW_TIMEOUT_MS = 15e3;
 function runHostBin(bin, args, opts) {
-  return isWin ? execFileP2("cmd.exe", ["/c", bin, ...args], opts) : execFileP2(bin, args, opts);
+  const { step, timeout } = opts;
+  const shared = { timeout, stdio: ["ignore", "pipe", "pipe"], maxBuffer: 16 * 1024 * 1024 };
+  const file = isWin ? "cmd.exe" : bin;
+  const argv = isWin ? ["/c", bin, ...args] : args;
+  return step ? execFileHard(file, argv, { ...shared, step }) : execFileP2(file, argv, shared);
 }
 function surfaceConfigRoot(surface, env = process.env, home = (0, import_node_os4.homedir)()) {
   if (surface === "codex") return env.CODEX_HOME?.trim() || (0, import_node_path14.join)(home, ".codex");
@@ -9050,27 +9104,14 @@ function snapshotPluginGuardInput(surface = detectSurface(process.env), isOrgRep
     ) : (0, import_node_fs15.existsSync)((0, import_node_path14.join)(root, "plugins", "cache", "mutmutco", "mmi"))
   };
 }
-async function runClaudePlugin(args) {
+async function runPluginCli(bin, args, log) {
   try {
-    await runHostBin("claude", args, { timeout: CLAUDE_PLUGIN_TIMEOUT_MS });
+    await runHostBin(bin, args, { timeout: CLAUDE_PLUGIN_TIMEOUT_MS, step: `${bin} ${args.join(" ")}` });
     return true;
-  } catch {
-    return false;
-  }
-}
-async function runCodexPlugin(args) {
-  try {
-    await runHostBin("codex", args, { timeout: CLAUDE_PLUGIN_TIMEOUT_MS });
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function runKiloPlugin(args) {
-  try {
-    await runHostBin("kilo", args, { timeout: CLAUDE_PLUGIN_TIMEOUT_MS });
-    return true;
-  } catch {
+  } catch (error) {
+    if (error instanceof ExecDeadlineError) {
+      log(`  \u2717 ${error.message} Recover with: mmi-cli plugin heal`);
+    }
     return false;
   }
 }
@@ -9131,7 +9172,8 @@ async function installCursorPluginCheckout(env = process.env) {
       });
     } else {
       await runHostBin("gh", ["repo", "clone", "mutmutco/MMI-Hub", staged, "--", "--branch", "main", "--depth", "1"], {
-        timeout: CLAUDE_PLUGIN_TIMEOUT_MS
+        timeout: CLAUDE_PLUGIN_TIMEOUT_MS,
+        step: "gh repo clone mutmutco/MMI-Hub"
       });
     }
     if (!cursorPluginTreeHealthy(staged)) {
@@ -9161,7 +9203,8 @@ async function installCursorPluginCheckout(env = process.env) {
 async function marketplaceAddRefSupported(bin) {
   try {
     const { stdout, stderr } = await runHostBin(bin, ["plugin", "marketplace", "add", "--help"], {
-      timeout: CLAUDE_PLUGIN_TIMEOUT_MS
+      timeout: CLAUDE_PLUGIN_TIMEOUT_MS,
+      step: `${bin} plugin marketplace add --help`
     });
     return marketplaceAddSupportsRef(`${stdout}
 ${stderr}`);
@@ -9191,7 +9234,7 @@ async function applyPluginHeal(surface, log, opts) {
   if (token === "kilo") {
     log("  \u21BB reinstalling the MMI plugin via `kilo plugin` (install \u2192 server() provisions the skills)\u2026");
     for (const step of descriptor.healSteps) {
-      const ok = await runKiloPlugin([...step.args]);
+      const ok = await runPluginCli("kilo", [...step.args], log);
       if (healStepAborts(step, ok)) return false;
     }
     return true;
@@ -9207,7 +9250,7 @@ async function applyPluginHeal(surface, log, opts) {
   const pins = token === "claude" ? captureMarketplacePins(readKnownMarketplacesFile(pinsPath), [MMI_MARKETPLACE_NAME, JERV_MARKETPLACE_NAME]) : /* @__PURE__ */ new Map();
   try {
     for (const step of steps) {
-      const ok = token === "claude" ? await runClaudePlugin([...step.args]) : await runCodexPlugin([...step.args]);
+      const ok = await runPluginCli(token, [...step.args], log);
       if (healStepAborts(step, ok)) return false;
     }
   } finally {
@@ -9270,11 +9313,27 @@ function readKnownMarketplacesFile(path2) {
     return void 0;
   }
 }
-function writeMarketplacePinsOnDisk(path2, pins, succeeded, failedVerb) {
+function claudeCodeIsRunning(env = process.env, listProcesses = defaultProcessList) {
+  if (env.CLAUDE_CODE_SESSION_ID?.trim() || env.CLAUDECODE?.trim() || env.CLAUDE_PLUGIN_ROOT?.trim()) return true;
+  let table;
+  try {
+    table = listProcesses();
+  } catch {
+    return true;
+  }
+  if (!table.trim()) return true;
+  return table.split(/\r?\n/).some((line) => /(^|[/\\])claude(\.(exe|cmd|ps1))?\s/.test(`${line.trim()} `));
+}
+function defaultProcessList() {
+  return isWin ? (0, import_node_child_process6.execFileSync)("powershell.exe", ["-NoProfile", "-Command", "Get-CimInstance Win32_Process | ForEach-Object { $_.CommandLine }"], { encoding: "utf8", windowsHide: true, maxBuffer: 32 * 1024 * 1024, timeout: 15e3 }) : (0, import_node_child_process6.execFileSync)("ps", ["-eo", "args="], { encoding: "utf8", windowsHide: true, timeout: 15e3 });
+}
+function writeMarketplacePinsOnDisk(path2, pins, succeeded, failedVerb, declineWhileHostLive) {
   if (pins.size === 0) return void 0;
   const after = readKnownMarketplacesFile(path2);
   const next = restoreMarketplacePins(after, pins);
   if (next === null) return void 0;
+  const declined = declineWhileHostLive?.();
+  if (declined) return declined;
   try {
     (0, import_node_fs15.writeFileSync)(path2, next, "utf8");
   } catch {
@@ -9287,16 +9346,27 @@ function writeMarketplacePinsOnDisk(path2, pins, succeeded, failedVerb) {
   });
   return failed.length ? `${failedVerb} did NOT take for ${failed.map(([n]) => n).join(", ")} \u2014 set it by hand` : succeeded(pins);
 }
-function restoreMarketplacePinsOnDisk(path2, pins) {
-  return writeMarketplacePinsOnDisk(path2, pins, restoredPinsLine, "restore");
-}
-function applyOrgMarketplacePins(path2, names) {
+function restoreMarketplacePinsOnDisk(path2, pins, hostIsRunning = claudeCodeIsRunning) {
   return writeMarketplacePinsOnDisk(
+    path2,
+    pins,
+    (restored) => hostIsRunning() ? `${restoredPinsLine(restored)}, but Claude Code is running and can rewrite this file from its own copy \u2014 restart it, then \`mmi-cli doctor --apply\` if the pins did not survive` : restoredPinsLine(restored),
+    "restore"
+  );
+}
+function applyOrgMarketplacePins(path2, names, hostIsRunning = claudeCodeIsRunning) {
+  let landed = false;
+  const detail = writeMarketplacePinsOnDisk(
     path2,
     new Map(names.map((name) => [name, ORG_MARKETPLACE_PINS])),
-    (pins) => `pinned ${[...pins.keys()].join(", ")} to ${ORG_MARKETPLACE_PINS.ref} with auto-update on`,
-    "pin"
+    (pins) => {
+      landed = true;
+      return `pinned ${[...pins.keys()].join(", ")} to ${ORG_MARKETPLACE_PINS.ref} with auto-update on`;
+    },
+    "pin",
+    () => hostIsRunning() ? "not pinned \u2014 Claude Code is running and rewrites this registration from its own copy; quit it, then run `mmi-cli doctor --apply`" : void 0
   );
+  return detail === void 0 ? void 0 : { detail, wrote: landed };
 }
 function writeMarketplacePinPending(path2, names, now = Date.now()) {
   try {
@@ -22906,12 +22976,42 @@ var canonicalPriorityColors = { Urgent: "RED", High: "ORANGE", Medium: "YELLOW",
 function miscoloredOptions(options, canon) {
   return (options ?? []).filter((o) => canon[o.name] != null && o.color != null && o.color !== canon[o.name]).map((o) => `${o.name}=${o.color} (want ${canon[o.name]})`);
 }
+function missingBoardViews(views, required) {
+  return required.filter((req) => !views.some((v) => v.name === req.name && v.layout === req.layout));
+}
+function boardGroupingDrift(board, wantColumn, wantSwimlane) {
+  if (!board) return ["no Board view found"];
+  const problems = [];
+  if (!board.verticalGroupByFields.includes(wantColumn)) {
+    problems.push(`columns: ${board.verticalGroupByFields.join(", ") || "none"} (want ${wantColumn})`);
+  }
+  if (!board.groupByFields.includes(wantSwimlane)) {
+    problems.push(`swimlanes: ${board.groupByFields.join(", ") || "none"} (want ${wantSwimlane})`);
+  }
+  return problems;
+}
+function boardCardFieldDrift(visibleFields, canonical) {
+  const have = new Set(visibleFields);
+  const want = new Set(canonical);
+  return {
+    missing: canonical.filter((f) => !have.has(f)),
+    extra: visibleFields.filter((f) => !want.has(f))
+  };
+}
 var requiredProjectWorkflows = [
   "Auto-add sub-issues to project",
   "Auto-archive items",
   "Item added to project",
   "Item closed"
 ];
+var requiredBoardViews = [
+  { name: "List", layout: "TABLE_LAYOUT" },
+  { name: "Board", layout: "BOARD_LAYOUT" },
+  { name: "Roadmap", layout: "ROADMAP_LAYOUT" }
+];
+var requiredBoardColumnField = "Status";
+var requiredBoardSwimlaneField = "Repository";
+var requiredBoardCardFields = ["Title", "Assignees", "Status", "Labels", "Linked pull requests", "Parent issue", "Sub-issues progress", "Priority"];
 var requiredOrgRulesetTypes = ["pull_request", "non_fast_forward", "deletion"];
 var requiredHubStatusChecks = ["cli", "infra", "docs"];
 var requiredProductStatusChecks = ["gate"];
@@ -23260,6 +23360,48 @@ async function verifyBootstrap(repo, repoClass, deps, releaseTrack) {
         label: `Project workflow enabled: ${workflowName}`
       });
     }
+    const viewsQuery = `query($login: String!, $number: Int!) { organization(login: $login) { projectV2(number: $number) { views(first: 10) { nodes { name layout groupByFields(first: 5) { nodes { ... on ProjectV2FieldCommon { name } } } verticalGroupByFields(first: 5) { nodes { ... on ProjectV2FieldCommon { name } } } visibleFields(first: 20) { nodes { ... on ProjectV2FieldCommon { name } } } } } } } }`;
+    const boardViews = await (async () => {
+      try {
+        const data = await deps.client.graphql(viewsQuery, {
+          login: config.projectOwner,
+          number: config.projectNumber
+        });
+        const nodes = data.organization?.projectV2?.views?.nodes ?? [];
+        const names = (conn) => (conn?.nodes ?? []).filter((f) => Boolean(f?.name)).map((f) => f.name);
+        return nodes.filter((v) => Boolean(v)).map((v) => ({
+          name: v.name,
+          layout: v.layout,
+          groupByFields: names(v.groupByFields),
+          verticalGroupByFields: names(v.verticalGroupByFields),
+          visibleFields: names(v.visibleFields)
+        }));
+      } catch {
+        return [];
+      }
+    })();
+    const missingViews = missingBoardViews(boardViews, requiredBoardViews);
+    checks.push({
+      ok: missingViews.length === 0,
+      label: "Project view triple present: List/Board/Roadmap (#4093)",
+      detail: missingViews.length ? `missing: ${missingViews.map((v) => `${v.name} (${v.layout})`).join(", ")} \u2014 createProjectV2View/updateProjectV2View is API-writable (name + layout)` : void 0
+    });
+    const boardView = boardViews.find((v) => v.layout === "BOARD_LAYOUT");
+    const groupingDrift = boardGroupingDrift(boardView, requiredBoardColumnField, requiredBoardSwimlaneField);
+    checks.push({
+      ok: groupingDrift.length === 0,
+      label: `Board view grouped by ${requiredBoardColumnField} columns / ${requiredBoardSwimlaneField} swimlanes (#4093)`,
+      detail: groupingDrift.length ? `${groupingDrift.join("; ")} \u2014 GitHub exposes no create/update mutation for view grouping (ProjectV2ViewConfigurationInput carries only visibleFieldIds); fix in the UI: Board view \u2192 \u2699 (top-right) \u2192 Group by \u2192 ${requiredBoardColumnField}, Swimlanes \u2192 ${requiredBoardSwimlaneField} \u2192 Save view` : void 0
+    });
+    const cardDrift = boardCardFieldDrift(boardView?.visibleFields ?? [], requiredBoardCardFields);
+    checks.push({
+      ok: cardDrift.missing.length === 0 && cardDrift.extra.length === 0,
+      label: "Board view card fields match the org standard (#4093)",
+      detail: cardDrift.missing.length || cardDrift.extra.length ? `${[
+        cardDrift.missing.length ? `missing: ${cardDrift.missing.join(", ")}` : null,
+        cardDrift.extra.length ? `extra: ${cardDrift.extra.join(", ")}` : null
+      ].filter(Boolean).join("; ")} \u2014 API-writable via updateProjectV2View(configuration:{visibleFieldIds:[...]}); fix in the UI (Board view \u2192 Fields) or that mutation` : void 0
+    });
   }
   const projectRegistry = localRegistryCheck(deps, "projects.json", (json) => Array.isArray(json?.projects) && projectRegistryIncludesRepo(json.projects, repo));
   if (projectRegistry != null) checks.push({ ok: projectRegistry, label: "project registry includes repo" });
@@ -24037,27 +24179,41 @@ function decideStage(inputs) {
 var import_node_net2 = require("node:net");
 var STAGE_LIVE_HUB_REPO = "mutmutco/MMI-Hub";
 var IP_ECHO_URL = "https://api.ipify.org";
+var IP6_ECHO_URL = "https://api6.ipify.org";
 var IP_DETECT_TIMEOUT_MS = 1e4;
 function validStageLiveIp(ip) {
   return (0, import_node_net2.isIP)(ip.trim()) !== 0;
 }
 async function detectPublicIp(fetchImpl = fetch) {
+  return detectPublicIpFrom(IP_ECHO_URL, fetchImpl);
+}
+async function detectCallerIps(fetchImpl = fetch) {
+  const [v4, v6] = await Promise.allSettled([
+    detectPublicIp(fetchImpl),
+    detectPublicIpFrom(IP6_ECHO_URL, fetchImpl)
+  ]);
+  if (v4.status === "rejected") throw v4.reason;
+  const ip = v4.value;
+  const candidate = v6.status === "fulfilled" ? v6.value : void 0;
+  return { ip, ip6: candidate && (0, import_node_net2.isIP)(candidate) === 6 ? candidate : void 0 };
+}
+async function detectPublicIpFrom(url, fetchImpl) {
   let res;
   try {
-    res = await fetchImpl(IP_ECHO_URL, { signal: AbortSignal.timeout(IP_DETECT_TIMEOUT_MS) });
+    res = await fetchImpl(url, { signal: AbortSignal.timeout(IP_DETECT_TIMEOUT_MS) });
   } catch (e) {
-    throw new Error(`public IP detection failed (${IP_ECHO_URL}): ${e.message}`);
+    throw new Error(`public IP detection failed (${url}): ${e.message}`);
   }
-  if (!res.ok) throw new Error(`public IP detection failed: HTTP ${res.status} from ${IP_ECHO_URL}`);
+  if (!res.ok) throw new Error(`public IP detection failed: HTTP ${res.status} from ${url}`);
   const ip = (await res.text()).trim();
-  if (!validStageLiveIp(ip)) throw new Error(`public IP detection returned a non-IP body from ${IP_ECHO_URL}: "${ip.slice(0, 80)}"`);
+  if (!validStageLiveIp(ip)) throw new Error(`public IP detection returned a non-IP body from ${url}: "${ip.slice(0, 80)}"`);
   return ip;
 }
 function stageLiveUpSteps(t) {
   return [
-    { label: `detect your public IP (${IP_ECHO_URL}, bounded)` },
+    { label: `detect your public IPv4 and IPv6 (${IP_ECHO_URL} + ${IP6_ECHO_URL}, bounded, in parallel)` },
     { label: `deploy ${t.ref ?? "<current branch>"} to the ${t.slug} dev stage via the Hub backend (tenant-deploy)` },
-    { label: `gate ${t.host} to your IP at the Cloudflare edge via the Hub backend (tenant-control cf-gate-allow)` },
+    { label: `gate ${t.host} to your IPv4 and your IPv6 /64 at the Cloudflare edge via the Hub backend (tenant-control cf-gate-allow)` },
     { label: "tear down when done", command: "mmi-cli stage --live --down --apply" }
   ];
 }
@@ -24069,11 +24225,14 @@ function stageLiveDownSteps(t) {
 }
 async function runStageLiveUp(deps, t) {
   if (!t.ref?.trim()) throw new Error("stage --live: cannot resolve the current branch to deploy");
-  const ip = (await deps.detectIp()).trim();
+  const detected = await deps.detectIp();
+  const ip = detected.ip.trim();
   if (!validStageLiveIp(ip)) throw new Error(`stage --live: detected public IP is not a literal IPv4/IPv6 address: "${ip.slice(0, 80)}"`);
+  const ip6 = detected.ip6?.trim() || void 0;
   if (!t.host?.trim()) throw new Error("stage --live: cannot resolve the dev edge host (registry edgeDomains.dev)");
   await deps.deployDev({ repo: t.repo, ref: t.ref });
-  await deps.control({ repo: t.repo, action: "cf-gate-allow", host: t.host, ip });
+  await deps.control({ repo: t.repo, action: "cf-gate-allow", host: t.host, ip, ip6 });
+  const allowed = ip6 ? `${ip} and your IPv6 /64 prefix (from ${ip6})` : `${ip} (IPv4 only \u2014 no public IPv6 detected)`;
   return {
     command: "stage --live",
     mode: "up",
@@ -24081,10 +24240,11 @@ async function runStageLiveUp(deps, t) {
     repo: t.repo,
     ref: t.ref,
     ip,
+    ip6,
     dispatched: ["tenant-deploy.yml", "tenant-control.yml"],
     // #2656: the gate now writes a skip+block pair and self-verifies from the runner (a non-allowed vantage),
     // so a gate that failed to close fails the run RED. The stage is private only once that gate run is green.
-    message: `dispatched the dev deploy of ${t.ref} and the Cloudflare edge gate for ${t.host} \u2192 ${ip}; watch the runs in ${STAGE_LIVE_HUB_REPO} Actions and treat the stage as private ONLY once the cf-gate-allow run is green (it self-verifies the host is blocked) \u2014 tear down with: mmi-cli stage --live --down --apply`
+    message: `dispatched the dev deploy of ${t.ref} and the Cloudflare edge gate for ${t.host} \u2192 ${allowed}; watch the runs in ${STAGE_LIVE_HUB_REPO} Actions and treat the stage as private ONLY once the cf-gate-allow run is green (it self-verifies the host is blocked) \u2014 tear down with: mmi-cli stage --live --down --apply`
   };
 }
 async function runStageLiveDown(deps, t) {
@@ -24221,13 +24381,13 @@ function registerStageCommands(program3) {
     }
     const rcDeps = registryClientDeps(await loadConfig());
     const deps = {
-      detectIp: () => detectPublicIp(),
+      detectIp: () => detectCallerIps(),
       deployDev: async ({ repo, ref }) => {
         const res = await tenantDeploy({ repo, stage: "dev", ref }, rcDeps);
         if (!res.ok) throw new Error(`dev deploy dispatch failed: ${res.body?.error ?? res.error ?? `HTTP ${res.status}`}`);
       },
-      control: async ({ repo, action, host, ip }) => {
-        const res = await tenantControl({ repo, stage: "dev", action, host, ip }, rcDeps);
+      control: async ({ repo, action, host, ip, ip6 }) => {
+        const res = await tenantControl({ repo, stage: "dev", action, host, ip, ip6 }, rcDeps);
         if (!res.ok) throw new Error(`runtime tenant control ${action} dispatch failed: ${res.body?.error ?? res.error ?? `HTTP ${res.status}`}`);
       }
     };
@@ -25419,6 +25579,88 @@ async function fetchRestCorePool(gh = defaultGhApi) {
   }
 }
 
+// src/pr-create-docs-check.ts
+var GIT_TIMEOUT_MS2 = 15e3;
+function createPrCreateDocsIndexDeps() {
+  return {
+    worktreeRoot: async () => {
+      try {
+        const { stdout } = await execFileP2("git", ["rev-parse", "--show-toplevel"], { timeout: GIT_TIMEOUT_MS2 });
+        return stdout.trim() || void 0;
+      } catch {
+        return void 0;
+      }
+    },
+    originRepo: async (root) => {
+      try {
+        const { stdout } = await execFileP2("git", ["-C", root, "remote", "get-url", "origin"], { timeout: GIT_TIMEOUT_MS2 });
+        return repoFromRemoteUrl(stdout.trim());
+      } catch {
+        return void 0;
+      }
+    },
+    refResolves: async (root, ref) => {
+      try {
+        await execFileP2("git", ["-C", root, "rev-parse", "--verify", "--quiet", `${ref}^{commit}`], { timeout: GIT_TIMEOUT_MS2 });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    listDocsAtRef: async (root, ref) => {
+      try {
+        const { stdout } = await execFileP2("git", ["-C", root, "ls-tree", "-r", "--name-only", ref, "--", "docs"], { timeout: GIT_TIMEOUT_MS2 });
+        return stdout.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+      } catch {
+        return [];
+      }
+    },
+    readAtRef: async (root, ref, path2) => {
+      try {
+        const { stdout } = await execFileP2("git", ["-C", root, "show", `${ref}:${path2}`], { timeout: GIT_TIMEOUT_MS2 });
+        return stdout;
+      } catch {
+        return void 0;
+      }
+    }
+  };
+}
+async function checkDocsIndexAtHead(opts, deps) {
+  const root = await deps.worktreeRoot();
+  if (!root) return void 0;
+  if (opts.repo) {
+    const origin = await deps.originRepo(root);
+    if (!origin || origin.toLowerCase() !== opts.repo.toLowerCase()) return void 0;
+  }
+  const ref = opts.head || "HEAD";
+  if (!await deps.refResolves(root, ref)) return void 0;
+  const paths = await deps.listDocsAtRef(root, ref);
+  if (!paths.includes(DOCS_INDEX_PATH)) return void 0;
+  const relDocs = paths.filter((p) => p.startsWith("docs/")).map((p) => p.slice("docs/".length)).filter(isRoutableDocsPath);
+  const [indexContent, docContents] = await Promise.all([
+    deps.readAtRef(root, ref, DOCS_INDEX_PATH),
+    Promise.all(relDocs.map((rel) => deps.readAtRef(root, ref, `docs/${rel}`)))
+  ]);
+  const contentByPath = new Map(relDocs.map((rel, i) => [rel, docContents[i] ?? ""]));
+  const atRefDeps = {
+    listDocs: () => relDocs,
+    readDoc: (rel) => contentByPath.get(rel) ?? "",
+    readIndex: () => indexContent ?? null,
+    writeIndex: () => {
+      throw new Error("checkDocsIndexAtHead: read-only \u2014 a commit ref is never written to");
+    }
+  };
+  const result = docsIndex(atRefDeps, { check: true });
+  if (!result.drift) {
+    return { ok: true, detail: `${DOCS_INDEX_PATH} matches the docs/ tree at ${ref === "HEAD" ? "HEAD" : ref}` };
+  }
+  return {
+    ok: false,
+    detail: `${DOCS_INDEX_PATH} is stale at the commit this PR would open from \u2014 it no longer matches the docs/ tree there`,
+    fix: "run `mmi-cli docs index --write`, commit docs/index.md, and push again before retrying `pr create`"
+  };
+}
+
 // src/worktree-lifecycle-commands.ts
 var import_node_fs31 = require("node:fs");
 var import_promises9 = require("node:fs/promises");
@@ -28911,6 +29153,32 @@ function checkSessionPayload(probe) {
     verbose: evidence
   };
 }
+function checkDocsIndex(probe) {
+  if (!probe) return null;
+  const evidence = [
+    // The WORKING TREE, said out loud. This row reads disk and never asks git what is staged or committed,
+    // so it must not claim to have measured the commit: a developer who ran `--write` and has not committed
+    // has a current tree and a stale HEAD, and a row that said "committed: current" there would be the one
+    // failure this check exists to prevent, one layer down. Closing that gap belongs to the surface that
+    // knows about commits (`pr create`, #4092), not to a local hygiene reading.
+    `${DOCS_INDEX_PATH}: read from the working tree, not from HEAD`,
+    `records indexed: ${probe.docCount}`,
+    // Named because it is the one thing a Windows operator reproducing a CI failure needs to trust the
+    // verdict: the comparison normalizes CRLF, so this row and the Linux gate agree on the same content (#3411).
+    "comparison: eol-insensitive, against the index the generator renders now"
+  ];
+  if (!probe.drift) {
+    return { ok: true, id: "docs-index", label: "docs index", detail: "current", verbose: evidence };
+  }
+  return {
+    ok: false,
+    id: "docs-index",
+    label: "docs index",
+    detail: "stale \u2014 docs/index.md no longer matches the docs/ tree",
+    fix: "run `mmi-cli docs index --write` and commit docs/index.md",
+    verbose: evidence
+  };
+}
 function planGitignore(current) {
   const { content, changed } = upsertManagedGitignoreBlock(current);
   return changed ? { ok: false, content } : { ok: true };
@@ -29058,8 +29326,8 @@ async function runDoctorClean(opts, io, deps) {
     if (applyEnv) {
       const healed = deps.healMarketplacePins();
       if (healed) {
-        healIntent(`marketplace pins \u2014 ${healed}`);
-        restartPending = true;
+        healIntent(`marketplace pins \u2014 ${healed.detail}`);
+        if (healed.wrote) restartPending = true;
       }
     }
     for (const row of deps.marketplaceRows()) emitNow(row);
@@ -29078,6 +29346,28 @@ async function runDoctorClean(opts, io, deps) {
       });
     }
   }
+  async function runDocsIndexRow() {
+    let probe;
+    try {
+      probe = deps.docsIndexState(await deps.repoRoot());
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      emitNow({
+        ok: false,
+        id: "docs-index",
+        label: "docs index",
+        // The measurement goes in `detail` and the one next action in `fix`, per docs/doctor-contract.md
+        // § check model — never the error text stapled to the front of the advice, and never "re-run the
+        // read that just failed" as the action.
+        detail: `could not be read \u2014 ${message}`,
+        fix: "repair the docs/ tree this repo cannot walk, then re-run doctor",
+        verbose: [`probe threw: ${message}`]
+      });
+      return;
+    }
+    const docs2 = checkDocsIndex(probe);
+    if (docs2) emitNow(docs2);
+  }
   async function runHousekeeperRows() {
     const repoRoot2 = await deps.repoRoot();
     try {
@@ -29148,6 +29438,9 @@ async function runDoctorClean(opts, io, deps) {
     { id: "plugin-cache", when: true, run: runPluginCacheRow },
     { id: "sessionstart-payload", when: true, run: runSessionPayloadRow },
     { id: "marketplace", when: true, run: runMarketplaceRows },
+    // A `docs/` tree walk plus one batched `git check-ignore` — cheap next to the two rows below it, but a
+    // disk walk and a subprocess all the same, so full lane only (#4091).
+    { id: "docs-index", when: isOrgRepo && lane.full, run: runDocsIndexRow },
     // The two most expensive things in this file — a real `git fetch` plus train-branch fast-forward,
     // and a `gh`-backed gc sweep with a 20s timeout — so org repos on the full lane only (#3485).
     { id: "train-branches", when: isOrgRepo && lane.full, run: runTrainSyncRow },
@@ -29589,13 +29882,29 @@ function mmiDoctorDeps(opts = {}) {
         const home = (0, import_node_os14.homedir)();
         const names = [MMI_MARKETPLACE_NAME];
         const result = applyOrgMarketplacePins((0, import_node_path35.join)(home, ...KNOWN_MARKETPLACES_RELATIVE), names);
-        if (result?.startsWith("pinned ")) {
+        if (result?.wrote) {
           writeMarketplacePinPending((0, import_node_path35.join)(home, ".claude", "plugins", ".mmi-marketplace-pin-pending.json"), names);
         }
         return result;
       } catch {
         return void 0;
       }
+    },
+    // #4091: the same `docs index --check` comparison the required CI gate runs, in-process. Rooted at the
+    // repo root doctor already resolved — never `process.cwd()`, which would have `mmi-cli doctor` run from
+    // `cli/` measure a `cli/docs/` tree that does not exist.
+    //
+    // `existsSync` on `docs/index.md` is the adoption gate, and it sits UNDER the table's org-repo gate
+    // rather than replacing it: a missing index is drift by construction, so without this a repo that never
+    // adopted the generated routing index (MMG-Unlive: `docs/Archive/**` only, no index, no gate.yml) would
+    // get a permanent ✗ demanding an artifact it never asked for.
+    docsIndexState: (root) => {
+      if (!(0, import_node_fs36.existsSync)((0, import_node_path35.join)(root, DOCS_INDEX_PATH))) return void 0;
+      const real = createDocsIndexDeps(root);
+      let docs2;
+      const listDocs = () => docs2 ??= real.listDocs();
+      const drift = docsIndex({ ...real, listDocs }, { check: true }).drift;
+      return { drift, docCount: listDocs().length };
     }
   };
 }
@@ -31440,6 +31749,10 @@ withExamples(pr.command("create").description("create a PR and print {number,url
     return fail(`pr create: ${e.message}`, e instanceof TextArgError ? { code: e.code, offending_flag: e.offendingFlag } : void 0);
   }
   body = normalizeClosingDirectives(body);
+  const docsCheck = await checkDocsIndexAtHead({ repo: o.repo, head: o.head }, createPrCreateDocsIndexDeps());
+  if (docsCheck && !docsCheck.ok) {
+    return fail(`pr create: ${docsCheck.detail} \u2014 ${docsCheck.fix}`);
+  }
   const created = await ghCreate(buildPrArgs({ title, body, base: o.base, head: o.head, repo: o.repo, draft: o.draft }));
   console.log(JSON.stringify(created));
 }), [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "3.89.0",
+  "version": "3.91.0",
   "description": "MMI Future CLI — the org dev toolbox and shared cross-IDE engine for every registry-declared MMI coding surface.",
   "type": "module",
   "license": "UNLICENSED",