@mutmutco/pi-plugin 4.2.5 → 4.2.7

package/package.json

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

package/skills/bootstrap/seeds/gate.template.yml

@@ -97,10 +97,14 @@ jobs:
       # cache policy is declared on runner-node-toolchain (cache + cache-restore-max-mb). Per-job
       # NPM_CONFIG_CACHE above is the org default; unbounded Actions cache blobs can exhaust mmi-live
       # disks mid-extract before the real check runs (Jerv-Hub SQLCipher gate, ~4.3GB restore).
+      # MMI-Hub#5871: declare the npm MAJOR rather than inheriting whatever the runner's node bundles.
+      # A bare major, never an exact patch (it goes stale and then prescribes downgrading operator
+      # hosts toward it, #5862) and never `latest` (it takes the next major silently, #4782).
       - if: ${{ '{{GATE_RUNTIME}}' == 'node' }}
         uses: mutmutco/MMI-Hub/.github/actions/runner-node-toolchain@{{GATE_RUNNER_SHA}}
         with:
           node-version: 24
+          npm-version: '12'
       - if: ${{ '{{GATE_RUNTIME}}' == 'python' }}
         uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with: { python-version: '{{GATE_PY_VERSION}}' }

package/skills/release/SKILL.md

@@ -187,13 +187,49 @@ Treating doctor's exit code as the gate halts a healthy train on cosmetic drift
 operator to ignore doctor's exit code entirely.
 
 **`mmi-cli devops release --apply` and `mmi-cli devops rcand --apply` now run an active npm-major preflight
-before any branch/tag mutation (#5666).** They read the repo's expected CI npm from `.github/workflows/gate.yml`
-(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` 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.
+before any branch/tag mutation (#5666).** They read the repo's expected CI npm, in this order (#5866,
+#5893): an explicit `npm-version:` on the gate's `runner-node-toolchain` step; else an explicit
+`npm install -g npm@<major>` step in gate.yml; else the infra gate's exact node pin through the
+bundled-npm map (only for an estate that still carries a retired pre-#5870 pin); else the publish
+workflow's own npm pin (`npm install -g npm@12`, the #5870 retirement shape). Local `npm -v`
+must match that npm **major**; a
+mismatch refuses `--apply` before any repository write.
+
+**Both gate shapes are a declaration; only a gate that declares NEITHER falls through (#5893).** A lane
+that installs its own npm has stated its npm as plainly as an `npm-version:` input — the shape differs, the
+intent does not. Reading only `npm-version:` skipped Jerv-JervCode's gate (floating `node-version: 24`
+plus `npm install -g npm@12`), fell through to publish.yml's stale npm 11, and prescribed a downgrade the
+repo had already retired (#2845, MMI-Hub#5871); the publish smoke then failed under npm 11 (`Cannot find
+module jiti/package.json` — a packed global install materializes no dependency closure under npm 11 once
+the root declares `bundleDependencies`), shipping v1.57.7 to main with a Release but no npm publish.
+**When gate.yml and publish.yml disagree on the npm major, that is a repo defect** — one lane will run the
+wrong toolchain whichever the preflight believes. The preflight names it and proceeds; fix it with a PR
+moving both pins together, never by silently trusting publish.yml.
+
+**Check which side is wrong before repairing (#5862).** The receipt names one direction — move the machine
+to the pin — and that is only right when the pin is current. Compare it against the registry first:
+
+```bash
+npm view npm version      # what npm is actually at
+```
+
+A pin **behind** latest is fixed by a PR moving the pin, not by a machine-global downgrade that every
+release host then inherits. The pin is coordinated, so move all of it together: on Jerv-Hub the same
+version lives in `publish.yml`, `DISTRIBUTION_NPM_VERSION`, `package.json` `packageManager`, and a
+workflow-contract test. Prefer declaring a bare **major** (`npm@12`) over an exact patch — an exact pin
+goes stale and then prescribes downgrades, and `latest` silently takes the next major.
+
+**Bumping the pin can break workflow code that reads npm output (#5862).** `npm pack --json` changed shape
+between majors (npm ≤10 a top-level array, npm ≥11 a name-keyed object) and npm 12 prints the `prepare`
+lifecycle script's stdout ahead of the document, so `JSON.parse(stdout)` throws. An inline
+`const [entry] = JSON.parse(pack.json)` in a workflow step is the hazard — on Jerv-Hub it failed **after**
+`npm publish` had already succeeded, leaving the GitHub Release assets and the Gateway deploy undone. Repo
+scripts that already tolerate both shapes (`scripts/distribution-assembly.mjs`, #4741) are the fix; audit
+inline workflow parsing before bumping.
+
+When the machine genuinely is the wrong side, the receipt's repair (`npm install -g npm@<CI major>`, then
+`node -v && npm -v`, then rerun the same release command) 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:
@@ -201,7 +237,8 @@ bad lockfile (#4578).** Before touching the lockfile, compare toolchains:
 npm -v
 gh api repos/{owner}/{repo}/actions/runs --jq '.workflow_runs[0].id'   # or read the gate log's
 # `node -v && npm -v` toolchain-preflight line (#3446) for the npm major CI ran with
-# When gate.yml has no bundled npm pin, read the publish workflow npm pin instead (#5666).
+# Read the gate's OWN declared npm first — `npm-version:` or `npm install -g npm@X` (#5893);
+# only a gate that declares neither falls back to the publish workflow npm pin (#5666).
 ```
 A different npm MAJOR (e.g. local 12 vs. CI's 11) resolves the same lockfile differently and throws `Missing:
 <pkg> from lock file` on a lockfile that is not actually broken. Align the local npm major
@@ -214,10 +251,11 @@ BEFORE inspecting package contents (deleted dir, malformed `package.json`, missi
 ```bash
 npm -v
 # green gate npm from the gate log's `node -v && npm -v` toolchain-preflight line (#3446),
-# the exact node pin in `.github/workflows/gate.yml` (Hub infra gate: node 24.19.0 → npm 11.17.0),
-# or the publish workflow npm pin when gate.yml has no bundled npm (#5666)
+# the gate's declared `npm-version:` or its `npm install -g npm@X` step (#5893), or an exact
+# node pin that maps to a bundled npm, or the publish workflow npm pin when the gate declares
+# no npm of its own (#5666)
 ```
-When local npm differs from the green gate (e.g. local npm 12 vs CI's 11.17.0), align local npm
+When local npm differs from the green gate (e.g. local npm 11 vs CI's 12), align local npm
 (`npm install -g npm@<gate npm>`) and rerun the train — do not rewrite the publish surface for an
 npm-internal missing module.
 
@@ -539,6 +577,20 @@ The one remaining caveat: `--watch` blocks only on deploy-model-named runs, not
 deploys — those you conclude from the `workflowRuns` list yourself. Any `failure` there is a failed release
 deploy even when the train reported success — flag it loudly and fix it before calling the release healthy.
 
+**Identify WHICH run is red before believing the wording (#5872).** The release pushes the tag and the
+branch seconds apart, so an ordinary repo CI gate lands on the release SHA too — it is enumerated
+alongside the deploy and publish runs, and a red one reads out as
+`deploy/publish on the release SHA FAILED`. On Jerv-Hub v3.4.4 that sentence appeared while `publish.yml`
+was green and npm was already serving 3.4.4: the red entry was a `gate` push run that had raced the
+shared runner's npm cache (the same SHA's tag-push gate passed, and a re-run passed). A red build gate
+**holds the release unverified but is not a publish failure** — and on Jerv-Hub it defers the fail-closed
+Gateway phase (#5699) until the gate is green, so it must be re-run and the release resumed, not
+re-tagged. Read the run NAMES in `workflowRuns` first:
+
+- `deploy.yml` / `publish.yml` / `tenant-deploy.yml` / `jerv-gateway` — a real deploy or publish verdict.
+- `gate` (or any repo CI workflow) on a `push` event — ordinary CI that happens to share the SHA. Re-run
+  it; nothing about the published artifact is in question.
+
 **Hub releases announce to Slack (#883).** Hub scope is **only** `mutmutco/MMI-Hub`: the commits/PRs on
 `origin/main..origin/development`, this repo's `deploy.yml` + `publish.yml`, and Hub tooling (`mmi-cli`,
 skills, plugin, registry, central workflows). Do **not** read another repo's board (`mmi-cli oracle board` / `/mmi`
@@ -655,6 +707,14 @@ Collect the backgrounded prod-deploy watch from Step 4 (it has typically finishe
 healthy (the central deploy workflow smoke step / a health check); **red** → report the failure prominently and flag
 that the release shipped on a failed deploy (re-run just the deploy — `main` is already correct).
 
+**Say which run is red, never just "deploy/publish failed" (#5872).** `--resume` reports a single
+`deployStatus` for every run on the release SHA, so a flaky repo CI gate that shares that SHA is reported
+in the language of a failed publication — the operator is told publication failed while npm is serving
+the version. Before writing that into a report, name the workflow: a red `deploy.yml` / `publish.yml` /
+`tenant-deploy.yml` / `jerv-gateway` is a real deploy or publish failure; a red `gate` on a `push` event
+is ordinary CI. Both hold the release unverified and both are fixed by re-running that run and resuming —
+neither is ever fixed by re-tagging — but only the first means anything about the artifact.
+
 **This distribution verifier is Hub-only.** It assumes the Hub release fold has already committed its
 generated artifacts. Non-Hub `registry-publish` repositories must not run `release-distribution.mjs
 verify`: use their own release-workflow evidence and the publish-visibility contract below.