@mutmutco/codex-plugin 4.5.169 → 4.5.171

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mmi",
-  "version": "4.5.169",
+  "version": "4.5.171",
   "mmiCompat": "4.x",
   "description": "MMI workflow skills and org gates delivery.",
   "author": {

package/cli/dist/main.cjs

@@ -10145,6 +10145,19 @@ function retriedFetch(deps, url, init) {
     sleep: deps.retrySleep
   });
 }
+async function backfillDeployHistory(since, apply, deps) {
+  if (!deps.baseUrl) throw new Error("Hub API URL not configured");
+  const token = await deps.token();
+  if (!token) throw new Error("no Hub session token (run `gh auth login`)");
+  const res = await retriedFetch({ ...deps, timeoutMs: TENANT_DEPLOY_TIMEOUT_MS }, `${deps.baseUrl.replace(/\/$/, "")}/deploy-history/backfill`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ since, dryRun: !apply })
+  });
+  const body = await res.json();
+  if (!res.ok) throw new Error(`deploy history backfill HTTP ${res.status}: ${body.error ?? res.statusText}`);
+  return body;
+}
 async function fetchTrainAuthority(repo, deps) {
   if (!deps.baseUrl) return { ok: false, error: "Hub API URL not configured" };
   const token = await deps.token();
@@ -19074,10 +19087,10 @@ var rollout_plan_default = {
     note: "The v4.0.0 stamp happens at cut time (D6e #4463); until then the candidate is the origin/development head artifacts (built cli/dist + npm pack), identity proven by dist content hash (D6a)."
   },
   baseline: {
-    version: "4.5.169",
-    tag: "v4.5.169",
-    commit: "4732697958bc",
-    npm: "@mutmutco/cli@4.5.169"
+    version: "4.5.171",
+    tag: "v4.5.171",
+    commit: "79faa07090b1",
+    npm: "@mutmutco/cli@4.5.171"
   },
   exitCriterion: "fleet-n-of-n",
   hubOnlyShortcut: "forbidden",
@@ -19094,14 +19107,14 @@ var rollout_plan_default = {
           repo: "mutmutco/mmi-hub",
           role: "canary",
           schedule: "train",
-          v3Target: "v4.5.169"
+          v3Target: "v4.5.171"
         }
       ],
       rollbackTrigger: "Any red inside the post-contract soak window: `devops train gate` FAIL attributable to the v4 doors, Hub endpoint health probe failure, a pre-v4 client admitted instead of receiving actionable HTTP 426, or npm consumer install/doctor failure on the v4-only dist.",
       rollback: {
         independent: true,
-        mechanism: "npm dist-tag latest -> 4.5.169 and redeploy the Hub Lambda from tag v4.5.169 (4732697958bc); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
-        v3Target: "v4.5.169 (@mutmutco/cli@4.5.169, tag commit 4732697958bc \u2014 last known-good release carrying the repo-index v4-only contract)"
+        mechanism: "npm dist-tag latest -> 4.5.171 and redeploy the Hub Lambda from tag v4.5.171 (79faa07090b1); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.5.171 (@mutmutco/cli@4.5.171, tag commit 79faa07090b1 \u2014 last known-good release carrying the repo-index v4-only contract)"
       }
     },
     {
@@ -19291,7 +19304,7 @@ function formatTrainStatus(r) {
     "",
     `release track: ${r.releaseTrack} \u2014 stages: ${r.branches.join(" -> ")}`,
     `cli version: ${r.cliVersion}${r.repoVersion ? ` (repo: ${r.repoVersion})` : ""}${r.releasedVersion ? ` (released: ${r.releasedVersion})` : ""}`,
-    `release bump intent: ${r.bumpIntent ?? "not declared \u2014 an ordinary train defaults to patch (#4929); set MMI_BUMP_INTENT=major|minor to override"}`
+    `release bump intent: ${r.bumpIntent ?? "not declared \u2014 an ordinary train defaults to patch (#4929)"} (proposed: patch; minor needs MMI_BUMP_REASON, major also MMI_MAJOR_APPROVED=<version> \u2014 docs/versioning.md)`
   ];
   if (r.versionLag.ok) {
     lines2.push("version lag: none \u2014 CLI is current");
@@ -26549,6 +26562,53 @@ async function selfConvergeTrainCli(input) {
   }
 }
 
+// src/bump-proposal.ts
+var BREAKING_BANG = /^[a-z]+(\([^)]*\))?!:/i;
+var BREAKING_TRAILER = /^BREAKING[ -]CHANGE:/m;
+var MAX_BUMP_REASON = 200;
+function proposeBump(commits, _opts = {}) {
+  const breaking = [];
+  for (const c of commits) {
+    if (BREAKING_BANG.test(c.subject) || BREAKING_TRAILER.test(c.body)) breaking.push(`${c.sha.slice(0, 8)} ${c.subject}`);
+  }
+  return { proposed: "patch", breaking };
+}
+function parseRangeLog(raw) {
+  return raw.split("").map((r) => r.replace(/^\n+/, "")).filter((r) => r.trim()).map((r) => {
+    const [sha = "", subject = "", body = ""] = r.split("");
+    return { sha: sha.trim(), subject: subject.trim(), body };
+  });
+}
+var RANGE_LOG_FORMAT = "--format=%H%x1f%s%x1f%b%x1e";
+function enforceBumpRules(input) {
+  const { env, proposal } = input;
+  const effective = input.preOneZero && input.intent === "major" ? "minor" : input.intent;
+  const reason = (env.MMI_BUMP_REASON ?? "").trim();
+  const evidence = proposal.breaking.join("; ");
+  const decision = () => ({ intent: effective, reason: reason || null, proposed: proposal.proposed, breaking: proposal.breaking });
+  if (effective !== "patch") {
+    if (!reason) throw new Error(`MMI_BUMP_INTENT=${input.intent} needs MMI_BUMP_REASON \u2014 a one-line reason (\u2264${MAX_BUMP_REASON} chars) for a real feature or significant change; patch is the default (#8499)`);
+    if (/[\r\n]/.test(reason) || reason.length > MAX_BUMP_REASON) throw new Error(`MMI_BUMP_REASON must be one line of at most ${MAX_BUMP_REASON} chars (#8499)`);
+  }
+  if (effective === "major") {
+    const approved = (env.MMI_MAJOR_APPROVED ?? "").trim().replace(/^v/, "");
+    const target = (input.majorTarget ?? "").replace(/^v/, "");
+    if (!approved) throw new Error(`a major release is owner-gated: set MMI_MAJOR_APPROVED=${target || "<target version>"} only after Jervaise's fresh approval in this turn (#8499)`);
+    if (approved !== target) throw new Error(`MMI_MAJOR_APPROVED=${approved} does not match the major target ${target}; a stale approval cannot tag a different major (#8499)`);
+    return decision();
+  }
+  if (proposal.breaking.length && effective === "patch") {
+    throw new Error(input.preOneZero ? `range carries breaking changes (${evidence}): this repo is held on 0.x.y, so declare MMI_BUMP_INTENT=minor with MMI_BUMP_REASON, or ship a shim (patch) (#8499)` : `range carries breaking changes (${evidence}): ship a shim (patch) or declare an owner-gated major (MMI_BUMP_INTENT=major, MMI_BUMP_REASON, MMI_MAJOR_APPROVED=<version>) (#8499)`);
+  }
+  if (proposal.breaking.length && !input.preOneZero) {
+    throw new Error(`range carries breaking changes (${evidence}): ship a shim (patch) or declare an owner-gated major (#8499)`);
+  }
+  return decision();
+}
+function bumpNotesLine(d) {
+  return `Version bump: ${d.intent} \u2014 ${d.reason ?? "default patch"}`;
+}
+
 // src/train-doctor.ts
 var TRAIN_LANES = ["release", "rcand", "hotfix"];
 var TROUBLESHOOTING_GUIDE = "docs/Guides/train-troubleshooting.md";
@@ -26844,6 +26904,17 @@ async function runTrainDoctor(input) {
   if (workflows === null && !startBranchMissing) {
     add({ code: "workflows-unreadable", severity: "blocker", source: "local", title: `.github/workflows at ${workflowsRef} could not be read from ${cwd} \u2014 the tag-addressability (#5428) and npm-major (#5666) preflights did not run`, remedy: `run from a checkout whose git can read ${workflowsRef} (fetch origin first), then rerun; an unread workflow set is unverified, not green` });
   }
+  if (lane === "release" && !startBranchMissing && startBranch) {
+    try {
+      const proposal = proposeBump(parseRangeLog(await git3(["log", `origin/main..origin/${startBranch}`, RANGE_LOG_FORMAT])));
+      add({ code: "bump-proposal", severity: "info", source: "origin", title: `bump proposal: ${proposal.proposed}`, remedy: "nothing \u2014 patch is the default; minor needs MMI_BUMP_REASON, major also MMI_MAJOR_APPROVED=<version> (docs/versioning.md)" });
+      for (const evidence of proposal.breaking) {
+        add({ code: "bump-breaking", severity: "warning", source: "origin", title: `breaking signal in the release range: ${evidence}`, remedy: "ship a shim (patch) or declare an owner-gated major; the train refuses otherwise" });
+      }
+    } catch (e) {
+      void e;
+    }
+  }
   if (lane === "release" && !startBranchMissing) {
     const required = meta?.requiredChecks?.length ? meta.requiredChecks : ["gate"];
     const emitters = (workflows ?? []).filter((f) => parseWorkflowJobIds(f.body).some((id) => required.some((context) => contextMatchesJobId(id, context))));
@@ -29610,6 +29681,17 @@ async function resolveTrainBumpIntent(deps, env = process.env, latestRelease, pr
   }
   return "patch";
 }
+async function enforceTrainBump(deps, env, intent, preOneZero, source) {
+  const raw = await deps.run("git", ["log", `origin/main..${source}`, RANGE_LOG_FORMAT]);
+  const proposal = proposeBump(parseRangeLog(raw), { preOneZero });
+  let majorTarget;
+  if (intent === "major") {
+    const explicit = (env.MMI_RELEASE_VERSION ?? "").trim().replace(/^v/, "");
+    const latest = await latestLocalReleaseTag(deps, void 0, preOneZero);
+    majorTarget = explicit || `${latest.major + 1}.0.0`;
+  }
+  return enforceBumpRules({ intent, env, proposal, preOneZero, majorTarget });
+}
 async function resolveHotfixVersion(deps, env = process.env, preOneZero = false) {
   const latest = await latestLocalReleaseTag(deps, "origin/main", preOneZero);
   if (latest.major === 0 && latest.minor === 0 && latest.patch === 0) {
@@ -29655,9 +29737,19 @@ async function runTrainApplyLocked(command, deps, options = {}) {
   await requireCleanTree(deps);
   await runGitRemoteRead(deps, ["fetch", "origin"]);
   const meta = requireProjectMetaForTrain(await loadProjectMeta(deps, ctx), ctx.repo);
-  const bumpIntent = await resolveTrainBumpIntent(deps, process.env, void 0, preOneZeroInForce(meta));
+  const declaredIntent = await resolveTrainBumpIntent(deps, process.env, void 0, preOneZeroInForce(meta));
   const branchHints = await loadReleaseTrackBranchHints(deps);
   const directTrack = isHubControlRepo(ctx.repo) || resolveReleaseTrack(meta, branchHints) === "direct";
+  const bump = await enforceTrainBump(
+    deps,
+    process.env,
+    declaredIntent,
+    preOneZeroInForce(meta),
+    command === "release" && !directTrack && options.dev !== true ? "origin/rc" : "origin/development"
+  );
+  const bumpIntent = bump.intent;
+  const bumpReceipt = { intent: bump.intent, reason: bump.reason, proposed: bump.proposed, breaking: bump.breaking };
+  options = { ...options, bumpLine: bumpNotesLine(bump) };
   assertSuiteAutoVersion(ctx.repo, meta, process.env, command === "release" && !directTrack);
   if (command === "release" && meta.suite === "mm-work") await requireSuiteReleaseSummary(deps, options.announceSummaryFile, options.announceSummaryFileTr);
   const pipelineInput = { deps, ctx, command, meta, branchHints, watch, options, bumpIntent };
@@ -29665,28 +29757,31 @@ async function runTrainApplyLocked(command, deps, options = {}) {
     if (directTrack) {
       throw new Error("direct-track repos release straight to main (no rc); run `mmi-cli devops release --apply` from development instead of rcand");
     }
-    return withCheckoutRestoredAfterRelease(deps, await runTrainApplyPipeline("rcand", pipelineInput), "development");
+    return withCheckoutRestoredAfterRelease(deps, await runPipelineWithBump(bumpReceipt, "rcand", pipelineInput), "development");
   }
   if (directTrack) {
     return withCheckoutRestoredAfterRelease(
       deps,
-      await runTrainApplyPipeline("release-dev", { ...pipelineInput, directTrack: true }),
+      await runPipelineWithBump(bumpReceipt, "release-dev", { ...pipelineInput, directTrack: true }),
       "development"
     );
   }
   if (command === "release" && options.dev) {
     return withCheckoutRestoredAfterRelease(
       deps,
-      await runTrainApplyPipeline("release-dev", pipelineInput),
+      await runPipelineWithBump(bumpReceipt, "release-dev", pipelineInput),
       "development"
     );
   }
   return withCheckoutRestoredAfterRelease(
     deps,
-    await runTrainApplyPipeline("release-full", pipelineInput),
+    await runPipelineWithBump(bumpReceipt, "release-full", pipelineInput),
     "rc"
   );
 }
+async function runPipelineWithBump(bump, mode, input) {
+  return { ...await runTrainApplyPipeline(mode, input), bump };
+}
 
 // src/ci-audit.ts
 var HUB_REPO4 = "mutmutco/MMI-Hub";
@@ -31076,6 +31171,7 @@ function consolidateCommandNamespaces(program3) {
   const runtimeDeploy = runtime.command("deploy").description("runtime deployment status");
   const deploy = child(program3, "deploy");
   move(deploy, runtimeDeploy, "status");
+  move(deploy, runtimeDeploy, "history-backfill");
   remove(program3, "deploy");
   move(program3, runtime, "box");
   move(program3, runtime, "edge");
@@ -32476,7 +32572,7 @@ function parseTrainTag(tag) {
 function cmpTrainRelease(a, b) {
   return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
 }
-function trainPlanTargetsFromTags(tags, explicitRaw) {
+function trainPlanTargetsFromTags(tags, explicitRaw, intent = process.env.MMI_BUMP_INTENT) {
   const all = tags.map(parseTrainTag).filter((v) => Boolean(v));
   const release = all.find((v) => v.rc === null) ?? { major: 0, minor: 0, patch: 0, rc: null };
   const targets = {};
@@ -32493,7 +32589,8 @@ function trainPlanTargetsFromTags(tags, explicitRaw) {
     }
   }
   if (!targets.plannedReleaseError) {
-    const planned = explicit ?? { major: release.major, minor: release.minor + 1, patch: 0, rc: null };
+    const bumped = intent === "major" ? { major: release.major + 1, minor: 0, patch: 0 } : intent === "minor" ? { major: release.major, minor: release.minor + 1, patch: 0 } : { major: release.major, minor: release.minor, patch: release.patch + 1 };
+    const planned = explicit ?? { ...bumped, rc: null };
     targets.plannedRelease = `v${planned.major}.${planned.minor}.${planned.patch}`;
   }
   let rcs = all.filter((v) => v.rc !== null);
@@ -32983,6 +33080,9 @@ function parseSecretsCatalogVar(raw) {
     if (e.aliases !== void 0 && (!Array.isArray(e.aliases) || e.aliases.some((a) => typeof a !== "string"))) {
       throw new Error(`org project set: secrets["${mapKey}"].aliases must be a string array`);
     }
+    if (e.branchReadable !== void 0 && typeof e.branchReadable !== "boolean") {
+      throw new Error(`org project set: secrets["${mapKey}"].branchReadable must be a boolean`);
+    }
   }
   return parsed;
 }
@@ -33481,7 +33581,7 @@ var SETTABLE_VAR_HINTS = {
   requiredBuildSecrets: 'JSON flat array, e.g. ["NODE_AUTH_TOKEN=@github-packages-token"]',
   tenantTasks: 'JSON map {name:{service,command[],stages[],timeoutSeconds?,artifact?:"required",output?:"file",secretOutput?:{path,vault:{repo,key},overwrite?}}} \u2014 merged per entry, at most 20 stored in total; retire ONE task with --unset-task NAME; use {artifact} in argv when required; a secretOutput is master-only',
   internalPeers: "JSON {owner/repo:[dev|rc|main]} \u2014 same-box suite peers via the box Caddy; clear with --unset internalPeers (#7886)",
-  secrets: "JSON catalog map keyed by KEY {key,purpose,group,owner,stages[],consumers[]} \u2014 merged per entry; drop ONE entry with --unset-secret KEY; clear ALL with --unset secrets --confirm-clear-secrets; prefer --secrets-file",
+  secrets: "JSON catalog map keyed by KEY {key,purpose,group,owner,stages[],consumers[],branchReadable?} \u2014 merged per entry; drop ONE entry with --unset-secret KEY; clear ALL with --unset secrets --confirm-clear-secrets; prefer --secrets-file",
   edgeDomains: "JSON {dev,rc,main} domain map",
   statusOptions: "JSON name\u2192id map",
   priorityOptions: "JSON {Urgent,High,Medium,Low}\u2192id map",
@@ -37883,6 +37983,19 @@ function formatDeployStatus(r) {
 var STAGES2 = ["dev", "rc", "main"];
 function registerDeployCommands(program3) {
   const deploy = program3.command("deploy").description("per-stage deploy observability \u2014 last run, health, and running version (#2688)");
+  deploy.command("history-backfill").description("master-only registry history backfill from Hub tenant-deploy runs (dry-run by default; no dispatch)").requiredOption("--since <ISO>", "include runs created at or after this timestamp").option("--apply", "write successful runs to Hub deploy history").option("--json", "machine-readable counts").action(async (o) => {
+    try {
+      const report = await backfillDeployHistory(o.since, o.apply === true, registryClientDeps(await loadConfig()));
+      if (o.json) console.log(JSON.stringify(report, null, 2));
+      else {
+        console.log(`${report.dryRun ? "Dry-run" : "Applied"} since ${report.since}: ${report.totalRuns} runs, ${report.written} written`);
+        for (const [repo, counts] of Object.entries(report.perRepo)) console.log(`${repo}: ${counts.success} success, ${counts.failed} failed, ${counts.cancelled} cancelled, ${counts.other} other`);
+        console.log(`Skipped: ${report.skipped.nonSha} non-SHA, ${report.skipped.unregistered} unregistered/ambiguous, ${report.skipped.badTitle} bad title`);
+      }
+    } catch (e) {
+      return failGraceful(`deploy history-backfill: ${e.message}`);
+    }
+  });
   deploy.command("status <stage>").description("last deploy run + runtime health probe + running version for a stage (defaults to the current repo); a root answering 401/403/404 is re-probed at /health and the `url` field names the endpoint that answered (#6137)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "machine-readable output").action(async (stage, o) => {
     if (!STAGES2.includes(stage)) {
       return fail(`runtime deploy status: <stage> must be dev, rc, or main`);
@@ -42995,6 +43108,15 @@ async function openSuitePinPr(deps, input) {
   }
 }
 
+// src/pr-title-check.ts
+var CONVENTIONAL_PR_TITLE = /^(feat|fix|docs|chore|refactor|perf|test|build|ci|revert|style)(\([^)]+\))?!?: .+/;
+var EXEMPT_PR_TITLE = /^Merge pull request /;
+function prTitleRefusal(title) {
+  const t = title.trim();
+  if (CONVENTIONAL_PR_TITLE.test(t) || EXEMPT_PR_TITLE.test(t)) return null;
+  return `pr land: PR title "${t}" is not a Conventional type. Expected \`<type>(<scope>)?(!)?: <summary>\` with type one of feat|fix|docs|chore|refactor|perf|test|build|ci|revert|style (e.g. \`fix(cli): refuse a stale tag\`); retitle with \`gh pr edit <n> --title \u2026\` and land again (#8499)`;
+}
+
 // src/command-register-collaboration.ts
 var import_node_child_process17 = require("node:child_process");
 var import_node_fs47 = require("node:fs");
@@ -47935,6 +48057,9 @@ ${list}`);
           return typeof viewed.state === "string" ? viewed.state : void 0;
         }
       );
+      const landTitle = await execFileP("gh", ["pr", "view", number, ...repoArgs, "--json", "title", "--jq", ".title"], { timeout: GC_GH_TIMEOUT_MS }).then((r) => r.stdout.trim(), () => "");
+      const landTitleRefusal = landTitle ? prTitleRefusal(landTitle) : null;
+      if (landTitleRefusal) return refused(landTitleRefusal);
       const landSquashBody = squashBodyTextForMerge(landClosingGuardInput, true);
       warnSquashBodyClosingStrip("pr land", landClosingGuardInput, landSquashBody);
       const landClosingGuardVerdict = evaluateClosingGuard(landClosingGuardInput, {
@@ -57656,7 +57781,7 @@ projectDeploy.command("retire [owner/repo]").description("retire (tombstone) one
   }
   if (!result.ok) return failGraceful(`org project deploy retire: ${result.error ?? "read failed"}`);
 });
-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 (drop ONE entry with --unset-secret KEY; clear ALL with --unset secrets --confirm-clear-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"|?], "provider":"<optional>"}').option("--unset-secret <KEY...>", "remove exactly these #2244 catalog entries (repeatable; KEY or KEY@dev|rc|main). Refuses while a stage still requires the key \u2014 drop it from requiredRuntimeSecrets/requiredBuildSecrets first").option("--unset-task <NAME...>", "retire exactly these tenant tasks (repeatable; lowercase kebab-case names). Refuses a name that is not declared. tenantTasks merges per entry and is capped at 20 stored in total").option("--confirm-clear-secrets", "required to let --unset secrets wipe the WHOLE catalog (the refusal names how many entries that removes)").option("--unset <KEY...>", "META field to remove (repeatable): oauth, requiredRuntimeSecrets, requiredBuildSecrets, secrets (the WHOLE catalog \u2014 needs --confirm-clear-secrets), edgeDomains, requiredGcpApis, publishRequired, releaseChannel, releaseLanguage").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 (drop ONE entry with --unset-secret KEY; clear ALL with --unset secrets --confirm-clear-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"|?], "provider":"<optional>", "branchReadable":<optional boolean, master-only #8497>}').option("--unset-secret <KEY...>", "remove exactly these #2244 catalog entries (repeatable; KEY or KEY@dev|rc|main). Refuses while a stage still requires the key \u2014 drop it from requiredRuntimeSecrets/requiredBuildSecrets first").option("--unset-task <NAME...>", "retire exactly these tenant tasks (repeatable; lowercase kebab-case names). Refuses a name that is not declared. tenantTasks merges per entry and is capped at 20 stored in total").option("--confirm-clear-secrets", "required to let --unset secrets wipe the WHOLE catalog (the refusal names how many entries that removes)").option("--unset <KEY...>", "META field to remove (repeatable): oauth, requiredRuntimeSecrets, requiredBuildSecrets, secrets (the WHOLE catalog \u2014 needs --confirm-clear-secrets), edgeDomains, requiredGcpApis, publishRequired, releaseChannel, releaseLanguage").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 {

package/cli/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/codex-plugin",
-  "version": "4.5.169",
+  "version": "4.5.171",
   "description": "MMI workflow skills and org gates delivery.",
   "author": {
     "name": "MMI Future",

package/skills/org-guide/references/work-and-releases.md

@@ -118,6 +118,10 @@ Production changes require explicit authorization from the authorized human.
 Read the selected release skill before operating the train. Let it choose versions, run gates,
 publish, deploy, and verify the resulting release. A refusal requires fixing its cause; do not
 finish by hand, bypass checks, or start a duplicate release.
+Versions: patch is the default for fixes and small compatible additions. Minor is a deliberate call
+for a real feature, with a one-line reason. Major is a new start or direction and needs the owner's
+fresh approval before tagging. A breaking change refuses until it is shimmed or made an approved
+major. The [release](../../release/SKILL.md) skill names the exact switches.
 A release announces itself in Slack once its deploy and publish are green: the Hub to the org alerts channel, a product to its own
 project channel when the project's registry META sets `releaseChannel`; never post release notes
 by hand. The Hub always needs a curated `--announce-summary-file`, and so does any product whose

package/skills/release/SKILL.md

@@ -7,6 +7,8 @@ description: Ship rc or direct-track development to main and production.
 
 **Argument:** `/release minor`, `/release major`, or `/release patch` — a bare bump word, never a `--flag` or env var. No argument → `patch`; a `/release patch` from development is a legitimate ordinary release, `/hotfix` stays the cherry-pick promotion lane.
 
+**Bump rules** ([docs/versioning.md](../../docs/versioning.md)): patch is the default and needs nothing. `minor` only for a real feature or significant change, with a one-line reason exported as `MMI_BUMP_REASON`. `major` only with Jervaise's fresh approval in this turn: export `MMI_BUMP_REASON` and `MMI_MAJOR_APPROVED=<exact target version>` (e.g. `5.0.0`) only after that approval, never earlier or from a prior turn. A breaking signal in the range (`feat!:`, `BREAKING CHANGE:`) makes the train refuse until it is shimmed (patch) or declared an owner-gated major.
+
 # /release — ship to main + prod
 
 Full-track repos ship exactly what is on `rc` (never `development`): merge `rc → main`, tag `vX.Y.0`, publish the GitHub Release, deploy prod, roll `development` forward. Direct-track repos ship `development → main`, and the release event fires the repo's own deploy/publish workflow (MMI-Hub: `deploy.yml` + `publish.yml`). `rc` is ephemeral: `/rcand` creates its runtime, `/release` retires it after a confirmed prod deploy (`rcRetirement`). A prod release needs the authorized human's explicit go in the current turn — an agent never self-initiates it. The board needs no touch: items reached `Done` when their PRs merged to `development`.