@mutmutco/cli 0.8.2 → 0.10.0

package/README.md

@@ -10,6 +10,12 @@ This package is published from [mutmutco/MMI-Hub](https://github.com/mutmutco/MM
 npm install -g @mutmutco/cli
 ```
 
+Authenticate GitHub once for saga and Project board operations:
+
+```powershell
+gh auth login --hostname github.com --git-protocol https --web --scopes "project"
+```
+
 Then verify the installed command:
 
 ```powershell

package/dist/index.cjs

@@ -3038,7 +3038,7 @@ var {
 
 // src/index.ts
 var import_promises = require("node:fs/promises");
-var import_node_fs2 = require("node:fs");
+var import_node_fs3 = require("node:fs");
 var import_node_crypto = require("node:crypto");
 
 // src/rules-sync.ts
@@ -3052,6 +3052,18 @@ function needsUpdate(source, current) {
 function isRulesSource(orgRulesSource) {
   return orgRulesSource === "self";
 }
+function rulesSourceAuthHeaders(sourceUrl, token) {
+  if (!token) return void 0;
+  try {
+    const host = new URL(sourceUrl).hostname.toLowerCase();
+    if (host === "raw.githubusercontent.com" || host === "api.github.com") {
+      return { Authorization: `Bearer ${token}` };
+    }
+  } catch {
+    return void 0;
+  }
+  return void 0;
+}
 
 // src/saga-capture.ts
 function parseHookInput(stdin) {
@@ -3064,9 +3076,9 @@ function parseHookInput(stdin) {
 }
 
 // src/index.ts
-var import_node_child_process3 = require("node:child_process");
-var import_node_util2 = require("node:util");
-var import_node_path2 = require("node:path");
+var import_node_child_process4 = require("node:child_process");
+var import_node_util3 = require("node:util");
+var import_node_path4 = require("node:path");
 
 // src/saga-head-maintainer.ts
 var import_node_child_process = require("node:child_process");
@@ -3099,13 +3111,18 @@ function markHeadRun(path, now = Date.now()) {
 }
 function headPrompt(state) {
   return [
-    "You maintain two durable slots of a work-session: GOAL (the current objective) and PINNED (things",
-    "worth remembering). Given the CURRENT HEAD and the recent TRANSCRIPT + DECISIONS, return an updated",
-    "GOAL and PINNED only. Keep them tight and concrete; keep anything the user pinned; never invent;",
-    "preserve Turkish characters (\xE7 \u011F \u0131 \u0130 \xF6 \u015F \xFC) exactly. Do NOT manage next or the checklist \u2014 the note",
-    "path owns those. Never restate an unverified artifact-claim (a named file, PR, flag, or board state)",
+    "You maintain ONE durable slot of a work-session: PINNED (things worth remembering). Given the CURRENT",
+    "HEAD and the recent TRANSCRIPT + DECISIONS, return an updated PINNED only. Keep it tight and concrete;",
+    "keep anything the user pinned; never invent; preserve Turkish characters (\xE7 \u011F \u0131 \u0130 \xF6 \u015F \xFC) exactly. Do",
+    "NOT manage next or the checklist \u2014 the note path owns those. The ANCHOR is the read-only North-Star \u2014",
+    "NEVER change it. Never restate an unverified artifact-claim (a named file, PR, flag, or board state)",
     "as settled fact \u2014 keep it as the belief it was recorded as.",
-    'Output ONLY a JSON object: {"goal":string,"pinned":[string]}.',
+    "You MAY also propose supersessions: each DECISION is shown with a stable 0-based index. Propose a",
+    "supersession ONLY for a NEWER decision that directly contradicts/replaces an OLDER one where neither",
+    "already carries a supersededBy. HIGH PRECISION \u2014 propose ONLY when you are confident the older claim",
+    "is now false or obsolete; the newer decision's timestamp MUST be later than the older's (newer-supersedes-",
+    "older only, never the reverse). When unsure, propose nothing. NEVER touch the anchor, next, or checklist.",
+    'Output ONLY a JSON object: {"pinned":[string],"supersede":[{"older":int,"newer":int,"reason":string}]}.',
     "",
     "CURRENT HEAD:",
     JSON.stringify(state.head ?? {}, null, 2),
@@ -3114,7 +3131,7 @@ function headPrompt(state) {
     JSON.stringify(state.actionLog ?? []),
     "",
     "DECISIONS:",
-    (state.decisions ?? []).map((d) => `- ${d}`).join("\n") || "(none)"
+    (state.decisions ?? []).map((d, i) => `[${i}] ${d}`).join("\n") || "(none)"
   ].join("\n");
 }
 function parseHeadUpdate(raw) {
@@ -3128,16 +3145,23 @@ function parseHeadUpdate(raw) {
   }
   if (!obj || typeof obj !== "object") return null;
   const u = {};
-  if (typeof obj.goal === "string") u.goal = obj.goal;
   if (Array.isArray(obj.pinned)) u.pinned = obj.pinned.filter((x) => typeof x === "string");
+  if (Array.isArray(obj.supersede)) {
+    const supersede = obj.supersede.filter((e) => {
+      if (!e || typeof e !== "object") return false;
+      const { older, newer, reason } = e;
+      return Number.isInteger(older) && older >= 0 && Number.isInteger(newer) && newer >= 0 && older !== newer && typeof reason === "string" && reason.length > 0;
+    }).map((e) => ({ older: e.older, newer: e.newer, reason: e.reason }));
+    if (supersede.length) u.supersede = supersede;
+  }
   return Object.keys(u).length ? u : null;
 }
 async function runHeadEngine(prompt, timeoutMs = HEAD_ENGINE_TIMEOUT_MS) {
-  const { cmd, args, shell } = resolveEngine(process.platform, process.env.SAGA_HEAD_ENGINE);
+  const { cmd, args, shell: shell2 } = resolveEngine(process.platform, process.env.SAGA_HEAD_ENGINE);
   return await new Promise((resolve) => {
     let child;
     try {
-      child = (0, import_node_child_process.spawn)(cmd, args, { shell, windowsHide: true });
+      child = (0, import_node_child_process.spawn)(cmd, args, { shell: shell2, windowsHide: true });
     } catch {
       return resolve("");
     }
@@ -3246,11 +3270,12 @@ function buildNoteCapture(summary, o, id, evidence) {
   const queueOp = o.queueAdd ? { op: "add", text: o.queueAdd } : o.queueDone != null ? { op: "done", index: Number(o.queueDone) } : void 0;
   const state = o.diagnostic ? "diagnostic" : o.verified ? "verified" : "asserted";
   const source = o.diagnostic ? "probe" : "note";
-  const anchor = {};
-  if (evidence.sha) anchor.sha = evidence.sha;
-  if (evidence.branch) anchor.branch = evidence.branch;
-  if (evidence.pr) anchor.pr = evidence.pr;
-  if (evidence.file) anchor.file = evidence.file;
+  const ev = {};
+  if (evidence.sha) ev.sha = evidence.sha;
+  if (evidence.branch) ev.branch = evidence.branch;
+  if (evidence.pr) ev.pr = evidence.pr;
+  if (evidence.file) ev.file = evidence.file;
+  const anchor = o.anchor ? { intent: o.anchor, setAt: (/* @__PURE__ */ new Date()).toISOString() } : void 0;
   return {
     event: "note",
     id,
@@ -3260,14 +3285,17 @@ function buildNoteCapture(summary, o, id, evidence) {
     queueOp,
     state,
     source,
-    evidence: Object.keys(anchor).length ? anchor : void 0,
-    surface: process.env.MMI_AGENT_SURFACE || "claude"
+    evidence: Object.keys(ev).length ? ev : void 0,
+    surface: process.env.MMI_AGENT_SURFACE || "claude",
+    supersedes: o.supersedes,
+    anchor,
+    anchorForce: o.anchorForce || void 0
   };
 }
 
 // src/version-lag.ts
 var VERSION_LABEL = "installed plugin/adapter cache freshness";
-var VERSION_FIX = "refresh/update the MMI plugin, or run the repo-local CLI: node cli/dist/index.cjs doctor --json";
+var VERSION_FIX = "update the MMI plugin via /plugin; standalone npm CLI: npm install -g @mutmutco/cli@latest";
 function parseVersion(v) {
   return v.replace(/^v/, "").split(/[.-]/).slice(0, 3).map((part) => {
     const n = Number.parseInt(part, 10);
@@ -3824,41 +3852,41 @@ function parseWorktreePorcelain(stdout) {
   }
   return out;
 }
-function formatGcPlan(plan, apply) {
+function formatGcPlan(plan2, apply) {
   const lines = [`mmi-cli gc: ${apply ? "apply" : "dry-run"}`];
-  if (!plan.branches.length && !plan.trackingRefs.length) lines.push("nothing to clean");
-  if (plan.branches.length) {
+  if (!plan2.branches.length && !plan2.trackingRefs.length) lines.push("nothing to clean");
+  if (plan2.branches.length) {
     lines.push("local branches:");
-    for (const b of plan.branches) {
+    for (const b of plan2.branches) {
       const prs = b.prNumbers.length ? ` #${b.prNumbers.join(",#")}` : "";
       const wt = b.worktreePath ? ` (worktree: ${b.worktreePath})` : "";
       lines.push(` - ${b.branch} (${b.prState}${prs})${wt}`);
     }
   }
-  if (plan.trackingRefs.length) {
+  if (plan2.trackingRefs.length) {
     lines.push("stale tracking refs:");
-    for (const r of plan.trackingRefs) {
+    for (const r of plan2.trackingRefs) {
       const prs = r.prNumbers.length ? ` #${r.prNumbers.join(",#")}` : "";
       lines.push(` - ${r.ref} (${r.prState}${prs})`);
     }
   }
-  if (plan.skipped.length) {
+  if (plan2.skipped.length) {
     lines.push("skipped:");
-    for (const s of plan.skipped) {
+    for (const s of plan2.skipped) {
       lines.push(` - ${s.branch}: ${s.reason}${s.detail ? ` (${s.detail})` : ""}`);
     }
   }
-  if (!apply && (plan.branches.length || plan.trackingRefs.length)) lines.push("rerun with --apply to delete only the listed items");
+  if (!apply && (plan2.branches.length || plan2.trackingRefs.length)) lines.push("rerun with --apply to delete only the listed items");
   return lines.join("\n");
 }
 
 // src/command-plans.ts
-function stagePlan(stage = {}) {
+function stagePlan(stage2 = {}) {
   return [
     { label: "force-kill previous local stage", command: "mmi-cli stage stop --apply" },
-    { label: "run local build", command: stage.build || "(no stage.build configured)" },
-    { label: "start local stage", command: stage.up || "(no stage.up configured)" },
-    { label: "check health", command: stage.healthUrl ? `curl --fail ${stage.healthUrl}` : "(no stage.healthUrl configured)" }
+    { label: "run local build", command: stage2.build || "(no stage.build configured)" },
+    { label: "start local stage", command: stage2.up || "(no stage.up configured)" },
+    { label: "check health", command: stage2.healthUrl ? `curl --fail ${stage2.healthUrl}` : "(no stage.healthUrl configured)" }
   ];
 }
 function trainPlan(command) {
@@ -3886,26 +3914,492 @@ function trainPlan(command) {
   ];
 }
 function bootstrapPlan(repo, repoClass) {
-  const branches = repoClass === "content" ? "main" : "development, rc, main";
+  const branchModel = repoClass === "content" ? "content repo: main only" : "deployable repo: development, rc, main";
+  const protectedBranches = repoClass === "content" ? "main" : "development, rc, main";
   return [
     { label: `create or inspect ${repo}` },
-    { label: `provision branches: ${branches}`, gated: true },
-    { label: "apply branch protection / train allowlist", gated: true },
-    { label: "attach GitHub Project v2 and write .mmi/config.json", gated: true },
-    { label: "seed README.md and architecture.md", gated: true },
-    { label: "install plugin settings and register fanout", gated: true }
+    { label: `provision branch model: ${branchModel}`, gated: true },
+    { label: `apply branch protection / allowlist: ${protectedBranches}`, gated: true },
+    { label: "attach GitHub Project v2 and write saga-ready .mmi/config.json", gated: true },
+    { label: "seed README.md, architecture.md, AGENTS.md, and CLAUDE.md", gated: true },
+    { label: "commit .claude/settings.json and .cursor/rules/<repo>.mdc", gated: true },
+    { label: `register fanout target on ${repoClass === "content" ? "main" : "development"}`, gated: true }
   ];
 }
 
-// src/index.ts
+// src/doctor.ts
+var GH_PROJECT_LOGIN_FIX = 'run: gh auth login --hostname github.com --git-protocol https --web --scopes "project"';
+function buildGithubAuthCheck(input) {
+  const ok = Boolean(input.login?.trim());
+  return {
+    ok,
+    label: "GitHub auth identity (saga + gh ops)",
+    fix: input.ghInstalled ? GH_PROJECT_LOGIN_FIX : `install GitHub CLI (https://cli.github.com), then: ${GH_PROJECT_LOGIN_FIX.replace(/^run: /, "")}`
+  };
+}
+
+// src/stage-runner.ts
+var import_node_child_process3 = require("node:child_process");
+var import_node_fs2 = require("node:fs");
+var import_node_path2 = require("node:path");
+var import_node_util2 = require("node:util");
 var execFileP2 = (0, import_node_util2.promisify)(import_node_child_process3.execFile);
+function stageStatePath(cwd = process.cwd()) {
+  return (0, import_node_path2.join)(cwd, "tmp", "stage", "state.json");
+}
+function validateStageConfig(config = {}, action) {
+  const problems = [];
+  if (action === "run" && !config.build?.trim()) problems.push("stage.build is required for stage run");
+  if (!config.up?.trim()) problems.push("stage.up is required to start the local stage");
+  if (config.healthUrl != null && config.healthUrl.trim() && !/^https?:\/\//.test(config.healthUrl.trim())) {
+    problems.push("stage.healthUrl must be an http(s) URL");
+  }
+  return problems;
+}
+async function shell(command, cwd, timeoutMs) {
+  await execFileP2(command, [], {
+    cwd,
+    shell: true,
+    timeout: timeoutMs,
+    windowsHide: true,
+    maxBuffer: 1024 * 1024 * 4
+  });
+}
+function readState(path) {
+  if (!(0, import_node_fs2.existsSync)(path)) return null;
+  try {
+    return JSON.parse((0, import_node_fs2.readFileSync)(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function killTree(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  if (process.platform === "win32") {
+    await execFileP2("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true }).catch(() => void 0);
+    return;
+  }
+  try {
+    process.kill(-pid, "SIGTERM");
+  } catch {
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+    }
+  }
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+    }
+  }
+}
+async function waitForHealth(url, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let last = "";
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(Math.min(5e3, timeoutMs)) });
+      if (res.ok) return;
+      last = `HTTP ${res.status}`;
+    } catch (e) {
+      last = e.message;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 1e3));
+  }
+  throw new Error(`stage health check timed out for ${url}${last ? ` (${last})` : ""}`);
+}
+async function stopStage(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const statePath = opts.statePath ?? stageStatePath(cwd);
+  const state = readState(statePath);
+  if (!state) {
+    return { ok: true, action: "stop", statePath, message: "no previous stage state found" };
+  }
+  await killTree(state.pid);
+  (0, import_node_fs2.rmSync)(statePath, { force: true });
+  return { ok: true, action: "stop", statePath, pid: state.pid, message: `stopped previous stage pid ${state.pid}` };
+}
+async function startStage(config = {}, opts = {}) {
+  const problems = validateStageConfig(config, "start");
+  if (problems.length) throw new Error(problems.join("; "));
+  const cwd = opts.cwd ?? process.cwd();
+  const statePath = opts.statePath ?? stageStatePath(cwd);
+  const dir = statePath.slice(0, Math.max(statePath.lastIndexOf("/"), statePath.lastIndexOf("\\")));
+  (0, import_node_fs2.mkdirSync)(dir, { recursive: true });
+  const up = config.up.trim();
+  const child = (0, import_node_child_process3.spawn)(up, {
+    cwd,
+    shell: true,
+    detached: true,
+    windowsHide: true,
+    stdio: "ignore"
+  });
+  const state = {
+    pid: child.pid ?? 0,
+    command: up,
+    cwd,
+    startedAt: (opts.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
+    healthUrl: config.healthUrl?.trim() || void 0
+  };
+  (0, import_node_fs2.writeFileSync)(statePath, JSON.stringify(state, null, 2), "utf8");
+  if (state.healthUrl) await waitForHealth(state.healthUrl, opts.timeoutMs ?? 6e4);
+  const result = { ok: true, action: "start", statePath, pid: state.pid, message: `started stage pid ${state.pid}` };
+  opts.onReady?.(result);
+  child.unref();
+  return result;
+}
+async function runStage(config = {}, opts = {}) {
+  const problems = validateStageConfig(config, "run");
+  if (problems.length) throw new Error(problems.join("; "));
+  const cwd = opts.cwd ?? process.cwd();
+  const timeoutMs = opts.timeoutMs ?? 6e4;
+  await stopStage({ ...opts, cwd });
+  await shell(config.build.trim(), cwd, timeoutMs);
+  const started = await startStage(config, { ...opts, cwd, timeoutMs });
+  return { ...started, action: "run", message: `built and ${started.message}` };
+}
+
+// src/bootstrap-verify.ts
+var requiredDocs = ["README.md", "architecture.md", "AGENTS.md", "CLAUDE.md", ".claude/settings.json", ".mmi/config.json"];
+var requiredIssueTemplates = [
+  ".github/ISSUE_TEMPLATE/bug.yml",
+  ".github/ISSUE_TEMPLATE/feature.yml",
+  ".github/ISSUE_TEMPLATE/task.yml",
+  ".github/ISSUE_TEMPLATE/config.yml"
+];
+var requiredWorkflows = [".github/workflows/pr-to-board.yml"];
+var requiredLabels = ["bug", "feature", "task", "priority:high", "priority:medium", "priority:low"];
+var requiredStatusOptions = ["Todo", "In Progress", "In Review", "Done"];
+var requiredProjectWorkflows = [
+  "Auto-add sub-issues to project",
+  "Auto-close issue",
+  "Item added to project",
+  "Item closed",
+  "Pull request linked to issue",
+  "Pull request merged"
+];
+var requiredActionsVariables = ["MMI_APP_ID"];
+var requiredActionsSecrets = ["MMI_APP_PRIVATE_KEY"];
+function expectedBranches(repoClass) {
+  return repoClass === "content" ? ["main"] : ["development", "rc", "main"];
+}
+function safeJson(text, fallback) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return fallback;
+  }
+}
+async function ghJson(deps, args, fallback) {
+  try {
+    return safeJson((await deps.gh(args)).stdout, fallback);
+  } catch {
+    return fallback;
+  }
+}
+async function contentExists(deps, repo, branch, path) {
+  try {
+    const encodedPath = path.split("/").map(encodeURIComponent).join("/");
+    await deps.gh(["api", `repos/${repo}/contents/${encodedPath}?ref=${encodeURIComponent(branch)}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function contentText(deps, repo, branch, path) {
+  try {
+    const encodedPath = path.split("/").map(encodeURIComponent).join("/");
+    const response = safeJson(
+      (await deps.gh(["api", `repos/${repo}/contents/${encodedPath}?ref=${encodeURIComponent(branch)}`])).stdout,
+      {}
+    );
+    if (response.content == null) return null;
+    if (response.encoding != null && response.encoding !== "base64") return null;
+    return Buffer.from(response.content.replace(/\s/g, ""), "base64").toString("utf8");
+  } catch {
+    return null;
+  }
+}
+async function protectedBranch(deps, repo, branch) {
+  try {
+    await deps.gh(["api", `repos/${repo}/branches/${branch}/protection`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function optionDetail(missing) {
+  return missing.length === 0 ? void 0 : `missing: ${missing.join(", ")}`;
+}
+function localRegistryCheck(deps, path, predicate) {
+  const text = deps.readLocalFile?.(path);
+  if (text == null) return null;
+  return predicate(safeJson(text, null));
+}
+async function verifyBootstrap(repo, repoClass, deps) {
+  const branchesWanted = expectedBranches(repoClass);
+  const baseBranch = repoClass === "content" ? "main" : "development";
+  const checks = [];
+  const repoInfo = await ghJson(deps, ["api", `repos/${repo}`], {});
+  checks.push({ ok: Boolean(repoInfo.default_branch), label: "repo exists" });
+  checks.push({ ok: repoInfo.default_branch === baseBranch, label: `default branch is ${baseBranch}`, detail: repoInfo.default_branch || "missing" });
+  checks.push({ ok: repoInfo.has_wiki === true, label: "wiki enabled", detail: repoInfo.has_wiki === true ? void 0 : "has_wiki is false or unavailable" });
+  const branchList = await ghJson(deps, ["api", `repos/${repo}/branches`, "--paginate"], []);
+  const branchNames = new Set(branchList.map((b) => b.name));
+  for (const branch of branchesWanted) {
+    checks.push({ ok: branchNames.has(branch), label: `branch exists: ${branch}` });
+    checks.push({ ok: await protectedBranch(deps, repo, branch), label: `branch protection exists: ${branch}` });
+  }
+  for (const path of requiredDocs) {
+    checks.push({ ok: await contentExists(deps, repo, baseBranch, path), label: `bootstrap artifact exists: ${path}` });
+  }
+  for (const path of requiredIssueTemplates) {
+    checks.push({ ok: await contentExists(deps, repo, baseBranch, path), label: `issue template exists: ${path}` });
+  }
+  for (const path of requiredWorkflows) {
+    checks.push({ ok: await contentExists(deps, repo, baseBranch, path), label: `automation workflow exists: ${path}` });
+  }
+  checks.push({ ok: await contentExists(deps, repo, baseBranch, ".cursor/environment.json"), label: "Cursor environment committed" });
+  const labels = await ghJson(deps, ["label", "list", "--repo", repo, "--limit", "200", "--json", "name"], []);
+  const labelNames = new Set(labels.map((l) => l.name));
+  for (const label of requiredLabels) {
+    checks.push({ ok: labelNames.has(label), label: `label exists: ${label}` });
+  }
+  const actions = await ghJson(deps, ["api", `repos/${repo}/actions/permissions`], {});
+  checks.push({ ok: actions.enabled === true, label: "GitHub Actions enabled" });
+  const variables = await ghJson(deps, ["variable", "list", "--repo", repo, "--json", "name"], []);
+  const variableNames = new Set(variables.map((v) => v.name));
+  for (const variable of requiredActionsVariables) {
+    checks.push({ ok: variableNames.has(variable), label: `Actions variable exists: ${variable}` });
+  }
+  const secrets = await ghJson(deps, ["secret", "list", "--repo", repo, "--json", "name"], []);
+  const secretNames = new Set(secrets.map((s) => s.name));
+  for (const secret of requiredActionsSecrets) {
+    checks.push({ ok: secretNames.has(secret), label: `Actions secret exists: ${secret}` });
+  }
+  const config = safeJson(await contentText(deps, repo, baseBranch, ".mmi/config.json") || "", null);
+  checks.push({
+    ok: Boolean(config?.projectOwner && config?.projectNumber),
+    label: ".mmi project board config exists"
+  });
+  if (config?.projectOwner && config.projectNumber != null) {
+    const project = await ghJson(
+      deps,
+      ["project", "field-list", String(config.projectNumber), "--owner", config.projectOwner, "--format", "json"],
+      {}
+    );
+    const fields = project.fields || [];
+    const statusField = fields.find((field) => field.name === "Status");
+    const labelField = fields.find((field) => field.name === "Labels");
+    checks.push({
+      ok: Boolean(statusField),
+      label: `Project Status field exists: ${config.projectOwner}#${config.projectNumber}`
+    });
+    checks.push({
+      ok: Boolean(labelField),
+      label: `Project Labels field exists: ${config.projectOwner}#${config.projectNumber}`
+    });
+    if (statusField != null) {
+      const optionNames = new Set((statusField.options || []).map((option) => option.name));
+      const missingOptions = requiredStatusOptions.filter((option) => !optionNames.has(option));
+      checks.push({
+        ok: missingOptions.length === 0,
+        label: "Project Status lanes configured",
+        detail: optionDetail(missingOptions)
+      });
+      checks.push({
+        ok: config.statusFieldId === statusField.id,
+        label: ".mmi statusFieldId matches project"
+      });
+      for (const optionName of requiredStatusOptions) {
+        const projectOption = statusField.options?.find((option) => option.name === optionName);
+        checks.push({
+          ok: Boolean(projectOption?.id && config.statusOptions?.[optionName] === projectOption.id),
+          label: `.mmi status option matches project: ${optionName}`
+        });
+      }
+    }
+    const workflowQuery = "query($login: String!, $number: Int!) { organization(login: $login) { projectV2(number: $number) { workflows(first: 30) { nodes { name enabled } } } } }";
+    const workflowResponse = await ghJson(
+      deps,
+      ["api", "graphql", "-f", `query=${workflowQuery}`, "-f", `login=${config.projectOwner}`, "-F", `number=${config.projectNumber}`],
+      {}
+    );
+    const workflows = workflowResponse.data?.organization?.projectV2?.workflows?.nodes || [];
+    for (const workflowName of requiredProjectWorkflows) {
+      checks.push({
+        ok: workflows.some((workflow) => workflow.name === workflowName && workflow.enabled === true),
+        label: `Project workflow enabled: ${workflowName}`
+      });
+    }
+  }
+  const fanout = repo === "mutmutco/MMI-Hub" ? true : localRegistryCheck(deps, ".github/fanout-targets.json", (json) => Array.isArray(json?.repos) && json.repos.some((r) => r.repo === repo.split("/")[1] && r.branch === baseBranch));
+  if (fanout != null) checks.push({ ok: fanout, label: `fanout target registered on ${baseBranch}` });
+  const projectRegistry = localRegistryCheck(deps, "projects.json", (json) => Array.isArray(json?.projects) && json.projects.some((p) => (p.repos || []).includes(repo)));
+  if (projectRegistry != null) checks.push({ ok: projectRegistry, label: "cloud-agent project registry includes repo" });
+  return { ok: checks.every((c) => c.ok), repo, class: repoClass, baseBranch, checks };
+}
+function renderBootstrapVerifyReport(report) {
+  const lines = [`mmi-cli bootstrap verify: ${report.ok ? "OK" : "CHECK"} ${report.repo} (${report.class}, ${report.baseBranch})`];
+  for (const check of report.checks) {
+    lines.push(`${check.ok ? "OK" : "FAIL"} ${check.label}${check.detail ? ` - ${check.detail}` : ""}`);
+  }
+  return lines.join("\n");
+}
+
+// src/plan.ts
+var import_node_path3 = require("node:path");
+var PLANS_DIR = "plans";
+var META_FILE = (0, import_node_path3.join)(PLANS_DIR, ".plan-meta.json");
+var planPath = (slug) => (0, import_node_path3.join)(PLANS_DIR, `${slug}.md`);
+var metaKey = (project, slug) => `${project}/${slug}`;
+function parseMeta(raw) {
+  if (!raw) return {};
+  try {
+    const o = JSON.parse(raw);
+    return o && typeof o === "object" ? o : {};
+  } catch {
+    return {};
+  }
+}
+function serializeMeta(meta) {
+  return JSON.stringify(meta, null, 2) + "\n";
+}
+function hashContent(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16);
+}
+function staleHint(slug) {
+  return `remote "${slug}" is newer \u2014 run \`mmi-cli plan pull ${slug}\` first (your local is based on an older version), or re-push with \`--force\` to overwrite`;
+}
+function formatPlanList(plans) {
+  return plans.map((p) => `${p.slug}  \xB7  ${p.updatedAt ?? "-"}  \xB7  ${p.project}`).join("\n");
+}
+var TIMEOUT_MS = 8e3;
+async function planPush(deps, slug, opts = {}) {
+  const raw = deps.readLocal(slug);
+  if (raw == null) {
+    deps.err(`no local ${planPath(slug)} to push`);
+    return;
+  }
+  const content = normalizeEol(raw);
+  const project = opts.project ?? await deps.project();
+  const meta = parseMeta(deps.readMetaRaw());
+  const entry = meta[metaKey(project, slug)];
+  const body = { project, slug, content };
+  if (opts.force) body.force = true;
+  else if (entry?.etag) body.baseEtag = entry.etag;
+  const res = await deps.fetch(`${deps.apiUrl}/plan/put`, {
+    method: "POST",
+    headers: await deps.headers({ "content-type": "application/json" }),
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(TIMEOUT_MS)
+  });
+  if (res.ok) {
+    const out = await res.json();
+    meta[metaKey(project, slug)] = { etag: out.etag, hash: hashContent(content), syncedAt: deps.now() };
+    deps.writeMetaRaw(serializeMeta(meta));
+    deps.log(`pushed ${slug}`);
+  } else if (res.status === 409) {
+    deps.err(staleHint(slug));
+  } else {
+    deps.err(`plan push failed: HTTP ${res.status}`);
+  }
+}
+async function planPull(deps, slug, opts = {}) {
+  const project = opts.project ?? await deps.project();
+  const meta = parseMeta(deps.readMetaRaw());
+  const entry = meta[metaKey(project, slug)];
+  const local = deps.readLocal(slug);
+  if (local != null && entry && !opts.force && hashContent(normalizeEol(local)) !== entry.hash) {
+    deps.err(`local ${planPath(slug)} has unpushed edits \u2014 push it, or pull with --force to overwrite`);
+    return;
+  }
+  const qs = new URLSearchParams({ project, slug }).toString();
+  const res = await deps.fetch(`${deps.apiUrl}/plan/get?${qs}`, {
+    method: "GET",
+    headers: await deps.headers(),
+    signal: AbortSignal.timeout(TIMEOUT_MS)
+  });
+  if (res.status === 404) {
+    deps.err(`no plan "${slug}" found on the server`);
+    return;
+  }
+  if (!res.ok) {
+    deps.err(`plan pull failed: HTTP ${res.status}`);
+    return;
+  }
+  const doc = await res.json();
+  const content = normalizeEol(doc.content ?? "");
+  deps.writeLocal(slug, content);
+  meta[metaKey(project, slug)] = { etag: doc.etag, hash: hashContent(content), syncedAt: deps.now() };
+  deps.writeMetaRaw(serializeMeta(meta));
+  deps.log(`pulled ${slug} \u2192 ${planPath(slug)}`);
+}
+async function planList(deps, opts = {}) {
+  const qs = opts.project ? `?${new URLSearchParams({ project: opts.project }).toString()}` : "";
+  let res;
+  try {
+    res = await deps.fetch(`${deps.apiUrl}/plan/list${qs}`, {
+      method: "GET",
+      headers: await deps.headers(),
+      signal: AbortSignal.timeout(TIMEOUT_MS)
+    });
+  } catch (e) {
+    if (!opts.quiet) deps.err(`plan list: ${e.message}`);
+    return;
+  }
+  if (!res.ok) {
+    if (!opts.quiet) deps.err(`plan list failed: HTTP ${res.status}`);
+    return;
+  }
+  const { plans } = await res.json();
+  if (opts.json) {
+    deps.log(JSON.stringify(plans));
+    return;
+  }
+  if (!plans.length) {
+    if (!opts.quiet) deps.log("no plans");
+    return;
+  }
+  deps.log(formatPlanList(plans));
+}
+async function planDelete(deps, slug, opts = {}) {
+  const project = opts.project ?? await deps.project();
+  const res = await deps.fetch(`${deps.apiUrl}/plan/delete`, {
+    method: "POST",
+    headers: await deps.headers({ "content-type": "application/json" }),
+    body: JSON.stringify({ project, slug }),
+    signal: AbortSignal.timeout(TIMEOUT_MS)
+  });
+  if (!res.ok) {
+    deps.err(`plan delete failed: HTTP ${res.status}`);
+    return;
+  }
+  deps.removeLocal(slug);
+  const meta = parseMeta(deps.readMetaRaw());
+  delete meta[metaKey(project, slug)];
+  deps.writeMetaRaw(serializeMeta(meta));
+  deps.log(`deleted ${slug}`);
+}
+
+// src/index.ts
+var execFileP3 = (0, import_node_util3.promisify)(import_node_child_process4.execFile);
 var GIT_TIMEOUT_MS = 1e4;
 var GC_GH_TIMEOUT_MS = 2e4;
 async function githubToken() {
   if (process.env.GH_TOKEN) return process.env.GH_TOKEN;
   if (process.env.GITHUB_TOKEN) return process.env.GITHUB_TOKEN;
   try {
-    const { stdout } = await execFileP2("gh", ["auth", "token"]);
+    const { stdout } = await execFileP3("gh", ["auth", "token"]);
     return stdout.trim() || void 0;
   } catch {
     return void 0;
@@ -3913,7 +4407,7 @@ async function githubToken() {
 }
 async function githubLogin() {
   try {
-    const { stdout } = await execFileP2("gh", ["api", "user", "--jq", ".login"]);
+    const { stdout } = await execFileP3("gh", ["api", "user", "--jq", ".login"]);
     return stdout.trim() || void 0;
   } catch {
     return void 0;
@@ -3935,7 +4429,7 @@ var DEFAULT_KB_SOURCE = "https://raw.githubusercontent.com/mutmutco/MM-KB/main";
 var SESSION_FILE = ".mmi/.session";
 var gitOut = async (args) => {
   try {
-    return (await execFileP2("git", [...args])).stdout.trim();
+    return (await execFileP3("git", [...args])).stdout.trim();
   } catch {
     return "";
   }
@@ -3945,7 +4439,7 @@ function sessionDeps() {
     env: process.env,
     readPersisted: () => {
       try {
-        return (0, import_node_fs2.readFileSync)(SESSION_FILE, "utf8");
+        return (0, import_node_fs3.readFileSync)(SESSION_FILE, "utf8");
       } catch {
         return null;
       }
@@ -3958,8 +4452,8 @@ function sessionDeps() {
 var resolveSessionId = () => resolveSession(sessionDeps());
 function persistSession(id) {
   try {
-    (0, import_node_fs2.mkdirSync)(".mmi", { recursive: true });
-    (0, import_node_fs2.writeFileSync)(SESSION_FILE, id, "utf8");
+    (0, import_node_fs3.mkdirSync)(".mmi", { recursive: true });
+    (0, import_node_fs3.writeFileSync)(SESSION_FILE, id, "utf8");
   } catch {
   }
 }
@@ -3995,18 +4489,18 @@ async function readStdin() {
 async function ghPrs(limit) {
   const args = (state) => ["pr", "list", "--state", state, "--limit", String(limit), "--json", "number,headRefName,state"];
   const [open, closed] = await Promise.all([
-    execFileP2("gh", args("open"), { timeout: GC_GH_TIMEOUT_MS }),
-    execFileP2("gh", args("closed"), { timeout: GC_GH_TIMEOUT_MS })
+    execFileP3("gh", args("open"), { timeout: GC_GH_TIMEOUT_MS }),
+    execFileP3("gh", args("closed"), { timeout: GC_GH_TIMEOUT_MS })
   ]);
   return [...JSON.parse(open.stdout || "[]"), ...JSON.parse(closed.stdout || "[]")];
 }
 async function worktreeBranches() {
-  const { stdout } = await execFileP2("git", ["worktree", "list", "--porcelain"], { timeout: GIT_TIMEOUT_MS });
+  const { stdout } = await execFileP3("git", ["worktree", "list", "--porcelain"], { timeout: GIT_TIMEOUT_MS });
   const parsed = parseWorktreePorcelain(stdout);
   return await Promise.all(parsed.map(async (w) => {
     let dirty = true;
     try {
-      const { stdout: status } = await execFileP2("git", ["-C", w.path, "status", "--porcelain"], { timeout: GIT_TIMEOUT_MS });
+      const { stdout: status } = await execFileP3("git", ["-C", w.path, "status", "--porcelain"], { timeout: GIT_TIMEOUT_MS });
       dirty = status.trim().length > 0;
     } catch {
       dirty = true;
@@ -4018,7 +4512,7 @@ async function gcPlan(remote, limit) {
   const [branches, current, stale, prs, worktrees] = await Promise.all([
     gitOut(["branch", "--format=%(refname:short)"]),
     gitOut(["rev-parse", "--abbrev-ref", "HEAD"]),
-    execFileP2("git", ["remote", "prune", remote, "--dry-run"], { timeout: GIT_TIMEOUT_MS }).then((r) => parseRemotePruneDryRun(`${r.stdout}${r.stderr}`)).catch(() => []),
+    execFileP3("git", ["remote", "prune", remote, "--dry-run"], { timeout: GIT_TIMEOUT_MS }).then((r) => parseRemotePruneDryRun(`${r.stdout}${r.stderr}`)).catch(() => []),
     ghPrs(limit),
     worktreeBranches()
   ]);
@@ -4031,26 +4525,26 @@ async function gcPlan(remote, limit) {
     remote
   });
 }
-async function applyGcPlan(plan, remote) {
-  for (const branch of plan.branches) {
-    if (branch.worktreePath) await execFileP2("git", ["worktree", "remove", branch.worktreePath], { timeout: GIT_TIMEOUT_MS });
-    await execFileP2("git", ["branch", "-D", branch.branch], { timeout: GIT_TIMEOUT_MS });
+async function applyGcPlan(plan2, remote) {
+  for (const branch of plan2.branches) {
+    if (branch.worktreePath) await execFileP3("git", ["worktree", "remove", branch.worktreePath], { timeout: GIT_TIMEOUT_MS });
+    await execFileP3("git", ["branch", "-D", branch.branch], { timeout: GIT_TIMEOUT_MS });
   }
-  for (const ref of plan.trackingRefs) {
-    await execFileP2("git", ["update-ref", "-d", `refs/remotes/${remote}/${ref.branch}`], { timeout: GIT_TIMEOUT_MS });
+  for (const ref of plan2.trackingRefs) {
+    await execFileP3("git", ["update-ref", "-d", `refs/remotes/${remote}/${ref.branch}`], { timeout: GIT_TIMEOUT_MS });
   }
-  if (plan.branches.some((b) => b.worktreePath)) {
-    await execFileP2("git", ["worktree", "prune"], { timeout: GIT_TIMEOUT_MS });
+  if (plan2.branches.some((b) => b.worktreePath)) {
+    await execFileP3("git", ["worktree", "prune"], { timeout: GIT_TIMEOUT_MS });
   }
 }
 function resolveVersion() {
   try {
-    const manifest = (0, import_node_path2.join)(__dirname, "..", "..", ".claude-plugin", "plugin.json");
-    return JSON.parse((0, import_node_fs2.readFileSync)(manifest, "utf8")).version || "0.0.0";
+    const manifest = (0, import_node_path4.join)(__dirname, "..", "..", ".claude-plugin", "plugin.json");
+    return JSON.parse((0, import_node_fs3.readFileSync)(manifest, "utf8")).version || "0.0.0";
   } catch {
     try {
-      const pkg = (0, import_node_path2.join)(__dirname, "..", "package.json");
-      return JSON.parse((0, import_node_fs2.readFileSync)(pkg, "utf8")).version || "0.0.0";
+      const pkg = (0, import_node_path4.join)(__dirname, "..", "package.json");
+      return JSON.parse((0, import_node_fs3.readFileSync)(pkg, "utf8")).version || "0.0.0";
     } catch {
       return "0.0.0";
     }
@@ -4058,7 +4552,7 @@ function resolveVersion() {
 }
 function readRepoVersion() {
   try {
-    return JSON.parse((0, import_node_fs2.readFileSync)((0, import_node_path2.join)(process.cwd(), ".claude-plugin", "plugin.json"), "utf8")).version || void 0;
+    return JSON.parse((0, import_node_fs3.readFileSync)((0, import_node_path4.join)(process.cwd(), ".claude-plugin", "plugin.json"), "utf8")).version || void 0;
   } catch {
     return void 0;
   }
@@ -4084,21 +4578,23 @@ rules.command("sync").option("--quiet", "stay silent unless something changed or
     return;
   }
   const base = (cfg.orgRulesSource ?? DEFAULT_RULES_SOURCE).replace(/\/$/, "");
+  const token = await githubToken();
   let changed = 0;
   for (const file of ["AGENTS.md", "CLAUDE.md", ".claude/settings.json"]) {
     let source;
     try {
-      const res = await fetch(`${base}/${file}`);
+      const url = `${base}/${file}`;
+      const res = await fetch(url, { headers: rulesSourceAuthHeaders(url, token) });
       if (!res.ok) throw new Error(`HTTP ${res.status}`);
       source = await res.text();
     } catch (e) {
       if (!opts.quiet) console.error(`mmi-cli rules: could not fetch ${file} (${e.message}); left it untouched`);
       continue;
     }
-    const current = (0, import_node_fs2.existsSync)(file) ? await (0, import_promises.readFile)(file, "utf8") : null;
+    const current = (0, import_node_fs3.existsSync)(file) ? await (0, import_promises.readFile)(file, "utf8") : null;
     if (needsUpdate(source, current)) {
       const slash = file.lastIndexOf("/");
-      if (slash > 0) (0, import_node_fs2.mkdirSync)(file.slice(0, slash), { recursive: true });
+      if (slash > 0) (0, import_node_fs3.mkdirSync)(file.slice(0, slash), { recursive: true });
       await (0, import_promises.writeFile)(file, normalizeEol(source), "utf8");
       changed++;
       if (!opts.quiet) console.log(`mmi-cli rules: updated ${file}`);
@@ -4112,7 +4608,7 @@ async function runNote(summary, o) {
   const capture = buildNoteCapture(summary, o, (0, import_node_crypto.randomUUID)(), { sha: sha || void 0, branch: key.branch });
   await postCapture(capture);
 }
-saga.command("note <summary>").description("record a one-line structured note into your saga (the per-turn capture)").option("--next <text>", 'set "where I left off" (NEXT)').option("--decision <text>", "append a verbatim decision").option("--queue-add <text>", "add a worklist item").option("--queue-done <n>", "mark worklist item N done").option("--verified", "mark this claim as checked against source (state: verified, else asserted)").option("--diagnostic", "isolate a probe write (state: diagnostic, source: probe) \u2014 never resume/LAST 5").action((summary, o) => runNote(summary, o));
+saga.command("note <summary>").description("record a one-line structured note into your saga (the per-turn capture)").option("--next <text>", 'set "where I left off" (NEXT)').option("--decision <text>", "append a verbatim decision").option("--queue-add <text>", "add a worklist item").option("--queue-done <n>", "mark worklist item N done").option("--verified", "mark this claim as checked against source (state: verified, else asserted)").option("--diagnostic", "isolate a probe write (state: diagnostic, source: probe) \u2014 never resume/LAST 5").option("--supersedes <key>", "retire prior decisions matching an evidence key (pr:N | file:path)").option("--anchor <intent>", "set the sprint North-Star (write-protected; needs --anchor-force to change)").option("--anchor-force", "overwrite an existing anchor").action((summary, o) => runNote(summary, o));
 saga.command("probe <summary>").description("record a diagnostic probe note (alias for `saga note --diagnostic`)").option("--next <text>", 'set "where I left off" (NEXT)').option("--decision <text>", "append a verbatim decision").option("--queue-add <text>", "add a worklist item").option("--queue-done <n>", "mark worklist item N done").action((summary, o) => runNote(summary, { ...o, diagnostic: true }));
 saga.command("show").option("--quiet", "no-op silently when unconfigured/unreachable (SessionStart hook)").option("--latest-anywhere", "resume the newest saga across all repos (default: current repo)").description("print your resume block \u2014 current repo HEAD + project memory (where you left off)").action(async (opts) => {
   const cfg = await loadConfig();
@@ -4146,7 +4642,7 @@ saga.command("head-update").option("--run", "detached worker: fetch state, run t
     if (!headGateDue(tsPath)) return;
     markHeadRun(tsPath);
     try {
-      (0, import_node_child_process3.spawn)(process.execPath, [process.argv[1], "saga", "head-update", "--run"], {
+      (0, import_node_child_process4.spawn)(process.execPath, [process.argv[1], "saga", "head-update", "--run"], {
         detached: true,
         stdio: "ignore",
         windowsHide: true
@@ -4164,7 +4660,8 @@ saga.command("head-update").option("--run", "detached worker: fetch state, run t
     if (!res.ok) return;
     const state = await res.json();
     if (!state.actionLog?.length) return;
-    const update = parseHeadUpdate(await runHeadEngine(headPrompt(state)));
+    const decisionTexts = (state.decisions ?? []).map((d) => typeof d === "string" ? d : d.text);
+    const update = parseHeadUpdate(await runHeadEngine(headPrompt({ ...state, decisions: decisionTexts })));
     if (!update) return;
     await fetch(`${cfg.sagaApiUrl}/saga/head`, {
       method: "POST",
@@ -4214,10 +4711,10 @@ program2.command("gc").description("dry-run cleanup for merged/closed PR branche
   const limit = Number.parseInt(o.limit, 10);
   if (!Number.isFinite(limit) || limit < 1) return fail("gc: --limit must be a positive integer");
   try {
-    const plan = await gcPlan(o.remote, limit);
-    if (o.apply) await applyGcPlan(plan, o.remote);
-    if (o.json) return console.log(JSON.stringify({ dryRun: !o.apply, remote: o.remote, plan }, null, 2));
-    console.log(formatGcPlan(plan, Boolean(o.apply)));
+    const plan2 = await gcPlan(o.remote, limit);
+    if (o.apply) await applyGcPlan(plan2, o.remote);
+    if (o.json) return console.log(JSON.stringify({ dryRun: !o.apply, remote: o.remote, plan: plan2 }, null, 2));
+    console.log(formatGcPlan(plan2, Boolean(o.apply)));
   } catch (e) {
     fail(`gc: ${e.message}`);
   }
@@ -4230,21 +4727,21 @@ program2.command("kb").description("org knowledgebase (read-only)").command("get
 });
 async function ghCreate(args) {
   try {
-    const { stdout } = await execFileP2("gh", args);
+    const { stdout } = await execFileP3("gh", args);
     return parseCreatedUrl(stdout);
   } catch (e) {
     const err = e;
     fail(`gh ${args[0]} create failed: ${(err.stderr || err.message || String(e)).trim()}`);
   }
 }
-async function ghJson(args, timeout = 1e4) {
-  const { stdout } = await execFileP2("gh", args, { timeout });
+async function ghJson2(args, timeout = 1e4) {
+  const { stdout } = await execFileP3("gh", args, { timeout });
   return JSON.parse(stdout);
 }
 async function resolveRepo(repo) {
   if (repo) return repo;
   try {
-    const { stdout } = await execFileP2("gh", ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"], { timeout: 5e3 });
+    const { stdout } = await execFileP3("gh", ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"], { timeout: 5e3 });
     return stdout.trim() || void 0;
   } catch {
     return void 0;
@@ -4254,7 +4751,7 @@ function scheduleRelatedDiscovery(o) {
   try {
     const args = ["issue", "discover-related", "--number", String(o.number), "--title", o.title, "--body", o.body];
     if (o.repo) args.push("--repo", o.repo);
-    (0, import_node_child_process3.spawn)(process.execPath, [process.argv[1], ...args], {
+    (0, import_node_child_process4.spawn)(process.execPath, [process.argv[1], ...args], {
       detached: true,
       stdio: "ignore",
       windowsHide: true,
@@ -4263,6 +4760,77 @@ function scheduleRelatedDiscovery(o) {
   } catch {
   }
 }
+function makePlanDeps(cfg) {
+  const ensureDir = () => (0, import_node_fs3.mkdirSync)(PLANS_DIR, { recursive: true });
+  return {
+    apiUrl: cfg.sagaApiUrl,
+    fetch: (url, init) => fetch(url, init),
+    headers: (extra) => sagaHeaders(extra),
+    project: async () => (await sagaKey(cfg)).project,
+    readLocal: (slug) => {
+      try {
+        return (0, import_node_fs3.readFileSync)(planPath(slug), "utf8");
+      } catch {
+        return null;
+      }
+    },
+    writeLocal: (slug, content) => {
+      ensureDir();
+      (0, import_node_fs3.writeFileSync)(planPath(slug), content, "utf8");
+    },
+    removeLocal: (slug) => {
+      try {
+        (0, import_node_fs3.rmSync)(planPath(slug));
+      } catch {
+      }
+    },
+    readMetaRaw: () => {
+      try {
+        return (0, import_node_fs3.readFileSync)(META_FILE, "utf8");
+      } catch {
+        return null;
+      }
+    },
+    writeMetaRaw: (raw) => {
+      ensureDir();
+      (0, import_node_fs3.writeFileSync)(META_FILE, raw, "utf8");
+    },
+    log: (m) => console.log(m),
+    err: (m) => console.error(m),
+    now: () => (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function openInEditor(path) {
+  const editor = process.env.EDITOR || process.env.VISUAL;
+  if (!editor) {
+    console.log(`plan at ${path} (set $EDITOR to open it automatically)`);
+    return;
+  }
+  try {
+    (0, import_node_child_process4.spawn)(editor, [path], { stdio: "inherit" });
+  } catch {
+    console.log(`open ${path} manually`);
+  }
+}
+async function withPlan(quiet, run) {
+  const cfg = await loadConfig();
+  if (!cfg.sagaApiUrl) {
+    if (!quiet) fail("plan: sagaApiUrl not configured in .mmi/config.json");
+    return;
+  }
+  await run(makePlanDeps(cfg));
+}
+var plan = program2.command("plan").description("your cross-device plans/SSOTs (S3-backed, git-clean)");
+plan.command("push <slug>").description("push a local plan (plans/<slug>.md) to the server").option("--project <name>", "override the project key").option("--force", "overwrite the remote even if it changed since your last sync").action((slug, o) => withPlan(false, (d) => planPush(d, slug, o)));
+plan.command("pull <slug>").description("pull a plan from the server into plans/<slug>.md").option("--project <name>", "override the project key").option("--force", "overwrite local even if it has unpushed edits").action((slug, o) => withPlan(false, (d) => planPull(d, slug, o)));
+plan.command("list").description("list your plans (cross-device)").option("--project <name>", "filter by project").option("--json", "machine-readable output").option("--quiet", "silent when unconfigured/empty/unreachable (SessionStart hook)").action((o) => withPlan(o.quiet ?? false, (d) => planList(d, o)));
+plan.command("open <slug>").description("pull if needed, then open plans/<slug>.md in $EDITOR").option("--project <name>", "override the project key").action(
+  (slug, o) => withPlan(false, async (d) => {
+    await planPull(d, slug, { project: o.project });
+    openInEditor(planPath(slug));
+  })
+);
+plan.command("delete <slug>").description("delete a plan from the server and the local copy").option("--project <name>", "override the project key").action((slug, o) => withPlan(false, (d) => planDelete(d, slug, o)));
 var issue = program2.command("issue").description("issues \u2014 reliable create with structured output");
 issue.command("create").description("create an issue (type \u2192 label) and print {number,url,label} JSON").requiredOption("--type <type>", "bug | feature | task (sets the matching label)").requiredOption("--title <title>", "issue title").requiredOption("--body <body>", "issue body (markdown)").requiredOption("--priority <priority>", "high | medium | low (adds a priority:<p> label)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action(async (o) => {
   let args;
@@ -4281,7 +4849,7 @@ issue.command("discover-related").description("find related issues for an existi
   const repo = await resolveRepo(o.repo);
   if (!repo) return fail("issue discover-related: could not resolve repo");
   try {
-    const issues = await ghJson([
+    const issues = await ghJson2([
       "issue",
       "list",
       "--repo",
@@ -4296,7 +4864,7 @@ issue.command("discover-related").description("find related issues for an existi
     const candidates = findRelatedIssues({ number, title: o.title, body: o.body }, issues);
     if (o.json) return console.log(JSON.stringify({ number, repo, candidates }, null, 2));
     if (!candidates.length) return;
-    const viewed = await ghJson([
+    const viewed = await ghJson2([
       "issue",
       "view",
       String(number),
@@ -4306,7 +4874,7 @@ issue.command("discover-related").description("find related issues for an existi
       "comments"
     ]);
     if (viewed.comments.some((comment) => comment.body.includes(relatedMarker(number)))) return;
-    await execFileP2("gh", ["issue", "comment", String(number), "--repo", repo, "--body", buildRelatedComment(number, candidates)], { timeout: 1e4 });
+    await execFileP3("gh", ["issue", "comment", String(number), "--repo", repo, "--body", buildRelatedComment(number, candidates)], { timeout: 1e4 });
   } catch {
   }
 });
@@ -4345,11 +4913,102 @@ function renderSteps(title, steps) {
     ...steps.map((step, i) => `${i + 1}. ${step.gated ? "[gated] " : ""}${step.label}${step.command ? ` - ${step.command}` : ""}`)
   ].join("\n");
 }
-program2.command("stage").description("plan or run the repo local stage environment").option("--json", "machine-readable output").option("--apply", "reserved for future stage execution; requires repo stage config").action(async (o) => {
-  if (o.apply) return fail("stage: execution is not implemented yet; use the dry-run plan and the existing /stage skill");
-  const steps = stagePlan((await loadConfig()).stage);
+function rawFlag(flag) {
+  return process.argv.includes(flag);
+}
+function rawValue(flag, fallback) {
+  const index = process.argv.indexOf(flag);
+  return index >= 0 && process.argv[index + 1] ? process.argv[index + 1] : fallback;
+}
+function printLine(value) {
+  (0, import_node_fs3.writeSync)(1, `${value}
+`);
+}
+function stageKeepAlive() {
+  return setTimeout(() => void 0, 5 * 60 * 1e3);
+}
+var stage = program2.command("stage").description("plan or run the repo local stage environment").option("--json", "machine-readable output").option("--apply", "run the full local stage: stop previous, build, start, health-check").option("--timeout-ms <ms>", "bounded build/health timeout", "60000").action(async (o) => {
+  const cfg = (await loadConfig()).stage;
+  if (o.apply) {
+    const hold = stageKeepAlive();
+    try {
+      const result = await runStage(cfg, { timeoutMs: Number(o.timeoutMs || 6e4) });
+      return printLine(o.json ? JSON.stringify(result) : `mmi-cli stage: ${result.message}`);
+    } catch (e) {
+      return fail(`stage: ${e.message}`);
+    } finally {
+      clearTimeout(hold);
+    }
+  }
+  const steps = stagePlan(cfg);
   console.log(o.json ? JSON.stringify({ command: "stage", steps }, null, 2) : renderSteps("mmi-cli stage: dry-run plan", steps));
 });
+stage.command("stop").description("stop the previous local stage process recorded in tmp/stage/state.json").option("--json", "machine-readable output").option("--apply", "kill the recorded process tree and remove the state file").action(async () => {
+  const o = { json: rawFlag("--json"), apply: rawFlag("--apply") };
+  if (!o.apply) {
+    const steps = [{ label: "stop recorded local stage", command: "mmi-cli stage stop --apply" }];
+    return printLine(o.json ? JSON.stringify({ command: "stage stop", steps }, null, 2) : renderSteps("mmi-cli stage stop: dry-run plan", steps));
+  }
+  try {
+    const result = await stopStage();
+    printLine(o.json ? JSON.stringify(result) : `mmi-cli stage stop: ${result.message}`);
+  } catch (e) {
+    fail(`stage stop: ${e.message}`);
+  }
+});
+stage.command("start").description("start the configured local stage process and optionally wait for health").option("--json", "machine-readable output").option("--apply", "start the configured stage.up process").option("--timeout-ms <ms>", "bounded health timeout", "60000").action(async () => {
+  const o = { json: rawFlag("--json"), apply: rawFlag("--apply"), timeoutMs: rawValue("--timeout-ms", "60000") };
+  const cfg = (await loadConfig()).stage;
+  if (!o.apply) {
+    const steps = [{ label: "start local stage", command: cfg?.up || "(no stage.up configured)" }];
+    return printLine(o.json ? JSON.stringify({ command: "stage start", steps }, null, 2) : renderSteps("mmi-cli stage start: dry-run plan", steps));
+  }
+  try {
+    const hold = stageKeepAlive();
+    let printed = false;
+    try {
+      const result = await startStage(cfg, {
+        timeoutMs: Number(o.timeoutMs || 6e4),
+        onReady: (ready) => {
+          printed = true;
+          printLine(o.json ? JSON.stringify(ready) : `mmi-cli stage start: ${ready.message}`);
+        }
+      });
+      if (!printed) printLine(o.json ? JSON.stringify(result) : `mmi-cli stage start: ${result.message}`);
+    } finally {
+      clearTimeout(hold);
+    }
+  } catch (e) {
+    fail(`stage start: ${e.message}`);
+  }
+});
+stage.command("run").description("force-stop previous stage, build, start, and health-check").option("--json", "machine-readable output").option("--apply", "run the configured stage sequence").option("--timeout-ms <ms>", "bounded build/health timeout", "60000").action(async () => {
+  const o = { json: rawFlag("--json"), apply: rawFlag("--apply"), timeoutMs: rawValue("--timeout-ms", "60000") };
+  const cfg = (await loadConfig()).stage;
+  if (!o.apply) {
+    const steps = stagePlan(cfg);
+    return printLine(o.json ? JSON.stringify({ command: "stage run", steps }, null, 2) : renderSteps("mmi-cli stage run: dry-run plan", steps));
+  }
+  try {
+    const hold = stageKeepAlive();
+    let printed = false;
+    try {
+      const result = await runStage(cfg, {
+        timeoutMs: Number(o.timeoutMs || 6e4),
+        onReady: (ready) => {
+          const runReady = { ...ready, action: "run", message: `built and ${ready.message}` };
+          printed = true;
+          printLine(o.json ? JSON.stringify(runReady) : `mmi-cli stage run: ${runReady.message}`);
+        }
+      });
+      if (!printed) printLine(o.json ? JSON.stringify(result) : `mmi-cli stage run: ${result.message}`);
+    } finally {
+      clearTimeout(hold);
+    }
+  } catch (e) {
+    fail(`stage run: ${e.message}`);
+  }
+});
 for (const commandName of ["rc", "release", "hotfix"]) {
   program2.command(commandName).description(`plan ${commandName} train operations; mutations require explicit approval`).option("--json", "machine-readable output").option("--apply", "reserved for future train execution after explicit admin approval").action((o) => {
     if (o.apply) return fail(`${commandName}: execution is not implemented yet; use the dry-run plan and the existing /${commandName} skill`);
@@ -4357,34 +5016,45 @@ for (const commandName of ["rc", "release", "hotfix"]) {
     console.log(o.json ? JSON.stringify({ command: commandName, steps }, null, 2) : renderSteps(`mmi-cli ${commandName}: dry-run plan`, steps));
   });
 }
-program2.command("bootstrap").description("plan repo bootstrap operations; mutations require master-admin approval").requiredOption("--repo <owner/repo>", "target repo").option("--class <class>", "deployable | content", "deployable").option("--json", "machine-readable output").option("--apply", "reserved for future bootstrap execution after explicit master-admin approval").action((o) => {
+var bootstrap = program2.command("bootstrap").description("plan repo bootstrap operations; mutations require master-admin approval").option("--repo <owner/repo>", "target repo").option("--class <class>", "deployable | content", "deployable").option("--json", "machine-readable output").option("--apply", "reserved for future bootstrap execution after explicit master-admin approval").action((o) => {
+  if (!o.repo) return fail("bootstrap: required option --repo <owner/repo> not specified");
   if (o.apply) return fail("bootstrap: execution is not implemented yet; use the dry-run plan and the existing /bootstrap skill");
   if (o.class !== "deployable" && o.class !== "content") return fail("bootstrap: --class must be deployable or content");
   const steps = bootstrapPlan(o.repo, o.class);
   console.log(o.json ? JSON.stringify({ command: "bootstrap", repo: o.repo, class: o.class, steps }, null, 2) : renderSteps(`mmi-cli bootstrap: dry-run plan for ${o.repo}`, steps));
 });
+bootstrap.command("verify <repo>").description("audit whether an existing repo is bootstrapped correctly; no mutations").option("--class <class>", "deployable | content", "deployable").option("--json", "machine-readable output").action(async (repo) => {
+  const o = { class: rawValue("--class", "deployable"), json: rawFlag("--json") };
+  if (o.class !== "deployable" && o.class !== "content") return fail("bootstrap verify: --class must be deployable or content");
+  const report = await verifyBootstrap(repo, o.class, {
+    gh: async (args) => execFileP3("gh", args, { timeout: 2e4 }),
+    readLocalFile: (path) => (0, import_node_fs3.existsSync)(path) ? (0, import_node_fs3.readFileSync)(path, "utf8") : null
+  });
+  console.log(o.json ? JSON.stringify(report, null, 2) : renderBootstrapVerifyReport(report));
+  if (!report.ok) process.exitCode = 1;
+});
 var isWin = process.platform === "win32";
 program2.command("doctor").description("check onboarding gates (GitHub auth, mmi-cli on PATH, repo config, plugin git clone) and print fixes").option("--banner", "one-line resume summary; silent when all gates pass").option("--json", "machine-readable output").action(async (opts) => {
   const checks = [];
-  const token = await githubToken();
-  let ghFix = "run: gh auth login";
-  if (!token) {
+  const login = await githubLogin();
+  let ghInstalled = true;
+  if (!login) {
     try {
-      await execFileP2("gh", ["--version"]);
+      await execFileP3("gh", ["--version"]);
     } catch {
-      ghFix = "install GitHub CLI (https://cli.github.com), then: gh auth login";
+      ghInstalled = false;
     }
   }
-  checks.push({ ok: Boolean(token), label: "GitHub auth (saga + gh ops)", fix: ghFix });
+  checks.push(buildGithubAuthCheck({ login, ghInstalled }));
   let onPath = false;
   try {
-    await execFileP2(isWin ? "where" : "which", ["mmi-cli"]);
+    await execFileP3(isWin ? "where" : "which", ["mmi-cli"]);
     onPath = true;
   } catch {
   }
   if (!onPath) {
     const root = process.env.CLAUDE_PLUGIN_ROOT;
-    if (root && (0, import_node_fs2.existsSync)(`${root}/bin/mmi-cli${isWin ? ".cmd" : ""}`)) onPath = true;
+    if (root && (0, import_node_fs3.existsSync)(`${root}/bin/mmi-cli${isWin ? ".cmd" : ""}`)) onPath = true;
   }
   checks.push({ ok: onPath, label: "mmi-cli on PATH", fix: "auto-provisioned at session start \u2014 reopen the session, or install the MMI plugin" });
   checks.push(buildVersionLagReport({
@@ -4398,13 +5068,13 @@ program2.command("doctor").description("check onboarding gates (GitHub auth, mmi
   const CLONE_FIX = 'run: git config --global url."https://github.com/".insteadOf "git@github.com:"';
   let cloneOk = false;
   try {
-    const { stdout } = await execFileP2("git", ["config", "--global", "--get-all", REWRITE_KEY]);
+    const { stdout } = await execFileP3("git", ["config", "--global", "--get-all", REWRITE_KEY]);
     cloneOk = stdout.split("\n").some((l) => l.trim() === "git@github.com:");
   } catch {
   }
   if (!cloneOk) {
     try {
-      await execFileP2("git", ["config", "--global", "--add", REWRITE_KEY, "git@github.com:"]);
+      await execFileP3("git", ["config", "--global", "--add", REWRITE_KEY, "git@github.com:"]);
       cloneOk = true;
       if (!opts.banner && !opts.json) console.error("  \u21BB repaired: git insteadOf git@github.com \u2192 https (plugin clone over HTTPS)");
     } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "description": "MMI Future CLI — delivers the org rules (whole-file), plus saga and KB access. The cross-IDE engine the plugin's SessionStart hook drives.",
   "type": "module",
   "license": "UNLICENSED",
@@ -31,7 +31,9 @@
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
-  "dependencies": { "commander": "^12.1.0" },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "esbuild": "^0.24.0",