@mutmutco/cli 3.71.0 → 3.72.0

package/dist/main.cjs

@@ -37,6 +37,7 @@ __export(index_exports, {
   envHealLockPath: () => envHealLockPath,
   gcPlan: () => gcPlan,
   isOrgRegisteredRepo: () => isOrgRegisteredRepo,
+  parseInvalidChoiceError: () => parseInvalidChoiceError,
   positionalTargetForm: () => positionalTargetForm,
   registryClientDeps: () => registryClientDeps,
   repoSlug: () => repoSlug,
@@ -4052,7 +4053,9 @@ function argvWantsMachineFailure() {
 }
 function commandFromFailMessage(msg) {
   const head = msg.split(":", 1)[0].trim();
-  return head || "mmi-cli";
+  if (!head || head.startsWith("-")) return "mmi-cli";
+  if (!/^[a-z][a-z0-9-]*(?: [a-z][a-z0-9-]*){0,3}$/.test(head)) return "mmi-cli";
+  return head;
 }
 function fail(msg, payload) {
   const json = argvWantsMachineFailure();
@@ -6686,21 +6689,39 @@ function patchRulesetRequiredContexts(body, contexts) {
 function findProductRuleset(rulesets) {
   return rulesets.find((r) => r.name === PRODUCT_RULESET_NAME);
 }
-async function activateProductRuleset(repo, rulesetBody, client) {
-  const want = new Set(rulesetRequiredContexts({ rules: rulesetBody.rules }));
+async function latestCompletedGateRun(repo, client, query) {
+  const res = await client.rest(
+    "GET",
+    `repos/${repo}/actions/workflows/gate.yml/runs?status=completed&per_page=1${query}`,
+    { timeoutMs: 2e4 }
+  );
+  return res?.workflow_runs?.[0];
+}
+async function gateIsProvenGreen(repo, client, baseBranch) {
+  try {
+    const onBase = await latestCompletedGateRun(repo, client, `&branch=${encodeURIComponent(baseBranch)}`);
+    const latest = onBase ?? await latestCompletedGateRun(repo, client, "");
+    return latest?.conclusion === "success";
+  } catch {
+    return false;
+  }
+}
+async function activateProductRuleset(repo, rulesetBody, client, enforcement = "active") {
+  const body = { ...rulesetBody, enforcement };
+  const want = new Set(rulesetRequiredContexts({ rules: body.rules }));
   const list = await client.rest("GET", `repos/${repo}/rulesets`, { timeoutMs: 2e4 });
   const existing = findProductRuleset(list ?? []);
   if (existing?.id != null) {
     const detail = await client.rest("GET", `repos/${repo}/rulesets/${existing.id}`, { timeoutMs: 2e4 });
     const have = new Set(rulesetRequiredContexts(detail));
-    if (detail.enforcement === "active" && have.size === want.size && [...want].every((c) => have.has(c))) {
-      return { action: "skipped", detail: "active ruleset already matches required contexts" };
+    if (detail.enforcement === enforcement && have.size === want.size && [...want].every((c) => have.has(c))) {
+      return { action: "skipped", enforcement, detail: `${enforcement} ruleset already matches required contexts` };
     }
-    await client.rest("PUT", `repos/${repo}/rulesets/${existing.id}`, { body: rulesetBody, timeoutMs: 2e4 });
-    return { action: "updated", detail: `ruleset ${existing.id}` };
+    await client.rest("PUT", `repos/${repo}/rulesets/${existing.id}`, { body, timeoutMs: 2e4 });
+    return { action: "updated", enforcement, detail: `ruleset ${existing.id}` };
   }
-  await client.rest("POST", `repos/${repo}/rulesets`, { body: rulesetBody, timeoutMs: 2e4 });
-  return { action: "created" };
+  await client.rest("POST", `repos/${repo}/rulesets`, { body, timeoutMs: 2e4 });
+  return { action: "created", enforcement };
 }
 
 // src/workflow-context.ts
@@ -8109,6 +8130,32 @@ async function seedRulesetRefIfMissing(repo, deps, derivedVars, baseBranch, resu
     result.errors.push(`ruleset reference seed failed: ${e.message}`);
   }
 }
+async function parkProductRuleset(repo, deps) {
+  const result = { repo, applied: [], skipped: [], errors: [] };
+  try {
+    const list = await deps.client.rest("GET", `repos/${repo}/rulesets`, { timeoutMs: 2e4 });
+    const existing = findProductRuleset(list ?? []);
+    if (existing?.id == null) {
+      result.skipped.push(`no ${PRODUCT_RULESET_NAME} ruleset on ${repo} \u2014 nothing to park`);
+      return result;
+    }
+    const detail = await deps.client.rest("GET", `repos/${repo}/rulesets/${existing.id}`, { timeoutMs: 2e4 });
+    if (detail.enforcement !== "active") {
+      result.skipped.push(`${PRODUCT_RULESET_NAME} is already ${detail.enforcement ?? "non-enforcing"}`);
+      return result;
+    }
+    await deps.client.rest("PUT", `repos/${repo}/rulesets/${existing.id}`, {
+      body: { ...detail, enforcement: "disabled" },
+      timeoutMs: 2e4
+    });
+    result.applied.push(
+      `${PRODUCT_RULESET_NAME} parked (disabled; contexts [${rulesetRequiredContexts(detail).join(", ") || "none"}] kept)`
+    );
+  } catch (e) {
+    result.errors.push(`park failed: ${e.message}`);
+  }
+  return result;
+}
 async function applyCiReconcileRepo(repo, deps) {
   const merge = await applyCiReconcileMergeSettings(repo, deps);
   const meta = await deps.getProjectMeta(slugFromRepo(repo));
@@ -8126,6 +8173,12 @@ async function applyCiReconcileRepo(repo, deps) {
     merge.errors.push(`missing ${PRODUCT_RULESET_REF} on development \u2014 run bootstrap apply first`);
     return merge;
   }
+  if (!await gateIsProvenGreen(repo, deps.client, "development")) {
+    merge.skipped.push(
+      "product ruleset left non-enforcing \u2014 the gate is not green on development; activating it would block every PR (#3694)"
+    );
+    return merge;
+  }
   try {
     let body = stripRulesetComment(raw);
     if (!driftCheck?.ok) {
@@ -9359,7 +9412,7 @@ function boardConfigFromProject(meta, floor = {}) {
 
 // src/cli-doctor-shared.ts
 var import_node_fs15 = require("node:fs");
-var import_node_path13 = require("node:path");
+var import_node_path14 = require("node:path");
 var import_node_fs16 = require("node:fs");
 
 // src/readiness-audit.ts
@@ -9477,6 +9530,193 @@ ${lines.join("\n")}`;
 
 // src/secrets.ts
 var import_node_child_process6 = require("node:child_process");
+
+// src/gh-create.ts
+var import_promises = require("node:fs/promises");
+var import_node_os3 = require("node:os");
+var import_node_path13 = require("node:path");
+var import_node_crypto3 = require("node:crypto");
+var ISSUE_TYPES = ["bug", "feature", "task"];
+var GH_MUTATION_TIMEOUT_MS = 12e4;
+function timeoutKillNote(err, timeoutMs) {
+  if (typeof err !== "object" || err === null || !err.killed) return void 0;
+  return `killed at the ${timeoutMs}ms timeout \u2014 the write may have completed server-side; verify before retrying`;
+}
+function normalizePriority(priority) {
+  const p = priority.trim().toLowerCase().replace(/[\s_-]+/g, "");
+  if (!CLI_PRIORITIES.includes(p)) {
+    throw new Error(`unknown priority "${priority}" \u2014 expected one of: ${CLI_PRIORITIES.join(", ")}`);
+  }
+  return p;
+}
+function parseCreatedUrl(stdout) {
+  const re = /https:\/\/github\.com\/[^\s]+\/(?:issues|pull)\/(\d+)/g;
+  let match;
+  let last;
+  while ((match = re.exec(stdout)) !== null) {
+    last = { number: Number(match[1]), url: match[0] };
+  }
+  if (!last) throw new Error(`could not find a github issue/PR URL in gh output:
+${stdout.trim() || "(empty)"}`);
+  return last;
+}
+function buildIssueArgs({ type, title, body, priority, repo, labels }) {
+  if (!ISSUE_TYPES.includes(type)) throw new Error(`unknown issue type "${type}" \u2014 expected one of: ${ISSUE_TYPES.join(", ")}`);
+  normalizePriority(priority);
+  const args = ["issue", "create"];
+  if (repo) args.push("--repo", repo);
+  args.push("--title", title, "--body", body, "--label", type);
+  for (const label of labels ?? []) args.push("--label", label);
+  return args;
+}
+async function ensureLabelsExist(labels, repo, deps = {}) {
+  const run = deps.run ?? execFileP2;
+  for (const label of new Set(labels)) {
+    const args = ["label", "create", label, "--color", "ededed"];
+    if (repo) args.push("--repo", repo);
+    try {
+      await run("gh", args, { timeout: GH_MUTATION_TIMEOUT_MS });
+    } catch {
+    }
+  }
+}
+async function bodyArgsViaFile(args, deps = {}) {
+  const i = args.indexOf("--body");
+  if (i === -1 || i + 1 >= args.length) return { args, cleanup: async () => {
+  } };
+  const write = deps.write ?? import_promises.writeFile;
+  const remove2 = deps.remove ?? import_promises.unlink;
+  const ensureDir = deps.ensureDir ?? import_promises.mkdir;
+  const dir = deps.dir ?? (0, import_node_os3.tmpdir)();
+  const file = (0, import_node_path13.join)(dir, `mmi-gh-body-${process.pid}-${(0, import_node_crypto3.randomBytes)(4).toString("hex")}.md`);
+  await ensureDir((0, import_node_path13.dirname)(file), { recursive: true }).catch(() => {
+  });
+  await write(file, args[i + 1], "utf8");
+  return {
+    args: [...args.slice(0, i), "--body-file", file, ...args.slice(i + 2)],
+    cleanup: async () => {
+      try {
+        await remove2(file);
+      } catch {
+      }
+    }
+  };
+}
+function buildAddToProjectArgs(projectId, contentId) {
+  if (!projectId) throw new Error("addToProject: projectId is required");
+  if (!contentId) throw new Error("addToProject: contentId is required");
+  return [
+    "api",
+    "graphql",
+    "-f",
+    "query=mutation($p:ID!,$c:ID!){addProjectV2ItemById(input:{projectId:$p,contentId:$c}){item{id}}}",
+    "-f",
+    `p=${projectId}`,
+    "-f",
+    `c=${contentId}`
+  ];
+}
+function parseAddedItemId(stdout) {
+  try {
+    return JSON.parse(stdout)?.data?.addProjectV2ItemById?.item?.id || void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isAlreadyOnBoardError(stderr) {
+  return /already exists in (?:this|the) project/i.test(stderr);
+}
+var CLOSING_KEYWORD = "clos(?:e|es|ed)|fix(?:es|ed)?|resolve(?:s|d)?";
+var CLOSING_CHAIN = new RegExp(
+  `\\b(${CLOSING_KEYWORD})(\\s+)#(\\d+)((?:\\s*(?:,|,?\\s+and)\\s*#\\d+)+)`,
+  "gi"
+);
+function normalizeClosingDirectives(body) {
+  if (!body.includes("#")) return body;
+  const segments = body.split(/(```[\s\S]*?```|~~~[\s\S]*?~~~|`[^`\n]*`)/g);
+  return segments.map(
+    (seg, i) => i % 2 === 1 ? seg : seg.replace(
+      CLOSING_CHAIN,
+      (_m, kw, ws, first, tail) => `${kw}${ws}#${first}${tail.replace(/#(\d+)/g, "closes #$1")}`
+    )
+  ).join("");
+}
+function buildPrArgs({ title, body, base, head, repo, draft }) {
+  const args = ["pr", "create"];
+  if (repo) args.push("--repo", repo);
+  args.push("--title", title, "--body", body);
+  if (base) args.push("--base", base);
+  if (head) args.push("--head", head);
+  if (draft) args.push("--draft");
+  return args;
+}
+function parseExistingPr(stderr) {
+  if (!/already exists/i.test(stderr)) return void 0;
+  const match = /https:\/\/\S*\/pull\/(\d+)/.exec(stderr);
+  if (!match) return void 0;
+  return { number: Number(match[1]), url: match[0] };
+}
+var GH_CREATE_UPSTREAM_RETRIES = 3;
+var GH_CREATE_RETRY_BACKOFF_MS = [2e3, 5e3];
+function httpStatusCodes(stderr) {
+  const out = [];
+  for (const m of stderr.matchAll(/\bHTTP\/?\d*(?:\.\d)?\s+(\d{3})\b/g)) out.push(Number(m[1]));
+  for (const m of stderr.matchAll(/\b(\d{3})\s+Internal Server Error\b/g)) out.push(Number(m[1]));
+  return out;
+}
+function isUpstreamGitHubFault(stderr) {
+  const codes = httpStatusCodes(stderr);
+  if (codes.some((c) => c >= 400 && c < 500)) return false;
+  if (codes.some((c) => c >= 500 && c < 600)) return true;
+  return /Something went wrong while executing your query/.test(stderr) || /^\s*unexpected end of JSON input\s*$/m.test(stderr);
+}
+function mayRetryCreate(verb) {
+  return verb === "pr";
+}
+function upstreamFaultMessage(verb, stderr) {
+  const requestId = /\b([0-9A-F]{4}:[0-9A-F]{4,6}:[0-9A-F]+:[0-9A-F]+:[0-9A-F]+)\b/.exec(stderr)?.[1];
+  const advice = mayRetryCreate(verb) ? "Retrying is the right action" : "The write may have completed server-side before the error \u2014 VERIFY before retrying, or a retry will duplicate it";
+  return `gh ${verb} create failed: GitHub's API is failing (server-side 5xx) \u2014 this is NOT a problem with your diff or arguments. GitHub request ID: ${requestId ?? "unavailable"}. ${advice}; note githubstatus.com may still read green while this is happening.`;
+}
+async function ghCreate(args, deps = {}) {
+  const exec = deps.exec ?? execFileP2;
+  const sleep3 = deps.sleep ?? ((ms) => new Promise((resolve5) => setTimeout(resolve5, ms)));
+  const swapped = await bodyArgsViaFile(args);
+  try {
+    for (let attempt = 1; attempt <= GH_CREATE_UPSTREAM_RETRIES; attempt++) {
+      try {
+        const { stdout } = await exec("gh", swapped.args, { timeout: GH_MUTATION_TIMEOUT_MS });
+        return parseCreatedUrl(stdout);
+      } catch (e) {
+        const err = e;
+        const errText = `${err.stderr ?? ""}
+${err.message ?? ""}`;
+        const faultText = (err.stderr ?? "").trim() ? err.stderr : err.message ?? "";
+        const existing = args[0] === "pr" ? parseExistingPr(errText) : void 0;
+        if (existing) {
+          await swapped.cleanup();
+          console.warn(`${args[0]} create: a PR already exists for this branch \u2014 #${existing.number} (nothing to do)`);
+          return { ...existing, existing: true };
+        }
+        const note = timeoutKillNote(e, GH_MUTATION_TIMEOUT_MS);
+        if (isUpstreamGitHubFault(faultText) && mayRetryCreate(args[0]) && attempt < GH_CREATE_UPSTREAM_RETRIES) {
+          const waitMs = GH_CREATE_RETRY_BACKOFF_MS[attempt - 1];
+          console.warn(`gh ${args[0]} create: GitHub API server fault (attempt ${attempt}/${GH_CREATE_UPSTREAM_RETRIES}) \u2014 retrying in ${waitMs}ms`);
+          await sleep3(waitMs);
+          continue;
+        }
+        await swapped.cleanup();
+        if (isUpstreamGitHubFault(faultText)) return fail(upstreamFaultMessage(args[0], faultText));
+        return fail(`gh ${args[0]} create failed: ${(err.stderr || err.message || String(e)).trim()}${note ? ` (${note})` : ""}`);
+      }
+    }
+    throw new Error("ghCreate: retry loop exhausted without a verdict");
+  } finally {
+    await swapped.cleanup();
+  }
+}
+
+// src/secrets.ts
 var OWNER = "mutmutco";
 var SSM_ROOT = "/mmi-future";
 var PROJECT_TIER_SEGMENT = "dev";
@@ -10105,6 +10345,15 @@ async function secretsRequest(deps, key, opts) {
     deps.err(`invalid secret key ${JSON.stringify(key)}`);
     return false;
   }
+  let priority = "medium";
+  if (opts.priority !== void 0) {
+    try {
+      priority = normalizePriority(opts.priority);
+    } catch (e) {
+      deps.err(`secrets request: ${e.message}`);
+      return false;
+    }
+  }
   const repo = await targetRepo(deps, opts);
   const requester = await probeCapabilities(deps, repo);
   if (requester?.role === "master") {
@@ -10122,7 +10371,7 @@ async function secretsRequest(deps, key, opts) {
     body: JSON.stringify({
       repo,
       key,
-      priority: opts.priority ?? "medium",
+      priority,
       reason: opts.reason,
       context: opts.context
     }),
@@ -10749,7 +10998,7 @@ async function localBranchHeads() {
 }
 async function currentRepoWorktreeGitRoot(repoRoot2) {
   const gitCommonDir = (await execFileP2("git", ["rev-parse", "--git-common-dir"], { timeout: GIT_TIMEOUT_MS }).catch(() => ({ stdout: "" }))).stdout.trim();
-  return gitCommonDir ? (0, import_node_path13.resolve)(repoRoot2, gitCommonDir, "worktrees") : "";
+  return gitCommonDir ? (0, import_node_path14.resolve)(repoRoot2, gitCommonDir, "worktrees") : "";
 }
 async function worktreeBranches() {
   const { stdout } = await execFileP2("git", ["worktree", "list", "--porcelain"], { timeout: GIT_TIMEOUT_MS });
@@ -10769,7 +11018,7 @@ function resolveGitdirForWorktreeFile(worktreePath, content) {
   const match = /^gitdir:\s*(.+)\s*$/im.exec(content);
   if (!match?.[1]) return void 0;
   const raw = match[1].trim();
-  return (0, import_node_path13.isAbsolute)(raw) ? raw : (0, import_node_path13.resolve)(worktreePath, raw);
+  return (0, import_node_path14.isAbsolute)(raw) ? raw : (0, import_node_path14.resolve)(worktreePath, raw);
 }
 function metadataOwnsMissingWorktreeDir(worktreePath, worktreeGitRoot) {
   if (!worktreeGitRoot) return false;
@@ -10778,9 +11027,9 @@ function metadataOwnsMissingWorktreeDir(worktreePath, worktreeGitRoot) {
     for (const ent of entries) {
       if (!ent.isDirectory()) continue;
       try {
-        const gitdirPath = (0, import_node_fs15.readFileSync)((0, import_node_path13.join)(worktreeGitRoot, ent.name, "gitdir"), "utf8").trim();
-        const resolvedGitdir = (0, import_node_path13.isAbsolute)(gitdirPath) ? gitdirPath : (0, import_node_path13.resolve)(worktreeGitRoot, ent.name, gitdirPath);
-        if (sameWorktreeMetadataPath((0, import_node_path13.dirname)(resolvedGitdir), worktreePath)) return true;
+        const gitdirPath = (0, import_node_fs15.readFileSync)((0, import_node_path14.join)(worktreeGitRoot, ent.name, "gitdir"), "utf8").trim();
+        const resolvedGitdir = (0, import_node_path14.isAbsolute)(gitdirPath) ? gitdirPath : (0, import_node_path14.resolve)(worktreeGitRoot, ent.name, gitdirPath);
+        if (sameWorktreeMetadataPath((0, import_node_path14.dirname)(resolvedGitdir), worktreePath)) return true;
       } catch {
       }
     }
@@ -10799,7 +11048,7 @@ function pathExistsKnown(path2) {
   }
 }
 function inspectSiblingWorktreeDir(path2, worktreeGitRoot) {
-  const gitPath = (0, import_node_path13.join)(path2, ".git");
+  const gitPath = (0, import_node_path14.join)(path2, ".git");
   let st;
   try {
     st = (0, import_node_fs16.lstatSync)(gitPath);
@@ -10853,7 +11102,7 @@ async function preservedBranches() {
 async function siblingWorktreeDirs(explicitRoot) {
   const repoRoot2 = (await execFileP2("git", ["rev-parse", "--show-toplevel"], { timeout: GIT_TIMEOUT_MS }).catch(() => ({ stdout: "" }))).stdout.trim() || process.cwd();
   const worktreeGitRoot = await currentRepoWorktreeGitRoot(repoRoot2);
-  const primaryRepoRoot = worktreeGitRoot ? (0, import_node_path13.dirname)((0, import_node_path13.dirname)(worktreeGitRoot)) : repoRoot2;
+  const primaryRepoRoot = worktreeGitRoot ? (0, import_node_path14.dirname)((0, import_node_path14.dirname)(worktreeGitRoot)) : repoRoot2;
   try {
     const dirs = explicitRoot ? listDirsIn(resolveExplicitScanRoot(explicitRoot, primaryRepoRoot)) : worktreeScanDirs(siblingMmiWorktreesRoot(primaryRepoRoot), primaryRepoRoot, listDirsIn, isRepoCheckoutDir);
     return dirs.map((dir) => inspectSiblingWorktreeDir(dir, worktreeGitRoot)).filter((entry) => Boolean(entry));
@@ -10863,13 +11112,13 @@ async function siblingWorktreeDirs(explicitRoot) {
 }
 function listDirsIn(dir) {
   try {
-    return (0, import_node_fs16.readdirSync)(dir, { withFileTypes: true }).filter((ent) => ent.isDirectory()).map((ent) => (0, import_node_path13.join)(dir, ent.name));
+    return (0, import_node_fs16.readdirSync)(dir, { withFileTypes: true }).filter((ent) => ent.isDirectory()).map((ent) => (0, import_node_path14.join)(dir, ent.name));
   } catch {
     return [];
   }
 }
 function isRepoCheckoutDir(dir) {
-  return (0, import_node_fs16.existsSync)((0, import_node_path13.join)(dir, ".git"));
+  return (0, import_node_fs16.existsSync)((0, import_node_path14.join)(dir, ".git"));
 }
 function resolveExplicitScanRoot(explicitRoot, repoRoot2) {
   let rootDirs;
@@ -10940,7 +11189,7 @@ function measureWorktreeRoot(root, deadline) {
       continue;
     }
     for (const ent of entries) {
-      const child2 = (0, import_node_path13.join)(current, ent.name);
+      const child2 = (0, import_node_path14.join)(current, ent.name);
       if (ent.isDirectory()) {
         if (depth0) dirs++;
         let isLink = false;
@@ -10963,7 +11212,7 @@ function measureWorktreeRoot(root, deadline) {
 }
 function worktreeRootsProbe(repoRoot2) {
   const authoritative = siblingMmiWorktreesRoot(repoRoot2);
-  const container = (0, import_node_path13.dirname)(authoritative);
+  const container = (0, import_node_path14.dirname)(authoritative);
   let names;
   try {
     names = (0, import_node_fs16.readdirSync)(container, { withFileTypes: true }).filter((ent) => ent.isDirectory()).map((ent) => ent.name);
@@ -12094,191 +12343,6 @@ async function resolveAutoAddBoardAttach(client, cfg, selector, priority, warn =
   return { projectItemId };
 }
 
-// src/gh-create.ts
-var import_promises = require("node:fs/promises");
-var import_node_os3 = require("node:os");
-var import_node_path14 = require("node:path");
-var import_node_crypto3 = require("node:crypto");
-var ISSUE_TYPES = ["bug", "feature", "task"];
-var GH_MUTATION_TIMEOUT_MS = 12e4;
-function timeoutKillNote(err, timeoutMs) {
-  if (typeof err !== "object" || err === null || !err.killed) return void 0;
-  return `killed at the ${timeoutMs}ms timeout \u2014 the write may have completed server-side; verify before retrying`;
-}
-function normalizePriority(priority) {
-  const p = priority.trim().toLowerCase().replace(/[\s_-]+/g, "");
-  if (!CLI_PRIORITIES.includes(p)) {
-    throw new Error(`unknown priority "${priority}" \u2014 expected one of: ${CLI_PRIORITIES.join(", ")}`);
-  }
-  return p;
-}
-function parseCreatedUrl(stdout) {
-  const re = /https:\/\/github\.com\/[^\s]+\/(?:issues|pull)\/(\d+)/g;
-  let match;
-  let last;
-  while ((match = re.exec(stdout)) !== null) {
-    last = { number: Number(match[1]), url: match[0] };
-  }
-  if (!last) throw new Error(`could not find a github issue/PR URL in gh output:
-${stdout.trim() || "(empty)"}`);
-  return last;
-}
-function buildIssueArgs({ type, title, body, priority, repo, labels }) {
-  if (!ISSUE_TYPES.includes(type)) throw new Error(`unknown issue type "${type}" \u2014 expected one of: ${ISSUE_TYPES.join(", ")}`);
-  normalizePriority(priority);
-  const args = ["issue", "create"];
-  if (repo) args.push("--repo", repo);
-  args.push("--title", title, "--body", body, "--label", type);
-  for (const label of labels ?? []) args.push("--label", label);
-  return args;
-}
-async function ensureLabelsExist(labels, repo, deps = {}) {
-  const run = deps.run ?? execFileP2;
-  for (const label of new Set(labels)) {
-    const args = ["label", "create", label, "--color", "ededed"];
-    if (repo) args.push("--repo", repo);
-    try {
-      await run("gh", args, { timeout: GH_MUTATION_TIMEOUT_MS });
-    } catch {
-    }
-  }
-}
-async function bodyArgsViaFile(args, deps = {}) {
-  const i = args.indexOf("--body");
-  if (i === -1 || i + 1 >= args.length) return { args, cleanup: async () => {
-  } };
-  const write = deps.write ?? import_promises.writeFile;
-  const remove2 = deps.remove ?? import_promises.unlink;
-  const ensureDir = deps.ensureDir ?? import_promises.mkdir;
-  const dir = deps.dir ?? (0, import_node_os3.tmpdir)();
-  const file = (0, import_node_path14.join)(dir, `mmi-gh-body-${process.pid}-${(0, import_node_crypto3.randomBytes)(4).toString("hex")}.md`);
-  await ensureDir((0, import_node_path14.dirname)(file), { recursive: true }).catch(() => {
-  });
-  await write(file, args[i + 1], "utf8");
-  return {
-    args: [...args.slice(0, i), "--body-file", file, ...args.slice(i + 2)],
-    cleanup: async () => {
-      try {
-        await remove2(file);
-      } catch {
-      }
-    }
-  };
-}
-function buildAddToProjectArgs(projectId, contentId) {
-  if (!projectId) throw new Error("addToProject: projectId is required");
-  if (!contentId) throw new Error("addToProject: contentId is required");
-  return [
-    "api",
-    "graphql",
-    "-f",
-    "query=mutation($p:ID!,$c:ID!){addProjectV2ItemById(input:{projectId:$p,contentId:$c}){item{id}}}",
-    "-f",
-    `p=${projectId}`,
-    "-f",
-    `c=${contentId}`
-  ];
-}
-function parseAddedItemId(stdout) {
-  try {
-    return JSON.parse(stdout)?.data?.addProjectV2ItemById?.item?.id || void 0;
-  } catch {
-    return void 0;
-  }
-}
-function isAlreadyOnBoardError(stderr) {
-  return /already exists in (?:this|the) project/i.test(stderr);
-}
-var CLOSING_KEYWORD = "clos(?:e|es|ed)|fix(?:es|ed)?|resolve(?:s|d)?";
-var CLOSING_CHAIN = new RegExp(
-  `\\b(${CLOSING_KEYWORD})(\\s+)#(\\d+)((?:\\s*(?:,|,?\\s+and)\\s*#\\d+)+)`,
-  "gi"
-);
-function normalizeClosingDirectives(body) {
-  if (!body.includes("#")) return body;
-  const segments = body.split(/(```[\s\S]*?```|~~~[\s\S]*?~~~|`[^`\n]*`)/g);
-  return segments.map(
-    (seg, i) => i % 2 === 1 ? seg : seg.replace(
-      CLOSING_CHAIN,
-      (_m, kw, ws, first, tail) => `${kw}${ws}#${first}${tail.replace(/#(\d+)/g, "closes #$1")}`
-    )
-  ).join("");
-}
-function buildPrArgs({ title, body, base, head, repo, draft }) {
-  const args = ["pr", "create"];
-  if (repo) args.push("--repo", repo);
-  args.push("--title", title, "--body", body);
-  if (base) args.push("--base", base);
-  if (head) args.push("--head", head);
-  if (draft) args.push("--draft");
-  return args;
-}
-function parseExistingPr(stderr) {
-  if (!/already exists/i.test(stderr)) return void 0;
-  const match = /https:\/\/\S*\/pull\/(\d+)/.exec(stderr);
-  if (!match) return void 0;
-  return { number: Number(match[1]), url: match[0] };
-}
-var GH_CREATE_UPSTREAM_RETRIES = 3;
-var GH_CREATE_RETRY_BACKOFF_MS = [2e3, 5e3];
-function httpStatusCodes(stderr) {
-  const out = [];
-  for (const m of stderr.matchAll(/\bHTTP\/?\d*(?:\.\d)?\s+(\d{3})\b/g)) out.push(Number(m[1]));
-  for (const m of stderr.matchAll(/\b(\d{3})\s+Internal Server Error\b/g)) out.push(Number(m[1]));
-  return out;
-}
-function isUpstreamGitHubFault(stderr) {
-  const codes = httpStatusCodes(stderr);
-  if (codes.some((c) => c >= 400 && c < 500)) return false;
-  if (codes.some((c) => c >= 500 && c < 600)) return true;
-  return /Something went wrong while executing your query/.test(stderr) || /^\s*unexpected end of JSON input\s*$/m.test(stderr);
-}
-function mayRetryCreate(verb) {
-  return verb === "pr";
-}
-function upstreamFaultMessage(verb, stderr) {
-  const requestId = /\b([0-9A-F]{4}:[0-9A-F]{4,6}:[0-9A-F]+:[0-9A-F]+:[0-9A-F]+)\b/.exec(stderr)?.[1];
-  const advice = mayRetryCreate(verb) ? "Retrying is the right action" : "The write may have completed server-side before the error \u2014 VERIFY before retrying, or a retry will duplicate it";
-  return `gh ${verb} create failed: GitHub's API is failing (server-side 5xx) \u2014 this is NOT a problem with your diff or arguments. GitHub request ID: ${requestId ?? "unavailable"}. ${advice}; note githubstatus.com may still read green while this is happening.`;
-}
-async function ghCreate(args, deps = {}) {
-  const exec = deps.exec ?? execFileP2;
-  const sleep3 = deps.sleep ?? ((ms) => new Promise((resolve5) => setTimeout(resolve5, ms)));
-  const swapped = await bodyArgsViaFile(args);
-  try {
-    for (let attempt = 1; attempt <= GH_CREATE_UPSTREAM_RETRIES; attempt++) {
-      try {
-        const { stdout } = await exec("gh", swapped.args, { timeout: GH_MUTATION_TIMEOUT_MS });
-        return parseCreatedUrl(stdout);
-      } catch (e) {
-        const err = e;
-        const errText = `${err.stderr ?? ""}
-${err.message ?? ""}`;
-        const faultText = (err.stderr ?? "").trim() ? err.stderr : err.message ?? "";
-        const existing = args[0] === "pr" ? parseExistingPr(errText) : void 0;
-        if (existing) {
-          await swapped.cleanup();
-          console.warn(`${args[0]} create: a PR already exists for this branch \u2014 #${existing.number} (nothing to do)`);
-          return { ...existing, existing: true };
-        }
-        const note = timeoutKillNote(e, GH_MUTATION_TIMEOUT_MS);
-        if (isUpstreamGitHubFault(faultText) && mayRetryCreate(args[0]) && attempt < GH_CREATE_UPSTREAM_RETRIES) {
-          const waitMs = GH_CREATE_RETRY_BACKOFF_MS[attempt - 1];
-          console.warn(`gh ${args[0]} create: GitHub API server fault (attempt ${attempt}/${GH_CREATE_UPSTREAM_RETRIES}) \u2014 retrying in ${waitMs}ms`);
-          await sleep3(waitMs);
-          continue;
-        }
-        await swapped.cleanup();
-        if (isUpstreamGitHubFault(faultText)) return fail(upstreamFaultMessage(args[0], faultText));
-        return fail(`gh ${args[0]} create failed: ${(err.stderr || err.message || String(e)).trim()}${note ? ` (${note})` : ""}`);
-      }
-    }
-    throw new Error("ghCreate: retry loop exhausted without a verdict");
-  } finally {
-    await swapped.cleanup();
-  }
-}
-
 // src/issue-body.ts
 var import_node_os4 = require("node:os");
 var TextArgError = class extends Error {
@@ -12684,6 +12748,32 @@ function withExamples(cmd, examples, note) {
   cmd.addHelpText("after", lines.join("\n") + "\n");
   return cmd;
 }
+var DECLARED_OPTIONS = /* @__PURE__ */ Symbol.for("mmi.commandManifest.declaredOptions");
+function withDeclaredOptions(cmd, options, footer) {
+  cmd[DECLARED_OPTIONS] = options;
+  const width = Math.max(...options.map((o) => o.flags.length));
+  const lines = ["", "Options:", ...options.map((o) => `  ${o.flags.padEnd(width)}  ${o.description}`)];
+  if (footer?.length) lines.push("", ...footer);
+  cmd.addHelpText("after", lines.join("\n") + "\n");
+  return cmd;
+}
+function readDeclaredOptions(cmd) {
+  const declared = cmd[DECLARED_OPTIONS];
+  if (!Array.isArray(declared)) return [];
+  return declared.map((o) => {
+    const takesValue = /[<[]/.test(o.flags);
+    return {
+      flags: o.flags,
+      description: o.description,
+      mandatory: false,
+      valueRequired: /</.test(o.flags),
+      optional: /\[/.test(o.flags),
+      takesValue,
+      variadic: o.flags.includes("..."),
+      negate: o.flags.includes("--no-")
+    };
+  });
+}
 function readExamples(cmd) {
   const ex = cmd[EXAMPLES];
   return Array.isArray(ex) && ex.length ? ex : void 0;
@@ -12723,12 +12813,14 @@ function buildCommand(cmd, path2) {
     name: cmd.name(),
     path: path2,
     arguments: cmd.registeredArguments.map(buildArgument),
-    options: cmd.options.map(buildOption),
+    // A hand-parsed command registers no Commander options, so its declared set is merged in (#3682).
+    options: [...cmd.options.map(buildOption), ...readDeclaredOptions(cmd)],
     subcommands: cmd.commands.map(
       (child2) => buildCommand(child2, path2 ? `${path2} ${child2.name()}` : child2.name())
     ),
     ...metadata
   };
+  if (cmd._allowUnknownOption) out.parses_own_argv = true;
   const description = cmd.description();
   if (description) out.description = description;
   const examples = readExamples(cmd);
@@ -16021,6 +16113,22 @@ async function auditTrainBranch(repo, branch, owners, deps, projectAdmins = /* @
     restrictions = null;
   }
   if (!restrictions) {
+    let branchExists = true;
+    try {
+      branchExists = Boolean(await deps.client.rest("GET", `repos/${repo}/branches/${branch}`));
+    } catch {
+      branchExists = false;
+    }
+    if (!branchExists) {
+      return [{
+        repo,
+        branch,
+        kind: "train-branch-missing",
+        severity: "medium",
+        detail: `${branch} is in this repo's locked train set but does not exist \u2014 either the branch was never created, or the repo's releaseTrack does not actually include it`,
+        remediation: `create it: gh api -X POST repos/${repo}/git/refs -f ref=refs/heads/${branch} -f sha=<development sha>, then initialize the lock (docs/Guides/repo-access.md). If the repo has no ${branch} stage, set its real track instead: mmi-cli org project set --var releaseTrack=<direct|trunk>`
+      }];
+    }
     return [{
       repo,
       branch,
@@ -18124,17 +18232,7 @@ function registerSecretsCommands(program3) {
     if (!ok) process.exitCode = 1;
   }));
   secrets.command("rm <key>").description("remove a secret from your own full project vault; org-infra requires master or an exact grant. --slug _org removes an org-infra <provider>/<KEY> value (#3315)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--slug <slug>", "org-infra namespace (e.g. _org) for the value removal \u2014 master or an exact grant (#3315)").action((key, o) => withSecrets((d) => secretsRemove(d, key, o)));
-  secrets.command("use").usage("<key> | --key <key> [--key <key>\u2026]  [-- <command>] [--repo <owner/repo>] [--slug <slug>] [--name <ENVVAR>]").argument("[args...]", "one secret key (or use --key), then `--` and the command to run").description("consume secrets KEYLESS: own-project full tree or exactly granted org-infra keys; injects each into the command env and never prints one. ONE positional key, or several via repeated `--key` (#3561). The wrapped command keeps its OWN flags (`-- node -e \u2026`, `-- curl -H \u2026`) with or without the `--`, because npm's PowerShell shim swallows `--` before the CLI sees it (#3436)").allowUnknownOption().helpOption(false).addHelpText("after", [
-    "",
-    "Options:",
-    "  --key <key>          a secret key; repeat for several. The only form no shell can misread \u2014",
-    "                       `npm` and `slack/token` are BOTH valid key names and plausible commands.",
-    "  --repo <owner/repo>  target repo (defaults to the current repo)",
-    "  --slug <slug>        org-infra namespace (e.g. _org) for a granted org secret",
-    "  --name <ENVVAR>      env var to inject under, single key only (default: the key leaf, UPPER_SNAKE)",
-    "",
-    "These belong BEFORE the `--`. Everything after it is the wrapped command, untouched."
-  ].join("\n")).action(function() {
+  secrets.command("use").usage("<key> | --key <key> [--key <key>\u2026]  [-- <command>] [--repo <owner/repo>] [--slug <slug>] [--name <ENVVAR>]").argument("[args...]", "one secret key (or use --key), then `--` and the command to run").description("consume secrets KEYLESS: own-project full tree or exactly granted org-infra keys; injects each into the command env and never prints one. ONE positional key, or several via repeated `--key` (#3561). The wrapped command keeps its OWN flags (`-- node -e \u2026`, `-- curl -H \u2026`) with or without the `--`, because npm's PowerShell shim swallows `--` before the CLI sees it (#3436)").allowUnknownOption().helpOption(false).action(function() {
     const parsed = parseSecretsUseArgv(secretsUseTail(process.argv));
     if (parsed.kind === "help") return this.outputHelp();
     return withSecrets(async (d) => {
@@ -18148,6 +18246,16 @@ function registerSecretsCommands(program3) {
       if (ok === false) process.exitCode = 1;
     });
   });
+  withDeclaredOptions(
+    secrets.commands.find((c) => c.name() === "use"),
+    [
+      { flags: "--key <key>", description: "a secret key; repeat for several. The only form no shell can misread \u2014 `npm` and `slack/token` are BOTH valid key names and plausible commands." },
+      { flags: "--repo <owner/repo>", description: "target repo (defaults to the current repo)" },
+      { flags: "--slug <slug>", description: "org-infra namespace (e.g. _org) for a granted org secret" },
+      { flags: "--name <ENVVAR>", description: "env var to inject under, single key only (default: the key leaf, UPPER_SNAKE)" }
+    ],
+    ["These belong BEFORE the `--`. Everything after it is the wrapped command, untouched."]
+  );
   secrets.command("grant <repo> <login> <key>").description("MASTER-ONLY: grant a project-admin standing access to an org-infra secret. Default is read/write on one exact key; --read grants keyless USE only, and only --read accepts a wildcard key (`*` = the whole namespace, `<provider>/*` = one provider group) (#3652)").option("--read", "read-only: permits keyless `secrets use`, never `set`/`rm`. Required for a wildcard key.").action((repo, login, key, o) => withSecrets((d) => secretsGrant(d, repo, login, key, { read: o.read })));
   secrets.command("revoke <repo> <login> <key>").description("MASTER-ONLY: withdraw a previously granted org-infra secret access (pass the grant key exactly as granted, wildcard included)").action((repo, login, key) => withSecrets((d) => secretsRevoke(d, repo, login, key, {})));
 }
@@ -19901,7 +20009,7 @@ function registerQueryCommands(program3) {
   const pr2 = program3.commands.find((c) => c.name() === "pr");
   if (!issue2 || !pr2) return;
   const deps = queryDeps();
-  issue2.command("list").description("bounded issue read \u2014 filter by label/state/assignee (NO free-text search); always prints JSON").option("--label <label>", "filter by label").option("--state <state>", "open | closed | all", "open").option("--assignee <login>", "filter by assignee login").option("--limit <n>", "max issues to return (capped at 100)", (v) => Number(v), DEFAULT_LIMIT).option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "machine-readable output (already the default \u2014 accepted for contract uniformity)").action(async (o) => {
+  issue2.command("list").description("bounded issue read \u2014 filter by label/state/assignee (NO free-text search); always prints JSON").option("--label <label>", "filter by label").addOption(new Option("--state <state>", "open | closed | all").default("open").choices(ISSUE_STATES)).option("--assignee <login>", "filter by assignee login").option("--limit <n>", "max issues to return (capped at 100)", (v) => Number(v), DEFAULT_LIMIT).option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "machine-readable output (already the default \u2014 accepted for contract uniformity)").action(async (o) => {
     try {
       const state = validateEnum("--state", ISSUE_STATES, o.state, "issue list");
       const rows = await runIssueList(deps, { label: o.label, state, assignee: o.assignee, limit: o.limit, repo: o.repo });
@@ -19920,7 +20028,7 @@ function registerQueryCommands(program3) {
       queryFail("issue children", e);
     }
   });
-  pr2.command("list").description("bounded PR read \u2014 --mine scopes to the viewer's own PRs (resolves the viewer via gh); always prints JSON").option("--mine", "only the caller's own PRs (resolves the viewer via `gh api user`)").option("--state <state>", "open | all", "open").option("--limit <n>", "max PRs to return (capped at 100)", (v) => Number(v), DEFAULT_LIMIT).option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "machine-readable output (already the default \u2014 accepted for contract uniformity)").action(async (o) => {
+  pr2.command("list").description("bounded PR read \u2014 --mine scopes to the viewer's own PRs (resolves the viewer via gh); always prints JSON").option("--mine", "only the caller's own PRs (resolves the viewer via `gh api user`)").addOption(new Option("--state <state>", "open | all").default("open").choices(PR_STATES)).option("--limit <n>", "max PRs to return (capped at 100)", (v) => Number(v), DEFAULT_LIMIT).option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "machine-readable output (already the default \u2014 accepted for contract uniformity)").action(async (o) => {
     try {
       const state = validateEnum("--state", PR_STATES, o.state, "pr list");
       const rows = await runPrList(deps, { mine: o.mine, state, limit: o.limit, repo: o.repo });
@@ -20071,6 +20179,21 @@ async function rulesetDetails2(deps, repo, list) {
   }
   return details;
 }
+async function orgRulesetExclusion(deps, repo) {
+  const [owner, name] = repo.split("/");
+  if (!owner || !name) return null;
+  const list = await restJson3(deps, `orgs/${owner}/rulesets`, []);
+  const excluding = [];
+  for (const ruleset of list) {
+    if (ruleset.id == null || ruleset.target !== "branch" || ruleset.enforcement !== "active") continue;
+    const full = await restJson3(deps, `orgs/${owner}/rulesets/${ruleset.id}`, null);
+    const excluded = full?.conditions?.repository_name?.exclude ?? [];
+    if (excluded.some((entry) => entry.toLowerCase() === name.toLowerCase())) {
+      excluding.push(full?.name ?? String(ruleset.id));
+    }
+  }
+  return excluding.length ? excluding.join(", ") : null;
+}
 function repoRefsMatch(a, b) {
   return a.toLowerCase() === b.toLowerCase();
 }
@@ -20134,11 +20257,12 @@ async function verifyBootstrap(repo, repoClass, deps, releaseTrack) {
   });
   try {
     const owners = new Set(await resolveOwners(deps));
-    const overgrants = await auditRepoCollaborators(repo, owners, deps);
+    const sanctioned = new Set(deps.sanctionedAdmins ?? []);
+    const overgrants = (await auditRepoCollaborators(repo, owners, deps, /* @__PURE__ */ new Set(), sanctioned)).filter((f) => f.kind === "collaborator-overgrant");
     checks.push({
       ok: overgrants.length === 0,
       label: "collaborator roles are master-only (no admin/maintain over-grant)",
-      detail: overgrants.length ? `over-granted: ${overgrants.map((f) => f.actor).join(", ")}` : void 0
+      detail: overgrants.length ? `over-granted: ${overgrants.map((f) => f.actor).join(", ")}` : sanctioned.size ? `sanctioned admin: ${[...sanctioned].join(", ")} (access-matrix.json, an owner decision)` : void 0
     });
   } catch {
   }
@@ -20314,10 +20438,11 @@ async function verifyBootstrap(repo, repoClass, deps, releaseTrack) {
   );
   const orgRuleset = activeOrgRulesets.find((ruleset) => missingRuleTypes(ruleset, requiredOrgRulesetTypes).length === 0);
   const missingOrgRuleTypes = activeOrgRulesets.length === 0 ? requiredOrgRulesetTypes : missingRuleTypes(activeOrgRulesets[0], requiredOrgRulesetTypes);
+  const excludedByOrgRuleset = orgRuleset ? null : await orgRulesetExclusion(deps, repo);
   checks.push({
-    ok: Boolean(orgRuleset),
+    ok: Boolean(orgRuleset) || Boolean(excludedByOrgRuleset),
     label: "covered by an active org ruleset",
-    detail: orgRuleset ? void 0 : activeOrgRulesets.length === 0 ? "no active Organization-sourced branch ruleset targets this repo" : `missing rule types: ${missingOrgRuleTypes.join(", ")}`
+    detail: orgRuleset ? void 0 : excludedByOrgRuleset ? `deliberately excluded by name from ${excludedByOrgRuleset} \u2014 an owner decision, not drift (org-architecture.md \xA74)` : activeOrgRulesets.length === 0 ? "no active Organization-sourced branch ruleset targets this repo" : `missing rule types: ${missingOrgRuleTypes.join(", ")}`
   });
   if (repo === HUB_REPO4) {
     const statusChecks = rulesetStatusChecks2(rulesets.filter((r) => r.target === "branch" && r.enforcement === "active"));
@@ -20466,13 +20591,13 @@ async function fetchOrgNoAgentFilesRuleset(client, org = ORG_LOGIN) {
 
 // src/bootstrap-commands.ts
 function registerBootstrapCommands(program3) {
-  const bootstrap = program3.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").action((o) => {
+  const bootstrap = program3.command("bootstrap").description("plan repo bootstrap operations; mutations require master-admin approval").option("--repo <owner/repo>", "target repo").addOption(new Option("--class <class>", "deployable | content").default("deployable").choices(["deployable", "content"])).option("--json", "machine-readable output").action((o) => {
     if (!o.repo) return fail("bootstrap: required option --repo <owner/repo> not specified");
     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) => {
+  bootstrap.command("verify <repo>").description("audit whether an existing repo is bootstrapped correctly; no mutations").addOption(new Option("--class <class>", "deployable | content").default("deployable").choices(["deployable", "content"])).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 cfg = await loadConfig();
@@ -20487,6 +20612,10 @@ function registerBootstrapCommands(program3) {
       readLocalFile: (path2) => path2 === "projects.json" && apiProjects != null ? apiProjects : (0, import_node_fs22.existsSync)(path2) ? (0, import_node_fs22.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.
+      // #3689: the same committed map the org access audit reads (#3664), so a sanctioned admin is not a
+      // permanent bootstrap failure on one surface and an intended state on the other. Absent file → no
+      // sanction, which is the pre-#3664 behaviour.
+      sanctionedAdmins: (0, import_node_fs22.existsSync)("access-matrix.json") ? entriesValueByCanonicalRepo(loadSanctionedAdmins((0, import_node_fs22.readFileSync)("access-matrix.json", "utf8")), repo) : void 0,
       requiredGcpApis: (() => {
         const v = meta?.requiredGcpApis;
         if (Array.isArray(v)) return v;
@@ -20521,7 +20650,7 @@ function registerBootstrapCommands(program3) {
     else console.log(renderOrgRulesetDriftReport(plan));
     if (plan.action !== "noop") process.exitCode = 1;
   });
-  bootstrap.command("apply <repo>").description("run from the MMI-Hub repo root: idempotent seed apply from skills/bootstrap/seeds/manifest.json; dry-run unless --execute (live, master-gated)").option("--class <class>", "deployable | content", "deployable").option("--project-type <type>", `${PROJECT_TYPES.join(" | ")} (capability shape)`).option("--deploy-model <model>", `${DEPLOY_MODELS.join(" | ")} (release/deploy path)`).option("--release-track <track>", `${RELEASE_TRACKS.join(" | ")} (branch topology; direct skips rc)`).option("--execute", "LIVE apply via gh (master-gated) \u2014 stamps seed files + labels into the repo").option("--var <KEY=VALUE...>", "placeholder values for repo-owned templates (repeatable)").option("--json", "machine-readable output").action(async (repo, cmdOpts) => {
+  bootstrap.command("apply <repo>").description("run from the MMI-Hub repo root: idempotent seed apply from skills/bootstrap/seeds/manifest.json; dry-run unless --execute (live, master-gated)").addOption(new Option("--class <class>", "deployable | content").default("deployable").choices(["deployable", "content"])).addOption(new Option("--project-type <type>", `${PROJECT_TYPES.join(" | ")} (capability shape)`).choices([...PROJECT_TYPES])).addOption(new Option("--deploy-model <model>", `${DEPLOY_MODELS.join(" | ")} (release/deploy path)`).choices([...DEPLOY_MODELS])).addOption(new Option("--release-track <track>", `${RELEASE_TRACKS.join(" | ")} (branch topology; direct skips rc)`).choices([...RELEASE_TRACKS])).option("--execute", "LIVE apply via gh (master-gated) \u2014 stamps seed files + labels into the repo").option("--var <KEY=VALUE...>", "placeholder values for repo-owned templates (repeatable)").option("--json", "machine-readable output").action(async (repo, cmdOpts) => {
     const o = {
       class: rawValue("--class", "deployable"),
       projectType: rawValue("--project-type", ""),
@@ -20531,6 +20660,9 @@ function registerBootstrapCommands(program3) {
       json: rawFlag("--json")
     };
     if (o.class !== "deployable" && o.class !== "content") return fail("bootstrap apply: --class must be deployable or content");
+    if (o.releaseTrack && !isReleaseTrack(o.releaseTrack)) {
+      return fail(`bootstrap apply: --release-track must be one of: ${RELEASE_TRACKS.join(", ")}`);
+    }
     const bootstrapReleaseTrack = resolveBootstrapReleaseTrack(o.class, o.releaseTrack || void 0);
     let parsedRepo;
     try {
@@ -20718,8 +20850,17 @@ function registerBootstrapCommands(program3) {
         const rulesetContent = resolveSeedContent({ ...rulesetSeed, target: rulesetSeed.target.replace("{{REPO_SLUG}}", slug) }, vars, readFile7);
         if (rulesetContent) {
           try {
-            const activation = await activateProductRuleset(repo, stripRulesetComment(rulesetContent), defaultGitHubClient());
-            applied.push(`product ruleset: ${activation.action}${activation.detail ? ` (${activation.detail})` : ""}`);
+            const client = defaultGitHubClient();
+            const proven = await gateIsProvenGreen(repo, client, baseBranch);
+            const activation = await activateProductRuleset(
+              repo,
+              stripRulesetComment(rulesetContent),
+              client,
+              proven ? "active" : "disabled"
+            );
+            applied.push(
+              `product ruleset: ${activation.action} (${activation.enforcement}${activation.detail ? `; ${activation.detail}` : ""})` + (proven ? "" : ` \u2014 the gate is not green on ${baseBranch}, so it is NOT enforcing. Activate once it is: mmi-cli ci reconcile --apply --repo ${repo}`)
+            );
           } catch (e) {
             return failGraceful(`bootstrap apply: product ruleset activation failed: ${e.message}`);
           }
@@ -24330,7 +24471,7 @@ function findCommandInManifest(manifest, commandPath3) {
   return visit(manifest.tree);
 }
 function registerExplainCommand(program3) {
-  program3.command("explain").description("print a command's purpose, flags, and examples from the live schema \u2014 one grounding call replaces trial-and-error").argument("[command...]", 'the command path to explain (e.g. "issue create")').option("--loop <name>", "print the canonical command sequence: agent | start-work | ship-pr | hotfix").action((commandArgs, opts) => {
+  program3.command("explain").description("print a command's purpose, flags, and examples from the live schema \u2014 one grounding call replaces trial-and-error").argument("[command...]", 'the command path to explain (e.g. "issue create")').addOption(new Option("--loop <name>", "print the canonical command sequence: agent | start-work | ship-pr | hotfix").choices(Object.keys(LOOP_PLAYBOOKS))).action((commandArgs, opts) => {
     if (opts.loop) {
       if (!LOOP_PLAYBOOKS[opts.loop]) {
         const valid = Object.keys(LOOP_PLAYBOOKS).join(", ");
@@ -25069,7 +25210,17 @@ function checkClaudePlugin(probe) {
       verbose: evidence
     };
   }
-  if (!released) return null;
+  if (!released) {
+    return {
+      id: "claude-plugin",
+      ok: false,
+      reportOnly: true,
+      label: "Claude plugin",
+      detail: `${installed ?? "installed"} \u2014 freshness UNKNOWN, the published version could not be read`,
+      fix: "check it directly: `npm view @mutmutco/cli version`, then `mmi-cli plugin heal` if behind",
+      verbose: evidence
+    };
+  }
   return { id: "claude-plugin", ok: true, label: "Claude plugin", ...installed ? { detail: installed } : {}, verbose: evidence };
 }
 function checkCliVersion(input, releasedNote) {
@@ -25078,7 +25229,17 @@ function checkCliVersion(input, releasedNote) {
     `running:  ${report.currentVersion}`,
     `published: ${report.releasedVersion ?? "(not checked \u2014 offline or --fast)"}${report.releasedVersion && releasedNote ? ` ${releasedNote}` : ""}`
   ];
-  if (!report.releasedVersion) return null;
+  if (!report.releasedVersion) {
+    return {
+      id: "cli-version",
+      ok: false,
+      reportOnly: true,
+      label: "mmi-cli",
+      detail: `${report.currentVersion} \u2014 freshness UNKNOWN, the published version could not be read`,
+      fix: "check it directly: `mmi-cli --version` against `npm view @mutmutco/cli version`; update with `npm install -g @mutmutco/cli@<released>`",
+      verbose: evidence
+    };
+  }
   if (report.ok) return { id: "cli-version", ok: true, label: "mmi-cli", detail: report.currentVersion, verbose: evidence };
   return {
     id: "cli-version",
@@ -25916,11 +26077,20 @@ var lastParseErrorKind = "other";
 var lastUnknownCommand;
 function classifyParseError(plain) {
   if (/unknown command/i.test(plain)) return "unknown-command";
-  if (/unknown option|missing required argument|too many arguments|argument missing/i.test(plain)) {
+  if (/unknown option|missing required argument|too many arguments|argument missing|is invalid\. Allowed choices are/i.test(plain)) {
     return "bad-arguments";
   }
   return "other";
 }
+function parseInvalidChoiceError(plain) {
+  const m = /option '([^']+)' argument '([^']*)' is invalid\. Allowed choices are ([^.]+)\./.exec(plain);
+  if (!m) return void 0;
+  return {
+    flag: m[1].split(/[ ,|]/)[0],
+    value: m[2],
+    expected: m[3].split(",").map((s) => s.trim()).filter(Boolean)
+  };
+}
 function resolveCommandFromArgv(root, argv) {
   let current = root;
   for (const token of argv) {
@@ -25982,6 +26152,22 @@ function envelopeAwareWriteErr(str) {
   }
   lastParseErrorKind = classifyParseError(plain);
   lastUnknownCommand = /unknown command '?([\w:-]+)'?/.exec(plain)?.[1];
+  const badChoice = parseInvalidChoiceError(plain);
+  if (badChoice) {
+    if (!argvWantsJson2()) {
+      process.stderr.write(str);
+      return;
+    }
+    process.stderr.write(
+      formatErrorEnvelope(`${badChoice.flag}: unknown value "${badChoice.value}"`, {
+        code: ERROR_CODES.ERR_BAD_ENUM,
+        offending_flag: badChoice.flag,
+        expected: badChoice.expected
+      }) + "\n"
+    );
+    unknownFlagJsonHandled = true;
+    return;
+  }
   const match = /unknown option '([^']+)'/.exec(plain);
   if (match) {
     const flag = match[1];
@@ -26568,7 +26754,7 @@ tests.command("policy").description("enforce this repo's test-policy.json agains
   }
 });
 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) => {
+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)").addOption(new Option("--outcome <kind>", "clean | refreshed | failed").makeOptionMandatory().choices(["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 {
     const repo = o.repo ?? await currentRepoFullName();
     const date = o.date ?? (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
@@ -26751,7 +26937,7 @@ deploys run centrally (tenant-deploy.yml); product repos carry no deploy files.
   }
 });
 var projectDeploy = project.command("deploy").description("read nonsecret DEPLOY# facts (domain, port, deploy path, substrate, host presence)");
-projectDeploy.command("get [owner/repo]").description("read nonsecret DEPLOY# facts for one project; defaults to the current repo").option("--stage <stage>", "dev | rc | main").option("--json", "machine-readable output").action(async (repoOrSlug, o) => {
+projectDeploy.command("get [owner/repo]").description("read nonsecret DEPLOY# facts for one project; defaults to the current repo").addOption(new Option("--stage <stage>", "dev | rc | main").choices(["dev", "rc", "main"])).option("--json", "machine-readable output").action(async (repoOrSlug, o) => {
   const cfg = await loadConfig();
   let target;
   try {
@@ -26766,7 +26952,7 @@ projectDeploy.command("get [owner/repo]").description("read nonsecret DEPLOY# fa
   const payload = stage ? { slug: out.slug, stage, deploy: out.stages[stage] ?? null } : out;
   console.log(JSON.stringify(payload));
 });
-project.command("set [owner/repo]").description("upsert project META (idempotent merge; master-gated)").option("--class <class>", "deployable | content").option("--project-type <type>", `${PROJECT_TYPES.join(" | ")} (capability shape)`).option("--deploy-model <model>", `${DEPLOY_MODELS.join(" | ")} (release/deploy path; none means no Hub deploy registration)`).option("--release-track <track>", `${RELEASE_TRACKS.join(" | ")} (branch topology; direct skips rc)`).option("--var <KEY=VALUE...>", settableVarHelp()).option("--set <KEY=VALUE...>", "alias of --var (one KEY=VALUE per flag; repeat the flag to set several)").option("--secrets-file <path>", 'read the #2244 secrets catalog map (JSON) from a file and merge it per entry into the existing catalog (clear all with --unset secrets). SHAPE: a JSON object keyed by env name, each entry {"key":"UPPER_SNAKE" (repeat the env name), "purpose":"<non-empty>", "group":"<e.g. auth|database>", "owner":"<github login>", "stages":[] (empty = the one stageless shared value; else any of dev/rc/main), "consumers":["runtime"|"box"|\u2026], "provider":"<optional>"}').option("--unset <KEY...>", "META field to remove (repeatable): oauth, requiredRuntimeSecrets, requiredBuildSecrets, secrets, edgeDomains, requiredGcpApis, publishRequired").option("--clear-web-profile", "remove web-only registry fields (oauth, edgeDomains) for non-web/content projects").option("--json", "machine-readable output").action(async (repoOrSlug, o) => {
+project.command("set [owner/repo]").description("upsert project META (idempotent merge; master-gated)").addOption(new Option("--class <class>", "deployable | content").choices(["deployable", "content"])).addOption(new Option("--project-type <type>", `${PROJECT_TYPES.join(" | ")} (capability shape)`).choices([...PROJECT_TYPES])).addOption(new Option("--deploy-model <model>", `${DEPLOY_MODELS.join(" | ")} (release/deploy path; none means no Hub deploy registration)`).choices([...DEPLOY_MODELS])).addOption(new Option("--release-track <track>", `${RELEASE_TRACKS.join(" | ")} (branch topology; direct skips rc)`).choices([...RELEASE_TRACKS])).option("--var <KEY=VALUE...>", settableVarHelp()).option("--set <KEY=VALUE...>", "alias of --var (one KEY=VALUE per flag; repeat the flag to set several)").option("--secrets-file <path>", 'read the #2244 secrets catalog map (JSON) from a file and merge it per entry into the existing catalog (clear all with --unset secrets). SHAPE: a JSON object keyed by env name, each entry {"key":"UPPER_SNAKE" (repeat the env name), "purpose":"<non-empty>", "group":"<e.g. auth|database>", "owner":"<github login>", "stages":[] (empty = the one stageless shared value; else any of dev/rc/main), "consumers":["runtime"|"box"|\u2026], "provider":"<optional>"}').option("--unset <KEY...>", "META field to remove (repeatable): oauth, requiredRuntimeSecrets, requiredBuildSecrets, secrets, edgeDomains, requiredGcpApis, publishRequired").option("--clear-web-profile", "remove web-only registry fields (oauth, edgeDomains) for non-web/content projects").option("--json", "machine-readable output").action(async (repoOrSlug, o) => {
   const cfg = await loadConfig();
   let target;
   try {
@@ -26880,7 +27066,7 @@ fullTrack.command("readiness <owner/repo>").description("aggregate branch topolo
   console.log(JSON.stringify(report, null, 2));
   if (!report.rcand.canApply) process.exitCode = 1;
 });
-project.command("set-deploy [owner/repo]").description("patch a tenant DEPLOY row \u2014 project-admin may set only --no-env-file on their own existing dev/rc row; master may seed/change all coords and main; defaults to the current repo").requiredOption("--stage <stage>", "dev | rc | main").option("--ssh-host <host>", "the box address the deploy ssh-es into; omit to keep the stored value (required only for a NEW hetzner-ssh row \u2014 `mmi-cli runtime box list` finds it)").option("--ssh-user <user>", "ssh user; omit to leave the row unchanged (default root on a new row)").option("--port <port>", "loopback port the container binds / Caddy upstream (1..65535); omit to leave the row unchanged").option("--substrate <substrate>", "hetzner-ssh; omit to leave the row unchanged").option("--deploy-path <path>", "on-box per-stage release root; omit to leave the row unchanged (default /opt/mmi/<slug>/<stage> on a new row)").option("--service <name>", "systemd/compose service name; omit to leave the row unchanged (default the slug on a new row)").option("--domain <domain>", "canonical serving host; omit to leave the row unchanged").option("--alias <domain...>", "extra serving hostname the box Caddy answers (repeatable); omit to leave the stored aliases unchanged").option("--clear-aliases", "remove EVERY serving alias from the row (#2986) \u2014 omitting --alias preserves them, so clearing needs saying out loud").option("--no-env-file <bool>", "set the DEPLOY# fileless flag (true|false) \u2014 own-repo project-admin dev/rc; master main; true = env passthrough with no .env symlink").option("--force", "explicit recovery override: skip fileless-compose verification only after independent proof").option("--json", "machine-readable output").action(async (repoOrSlug, o) => {
+project.command("set-deploy [owner/repo]").description("patch a tenant DEPLOY row \u2014 project-admin may set only --no-env-file on their own existing dev/rc row; master may seed/change all coords and main; defaults to the current repo").addOption(new Option("--stage <stage>", "dev | rc | main").makeOptionMandatory().choices(["dev", "rc", "main"])).option("--ssh-host <host>", "the box address the deploy ssh-es into; omit to keep the stored value (required only for a NEW hetzner-ssh row \u2014 `mmi-cli runtime box list` finds it)").option("--ssh-user <user>", "ssh user; omit to leave the row unchanged (default root on a new row)").option("--port <port>", "loopback port the container binds / Caddy upstream (1..65535); omit to leave the row unchanged").option("--substrate <substrate>", "hetzner-ssh; omit to leave the row unchanged").option("--deploy-path <path>", "on-box per-stage release root; omit to leave the row unchanged (default /opt/mmi/<slug>/<stage> on a new row)").option("--service <name>", "systemd/compose service name; omit to leave the row unchanged (default the slug on a new row)").option("--domain <domain>", "canonical serving host; omit to leave the row unchanged").option("--alias <domain...>", "extra serving hostname the box Caddy answers (repeatable); omit to leave the stored aliases unchanged").option("--clear-aliases", "remove EVERY serving alias from the row (#2986) \u2014 omitting --alias preserves them, so clearing needs saying out loud").option("--no-env-file <bool>", "set the DEPLOY# fileless flag (true|false) \u2014 own-repo project-admin dev/rc; master main; true = env passthrough with no .env symlink").option("--force", "explicit recovery override: skip fileless-compose verification only after independent proof").option("--json", "machine-readable output").action(async (repoOrSlug, o) => {
   const cfg = await loadConfig();
   let target;
   try {
@@ -27077,7 +27263,7 @@ function resolveCreateType(raw, command, labels) {
 }
 var issue = program2.command("issue").description("issues \u2014 reliable create with structured output");
 withExamples(mutating(
-  issue.command("create").description("create an issue (type \u2192 label) and print {number,url,label} JSON").option("--type <type>", "bug | feature | task (sets the matching label; required unless --batch)").option("--title <title>", "issue title").option("--title-file <path|->", "read the issue title from a UTF-8 file, or from stdin with -").option("--body <body>", "issue body (markdown)").option("--body-file <path|->", "read issue body from a UTF-8 file. `-` (stdin) needs a heredoc, which the agent inline-body guard denies (#1473/#2125) \u2014 prefer a real path; a title with backticks or newlines needs --title-file for the same reason (#3381)").option("--priority <priority>", "urgent | high | medium | low (defaults to medium; sets the board Priority field only \u2014 never a priority:* label, #416)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--label <label...>", "extra label(s) to attach (repeatable; auto-created if missing)").option("--parent <ref>", "file as a native sub-issue of this parent (#123, owner/repo#123, or URL)").option("--no-related", "skip the auto related-issues comment"),
+  issue.command("create").description("create an issue (type \u2192 label) and print {number,url,label} JSON").addOption(new Option("--type <type>", "bug | feature | task (sets the matching label; required unless --batch)").choices([...ISSUE_TYPES])).option("--title <title>", "issue title").option("--title-file <path|->", "read the issue title from a UTF-8 file, or from stdin with -").option("--body <body>", "issue body (markdown)").option("--body-file <path|->", "read issue body from a UTF-8 file. `-` (stdin) needs a heredoc, which the agent inline-body guard denies (#1473/#2125) \u2014 prefer a real path; a title with backticks or newlines needs --title-file for the same reason (#3381)").option("--priority <priority>", "urgent | high | medium | low (defaults to medium; sets the board Priority field only \u2014 never a priority:* label, #416)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--label <label...>", "extra label(s) to attach (repeatable; auto-created if missing)").option("--parent <ref>", "file as a native sub-issue of this parent (#123, owner/repo#123, or URL)").option("--no-related", "skip the auto related-issues comment"),
   // --dry-run/--validate-only plan: validate --type + --priority (mirrors the action — a bad enum fails
   // ERR_BAD_ENUM, a missing priority defaults to medium) then echo the resolved create intent. Refs
   // (`--parent`) and title-source are validated by the action on a real run.
@@ -27294,7 +27480,7 @@ ${list}`);
   }
   console.log(JSON.stringify({ number: parsed.number, repo, item: result.item.text, checked, changed: true }));
 });
-program2.command("report").description("file a friction report on the Hub board (Hub session auth, dedups open reports) and print {number,url} JSON").option("--title <title>", "one-line friction summary").option("--title-file <path|->", "read the friction summary from a UTF-8 file, or from stdin with -").option("--body <body>", "report body (markdown)").option("--body-file <path|->", "read report body from a UTF-8 file, or from stdin with -").option("--type <type>", "bug | feature | task (sets the matching label)", "task").option("--priority <priority>", "urgent | high | medium | low (defaults to medium; sets the board Priority field only, #416)").option("--repo <owner/repo>", 'attribute the report to a different source repo than the current checkout for the "Filed via..." footer (rare \u2014 usually auto-detected; every report always lands on the org Hub, never an alternate target, #263)').option("--force", "file a new issue even when an open report looks like a duplicate").option("--json", "machine-readable output (already the default \u2014 report always prints JSON; #682)").action(async (o) => {
+program2.command("report").description("file a friction report on the Hub board (Hub session auth, dedups open reports) and print {number,url} JSON").option("--title <title>", "one-line friction summary").option("--title-file <path|->", "read the friction summary from a UTF-8 file, or from stdin with -").option("--body <body>", "report body (markdown)").option("--body-file <path|->", "read report body from a UTF-8 file, or from stdin with -").addOption(new Option("--type <type>", "bug | feature | task (sets the matching label)").default("task").choices([...ISSUE_TYPES])).option("--priority <priority>", "urgent | high | medium | low (defaults to medium; sets the board Priority field only, #416)").option("--repo <owner/repo>", 'attribute the report to a different source repo than the current checkout for the "Filed via..." footer (rare \u2014 usually auto-detected; every report always lands on the org Hub, never an alternate target, #263)').option("--force", "file a new issue even when an open report looks like a duplicate").option("--json", "machine-readable output (already the default \u2014 report always prints JSON; #682)").action(async (o) => {
   let body;
   let priority;
   let title;
@@ -27338,7 +27524,7 @@ async function resolvePluginSha() {
     return void 0;
   }
 }
-program2.command("skill-lesson").description("file a skill-lesson on the Hub board (GitHub auth, dedups open lessons) and print {number,url} JSON").requiredOption("--skill <name>", `which skill misfired (${SKILL_NAMES.join(" | ")})`).option("--title <title>", "one-line summary of what misfired").option("--title-file <path|->", "read the one-line summary from a UTF-8 file, or from stdin with -").option("--body <body>", "lesson body: what misfired, the evidence, and the proposed amendment (markdown)").option("--body-file <path|->", "read the lesson body from a UTF-8 file, or from stdin with -").option("--priority <priority>", "urgent | high | medium | low (defaults to medium; sets the board Priority field only, #416)").option("--repo <owner/repo>", `target repo (defaults to the org Hub: ${HUB_REPO2})`).option("--force", "file a new issue even when an open lesson looks like a duplicate").option("--json", "machine-readable output (already the default \u2014 skill-lesson always prints JSON)").action(async (o) => {
+program2.command("skill-lesson").description("file a skill-lesson on the Hub board (GitHub auth, dedups open lessons) and print {number,url} JSON").addOption(new Option("--skill <name>", `which skill misfired (${SKILL_NAMES.join(" | ")})`).makeOptionMandatory().choices([...SKILL_NAMES])).option("--title <title>", "one-line summary of what misfired").option("--title-file <path|->", "read the one-line summary from a UTF-8 file, or from stdin with -").option("--body <body>", "lesson body: what misfired, the evidence, and the proposed amendment (markdown)").option("--body-file <path|->", "read the lesson body from a UTF-8 file, or from stdin with -").option("--priority <priority>", "urgent | high | medium | low (defaults to medium; sets the board Priority field only, #416)").option("--repo <owner/repo>", `target repo (defaults to the org Hub: ${HUB_REPO2})`).option("--force", "file a new issue even when an open lesson looks like a duplicate").option("--json", "machine-readable output (already the default \u2014 skill-lesson always prints JSON)").action(async (o) => {
   const targetRepo2 = o.repo ?? HUB_REPO2;
   const sourceRepo = await resolveRepo(void 0);
   const pluginSha = await resolvePluginSha();
@@ -27940,17 +28126,33 @@ async function resolveRcandPlanTargets() {
   }
 }
 for (const commandName of ["rcand", "release"]) {
-  program2.command(commandName).description(`plan ${commandName} train operations; mutations require explicit master-admin approval`).option("--json", "machine-readable output").option("--watch", "block on the deploy/publish workflow runs and report their outcomes").option("--apply", "execute the guarded master-only train after explicit approval").option("--announce-summary-file <path>", "release only: agent-curated summary lines for the Hub Slack announcement (#883)").option("--ack <shas>", "release only: comma-separated dev shas a human verified are in the candidate, overriding the hotfix-coverage guard for a conflicted port whose -x trailer was lost (#958)").option("--dev", "release only: full-track repos release development -> main directly, skipping rc (refuses if rc carries content not in development; no-op on direct-track repos) (#1062)").option("--repo <owner/repo>", "dry-run plan for a target repo without relying on the current checkout; --apply still uses the current checkout").action(async (o) => {
+  const trainCmd = program2.command(commandName).description(`plan ${commandName} train operations; mutations require explicit master-admin approval`).option("--json", "machine-readable output").option("--watch", "block on the deploy/publish workflow runs and report their outcomes").option("--apply", "execute the guarded master-only train after explicit approval");
+  const RELEASE_ONLY_FLAGS = [
+    { flags: "--announce-summary-file <path>", description: "agent-curated summary lines for the Hub Slack announcement (#883)" },
+    { flags: "--ack <shas>", description: "comma-separated dev shas a human verified are in the candidate, overriding the hotfix-coverage guard for a conflicted port whose -x trailer was lost (#958)" },
+    { flags: "--dev", description: "full-track repos release development -> main directly, skipping rc (refuses if rc carries content not in development; no-op on direct-track repos) (#1062)" }
+  ];
+  for (const f of RELEASE_ONLY_FLAGS) {
+    if (commandName === "release") {
+      trainCmd.option(f.flags, f.description);
+    } else {
+      trainCmd.addOption(new Option(f.flags, f.description).hideHelp());
+    }
+  }
+  trainCmd.option("--repo <owner/repo>", "dry-run plan for a target repo without relying on the current checkout; --apply still uses the current checkout").action(async (o) => {
     try {
       await requireFreshTrainCli(commandName);
     } catch (e) {
       return fail(`${commandName}: ${e.message}`);
     }
     if (o.ack && commandName !== "release") {
-      return fail("--ack applies only to release: it overrides the rc -> main hotfix-coverage guard, which rcand does not run");
+      return fail(`${commandName}: --ack applies only to release \u2014 it overrides the rc -> main hotfix-coverage guard, which rcand does not run. Run: mmi-cli release --ack <shas>`);
     }
     if (o.dev && commandName !== "release") {
-      return fail("--dev applies only to release: it ships development -> main skipping rc, which rcand cannot do");
+      return fail(`${commandName}: --dev applies only to release \u2014 it ships development -> main skipping rc, which rcand cannot do. Run: mmi-cli release --dev`);
+    }
+    if (o.announceSummaryFile && commandName !== "release") {
+      return fail(`${commandName}: --announce-summary-file applies only to release \u2014 rcand posts no Hub Slack announcement. Run: mmi-cli release --announce-summary-file <path>`);
     }
     if (o.apply && o.repo) {
       const rerun = `mmi-cli ${commandName} --apply${o.watch ? " --watch" : ""}${o.dev ? " --dev" : ""}${o.json ? " --json" : ""}`;
@@ -28039,21 +28241,24 @@ ci.command("audit").description("read-only fleet scan: gate workflow, ruleset co
   else console.log(renderCiAuditText(report));
   if (!report.ok) process.exitCode = 1;
 });
-ci.command("reconcile").description("audit + optionally apply merge settings and product ruleset activation (master-admin)").option("--json", "machine-readable output").option("--repo <owner/repo>", "reconcile one repo instead of the full registry").option("--apply", "PATCH merge settings + activate product ruleset when missing (master role required)").action(async (o) => {
-  if (o.apply) {
+ci.command("reconcile").description("audit + optionally apply merge settings and product ruleset activation (master-admin)").option("--json", "machine-readable output").option("--repo <owner/repo>", "reconcile one repo instead of the full registry").option("--apply", "PATCH merge settings + activate product ruleset when missing (master role required); activation is skipped while the repo's gate has never passed (#3694)").option("--park-ruleset", "stop the product ruleset enforcing without deleting it \u2014 keeps its required contexts (master role required)").action(async (o) => {
+  if (o.apply && o.parkRuleset) {
+    return fail("ci reconcile: --apply and --park-ruleset ask for opposite things; pass one");
+  }
+  if (o.apply || o.parkRuleset) {
     const verdict = await fetchTrainAuthority(HUB_REPO2, registryClientDeps(await loadConfig()));
     if (!verdict.ok || verdict.authority.role !== "master") {
-      return fail("ci reconcile --apply: master-admin required");
+      return fail(`ci reconcile ${o.apply ? "--apply" : "--park-ruleset"}: master-admin required`);
     }
   }
   const deps = ciAuditDeps();
   const audit = await auditOrgCi(deps, o.repo);
-  const applyResults = o.apply ? await Promise.all(audit.repos.map((r) => applyCiReconcileRepo(r.repo, deps))) : [];
+  const applyResults = o.apply ? await Promise.all(audit.repos.map((r) => applyCiReconcileRepo(r.repo, deps))) : o.parkRuleset ? await Promise.all(audit.repos.map((r) => parkProductRuleset(r.repo, deps))) : [];
   const payload = { audit, apply: applyResults };
   if (o.json) console.log(JSON.stringify(payload, null, 2));
   else {
     console.log(renderCiAuditText(audit));
-    if (o.apply) {
+    if (applyResults.length) {
       for (const r of applyResults) {
         console.log(`
 ${r.repo}: applied=[${r.applied.join("; ")}] skipped=[${r.skipped.join("; ")}]${r.errors.length ? ` errors=[${r.errors.join("; ")}]` : ""}`);
@@ -28304,6 +28509,7 @@ program2.parseAsync(process.argv).then(() => finishCliRun()).catch((e) => failGr
   envHealLockPath,
   gcPlan,
   isOrgRegisteredRepo,
+  parseInvalidChoiceError,
   positionalTargetForm,
   registryClientDeps,
   repoSlug,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "3.71.0",
+  "version": "3.72.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",