@mutmutco/cli 4.3.38 → 4.3.39

package/dist/main.cjs

@@ -4149,6 +4149,20 @@ var HOUSE_MAP = {
   onboard: "core"
   // repo-readiness orientation (front door — torn toward oracle, kept core)
 };
+var HOUSE_ALIASES = {
+  issue: ["devops"],
+  // filing/managing issues is oracle, but reads as shipping work
+  "issue create": ["devops"]
+};
+function isDeclaredHouseAlias(houseToken, lookupPath) {
+  const segments = lookupPath.split(" ");
+  for (let end = segments.length; end > 0; end -= 1) {
+    const key = segments.slice(0, end).join(" ");
+    const aliases = HOUSE_ALIASES[key];
+    if (aliases) return aliases.includes(houseToken);
+  }
+  return false;
+}
 function houseForPath(path2) {
   if (path2 === "") return "core";
   const segments = path2.split(" ");
@@ -5256,6 +5270,39 @@ function unknownCommandDomainGuide(parentPath, token) {
   return GUIDES.get(`${parentPath}:${token}`);
 }
 
+// src/verb-alias.ts
+var VERB_ALIAS_TABLE = [
+  // #6489: `board` has no `status` leaf (read|claim|show|move|done|doctor only); the read that
+  // answers "what is this issue/PR's board column" is `board show <ref>`.
+  { typed: ["oracle", "board", "status"], canonical: ["oracle", "board", "show"] },
+  { typed: ["board", "status"], canonical: ["board", "show"] },
+  // #6494: there is no top-level or housed `registry` command; org/registry project metadata is
+  // `oracle org project get`.
+  { typed: ["registry"], canonical: ["oracle", "org", "project", "get"] },
+  // #6486: filing/managing an issue reads as devops work (it ships something) but issues are oracle's
+  // live truth; the real command is `oracle issue create`. (A narrower house-token-only reroute for
+  // this same case may also exist elsewhere — this entry keeps the general table a complete answer on
+  // its own, not dependent on that mechanism landing.)
+  { typed: ["devops", "issue", "create"], canonical: ["oracle", "issue", "create"] }
+];
+var TABLE_BY_LENGTH = [...VERB_ALIAS_TABLE].sort((a, b) => b.typed.length - a.typed.length);
+function matchesAt(argv, start, tokens2) {
+  if (start + tokens2.length > argv.length) return false;
+  return tokens2.every((tok, i) => argv[start + i] === tok);
+}
+function applyVerbAlias(argv) {
+  const entry = TABLE_BY_LENGTH.find((e) => matchesAt(argv, 2, e.typed));
+  if (!entry) return void 0;
+  argv.splice(2, entry.typed.length, ...entry.canonical);
+  return { typed: entry.typed.join(" "), canonical: entry.canonical.join(" ") };
+}
+function resolveVerbAliasShim(argv) {
+  const hit = applyVerbAlias(argv);
+  if (!hit) return;
+  process.stderr.write(`mmi-cli: '${hit.typed}' is '${hit.canonical}' \u2014 ran it for you
+`);
+}
+
 // src/command-composition.ts
 var import_node_os22 = require("node:os");
 var import_node_path47 = require("node:path");
@@ -7195,6 +7242,50 @@ async function readRepoSurfaceLabels(repo, deps = {}) {
     return void 0;
   }
 }
+function surfaceWords(label) {
+  return label.slice(SURFACE_PREFIX.length).toLowerCase().split(/[-_]+/).filter(Boolean);
+}
+function pathWords(text) {
+  const words = [];
+  for (const hit of text.match(/[\w.-]+(?:\/[\w.-]+)+/g) ?? []) {
+    for (const segment of hit.split("/")) words.push(...segment.toLowerCase().split(/[-_.]+/).filter(Boolean));
+  }
+  return words;
+}
+function proseWords(text) {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+function inferSurface(candidates, context = {}) {
+  const sorted = [...candidates].sort();
+  if (sorted.length === 0) throw new Error("inferSurface: no surface:* candidates to choose from");
+  const pWords = new Set(pathWords(context.body ?? ""));
+  const tWords = /* @__PURE__ */ new Set([...proseWords(context.title ?? ""), ...proseWords(context.body ?? "")]);
+  let best = sorted[0];
+  let bestScore = 0;
+  let bestFromPath = false;
+  for (const label of sorted) {
+    const words = surfaceWords(label);
+    if (!words.length) continue;
+    const pathHits = words.filter((w) => pWords.has(w)).length;
+    const proseHits = words.filter((w) => tWords.has(w)).length;
+    const score = pathHits * 2 + proseHits;
+    if (score > bestScore) {
+      bestScore = score;
+      best = label;
+      bestFromPath = pathHits > 0;
+    }
+  }
+  if (bestScore === 0) {
+    return {
+      label: sorted[0],
+      reason: `no path or title/body word matched any of ${sorted.length} surface label(s) \u2014 defaulted to the alphabetically-first`
+    };
+  }
+  return {
+    label: best,
+    reason: bestFromPath ? "matched a path mentioned in the issue body" : "matched a word in the issue title/body"
+  };
+}
 async function checkSurfaceRequirement(input, deps = {}) {
   if (input.waiver) {
     const reason = input.waiver.reason.trim();
@@ -7226,20 +7317,7 @@ async function checkSurfaceRequirement(input, deps = {}) {
   }
   if (known.length === 0) return { enforcing: false, taxonomyAbsent: true };
   if (labelsCarrySurface(input.labels)) return { enforcing: true };
-  const command = input.command ?? "issue create";
-  const where = input.rowLabel ? `${input.rowLabel}: ` : "";
-  return {
-    enforcing: true,
-    refusal: {
-      message: `${command}: ${where}${input.repo} requires every open issue to carry exactly one surface:* label, and this one sets none \u2014 filing it unlabeled reds the board check on every open PR in that repo. Pass --surface <value>, or --no-surface if this filing is genuinely exempt`,
-      payload: {
-        code: ERROR_CODES.ERR_MISSING_FLAG,
-        offending_flag: "--surface",
-        // Advisory, not a closed enum: the board rule is "exactly one surface:* label", whatever its value.
-        expected: [...known].sort()
-      }
-    }
-  };
+  return { enforcing: true, inferred: inferSurface(known, { title: input.title, body: input.body }) };
 }
 function conflictingSurfaceInputs(surfaceFlag, labels) {
   if (!surfaceFlag) return void 0;
@@ -15617,10 +15695,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.3.38",
-    tag: "v4.3.38",
-    commit: "da4541fdb81e",
-    npm: "@mutmutco/cli@4.3.38"
+    version: "4.3.39",
+    tag: "v4.3.39",
+    commit: "cc67ff24bbec",
+    npm: "@mutmutco/cli@4.3.39"
   },
   exitCriterion: "fleet-n-of-n",
   hubOnlyShortcut: "forbidden",
@@ -15637,14 +15715,14 @@ var rollout_plan_default = {
           repo: "mutmutco/mmi-hub",
           role: "canary",
           schedule: "train",
-          v3Target: "v4.3.38"
+          v3Target: "v4.3.39"
         }
       ],
       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.3.38 and redeploy the Hub Lambda from tag v4.3.38 (da4541fdb81e); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
-        v3Target: "v4.3.38 (@mutmutco/cli@4.3.38, tag commit da4541fdb81e \u2014 last known-good release carrying the repo-index v4-only contract)"
+        mechanism: "npm dist-tag latest -> 4.3.39 and redeploy the Hub Lambda from tag v4.3.39 (cc67ff24bbec); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.3.39 (@mutmutco/cli@4.3.39, tag commit cc67ff24bbec \u2014 last known-good release carrying the repo-index v4-only contract)"
       }
     },
     {
@@ -21645,13 +21723,9 @@ async function runTrainDoctor(input) {
     add(linked ? { code: "worktree-isolated", severity: "blocker", source: "local", title: `this is a linked worktree on ${currentBranch2 || "(detached)"}, not the lane's start branch ${startBranch} (#2770)`, remedy: `run the ${lane} lane from the primary checkout on ${startBranch}; a linked worktree never carries the train` } : { code: "branch-mismatch", severity: "blocker", source: "local", title: `on ${currentBranch2 || "(detached)"}; the ${lane} lane starts from ${startBranch}`, remedy: `git checkout ${startBranch}, then rerun; --heal never switches branches \u2014 the branch you stand on names the lane you meant, and healing it would run the train off a branch you did not pick (#6432)` });
   }
   const stage = laneStage(lane);
-  const workflowsRef = `origin/${startBranch ?? "main"}`;
-  const workflows = deps.readWorkflows(cwd, workflowsRef);
-  if (workflows === null) {
-    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` });
-  }
+  let missing = [];
   if (hints) {
-    const missing = [
+    missing = [
       ...!hints.hasDevelopmentBranch && lane !== "hotfix" ? ["development"] : [],
       ...!hints.hasMainBranch ? ["main"] : [],
       // #6318: a `--dev` release never reads, merges or tags rc — a missing rc branch cannot block it.
@@ -21659,30 +21733,38 @@ async function runTrainDoctor(input) {
     ];
     if (missing.length) add({ code: "bootstrap-gap", severity: "blocker", source: "origin", title: `train branch(es) missing on origin: ${missing.join(", ")}`, remedy: `bootstrap the repo train: \`mmi-cli devops bootstrap apply ${repo} --execute\` (from the MMI-Hub root), then rerun` });
   }
-  try {
-    const required = await discoverRequiredCheckContexts(train, ctx, stage);
-    if (required.length === 0) {
-      add({ code: "bootstrap-gap", severity: "warning", source: "origin", title: `no ruleset requires a status check on ${stage} \u2014 the train tags without a check wait (the GitHub push gate is the backstop)`, remedy: `activate the product ruleset: \`mmi-cli devops bootstrap apply ${repo} --execute\` (from the MMI-Hub root), or \`mmi-cli devops ci audit --repo ${repo}\`` });
-    } else {
-      try {
-        assertTagAddressableRequiredContexts({ readWorkflows: () => workflows }, required, repo);
-      } catch (e) {
-        add({ code: "contexts-not-tag-addressable", severity: "blocker", source: "local", title: `required ${stage} check(s) cannot materialize on a tag push (#5428)`, remedy: message(e) });
-      }
-      if (startBranch) {
-        const tip = await git3(["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${startBranch}`]);
-        const checkRuns = JSON.parse(await train.run("gh", ["api", `repos/${repo}/commits/${tip}/check-runs`, "--jq", TRAIN_CHECK_RUNS_JQ]));
-        const statuses = JSON.parse(await train.run("gh", ["api", `repos/${repo}/commits/${tip}/status`, "--jq", TRAIN_COMMIT_STATUS_JQ]));
-        const observed = required.filter((c) => checkRuns.some((r) => r.name === c) || statuses.some((s) => s.context === c));
-        const red = observed.filter((c) => resolveContextState(c, checkRuns, statuses) === "failed");
-        const inFlight = observed.filter((c) => resolveContextState(c, checkRuns, statuses) === "pending");
-        const at = `${startBranch}@${tip.slice(0, 12)}`;
-        if (red.length) add({ code: "required-check-red", severity: "blocker", source: "origin", title: `required ${stage} check(s) failed on the lane's start branch tip: ${red.join(", ")} at ${at}`, remedy: `--heal never clears this one \u2014 a red trunk needs a fix, not a heal: land the failure's fix on ${startBranch} through a CI-gated PR, then rerun once its run is green (#6461)` });
-        else if (inFlight.length) add({ code: "required-check-red", severity: "warning", source: "origin", title: `required ${stage} check(s) still in flight on the lane's start branch tip: ${inFlight.join(", ")} at ${at}`, remedy: `wait for the run to conclude and rerun \u2014 the tip's verdict is not known yet, and the train would tag before it is` });
+  const startBranchMissing = startBranch != null && missing.includes(startBranch);
+  const workflowsRef = `origin/${startBranch ?? "main"}`;
+  const workflows = startBranchMissing ? null : deps.readWorkflows(cwd, workflowsRef);
+  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 (!startBranchMissing) {
+    try {
+      const required = await discoverRequiredCheckContexts(train, ctx, stage);
+      if (required.length === 0) {
+        add({ code: "bootstrap-gap", severity: "warning", source: "origin", title: `no ruleset requires a status check on ${stage} \u2014 the train tags without a check wait (the GitHub push gate is the backstop)`, remedy: `activate the product ruleset: \`mmi-cli devops bootstrap apply ${repo} --execute\` (from the MMI-Hub root), or \`mmi-cli devops ci audit --repo ${repo}\`` });
+      } else {
+        try {
+          assertTagAddressableRequiredContexts({ readWorkflows: () => workflows }, required, repo);
+        } catch (e) {
+          add({ code: "contexts-not-tag-addressable", severity: "blocker", source: "local", title: `required ${stage} check(s) cannot materialize on a tag push (#5428)`, remedy: message(e) });
+        }
+        if (startBranch) {
+          const tip = await git3(["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${startBranch}`]);
+          const checkRuns = JSON.parse(await train.run("gh", ["api", `repos/${repo}/commits/${tip}/check-runs`, "--jq", TRAIN_CHECK_RUNS_JQ]));
+          const statuses = JSON.parse(await train.run("gh", ["api", `repos/${repo}/commits/${tip}/status`, "--jq", TRAIN_COMMIT_STATUS_JQ]));
+          const observed = required.filter((c) => checkRuns.some((r) => r.name === c) || statuses.some((s) => s.context === c));
+          const red = observed.filter((c) => resolveContextState(c, checkRuns, statuses) === "failed");
+          const inFlight = observed.filter((c) => resolveContextState(c, checkRuns, statuses) === "pending");
+          const at = `${startBranch}@${tip.slice(0, 12)}`;
+          if (red.length) add({ code: "required-check-red", severity: "blocker", source: "origin", title: `required ${stage} check(s) failed on the lane's start branch tip: ${red.join(", ")} at ${at}`, remedy: `--heal never clears this one \u2014 a red trunk needs a fix, not a heal: land the failure's fix on ${startBranch} through a CI-gated PR, then rerun once its run is green (#6461)` });
+          else if (inFlight.length) add({ code: "required-check-red", severity: "warning", source: "origin", title: `required ${stage} check(s) still in flight on the lane's start branch tip: ${inFlight.join(", ")} at ${at}`, remedy: `wait for the run to conclude and rerun \u2014 the tip's verdict is not known yet, and the train would tag before it is` });
+        }
       }
+    } catch (e) {
+      unverified(`required status checks on ${stage}`, e);
     }
-  } catch (e) {
-    unverified(`required status checks on ${stage}`, e);
   }
   let ledgerTag;
   let ledgerPath;
@@ -24606,7 +24688,7 @@ function ciReconcileExitFailed(input) {
   }
   return input.applyResults.some((result) => result.errors.length > 0 || result.postApply == null || result.postApply.state !== "clean" && result.postApply.state !== "repaired");
 }
-async function authoritativeSafetyHold(authority, deps, repo, baseBranch) {
+async function authoritativeSafetyHold(authority, deps, repo, baseBranch, meta) {
   if (authority.coversReleaseBranches) {
     const prOnly = authority.contexts.filter((context) => TRAIN_PR_ONLY_CONTEXTS.has(context));
     if (prOnly.length > 0) {
@@ -24620,6 +24702,22 @@ async function authoritativeSafetyHold(authority, deps, repo, baseBranch) {
   if (missing.length > 0) {
     return `${authority.source} requires context(s) with no pull_request workflow emitter [${missing.join(", ")}]; no source or live mutation was made`;
   }
+  if (authority.coversReleaseBranches) {
+    const track = resolveReleaseTrack(meta, void 0, repo);
+    const releaseBranches = branchesForTrack(track).filter((b) => b !== baseBranch);
+    const ignore = /* @__PURE__ */ new Set([...AGENT_PR_BOOKKEEPING_CONTEXTS, ...TRAIN_PR_ONLY_CONTEXTS]);
+    const requiredForReleaseBranches = authority.contexts.filter((context) => !ignore.has(context));
+    for (const branch of releaseBranches) {
+      if (await branchPresence(deps, repo, branch) !== true) continue;
+      const emittedThere = await resolveEmittedPrContexts(deps, repo, branch);
+      if (emittedThere === void 0) continue;
+      const emittedThereSet = new Set(emittedThere);
+      const unreachable = requiredForReleaseBranches.filter((context) => !emittedThereSet.has(context));
+      if (unreachable.length > 0) {
+        return `${authority.source} requires context(s) [${unreachable.join(", ")}] on ${branch}, but ${branch}'s own workflows emit none of them \u2014 a base-${branch} PR (e.g. a hotfix) could never satisfy the gate; no source or live mutation was made. Remove [${unreachable.join(", ")}] from ${branch} requirements, or add the emitting workflow to ${branch}`;
+      }
+    }
+  }
   return null;
 }
 async function applyCiReconcileRepo(repo, deps) {
@@ -24636,7 +24734,7 @@ async function applyCiReconcileRepo(repo, deps) {
       empty.errors.push(`${PRODUCT_RULESET_REF} is not parseable: ${e.message}`);
       return finalizeCiReconcile(repo, deps, empty, report);
     }
-    const hold = await authoritativeSafetyHold(authority, deps, repo, baseBranch);
+    const hold = await authoritativeSafetyHold(authority, deps, repo, baseBranch, meta);
     if (hold) {
       empty.skipped.push(hold);
       return finalizeCiReconcile(repo, deps, empty, report, hold);
@@ -24644,7 +24742,7 @@ async function applyCiReconcileRepo(repo, deps) {
   } else if (report.class === "deployable" && !report.explicitNoCi) {
     const registryAuthority = registryAuthorityWithoutReference(meta, repo);
     if (registryAuthority) {
-      const hold = await authoritativeSafetyHold(registryAuthority, deps, repo, baseBranch);
+      const hold = await authoritativeSafetyHold(registryAuthority, deps, repo, baseBranch, meta);
       if (hold) {
         empty.skipped.push(hold);
         return finalizeCiReconcile(repo, deps, empty, report, hold);
@@ -24673,7 +24771,7 @@ async function applyCiReconcileRepo(repo, deps) {
       result.errors.push(`${PRODUCT_RULESET_REF} is not parseable: ${e.message}`);
       return finalizeCiReconcile(repo, deps, result, report);
     }
-    const hold = await authoritativeSafetyHold(authority, deps, repo, baseBranch);
+    const hold = await authoritativeSafetyHold(authority, deps, repo, baseBranch, meta);
     if (hold) {
       result.skipped.push(hold);
       return finalizeCiReconcile(repo, deps, result, report, hold);
@@ -29253,8 +29351,11 @@ function parseOauthVar(raw) {
   const out = {};
   for (const [key, value] of Object.entries(map)) {
     if (key === "subdomains" || key === "domains") {
-      if (!Array.isArray(value) || value.some((v) => typeof v !== "string" || !v.trim())) {
-        throw new Error(`org project set: oauth.${key} must be an array of non-empty strings`);
+      const allowEmpty = key === "subdomains";
+      if (!Array.isArray(value) || value.some((v) => typeof v !== "string" || v.trim() === "" && !(allowEmpty && v === ""))) {
+        throw new Error(
+          allowEmpty ? `org project set: oauth.${key} must be an array of strings ("" selects the apex \u2014 the domain itself)` : `org project set: oauth.${key} must be an array of non-empty strings`
+        );
       }
       out[key] = value.map((v) => v.trim());
     } else if (key === "callbackPath") {
@@ -33492,18 +33593,33 @@ async function preflightBatchSurfaces(validated, rowRepo, options) {
   }
   if (options.noSurface) return [];
   const errors = [];
-  const cache = /* @__PURE__ */ new Map();
+  const censusCache = /* @__PURE__ */ new Map();
+  const censusFor = (repo) => {
+    let pending = censusCache.get(repo);
+    if (!pending) {
+      pending = readRepoSurfaceLabels(repo);
+      censusCache.set(repo, pending);
+    }
+    return pending;
+  };
   for (const { row, spec } of validated) {
+    if (labelsCarrySurface(spec.labels)) continue;
     const repo = rowRepo(spec);
-    const key = [repo, labelsCarrySurface(spec.labels) ? "has" : "none"].join("::");
-    let verdict = cache.get(key);
-    if (!verdict) {
-      verdict = await checkSurfaceRequirement({ repo, labels: spec.labels, command: "issue create --batch" });
-      cache.set(key, verdict);
-      if (verdict.warn) process.stderr.write(`${verdict.warn}
-`);
+    const known = await censusFor(repo);
+    if (known === void 0) {
+      process.stderr.write(
+        `warning: could not read ${repo}'s labels, so row ${row}'s surface-label requirement was not checked; if that board enforces one surface:* label per open issue, add one with \`mmi-cli oracle issue edit <n> --add-label surface:<value>\`
+`
+      );
+      continue;
     }
-    if (verdict.refusal) errors.push({ row, error: verdict.refusal.message });
+    if (known.length === 0) continue;
+    const inferred = inferSurface(known, { title: spec.title, body: spec.body });
+    spec.labels = [...spec.labels ?? [], inferred.label];
+    process.stderr.write(
+      `mmi-cli: no --surface given \u2014 row ${row} filed under ${inferred.label} (${inferred.reason}). Pass --surface to choose.
+`
+    );
   }
   return errors;
 }
@@ -35597,8 +35713,8 @@ function registerSecretsCommands(program3) {
   const secrets = program3.command("secrets").description("project vault \u2014 project-admins self-serve their own repo's full tree (stageless + dev/rc/main); org-infra namespaces are master-gated");
   secrets.command("where").description("print where this repo's secrets live \u2014 the two-tier vault layout + well-known keys (no values)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "machine-readable output").action((o) => withSecrets((d) => secretsWhere(d, o)));
   secrets.command("list").description("list secret NAMES + tier for THIS repo (never values). To locate a key you cannot place \u2014 including org-infra (_org) \u2014 use the cross-slug view: `mmi-cli oracle org access capabilities` (#3436)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "machine-readable output").action((o) => withSecrets((d) => secretsList(d, o)));
-  secrets.command("find <intent>").description("resolve a plain-language intent to canonical secret names + the exact keyless-use command (master-only, #2244)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "machine-readable output").action((intent, o) => withSecrets(async (d) => {
-    if (!await secretsFind(d, intent, o)) process.exitCode = 1;
+  secrets.command("find <intent...>").description("resolve a plain-language intent to canonical secret names + the exact keyless-use command (master-only, #2244); an unquoted multi-word intent is joined with spaces (#6495)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "machine-readable output").action((intentWords, o) => withSecrets(async (d) => {
+    if (!await secretsFind(d, intentWords.join(" "), o)) process.exitCode = 1;
   }));
   secrets.command("catalog").description("the secret catalog \u2014 grouped, with each secret's exact keyless-use command (master-only, #2244)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--drift", "include the bidirectional reconciler drift report").option("--json", "machine-readable output").action((o) => withSecrets((d) => secretsCatalog(d, o)));
   secrets.command("doctor").description("vault drift report \u2014 declared-missing / orphan / off-scheme / duplicate (master-only, #2244)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "machine-readable output").action((o) => withSecrets(async (d) => {
@@ -37080,8 +37196,20 @@ function matchedMandatoryGlobs(paths, mandatory) {
     return list.some((path2) => re.test(path2));
   });
 }
-function evaluateTestCommandPolicy({ paths, mandatory, regulated = true, override = null, addedPaths = [] } = {}) {
+function evaluateTestCommandPolicy({ paths, mandatory, regulated = true, override = null, addedPaths = [], structuralRefusal = false } = {}) {
   const configuredMandatoryCount = mandatoryGlobList(mandatory).length;
+  if (structuralRefusal) {
+    return {
+      configuredMandatoryCount,
+      matchedMandatoryGlobs: [],
+      matchedMandatoryCount: 0,
+      testCommandsAllowed: false,
+      editsExistingTest: false,
+      reasonId: "test-command-outside-mandatory-zone",
+      testCommandNote: null,
+      commandClasses: { allowed: [], refused: [TEST_COMMAND_CLASS] }
+    };
+  }
   if (!regulated) {
     return {
       configuredMandatoryCount: 0,
@@ -37090,25 +37218,30 @@ function evaluateTestCommandPolicy({ paths, mandatory, regulated = true, overrid
       testCommandsAllowed: true,
       editsExistingTest: false,
       reasonId: null,
+      testCommandNote: null,
       commandClasses: { allowed: [TEST_COMMAND_CLASS], refused: [] }
     };
   }
   const matched = matchedMandatoryGlobs(paths, mandatory);
   const overrideAuthorizes = Array.isArray(override?.kinds) && override.kinds.includes(TEST_WORK_KIND);
   const existingTestEdited = editsExistingTest(paths, addedPaths);
-  const testCommandsAllowed = matched.length > 0 || overrideAuthorizes || existingTestEdited;
+  const inMandatoryZone = matched.length > 0 || overrideAuthorizes || existingTestEdited;
+  const testCommandsAllowed = true;
   return {
     configuredMandatoryCount,
     matchedMandatoryGlobs: matched,
     matchedMandatoryCount: matched.length,
     testCommandsAllowed,
-    /** #5842: true when the diff edits a test file that already existed — one of the facts that can
-     *  authorize the class, named so a refusal can say what was missing. */
+    /** #5842: true when the diff edits a test file that already existed — one of the facts that used
+     *  to authorize the class, kept for callers that still branch on it. */
     editsExistingTest: existingTestEdited,
-    reasonId: testCommandsAllowed ? null : "test-command-outside-mandatory-zone",
+    reasonId: null,
+    /** Informational only (#1166): set when the diff is outside the mandatory zone, so a caller can
+     *  note that CI does not require a test here — never a reason to refuse the run. */
+    testCommandNote: inMandatoryZone ? null : "test-command-outside-mandatory-zone",
     commandClasses: {
-      allowed: testCommandsAllowed ? [TEST_COMMAND_CLASS] : [],
-      refused: testCommandsAllowed ? [] : [TEST_COMMAND_CLASS]
+      allowed: [TEST_COMMAND_CLASS],
+      refused: []
     }
   };
 }
@@ -37778,7 +37911,12 @@ function runTestPolicy(root, deps = {}) {
     addedPaths: changed.filter((f) => f.status === "A" || f.status === "R").map((f) => f.path),
     mandatory: policy.mandatory,
     regulated: policy.declared !== false || policyRefusals.length > 0,
-    override: override && lookup.refusals.length === 0 ? { kinds: override.kinds } : null
+    override: override && lookup.refusals.length === 0 ? { kinds: override.kinds } : null,
+    // #1166: a still-blocking pre-diff finding (untrusted range, unresolvable base, a missing policy
+    // on the hotfix lane, a malformed trailer, an unwaived stale entry) means the diff itself was
+    // never evaluated — the mandatory-zone question this evaluator now answers permissively was
+    // never reached, so the refusal stands exactly as before.
+    structuralRefusal: blocking.length > 0
   });
   const result = {
     ok: findings.length === 0,
@@ -37792,6 +37930,7 @@ function runTestPolicy(root, deps = {}) {
     matchedMandatoryCount: commandPolicy.matchedMandatoryCount,
     testCommandsAllowed: commandPolicy.testCommandsAllowed,
     testCommandReasonId: commandPolicy.reasonId,
+    testCommandNote: commandPolicy.testCommandNote,
     commandClasses: commandPolicy.commandClasses
   };
   if (override) {
@@ -39808,7 +39947,7 @@ function registerCollaborationCommands(program3) {
   }
   const issue = program3.command("issue").description("issues \u2014 create and view with structured JSON (view; show, get and read alias view for board-verb/gh-shaped callers). Claims are board mutations: use `oracle board claim`, never `oracle issue claim` or the flat `board claim`");
   withExamples(mutating(
-    issue.command("create").description("create an issue (type \u2014 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 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("--surface <surface>", "issue surface, with or without the surface: prefix (#3789). Required when the target repo runs the one-surface-label board rule; any value satisfies it, so this is not a closed enum").option("--no-surface", "file without a surface label on a repo that requires one \u2014 for a genuinely exempt filing (e.g. a coop proof issue that spans every surface)").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 \u2014 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 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("--surface <surface>", "issue surface, with or without the surface: prefix (#3789). Any value satisfies the one-surface-label board rule, so this is not a closed enum. Omit it on an enforcing repo and one is inferred from the title/body (#1164) \u2014 the pick is printed and included in --json as surface_inferred/surface/surface_reason").option("--no-surface", "file without a surface label on a repo that requires one \u2014 for a genuinely exempt filing (e.g. a coop proof issue that spans every surface). Suppresses inference too").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: resolve the same title source and validate the same type, priority,
     // and surface contract as the real action. A plan that echoes the title-file PATH instead of its value
     // is not a plan of the mutation that will run (#3914).
@@ -39832,14 +39971,24 @@ function registerCollaborationCommands(program3) {
       if (clash) fail(clash.message, clash.payload);
       const planRepo = opts.batch || surfaceWaived() ? void 0 : await resolveRepo(opts.repo);
       const surface = resolveCreateSurface(opts);
+      let planInferred;
       if (planRepo) {
-        const { refusal, warn } = await checkSurfaceRequirement({
+        const { refusal, warn, inferred } = await checkSurfaceRequirement({
           repo: planRepo,
-          labels: [...planLabels, ...surface ? [surface] : []]
+          labels: [...planLabels, ...surface ? [surface] : []],
+          title,
+          body: opts.body
         });
         if (warn) process.stderr.write(`${warn}
 `);
         if (refusal) fail(refusal.message, refusal.payload);
+        if (inferred && !surface) {
+          planInferred = inferred;
+          process.stderr.write(
+            `mmi-cli: no --surface given \u2014 filed under ${inferred.label} (${inferred.reason}). Pass --surface to choose.
+`
+          );
+        }
       }
       return {
         command: "issue create",
@@ -39847,7 +39996,8 @@ function registerCollaborationCommands(program3) {
         title,
         priority,
         repo: opts.repo,
-        ...surface ? { surface } : {}
+        ...surface ? { surface } : {},
+        ...planInferred ? { surface_inferred: true, surface: planInferred.label, surface_reason: planInferred.reason } : {}
       };
     }
   ).action(async (o) => {
@@ -39859,6 +40009,7 @@ function registerCollaborationCommands(program3) {
     let extraLabels = [];
     let targetRepo2;
     let surfaceFlagLabel;
+    let surfaceInferred;
     try {
       issueType = resolveCreateType(o.type, "issue create", o.label);
       title = await resolveIssueTitle({ title: o.title, titleFile: o.titleFile }, { readFile: import_promises7.readFile, readStdin });
@@ -39890,8 +40041,8 @@ function registerCollaborationCommands(program3) {
       return fail(`issue create: ${e.message}`, e instanceof TextArgError ? { code: e.code, offending_flag: e.offendingFlag } : void 0);
     }
     {
-      const surfaceCheck = await checkSurfaceRequirement({ repo: targetRepo2, labels: extraLabels });
-      const { refusal, warn } = surfaceCheck;
+      const surfaceCheck = await checkSurfaceRequirement({ repo: targetRepo2, labels: extraLabels, title, body });
+      const { refusal, warn, inferred } = surfaceCheck;
       if (warn) process.stderr.write(`${warn}
 `);
       if (shouldWithdrawSurfaceFlag(surfaceCheck) && surfaceFlagLabel) {
@@ -39906,6 +40057,22 @@ function registerCollaborationCommands(program3) {
         });
         process.stderr.write(
           `warning: --surface ${surfaceFlagLabel} was dropped \u2014 ${targetRepo2} defines no surface:* labels, and creating one here would switch the one-surface-label rule on for every later filing in it. Use --label ${surfaceFlagLabel} if you really mean to start that taxonomy.
+`
+        );
+      }
+      if (inferred && !surfaceFlagLabel && !surfaceWaived()) {
+        extraLabels = [...extraLabels, inferred.label];
+        args = buildIssueArgs({
+          type: issueType,
+          title,
+          body,
+          priority,
+          repo: targetRepo2,
+          labels: extraLabels.length ? extraLabels : void 0
+        });
+        surfaceInferred = inferred;
+        process.stderr.write(
+          `mmi-cli: no --surface given \u2014 filed under ${inferred.label} (${inferred.reason}). Pass --surface to choose.
 `
         );
       }
@@ -39946,7 +40113,9 @@ function registerCollaborationCommands(program3) {
         ...attached.resetAt ? { resetAt: attached.resetAt } : {},
         ...attached.resetEpochSeconds !== void 0 ? { resetEpochSeconds: attached.resetEpochSeconds } : {}
       } : {},
-      ...parentLinkFields(parent, parentLinkError)
+      ...parentLinkFields(parent, parentLinkError),
+      // #1164: surfaced so a caller can see (and override with --surface) a pick it never asked for.
+      ...surfaceInferred ? { surface_inferred: true, surface: surfaceInferred.label, surface_reason: surfaceInferred.reason } : {}
     }));
   }), [
     'mmi-cli oracle issue create --type task --title "Wire the schema"',
@@ -42091,7 +42260,7 @@ function registerDeveloperCommands(program3) {
     }
   });
   const tests = program3.command("tests").description("a repo's test-policy.json \u2014 the opt-in test contract and its enforcement");
-  tests.command("policy").description("enforce this repo's test-policy.json against the diff: a mandatory-zone change must carry a test, an unrequested new test file is refused, a `protected` test file may not be deleted or renamed away, and a `protected` entry naming a missing file is refused. Override any of them with a `Test-Policy-Override: <reason>` commit trailer (#3605)").option("--json", "machine-readable result: { ok, base, policySource: { ref, sha, path }, root, changedCount, mandatoryCount, matchedMandatoryCount, matchedMandatoryGlobs, testCommandsAllowed, commandClasses, findings[] }").option("--base <ref>", "comparison base (default: TEST_POLICY_BASE, then origin/development, then origin/main)").option("--policy-ref <commit>", "load test-policy.json from the exact fetched origin/development commit and audit its protected/satisfiedBy paths against that commit's tree, not this checkout; valid only with --base origin/main").addOption(new Option("--repo <owner/repo>", "not accepted \u2014 tests policy reads the current checkout").hideHelp()).action(async (o) => {
+  tests.command("policy").description("enforce this repo's test-policy.json against the diff: a mandatory-zone change must carry a test, an unrequested new test file is refused, a `protected` test file may not be deleted or renamed away, and a `protected` entry naming a missing file is refused. Override any of them with a `Test-Policy-Override: <reason>` commit trailer (#3605)").option("--json", "machine-readable result: { ok, base, policySource: { ref, sha, path }, root, changedCount, mandatoryCount, matchedMandatoryCount, matchedMandatoryGlobs, testCommandsAllowed, testCommandNote, commandClasses, findings[] }").option("--base <ref>", "comparison base (default: TEST_POLICY_BASE, then origin/development, then origin/main)").option("--policy-ref <commit>", "load test-policy.json from the exact fetched origin/development commit and audit its protected/satisfiedBy paths against that commit's tree, not this checkout; valid only with --base origin/main").addOption(new Option("--repo <owner/repo>", "not accepted \u2014 tests policy reads the current checkout").hideHelp()).action(async (o) => {
     try {
       if (o.repo) {
         const rerun = `mmi-cli tests policy${o.base ? ` --base ${o.base}` : ""}${o.policyRef ? ` --policy-ref ${o.policyRef}` : ""}${o.json ? " --json" : ""}`;
@@ -42114,7 +42283,7 @@ function registerDeveloperCommands(program3) {
         return;
       }
       if (result.ok) {
-        const commandVerdict = result.testCommandsAllowed ? "test commands: allowed" : `test commands: refused [${result.testCommandReasonId}] \u2014 resolved repo: ${result.root}; if that is not the repo under test, start the command with a literal Set-Location "<your worktree>"`;
+        const commandVerdict = result.testCommandsAllowed ? result.testCommandNote ? `test commands: allowed (informational [${result.testCommandNote}] \u2014 CI does not require a test here)` : "test commands: allowed" : `test commands: refused [${result.testCommandReasonId}] \u2014 resolved repo: ${result.root}; if that is not the repo under test, start the command with a literal Set-Location "<your worktree>"`;
         console.log(
           `tests policy: OK (${result.changedCount} changed file(s); ${result.matchedMandatoryCount} of ${result.mandatoryCount} mandatory glob(s) matched, ${result.protectedCount} protected file(s); ${commandVerdict}).`
         );
@@ -45050,8 +45219,7 @@ project.command("sync-info [owner/repo]").description("synchronize the owning Gi
     return failGraceful(e.message);
   }
 });
-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").addOption(new Option("--stage <stage>", "dev | rc | main").choices(["dev", "rc", "main"])).option("--json", "machine-readable output").action(async (repoOrSlug, o) => {
+async function runProjectDeployGet(repoOrSlug, o) {
   const cfg = await loadConfig();
   let target;
   try {
@@ -45065,7 +45233,9 @@ projectDeploy.command("get [owner/repo]").description("read nonsecret DEPLOY# fa
   if (stage && !["dev", "rc", "main"].includes(stage)) return fail("org project deploy get: --stage must be dev, rc, or main");
   const payload = stage ? { slug: out.slug, stage, deploy: out.stages[stage] ?? null } : out;
   console.log(JSON.stringify(payload));
-});
+}
+var projectDeploy = project.command("deploy").description("read nonsecret DEPLOY# facts (domain, port, deploy path, substrate, host presence)").argument("[ownerRepo]", "shorthand for `get <owner/repo>`").addOption(new Option("--stage <stage>", "dev | rc | main").choices(["dev", "rc", "main"])).option("--json", "machine-readable output").action(async (ownerRepo, o) => runProjectDeployGet(ownerRepo, 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) => runProjectDeployGet(repoOrSlug, o));
 projectDeploy.command("doctor").description("read-only estate scan for duplicate Hetzner (sshHost, port) DEPLOY# coordinates (#5431); master-only; never auto-reassigns ports").option("--json", "machine-readable output").action(async (o) => {
   const cfg = await loadConfig();
   const report = await fetchDeployPortCollisions(registryClientDeps(cfg));
@@ -45313,11 +45483,13 @@ oauth.command("plan", { isDefault: true }).description("print the canonical JS o
     oc = parseOauthConfig(meta ?? {}, slug);
   } catch (e) {
     const message2 = e.message;
+    const declareCommand = `mmi-cli oracle org project set ${o.repo ?? `mutmutco/${slug}`} --var 'oauth={"subdomains":["${defaultSubdomain(slug)}"],"callbackPath":"${DEFAULT_CALLBACK_PATH}"}'`;
     if (/^oauth is not configured for /.test(message2)) {
-      return failGraceful(
+      return failGracefulEnvelope(
         `org oauth plan: ${message2}. Declare it in the registry META first:
-  mmi-cli oracle org project set ${o.repo ?? `mutmutco/${slug}`} --var 'oauth={"subdomains":["${defaultSubdomain(slug)}"],"callbackPath":"${DEFAULT_CALLBACK_PATH}"}'
-  New repo? The GCP project and its Google Auth Platform consent screen must exist too \u2014 docs/Guides/oauth-provision.md \u2014 New repo.`
+  ${declareCommand}
+  New repo? The GCP project and its Google Auth Platform consent screen must exist too \u2014 docs/Guides/oauth-provision.md \u2014 New repo.`,
+        { code: ERROR_CODES.ERR_STATE_CONFLICT, corrected_command: declareCommand }
       );
     }
     return failGraceful(`org oauth plan: ${message2}`);
@@ -45704,6 +45876,14 @@ function resolveHouseShim(argv) {
     argv.splice(2, 1);
     return;
   }
+  if (actual && isDeclaredHouseAlias(houseToken, lookupPath)) {
+    process.stderr.write(
+      `mmi-cli: '${lookupPath}' lives in house '${actual}', not '${houseToken}' \u2014 routed to \`mmi-cli ${canonicalPathFor(lookupPath)}\`
+`
+    );
+    argv.splice(2, 1);
+    return;
+  }
   if (actual) {
     refuseHouseShim(
       lookupPath,
@@ -45732,6 +45912,7 @@ function printHouseRootHelp(house) {
   );
   consoleIo.log(lines2.join("\n"));
 }
+resolveVerbAliasShim(process.argv);
 resolveHouseShim(process.argv);
 program2.parseAsync(process.argv).then(() => finishCliRun()).catch((e) => failGraceful(e.message));
 // Annotate the CommonJS export names for ESM import in node:

package/package.json

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