@mutmutco/pi-plugin 4.1.20 → 4.2.1

package/package.json

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

package/scripts/pretooluse-shell-gates.mjs

@@ -11,7 +11,7 @@ import { decide as decideCommandLadder, matchedVerb } from './command-ladder-gat
 import { handleGateCrash, handleMissingHookInput, recordGateSuccess } from './deny-gate-crash.mjs';
 import { readHookInput } from './hook-io.mjs';
 import { appendHookActivity } from './hook-trace.mjs';
-import { evaluateTestCommandPolicy } from './test-command-policy-core.mjs';
+import { evaluateTestCommandPolicy, isShallowRepository, readOverride } from './test-command-policy-core.mjs';
 
 // Secret echoes are blocked before execution on every active host.
 const SECRET_ECHO_MODE = process.env.MMI_SECRET_ECHO_LINT || 'block';
@@ -369,7 +369,7 @@ function policyMandatoryEntries(root) {
   return parsed.mandatory;
 }
 
-function taskDiffPaths(root) {
+function taskDiffBase(root) {
   const base = ['origin/development', 'origin/main'].find((ref) => {
     try {
       git(root, ['rev-parse', '--verify', `${ref}^{commit}`]);
@@ -379,6 +379,11 @@ function taskDiffPaths(root) {
     }
   });
   if (!base) throw new Error('neither origin/development nor origin/main resolves');
+  return base;
+}
+
+function taskDiffPaths(root) {
+  const base = taskDiffBase(root);
   const outputs = [
     git(root, ['diff', '--name-only', `${base}...HEAD`]),
     git(root, ['diff', '--name-only', '--cached']),
@@ -388,6 +393,27 @@ function taskDiffPaths(root) {
   return [...new Set(outputs.flatMap((output) => output.split(/\r?\n/).map((path) => path.trim()).filter(Boolean)))];
 }
 
+/**
+ * The waiver the gate may honour for this diff's range, or null (#5804).
+ *
+ * `mmi-cli tests policy` honours a valid `Test-Policy-Override` trailer on the findings layer while
+ * this gate refused the same diff's focused test — one policy, two answers, and the agent that wrote
+ * the audited trailer to run ONE focused test was then blocked from running exactly that test. The
+ * reader is the SHARED one, so the gate cannot drift from the CLI's verdict on what a waiver is.
+ *
+ * Two fail-closed guards mirror what the CLI reports before it honours anything:
+ *  - a SHALLOW clone's `base..HEAD` is unbounded (#3628) — nothing is honoured from a range the gate
+ *    cannot trust;
+ *  - refusals newer than the winning trailer (malformed shape, unknown scope) block the CLI's run,
+ *    so they block here too — no honouring a waiver the reporting layer just refused.
+ */
+function taskOverride(root, baseRef) {
+  if (isShallowRepository(root)) return null;
+  const base = git(root, ['merge-base', 'HEAD', baseRef]).toString().trim();
+  const { override, refusals } = readOverride(base, root);
+  return refusals.length === 0 ? override : null;
+}
+
 function runTestCommandPolicy(input, { stdout = process.stdout } = {}) {
   if (!requestedTestCommand(input?.tool_input?.command)) return { denied: false };
   const root = repositoryRoot(input);
@@ -397,10 +423,14 @@ function runTestCommandPolicy(input, { stdout = process.stdout } = {}) {
     if (!root || (mandatory = policyMandatoryEntries(root)) === null) return { denied: false };
     // #5519: same evaluator `mmi-cli tests policy` attaches to its OK summary — matched globs and
     // command classes cannot disagree with the CLI on the same path set.
+    // #5804: and the same waiver, read from the same range this diff was computed against, feeds the
+    // evaluator — an honoured override for out-of-zone test work permits the matching focused test.
+    const base = taskDiffBase(root);
     const decision = evaluateTestCommandPolicy({
       paths: taskDiffPaths(root),
       mandatory,
       regulated: true,
+      override: taskOverride(root, base),
     });
     if (decision.testCommandsAllowed) return { denied: false, decision };
   } catch (error) {

package/scripts/test-command-policy-core.mjs

@@ -1,4 +1,5 @@
-// test-command-policy-core.mjs — shared verdict for "may this diff run tests?" (#5519).
+// test-command-policy-core.mjs — shared verdict for "may this diff run tests?" (#5519), and the
+// ONE `Test-Policy-Override` reader both surfaces share (#5804).
 //
 // `mmi-cli tests policy` and the PreToolUse test-command gate both answer that question. Before
 // #5519 they answered it separately: the CLI summary printed the repository's CONFIGURED mandatory
@@ -7,12 +8,49 @@
 // hit TEST-POLICY TEST COMMAND REFUSED on the next line. Delegated workers and the parent hook also
 // diverged when they did not share an evaluator.
 //
-// This module is the one evaluator. It reports matched globs separately from configured totals and
-// the exact allowed/refused command classes. Pure: no IO, no git.
+// #5804 reopened the same divergence along the waiver axis: the CLI honoured a valid override
+// trailer on the findings layer and printed OK, while the gate — fed the same diff without the
+// waiver — refused the matching focused test on the next line. So the reader lives HERE, next to
+// the verdict it feeds, and both surfaces pass the SAME honoured waiver into `evaluateTestCommandPolicy`.
+// The reader is the only git-IO in this module, and it is git's own trailer parser plus the exact
+// guards #3628/#3637 established — the hook must never grow a second, looser trailer parser.
+
+import { execFileSync } from 'node:child_process';
 
 /** Command class the PreToolUse gate regulates. Non-test verification is never refused here. */
 export const TEST_COMMAND_CLASS = 'test';
 
+/** The commit trailer that carries a waiver. Live here so the reader and every message built from
+ *  it spell the key identically. */
+export const TRAILER_KEY = 'Test-Policy-Override';
+/** NOT the authority on what is honoured — {@link readOverride} asks git for that. This is the
+ *  DISAGREEMENT detector: a line shaped like the trailer that git's parser does not report is the
+ *  defect worth surfacing, because it waives the gate while leaving the audit trail empty. */
+const OVERRIDE_RE = /^Test-Policy-Override:\s*(.+)$/im;
+/** Record and field separators for the one `git log` call that reads sha, trailer and body at once. */
+const REC = '\u001e';
+const FLD = '\u001f';
+
+/** The kinds a `Test-Policy-Override` trailer may waive — the diff rules and nothing else. The
+ *  three refusal kinds (unresolvable-base, untrusted-range, malformed-override-trailer) are
+ *  deliberately absent: a waiver read out of a range the gate cannot trust would be the original
+ *  defect wearing the fix's clothes. */
+export const WAIVABLE_KINDS = [
+  'mandatory-zone-untested',
+  'unrequested-test-file',
+  'protected-removed',
+  'stale-protected-entry',
+  'stale-satisfied-by',
+];
+
+/** The one waivable kind whose finding is a VERDICT ON OUT-OF-ZONE TEST WORK ITSELF (#5804). Rule 1
+ *  always co-occurs with a matched glob (test commands already allowed there), and the deletion and
+ *  staleness kinds speak to policy hygiene, not to running tests — waiving them buys the deletion,
+ *  never the command class. `unrequested-test-file` is different: its finding says exactly what the
+ *  command gate refuses, "this test work was never asked for". A waiver over it IS the human's
+ *  "this test is requested" decision, so it — and only it — authorizes the `test` class. */
+const TEST_WORK_KIND = 'unrequested-test-file';
+
 /**
  * Glob body → regex body. Supports `**`, `*`, and `{a,b}` (including wildcards inside braces).
  * Kept byte-compatible with {@link globToRegExp} in cli/src/test-policy-core.ts so rule matching
@@ -66,13 +104,19 @@ export function matchedMandatoryGlobs(paths, mandatory) {
 }
 
 /**
- * Decide whether test commands are allowed against a path set and a mandatory zone.
+ * Decide whether test commands are allowed against a path set, a mandatory zone, and the waiver the
+ * caller has already read for this range (#5804).
  *
- * @param {{ paths: string[], mandatory?: unknown, regulated?: boolean }} input
+ * @param {{ paths: string[], mandatory?: unknown, regulated?: boolean,
+ *            override?: { kinds?: string[] } | null }} input
  *   `regulated: false` — no test-policy.json (estate default); tests are not gated.
  *   `regulated: true` (default) — a declared policy applies; zero matched globs refuses `test`.
+ *   `override` — the waiver honoured for this range, as {@link readOverride} returned it, or null.
+ *   A waiver whose kinds cover {@link TEST_WORK_KIND} authorizes the `test` class even with zero
+ *   matched globs: reporting and enforcement then state ONE decision, because both feed this
+ *   function the same receipt.
  */
-export function evaluateTestCommandPolicy({ paths, mandatory, regulated = true } = {}) {
+export function evaluateTestCommandPolicy({ paths, mandatory, regulated = true, override = null } = {}) {
   const configuredMandatoryCount = mandatoryGlobList(mandatory).length;
   if (!regulated) {
     return {
@@ -85,7 +129,8 @@ export function evaluateTestCommandPolicy({ paths, mandatory, regulated = true }
     };
   }
   const matched = matchedMandatoryGlobs(paths, mandatory);
-  const testCommandsAllowed = matched.length > 0;
+  const overrideAuthorizes = Array.isArray(override?.kinds) && override.kinds.includes(TEST_WORK_KIND);
+  const testCommandsAllowed = matched.length > 0 || overrideAuthorizes;
   return {
     configuredMandatoryCount,
     matchedMandatoryGlobs: matched,
@@ -98,3 +143,111 @@ export function evaluateTestCommandPolicy({ paths, mandatory, regulated = true }
     },
   };
 }
+
+function git(args, cwd) {
+  return execFileSync('git', args, { windowsHide: true, cwd, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
+}
+
+/** Split an optional `[kind, kind]` scope off the front of a trailer value. */
+function parseScope(value) {
+  const scoped = /^\[([^\]]*)\]\s*([\s\S]*)$/.exec(value);
+  if (!scoped) return { kinds: [...WAIVABLE_KINDS], reason: value, unknown: [] };
+  const named = scoped[1].split(',').map((k) => k.trim()).filter(Boolean);
+  return {
+    kinds: named,
+    reason: scoped[2].trim(),
+    unknown: named.filter((k) => !WAIVABLE_KINDS.includes(k)),
+  };
+}
+
+function invisibleTrailer(sha, line) {
+  return {
+    kind: 'malformed-override-trailer',
+    paths: [],
+    detail:
+      `OVERRIDE TRAILER GIT CANNOT SEE — commit ${sha.slice(0, 8)} carries\n`
+      + `    ${line}\n`
+      + `  but \`git log --format='%(trailers:key=${TRAILER_KEY})'\` reports nothing for it, so the waiver would\n`
+      + '  exist only to the regex that granted it. The trailer was chosen over a flag because it can be\n'
+      + '  AUDITED, and a reason the auditor cannot see is not a reason this gate accepts (#3628).\n'
+      + '  Git reads trailers from the LAST paragraph only, and every line of that paragraph must be a\n'
+      + '  trailer or an indented continuation — one bare line such as `Closes #123` disqualifies the whole\n'
+      + '  block. Indent the continuation lines, and leave nothing but trailers in that paragraph.\n'
+      + '  This is fixable forward: push a LATER commit on this branch carrying a well-formed trailer.\n'
+      + '  The nearest waiver wins, and it supersedes this one — no force-push, no re-filed branch.',
+  };
+}
+
+function unknownScope(sha, unknown) {
+  return {
+    kind: 'malformed-override-trailer',
+    paths: [],
+    detail:
+      `UNKNOWN OVERRIDE SCOPE — commit ${sha.slice(0, 8)} scopes its waiver to ${unknown.join(', ')}, which this\n`
+      + '  gate cannot report.\n'
+      + `  Waivable kinds: ${WAIVABLE_KINDS.join(', ')}.\n`
+      + '  Refused rather than widened: treating a typo as "waive everything" is how a scoped waiver turns\n'
+      + '  into a blanket exemption without anyone deciding it should.',
+  };
+}
+
+/**
+ * Whether this clone's history is grafted. Anything other than a plain `false` — including a git that
+ * cannot answer — counts as shallow: the question being asked is "may I trust a commit range", and
+ * "I could not tell" is not a yes.
+ */
+export function isShallowRepository(cwd) {
+  try {
+    return git(['rev-parse', '--is-shallow-repository'], cwd).trim() !== 'false';
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Read the waiver out of `base..HEAD` with GIT's own trailer parser, and refuse the disagreements.
+ *
+ * The regex is kept, but demoted to a cross-check: what it sees and what git sees must be the same
+ * set, and where they differ the difference IS the finding. On Jerv-PowerTools@e3d4b8ba the regex
+ * granted a waiver git reported no trailer for, and stored the first line of it — `"src/commands/
+ * grind.ts is outside test-policy.json's"` — as the justification, argument discarded.
+ *
+ * Moved here from cli/src/test-policy-core.ts (#5804) so the PreToolUse gate reads the SAME waiver
+ * the CLI reports — git's parser, the folded-whole value, the sha, the `[kind]` scoping, and the
+ * nearest-waiver-wins precedence — rather than a parallel line regex that would reintroduce the
+ * #3628 class on the execution side.
+ *
+ * @param {string} base merge-base of the change set; the waiver is read from `base..HEAD` only
+ * @param {string} cwd repository root the git commands run in
+ * @returns {{ override: { sha: string, reason: string, kinds: string[] } | null,
+ *             refusals: Array<{ kind: string, detail: string, paths: string[] }> }}
+ *   A non-empty `refusals` lists override-shaped problems from commits NEWER than the winning
+ *   waiver; the caller must treat the run as refused, never honour `override` past them.
+ */
+export function readOverride(base, cwd) {
+  const format = `%H${FLD}%(trailers:key=${TRAILER_KEY},valueonly,unfold)${FLD}%B${REC}`;
+  const refusals = [];
+  let override = null;
+  for (const record of git(['log', `${base}..HEAD`, `--format=${format}`], cwd).split(REC)) {
+    const [sha, trailer, body] = record.replace(/^\s+/, '').split(FLD);
+    if (!sha) continue;
+    // git log is newest-first, so the nearest waiver wins — as it always did — and once one is held
+    // every remaining record is OLDER than it and cannot change the answer. Stopping here is what
+    // gives a malformed trailer a forward-only remedy (#3637): the disagreement check below used to
+    // sit above this line, so an unparseable trailer refused the PR forever while the honoured waiver
+    // came from a commit after it. Rewriting that commit needs a force-push this estate does not do,
+    // which left re-filing the whole branch as the only exit. Precedence already applied to values;
+    // it now applies to the refusals read out of the same range.
+    if (override) break;
+    const value = (trailer ?? '').trim();
+    if (!value) {
+      const shaped = OVERRIDE_RE.exec(body ?? '');
+      if (shaped) refusals.push(invisibleTrailer(sha, shaped[0].trim()));
+      continue;
+    }
+    const { kinds, reason, unknown } = parseScope(value);
+    if (unknown.length > 0) refusals.push(unknownScope(sha, unknown));
+    else override = { sha, reason, kinds };
+  }
+  return { override, refusals };
+}

package/skills/bootstrap/SKILL.md

@@ -429,9 +429,10 @@ collaborator list + the per-branch allowlist are the record — no separate rost
   central workflows, so `MMI_APP_ID` / `MMI_APP_PRIVATE_KEY` live only on the Hub — a product repo seeds no
   App var/secret.
 - **Issue templates** — seed `.github/ISSUE_TEMPLATE/` (Bug · Feature · Task + `config.yml`).
-- **Merge settings (org canon)** — every repo: auto-merge on, squash on, delete-branch-on-merge on, so a
-  green allowlisted PR can land itself and never leaves a dead branch:
-  `gh api -X PATCH repos/$OWNER/$REPO -f allow_auto_merge=true -f allow_squash_merge=true -f delete_branch_on_merge=true`
+- **Merge settings (org canon)** — every repo: auto-merge on, squash on, automatic merged-branch deletion
+  off. A merged remote branch survives until delayed cleanup proves no open PR still uses it as a base
+  (#5789); deleting it at merge can irreversibly close stacked PRs:
+  `gh api -X PATCH repos/$OWNER/$REPO -f allow_auto_merge=true -f allow_squash_merge=true -F delete_branch_on_merge=false`
 - **Cursor environment** — `.cursor/environment.json` is retired org-wide (#2501): it caused Cursor to
   auto-spawn cloud agents nobody asked for. Bootstrap no longer seeds it and no
   repo should carry a tracked copy.

package/skills/mmi/SKILL.md

@@ -300,6 +300,15 @@ mmi-cli oracle issue view <N> --repo <owner/repo> --comments   # body + every co
 >
 > Never truncate at the last `}`; trailing prose can contain braces, and malformed/incomplete JSON must fail closed.
 
+> **Never capture board JSON with a shell redirect on Windows** (#5802). PowerShell 5.1's `> file.json` is
+> `Out-File`, which writes **UTF-16LE with a BOM**, so the file starts `FF FE` and the next step —
+> `readFileSync(path, 'utf8')` + `JSON.parse` — dies at position 1. Pass `--out <path>` instead: the CLI
+> writes the file itself as UTF-8 with no BOM, so the bytes never reach the shell.
+>
+> ```bash
+> mmi-cli oracle board read --json --out .jerv/tmp/board.json   # UTF-8, parses everywhere
+> ```
+
 (Triggers only when a dev commits to an existing item — no-op for the *report a bug / request a feature /
 something else* paths.)
 

package/skills/release/SKILL.md

@@ -191,8 +191,9 @@ before any branch/tag mutation (#5666).** They read the repo's expected CI npm f
 (when the infra gate's exact node pin maps to a bundled npm, e.g. node 24.19.0 → npm 11.17.0) or, when
 gate.yml only declares a floating node major with no bundled npm, from the publish workflow's explicit npm pin
 (e.g. `npx --yes npm@11.17.0 pack` in `publish.yml`). Local `npm -v` must match that npm **major**; a
-mismatch refuses `--apply` with an align-local-npm remedy — the same class of failure the fold-failure notes
-below describe, but caught before a wasted apply.
+mismatch refuses `--apply` before any repository write. The receipt gives the supported npm-only repair
+(`npm install -g npm@<exact CI version>`), the `node -v && npm -v` verification, and tells you to rerun the
+same release command. This preserves Node and avoids routing a machine-global mutation through the train.
 
 **A local `npm ci` failure during the fold on a lockfile CI already accepted is an npm-major mismatch, not a
 bad lockfile (#4578).** Before touching the lockfile, compare toolchains:
@@ -277,7 +278,8 @@ secret from a transport-error response.
 The train dispatches `actions-job-start-canary.yml` on MMI-Hub (Linux hosted, not `windows-latest`) and
 refuses to mint a tag if the canary job never starts (empty steps / billing refusal). If a tag is already
 on origin, do **not** recut: `mmi-cli devops release --retry-publish <run-id> --apply` retries that exact
-run.
+failed or cancelled run. A failed run retries failed jobs; a cancelled run reruns the whole idempotent
+publish workflow because GitHub does not classify cancelled jobs as failed (#5797).
 
 ## Step 0c — hotfix-coverage guard (fail closed, #839, #958)
 
@@ -624,8 +626,9 @@ mmi-cli oracle org project sync-info --apply   # omit --apply for the read-only
   - `checkout restoration failed while returning to …` / `origin/<branch> fast-forward failed` — the
     checkout or the pull errored. Read the appended git message; the release is unaffected.
 
-  `--resume` prints no `checkout:` clause at all, so after a resumed release check `git branch
-  --show-current` rather than assuming you were moved back.
+  `--resume` uses the same `checkout:` clause after every branch-mutating terminal path. Direct-track
+  resumes return to `development`; full-track resumes return to `rc`. A skipped restoration names the
+  dirty tree, checkout failure, or fast-forward failure and still leaves the shipped release intact.
 
 ## Step 6 — collect deploy verdict + report