@mutmutco/claude-plugin 4.0.15 → 4.0.17

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mmi",
   "displayName": "MMI",
-  "version": "4.0.15",
+  "version": "4.0.17",
   "mmiCompat": "4.x",
   "description": "MMI workflow skills and org gates delivery.",
   "author": {

package/package.json

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

package/skills/release/SKILL.md

@@ -38,6 +38,9 @@ nothing deploys before the protected `main` push accepts that checked SHA.
   branch's lineage and every tag-anchored check (coverage trailers, misalignment guard, version probes)
   re-flags or mis-reads forever after. Any merge that carries an already-tagged commit — the Step 5
   `main → development` roll-forward, any alignment PR — lands as a **true merge** (`--merge`), never squash.
+  `--wait` does not relax this: use `mmi-cli devops pr merge <n> --wait --merge` (or the policy-gated
+  `--auto --merge`). `--wait` alone still defaults the CLI merge method to squash and must not land an
+  alignment / tagged-commit-carrying PR.
 - **A refused train is a stop, never a license to finish by hand.** Every fail-closed halt below — authority
   probe, coverage guard, untolerated conflict, required checks, stray tag — ends the run. The recovery is
   always to fix the cause and re-run the train; it is never hand-resolving on `main`, bare-pushing a train
@@ -45,6 +48,12 @@ nothing deploys before the protected `main` push accepts that checked SHA.
 - **Version probes anchor on the latest Release tag, not a branch.** `next-version.mjs` and the fold derive
   the next version from tags; a branch manifest or a stale local tag is not a version source. (This is why a
   stray tag must be deleted locally too — a surviving local tag silently mints the *next* version, Step 3.)
+- **One `/release` at a time on a repo (#5380).** Two overlapping `--apply` runs race the shared tag namespace:
+  the slower train can tag a SHA that never got a fold commit, while the other sees that tag mid-flight and
+  mints the *next* version (a skip). Publish then fails verify (`root package and lockfile versions must
+  equal …`) and the broken GitHub Release can briefly hold **Latest**. `mmi-cli devops release --apply`
+  fail-closes post-fold / pre-tag when the computed tag (or a newer release tag) appears on origin since
+  the plan-phase probe — stop, do not hand-finish, do not start a second train. Recovery is below (Step 3).
 
 ## Step 0 — confirm + probe
 
@@ -181,6 +190,17 @@ not a lockfile failure (#4982).** Rename `node_modules` aside once into a gitign
 the identical train command. `npm ci` extracts into the now-empty tree and performs no unlinks; do not retry
 this workaround repeatedly.
 
+**A fold failure outside `npm ci` is often the repo's own npm lifecycle script, not a toolchain or lockfile
+problem (#5365).** App-style folds run `npm version`, which fires `preversion` / `version` / `postversion`
+(e.g. sync-workspace-version + refresh-distribution-bom); Hub folds run `release-distribution.mjs prepare`,
+which likewise executes repo scripts. When those fail, the train surfaces only
+`fold failed; local main was reset` — the real error is one layer down. Open the newest npm debug log
+(path printed by npm, typically under the npm cache `_logs/`) and read the verbose title / argv: if it
+names `npm version …` (or another non-`ci` command) and a `runScript` / lifecycle command failed, run that
+script standalone (e.g. `node scripts/refresh-distribution-bom.mjs`) to get the real error in seconds.
+Do this **before** suspecting npm major (#4578), cold cache (#4841), EPERM/EBUSY (#4982), or regenerating
+the lockfile — those classes apply to install failures, not to a script that already had `node_modules`.
+
 **Then check the version yourself — do not rely on doctor having printed a row (#3674).** "Read the rows"
 resolves to "proceed" when the row is *absent*, and doctor's version row is conditional. On 2026-07-27 this
 step reported healthy with no version line while the installed CLI was 3.70.0 against a released 3.71.0;
@@ -277,7 +297,8 @@ why (a hotfix freezes a snapshot that `development` can keep rewriting).
 Alignment PRs are the exception to the org's squash default: land them with a true merge —
 `mmi-cli devops pr merge <n> --auto --merge` (not squash; a squash discards the merge parentage, so the
 misalignment guard re-flags the same divergence on the next run). `--auto` clears the checks the PR
-triggers, which block an immediate merge right after a release.
+triggers, which block an immediate merge right after a release. When awaiting checks inline, keep
+`--merge`: `mmi-cli devops pr merge <n> --wait --merge` — `--wait` alone is not enough (merge floor above).
 
 **Exception — version-manifest and `.gitignore` paths.** `mmi-cli devops release --apply` tolerates
 conflicts confined to the version-fold paths (Step 1b) and `.gitignore` (#1037 — a
@@ -309,6 +330,10 @@ What the fold bumps, by repo:
 
 Nothing to do by hand; the `--apply` result reports the fold outcome (`versionFold`).
 
+When the fold fails here, classify with Step 0a's fold-failure notes before retrying or touching the
+lockfile. If the failure is outside `npm ci`, read the npm debug log's verbose title/argv and run the
+named lifecycle script standalone (#5365) — do not stop at `fold failed; local main was reset`.
+
 ## Step 2 — tag the release
 
 Full-track repos drop the `-rc.N` suffix from the open cycle. Direct-track repos use the next cycle directly
@@ -381,6 +406,16 @@ delete — mint the next version with `MMI_RELEASE_VERSION` instead. The CLI alr
 (`isStrayUnreleasedTag`, `cli/src/train-apply.ts`); this note surfaces the doctrine so a halted operator does
 not re-derive it from source.
 
+**Halted by a concurrent-train refusal, or a publish verify that says package/lockfile versions ≠ the tag
+(#5380)?** Same deletion class as a stray tag, plus the GitHub Release if one was created (it may still show
+as **Latest** while broken). Evidence shape: two tags one patch apart from overlapping `/release` runs (e.g.
+`v3.1.11` on a no-fold SHA + `v3.1.12` minted because that tag landed mid-flight), and verify text like
+`root package and lockfile versions must equal 3.1.11`. Do **not** leave the skip-version tag and continue —
+with the authorized human's go: delete the broken Release (`gh release delete vX.Y.Z --yes`), delete the
+stray tag locally and on origin, confirm `next-version` would re-derive the *same* version (not the skip),
+then re-run a **single** `mmi-cli devops release --apply`. If the newer skip-version already published
+cleanly, keep it and only remove the broken older Release/tag.
+
 ## Step 4 — GitHub Release + start prod deploy (non-blocking)
 
 For `tenant-container` repos, publish the GitHub Release and dispatch the central tenant deploy.
@@ -498,7 +533,8 @@ mmi-cli oracle org project sync-info --apply   # omit --apply for the read-only
   PR with a true merge** — `mmi-cli devops pr merge <number> --auto --merge` (never squash — a squash drops the merge
   parentage and the misalignment guard re-flags the divergence). `--auto` is what makes it land right after a
   release: the alignment PR's own `cli`/`infra`/`docs` checks are still running, so a plain immediate merge is
-  policy-blocked — `--auto` merges once they pass. Never force.
+  policy-blocked — `--auto` merges once they pass. If you await with `--wait` instead, still pass `--merge`
+  (`mmi-cli devops pr merge <number> --wait --merge`); `--wait` alone must not land the alignment PR. Never force.
 - Full-track repos: `mmi-cli devops release --apply` already aligned `rc` to the released `main` (#1036 — the
   push runs inside the authority-gated train; the result reports it as `rcAlignment`). No manual `rc`
   push — if the result reports a failed alignment, investigate and rerun via the train, never bare-push.
@@ -551,15 +587,36 @@ don't publish by hand.
 Watch it, then confirm npm caught up:
 ```bash
 gh run watch "$(gh run list --workflow publish.yml --event release --limit 1 --json databaseId -q '.[0].databaseId')" --exit-status
-node scripts/release-distribution.mjs verify "vX.Y.0"   # asserts registry versions, BOM identities, and published npm artifacts
+node scripts/release-distribution.mjs verify "X.Y.0"   # bare semver — asserts registry versions, BOM identities, and published npm artifacts
 ```
+**verify takes bare semver (#5379).** Pass `X.Y.Z`, not the git-tag form `vX.Y.Z`. Checkout still
+uses the tag (`git checkout "vX.Y.0"`); the distribution script's version argument is strict semver
+without a leading `v`.
 Run that verify from a checkout **at the tag** (`main` right after the release merge, `git checkout
 "vX.Y.0"`, or a worktree at the tag) — verify checks the working tree and refuses any other commit once
 the tag exists, so a stale `development`/`rc` checkout can't masquerade as a broken release.
 Release-blocking for Hub tooling changes: every public artifact must match the registry version and BOM
-identity. Manual fallback if CI can't publish: `node scripts/release-distribution.mjs publish "vX.Y.0"`
+identity. Manual fallback if CI can't publish: `node scripts/release-distribution.mjs publish "X.Y.0"`
 from a machine with npm auth.
 
+**npm tarball identity is packer-sensitive (#5366 / #5251).** `verify` without `--skip-npm-view`
+compares the registry's served `dist.integrity` (SSRI) against a live `npm pack` on THIS machine
+(`packedIntegrityBySurface`). A tarball SSRI covers file modes and packer (npm version) behavior, so
+that identity step is authoritative **only** when run in the publish environment (`publish.yml` on the
+self-hosted Linux runner) — or on an operator machine with the **same OS and npm major** as that
+runner. Elsewhere (Windows, a clean Linux container with a different packer, a mismatched npm major) a
+`tarball identity mismatch` can false-fail even when the published bytes match the tag: three different
+SSRIs (registry / Windows pack / container pack) with content-identical unpacked trees is the expected
+cross-environment shape, not a substituted artifact. Off the publish environment, either:
+- fall back to an **unpacked-content** proof — download the registry tarball (`npm pack <pkg>@X.Y.Z`
+  from the registry, or `npm view … dist.tarball`), `npm pack` from the tag checkout, unpack both, and
+  `diff -r` the trees (empty diff ⇒ identity OK; do not alarm on SSRI alone), or
+- skip the registry identity read with
+  `node scripts/release-distribution.mjs verify "X.Y.0" --skip-npm-view` and verify published content
+  by hand the same way.
+Do not treat an off-runner SSRI mismatch as a broken release, and do not change how the runner publishes
+to paper over a local packer difference.
+
 **Private packages (#2405) — never trust a bare `npm view` to mean "not published".** An unauthenticated
 `npm view <pkg>` returns a hard 404 on any package published with `publishConfig.access=restricted`
 (private) — indistinguishable from "not published" — because npm masks private packages from anonymous

package/skills/stage/SKILL.md

@@ -33,6 +33,15 @@ into the compose **process environment** — the compose file reads them via `en
 secret ever touches disk. A repo that still ships `.env.example` keeps the legacy `.env` bootstrap for
 back-compat until its compose migrates to passthrough; new repos should ship **no** `.env.example`.
 
+**Build-time secrets (#5381).** When META declares `requiredBuildSecrets` (e.g. Katip's
+`NODE_AUTH_TOKEN=@github-packages-token` for `@mutmutco/fofu-ds` on GitHub Packages), `/stage` injects those
+BuildKit ids into the **`docker compose build`** process env only — not into the running container. Central
+deploy mints the packages sentinel from Actions `GITHUB_TOKEN`; a laptop cannot. Resolution order: existing
+process env → stageless project vault secret under the BuildKit id (a `read:packages` PAT at
+`NODE_AUTH_TOKEN`). If both are missing, `/stage` fails with a teaching error before npm's opaque 401.
+Setup: [`docs/Guides/tenant-runtime.md`](../../docs/Guides/tenant-runtime.md) § Local `/stage`. Never commit
+or print the PAT.
+
 ## Step 0 — inspect the plan
 
 ```bash