@mutmutco/codex-plugin 3.131.0

package/skills/release/SKILL.md

@@ -0,0 +1,599 @@
+---
+name: release
+description: Ship rc or direct-track development to main and production.
+---
+
+**Host-native invocation:** Claude `/mmi:release` · Codex `$mmi:release` · jervcode/Kimi `/skill:release` · Kilo `skill` tool. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
+
+**Argument (#4929):** `/release minor`, `/release major`, or `/release patch` — a bare bump word, never a
+`--flag` or env var. Map it to `MMI_BUMP_INTENT` exported for the whole run (the train and
+`next-version.mjs` both read it). No argument → `patch`: a `/release patch` from development is a
+legitimate ordinary release; `/hotfix` remains the cherry-pick promotion lane.
+
+# /release — ship to main + prod
+
+Full-track repos ship **exactly what is on `rc`** (never pulls `development`): merge `rc → main`, tag
+`vX.Y.0`, publish a GitHub Release, dispatch the Hub central tenant deploy workflow for prod, then roll
+`development` forward. Direct-track repos — product repos with `releaseTrack: direct`, plus MMI-Hub via the `isHubControlRepo` special-case (its `releaseTrack` stays unset) — skip rc: release
+merges `development → main`, tags, publishes the GitHub Release, and the release event fires the repo's own
+deploy/publish workflow (for MMI-Hub, `deploy.yml` + `publish.yml`).
+`rc` is **ephemeral**: `/rcand` creates the rc runtime, `/release` retires it — after a confirmed full-track
+prod deploy the train stops the rc stage (reported as `rcRetirement` in the result; never fatal to the
+release). Full-track repos may also pass **`--dev`** to release `development → main` directly, skipping rc —
+the default stays `rc → main`. `--dev` **fails closed** when `origin/rc` carries content not yet in
+`development` (a dev → main release would drop it), and is a friendly no-op on direct-track repos.
+**Train-authority gated (D14):** the repo's project-admin or the master; the Hub repo's train is
+master-only. This is the **only** sanctioned prod path; a prod release still needs the authorized human's
+explicit per-turn go — an agent never self-initiates it. The board needs no
+touch — items reached `Done` when their PRs merged to `development`; `rc`/`main` are deploy stages, not lanes.
+
+Authority is structural + server-checked: step 0 asks the Hub (`mmi-cli oracle org access role`), and step 3 pushes
+to the protected `main` branch, whose per-repo allowlist carries the same people (master + that repo's
+project-admins; Hub: master + App only). Gate ordering: the tag lands the release SHA for checks, and
+nothing deploys before the protected `main` push accepts that checked SHA.
+
+## Merge floor (#3167 — non-negotiable, applies to every step below)
+
+- **Never squash-merge a tagged commit.** A squash re-mints the SHA, so the tag's commit vanishes from the
+  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.
+- **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
+  branch, acking to save time, or bypassing a check.
+- **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.)
+
+## Step 0 — confirm + probe
+
+Confirm the human holding train authority for THIS repo authorized a prod release this turn. Probe:
+```bash
+mmi-cli oracle org access role {owner}/{repo} --json   # Hub-verified: { role, train }
+```
+`train: false` — or any error (fail closed) → stop: a product repo's train belongs to that repo's
+project-admin or the master; the Hub train is master-only. **Three exceptions to fail-closed here, and all
+mean "unverified", never an authority verdict:**
+
+- A `repository … does not exist or is not visible to the org App` error (HTTP 404) means the probe target
+  is not a resolvable repo — a package name, a typo, a repo never created (#4778). It is UNKNOWN, not a
+  denial, and retrying will never change it: fix the `{owner}/{repo}` argument, then re-probe. Before the
+  fix this string came back `role: master, train: true, verified: true` for anything owner/name-shaped.
+
+- An `unknown command 'oracle'` error is a STALE CLI — the house-prefixed namespaces ship in newer
+  trains, so an old installed CLI can't even parse the probe. Jump to Step 0a, heal the CLI, then re-run
+  this probe; never conclude the command form is wrong from a pre-heal failure (#3150). The mirror-image
+  failure is a Wave-3 flat alias on a CURRENT CLI: the un-housed `org …`, `secrets …`, and
+  `release …` forms were removed in #4316 and fail closed with a house-prefix error — rewrite to the
+  house form (`mmi-cli oracle org …`, `mmi-cli vault secrets …`, `mmi-cli devops release …`); that is
+  never a stale CLI and never an authority verdict.
+- A **TIMEOUT or network error** (`operation aborted due to timeout`, DNS/socket failures) is **not** a
+  `train: false` denial (#3321). Read the probe's own `verified` field: `verified: false` means the verdict
+  could not be established, so the `train: false` beside it carries NO authority meaning. The client
+  already retries transient failures internally, so a *persistent* timeout points at the local network
+  rather than the Hub — resolve the Hub API host first (fails in seconds and rules out the whole
+  local-network class), then re-run the probe. Conclude "no train authority" ONLY from a `verified: true`
+  response. Aborting a legitimate release on an unverified probe is the failure this carve-out exists to
+  prevent.
+
+Then
+preconditions: clean tree; full-track repos run from `rc` (or from `development` with `--dev`), while
+direct-track repos run from `development`. Ordinary `/release` takes its bump intent from the bare
+argument (`/release minor|major|patch` → `MMI_BUMP_INTENT`, exported for the whole run); unstated, the
+train defaults to `patch` (#4929). An invalid intent fails `--apply` closed at intent resolution
+(`MMI_BUMP_INTENT must be one of major|minor|patch`), before any merge, tag, or fold.
+
+**Run from the checkout that already has that branch — never a fresh isolated worktree (#2770).** This is
+a shared-branch train operation (merge/tag/push against origin's protected `main`/`rc`), not an isolated
+feature-branch edit. A background-job harness that isolates every task into a fresh worktree by default
+breaks here: the new worktree's branch is never literally named `development`/`rc`, and `git checkout
+development` inside it fails outright when `development` is already checked out in the primary checkout (git
+worktrees cannot have the same branch checked out twice). If you are in such a worktree, exit it first and
+run the release from the primary checkout.
+The clean-tree check rejects UNTRACKED scratch too, not just modified tracked files. When `--apply` or
+`--resume` stops with `working tree must be clean before …`, run `git status --porcelain` on the paths it
+named and read BOTH status columns before touching anything (#1472, #4004):
+
+- `??` — untracked scratch. Gitignore it, or move it to a gitignored path like `tmp/`, then retry.
+- exactly ` M` (blank staged column) — the only state that can be churn rather than work. Test it with
+  `git diff HEAD --numstat -- <paths>`: non-empty is a real edit to commit or stash; empty means the
+  worktree normalizes straight back to HEAD (an LF↔CRLF rewrite, say), and `git checkout -- <paths>`
+  then clears the refusal without discarding anything.
+- anything else — `M `, `MM`, `A`, `D`, `R`, `T`, or any `U` conflict — is real work or an exceptional
+  index state. Commit, stash or resolve it; do not try to classify it.
+
+Do not substitute plain `git diff --numstat` for the `HEAD` form. It compares the worktree against the
+INDEX, so a change that is merely staged prints nothing at all, and reading that emptiness as
+"line-ending churn" throws the change away. The remedy is the index form of `git checkout` for the same
+reason: `git checkout HEAD -- <paths>` would overwrite a staged edit that was misread as churn.
+
+Full-track repos:
+```bash
+git fetch origin
+git rev-list --count origin/main..origin/rc
+```
+
+Direct-track repos (e.g. MMI-Hub):
+```bash
+git fetch origin
+git rev-list --count origin/main..origin/development
+```
+`0` → stop ("nothing to release").
+
+## Step 0a — stale CLI preflight (#1410)
+
+Before local gates or `release --apply`, ensure the repo-local / PATH `mmi-cli` matches the released train
+path — a stale checkout (e.g. 2.32.0 while 2.32.4 is released) fails release gates with opaque errors.
+Self-heal in place without repo writes (heals run by default since #3975; the flag suppresses only
+mutations of the working tree you are about to release from):
+```bash
+mmi-cli doctor --no-repo-writes
+```
+**Read the checks, not the exit code.** `doctor` exits non-zero on any failed check it could have healed —
+not just a version gap — so a red exit here does not by itself mean the train is blocked (#2962). The
+inverse is also true: a run can exit **0** while printing ✗ lines (report-only rows, #3485). Neither
+direction is a gate. Read the rows.
+
+- **Blocking:** a red `mmi-cli` / `Claude plugin` version line, or a reported `minClientVersion` gap.
+  `--no-repo-writes` does not block the env heals — the step above self-updates the npm global CLI
+  (#3272) and reinstalls the plugin (#3282), suppressing only repo-file writes — so the re-run should clear
+  it. If a gap persists, fix it — `mmi-cli doctor`, or `npm install -g @mutmutco/cli` — before
+  continuing. Do **not** proceed to Step 0b while the installed CLI is behind the Hub's `minClientVersion`.
+- **Not blocking:** every other red check is hygiene, not a train gate. Stale branches and scratch heal with
+  a plain `mmi-cli doctor` (after the release); `plugin cache` needs a different verb,
+  `mmi-cli plugin prune --apply` — saying doctor cleared it was wrong. Both still exit 1 until you run the
+  right verb. Read them, then proceed.
+
+Treating doctor's exit code as the gate halts a healthy train on cosmetic drift — or, worse, teaches an
+operator to ignore doctor's exit code entirely.
+
+**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:
+```bash
+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
+```
+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
+(`npm install -g npm@<CI major>`) and re-run `npm ci` before rewriting or regenerating the lockfile.
+
+**A `npm ci was killed (signal SIGTERM)` failure during the fold is a cold npm cache, not a lockfile or
+toolchain problem (#4841).** The signature is the kill, not error text: no `Missing:` line, no lockfile
+complaint at all — the fold's child-process budget expired while a cold cache installed the full tree.
+The npm-major note above is inert here (majors match, the lockfile is fine), and following it tempts the
+one thing it warns against — regenerating the lockfile for a problem that has nothing to do with it.
+Warm the cache with a plain `npm ci` in the release checkout, then rerun the identical train command; the
+rollback the failed fold already ran makes the rerun clean. Never regenerate or rewrite the lockfile in
+response to a SIGTERM kill.
+
+**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;
+`release --apply` refused one command later. Two lines, no dependency on another command's reporting
+completeness:
+```bash
+mmi-cli --version
+npm view @mutmutco/cli version    # public package; a bare view is trustworthy here
+```
+Mismatch → `npm install -g @mutmutco/cli@<released>` before Step 0b, **regardless of what doctor's rows
+said**. This is the check whose absence Step 0a's own title promises to cover, so it is not optional.
+
+## Step 0b — registry + main secret-name preflight
+
+Resolve the project META first; its `deployModel` decides the deploy path. `tenant-container` repos use the
+central tenant deployer and therefore need DEPLOY# coords. `hub-serverless` (MMI-Hub), `serverless`,
+`registry-publish`, and `solo-container` repos deploy from their own branch/release-triggered or model
+workflow, so do **not** dispatch `tenant-deploy.yml` for them.
+Verify META + required SSM secret names before touching `main`:
+```bash
+mmi-cli oracle org project get {owner}/{repo}
+mmi-cli vault secrets preflight --stage main --repo {owner}/{repo}
+```
+An enumerated missing META row or missing secret name → stop and repair the registry/secrets first. An
+HTTP 5xx, timeout, DNS, socket, or other transport failure is **unverified**, not evidence that a name is
+missing: retry the read/preflight and repair connectivity if it persists. Never provision or rename a
+secret from a transport-error response.
+
+## Step 0c — hotfix-coverage guard (fail closed, #839, #958)
+
+Full-track repos only. Direct-track repos skip this specific guard — not because they are exposed to no
+risk, but because the risk this guard checks structurally cannot arise there: a direct-track `/hotfix`
+cherry-picks straight from `development` onto `main`, so every hotfix trailer's source sha is *by
+construction* an ancestor of `origin/development` — a trailer-ancestry check would be permanently green and
+add no signal (#2786 — a literal port was considered and rejected as a false-confidence guard).
+
+Hotfixes are cherry-picked from `development` to `main` with **no back-merge** (see `/hotfix`), so a
+candidate cut *before* a fix landed on `development` would silently revert that hotfix in prod. The guard
+proves every main-only commit is in the candidate before the `rc → main` merge.
+
+**Direct-track repos are not risk-free, though — they carry a different, real failure mode:** a hotfix
+freezes a snapshot of the files it cherry-picks (e.g. docs, a test assertion) while `development` keeps
+evolving those same files afterward. Step 1's `development → main` merge preflight (untolerated-path
+conflict check) is what actually catches this — a genuine content conflict on the **next** release is
+expected when a hotfix's cherry-picked commits touched files `development` went on to rewrite
+incompatibly. That is routine, working-as-designed friction, not a fluke or a misconfiguration (incident:
+hotfix v3.16.1 #2765 cherry-picked #2762/#2768's doc sweep onto `main`; `development` then rewrote the same
+files further via #2767/#2771; `/release` correctly stopped on 4 conflicted files, resolved by confirming
+`development`'s side already represented the correct, current content and landing alignment PR #2784 — see
+#2786). When Step 1 stops this way: run `git merge-tree` (or read the conflict content directly) to confirm
+which side carries the correct current content, then land a true-merge alignment PR (never hand-resolve on
+`main`) before rerunning release.
+
+It runs **automatically inside `mmi-cli devops release --apply`** (Step 1+ below) — built into the CLI so it
+works in every product repo with no repo-local script. You do not invoke it separately.
+
+Per main-only commit it accepts: the `(cherry picked from commit <sha>)` trailer with that dev SHA an
+ancestor of `origin/rc` (immune to conflict-resolved ports); a matching `git patch-id` on the rc side
+(trailer-less picks); or a distribution-manifest-only bump (exempt — rc carries its own). Anything else
+**fails the release closed** → **stop**: the right fix is a re-cut `/rcand` from `development`. Only when
+the authorized human has manually verified the content is in the candidate, rerun with
+`mmi-cli devops release --apply --ack <sha>[,<sha>…]` — the ack is recorded in the verdict. Never ack to save time.
+
+## Step 0d — no docs-keeping on the release train (Hub#4164)
+
+Scheduled docs-janitor / wiki-keeper / living-docs freshness passes are **retired** (#4117/#4119).
+The release train does **not** open docs-only PRs, wait on README/architecture auto-merges, or
+treat prose refresh as a gate.
+
+Current state is compute-at-read + the estate repo-index (`mmi-cli oracle repo-index search`,
+`mmi-cli oracle org project`, board/schedules verbs). Durable WHY stays in `docs/decisions/`.
+If shipping code made a hand-written surface wrong, fix it on `development` as an ordinary PR
+**outside** the train — never as a release Step.
+
+## Step 1 — merge to main (never force)
+
+Full-track repos:
+
+```bash
+git checkout main
+git pull --ff-only origin main
+git merge rc --no-edit
+```
+
+Direct-track repos (e.g. MMI-Hub):
+```bash
+git checkout main
+git pull --ff-only origin main
+git merge development --no-edit
+```
+Conflict → abort + stop (the train is misaligned — investigate; don't hand-resolve on `main`). On a
+direct-track repo, a conflict here right after a hotfix is expected friction, not a fluke — see Step 0c for
+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.
+
+**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
+repo bootstrapped before the managed-gitignore era still carries the legacy file on `main`; the candidate
+carries the Hub-managed copy with project-local entries preserved). The org spine is no longer delivered per
+repo (hub-v3 WS4), so a spine-path conflict is treated like any other untolerated path. A hotfix bumps the manifests +
+committed CLI bundle on `main` only, so the next merge re-conflicts there even when the train is healthy —
+and the fold rewrites those exact paths right after the merge. For all tolerated paths the CLI takes the
+incoming side deterministically and continues. Any other conflicted path → abort + stop as above.
+
+## Step 1b — version fold (automatic, inside `mmi-cli devops release --apply`)
+
+Every release folds the version bump into the release itself (#976): after the merge onto local `main` and
+before the tag, the CLI bumps the version manifests to the release version and commits — **unconditionally,
+changed or not** — then the tag-first push (Step 3) earns that fresh commit its required checks. There is
+no separate bump PR, no `development` prep cycle, and `development` never sits ahead of the published
+version (the back-merge in Step 5 carries the bump back).
+
+What the fold bumps, by repo:
+- **Hub (`hub-serverless`):** the full locked distribution set via `scripts/release-distribution.mjs
+  prepare` — spine dogfood (`scripts/spine-dogfood.mjs`: verify docs/surfaces + the managed `.gitignore` block),
+  every registry-declared version holder, adapter payload synchronization, build output, and the public
+  artifact bill of materials — then verifies the set (`verify --skip-npm-view`). Publication and staging
+  both derive from `surfaces.json`; there is no second package list. Claude, Codex, Kimi, Cursor, and
+  Kilo are active.
+- **App-style repos with a root `package.json`** (most products): the manifest + lockfile version via
+  `npm version --no-git-tag-version`, kept in lockstep with the release tag.
+- **Repos with neither:** nothing to fold — the tag is the version.
+
+Nothing to do by hand; the `--apply` result reports the fold outcome (`versionFold`).
+
+## 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
+because they have no rc tag — `cycle` mode reads `MMI_BUMP_INTENT` (the `/release` argument; unset →
+`patch`, #4929). The Step 0 export is what covers the apply run — the inline prefix below only resolves
+the tag for display; `mmi-cli devops release --apply` re-derives intent itself and fail-closes before any
+merge, tag, or fold when the value is invalid:
+```bash
+TAG=$(node scripts/next-version.mjs release)                  # full-track repos -> vX.Y.0
+TAG=$(MMI_BUMP_INTENT=minor node scripts/next-version.mjs cycle)   # direct-track repos -> vX.Y.0
+git tag "$TAG"
+```
+
+## Step 3 — push tag, wait for the REQUIRED checks, then push main (the gate)
+
+`mmi-cli devops release --apply`'s exit code is **not** the release verdict: exit `2` can mean the release
+shipped successfully while protected-branch alignment remains pending, and exit `1` can mean a
+post-release follow-up failed after promotion — **or that the follow-up is merely unresolved** (#4939):
+a verdict of `releaseStatus=succeeded` with `followUpStatus=pending` (the release-triggered runs — e.g.
+the Hub's `deploy.yml` + `publish.yml` — had only just auto-fired) also exits nonzero, and a
+background-task harness surfacing exit codes misreads it as "release failed" when the release actually
+shipped. Classify from the verdict fields, never the exit code alone: `succeeded` + `pending` means
+shipped with the follow-up unresolved — watch the enumerated `workflowRuns` to conclusion; only a
+resolved failure there is a failed follow-up. Read the live release verdict and verify these four
+facts instead: the `main..development` count, the tag on `origin`, `gh release view`, and the runs on
+the release SHA.
+
+Required status checks are **per-repo branch protection, not a fixed list** — MMI-Hub's `main` requires
+`cli` · `infra` · `docs`, but a product repo may require different contexts or none at all (#1045). The
+release SHA is always fresh (the Step 1b fold commits on local `main`), so when checks ARE required,
+pushing the branch *first* is structurally rejected until CI catches up. Push the **tag first** (it lands
+the SHA and triggers the repo's CI — in MMI-Hub `gate.yml` runs on `v*` tags — without touching the
+protected ref), then probe what `main` actually requires and wait only for those contexts:
+
+```bash
+git push origin "vX.Y.0"                       # lands the SHA + triggers the repo's CI
+SHA=$(git rev-parse main)
+# discover the REQUIRED contexts on main (classic protection + rulesets; 404 = none from that source):
+gh api repos/{owner}/{repo}/branches/main/protection/required_status_checks --jq '[.contexts[]]'
+gh api repos/{owner}/{repo}/rules/branches/main \
+  --jq '[.[]|select(.type=="required_status_checks")|.parameters.required_status_checks[].context]'
+# ZERO required contexts -> push main immediately (the GitHub push gate is the backstop).
+# Otherwise poll until every required context is "success" on $SHA — never a hard-coded list, and bound
+# the wait (~10 min): on timeout, stop with a clear failure naming the pending/failed contexts.
+gh api repos/{owner}/{repo}/commits/$SHA/check-runs \
+  --jq '[.check_runs[]|{name:.name,conclusion:.conclusion}]'
+git push origin main
+```
+(`mmi-cli devops release --apply` performs this discovery + bounded wait itself.) A required context can only ever
+resolve on a tag SHA if its workflow runs on `push: tags` (or is otherwise SHA-addressable) — a PR/issue-event
+job (e.g. a stale hand-added `add-to-project` / `mark-merged-pr-done` board-automation check) structurally
+never produces a check-run there. The train recognizes that fixed pair by name and, after a short grace
+window, treats it as satisfied-for-the-tag instead of burning the full ~10-minute budget on a check-run that
+can never appear (#2404). Any OTHER required context still waits the full budget and, on timeout, names
+exactly which contexts never materialized vs. which were merely pending. If your repo's ruleset requires a
+PR-only job outside that pair, fix the ruleset (drop it, or replace with a real gate) — don't rely on the
+grace window for anything not on the allowlist.
+Rejected → stop (nothing released).
+
+**Halted on a FAILED required check (not merely pending)?** That is a **stray unreleased tag** (#2734): the
+tag is pushed but `main` was not, no GitHub Release exists, and nothing deployed/published off it — so it can
+never go forward (a failed check will not pass on that SHA). This is the **opposite** of a *resumable* partial
+state (checks passing/pending, only the branch push / Release / deploy left, where the recovery is to finish
+forward and you must NOT delete the tag). Here: fix the cause on `development` via a CI-gated PR, then **delete
+the stray tag** — `git push origin --delete vX.Y.0` **and** `git tag -d vX.Y.0` (delete the local tag too; a
+surviving local tag makes `next-version cycle` silently mint the *next* version) — and re-run `mmi-cli devops release
+--apply` (the fold re-tags the same version on the fixed HEAD). **Tag deletion is deletion-class → it needs the
+authorized human's explicit per-turn go.** Exception: if a publish/deploy DID run off the stray tag, do **not**
+delete — mint the next version with `MMI_RELEASE_VERSION` instead. The CLI already classifies this
+(`isStrayUnreleasedTag`, `cli/src/train-apply.ts`); this note surfaces the doctrine so a halted operator does
+not re-derive it from source.
+
+## Step 4 — GitHub Release + start prod deploy (non-blocking)
+
+For `tenant-container` repos, publish the GitHub Release and dispatch the central tenant deploy.
+```bash
+gh release create "vX.Y.0" --target main --generate-notes --latest
+gh workflow run tenant-deploy.yml --repo mutmutco/MMI-Hub \
+  -f slug={slug} -f repo={owner}/{repo} -f ref=main -f stage=main
+gh run watch "$(gh run list --workflow tenant-deploy.yml --limit 1 --json databaseId -q '.[0].databaseId')" \
+  --exit-status   # the central prod-deploy run — run this in the BACKGROUND (Bash run_in_background)
+```
+
+For `hub-serverless` (MMI-Hub), publish the GitHub Release but do **not** dispatch `tenant-deploy.yml`:
+the release event auto-fires `deploy.yml` for prod and `publish.yml` for the
+plugin/CLI package. A missing `DEPLOY#main` registry row for MMI-Hub is expected, not a tenant stack repair
+task. Watch/report the release-triggered `deploy.yml` and `publish.yml` runs instead.
+
+For other direct-track repos, the train dispatches nothing centrally: a `registry-publish` repo's release
+event fires its own `publish.yml` (npm / plugin marketplace); a `solo-container` repo deploys via its own
+workflow. Publish the GitHub Release, then watch/report that repo's own release-triggered run.
+
+`mmi-cli devops release --apply --json` returns the relevant run id/url data with `deployStatus`; `--watch` blocks
+on the run(s) and resolves `deployStatus` to `success`/`failure`. For tenant-container repos, that is the
+dispatched `tenant-deploy.yml` run. For Hub serverless, that is the auto-fired release `deploy.yml` and
+`publish.yml` workflow pair — watched on `mutmutco/MMI-Hub`. For `registry-publish`, that is the target
+repo's own release-triggered `publish.yml` run — watched on that repo, never dispatched, and never the
+central `tenant-publish.yml` (#2428: dispatching both is a guaranteed npm E409 double-publish, since the
+repo's own release-triggered publish always wins the version race).
+`promoted: true` stays set even on a failed deploy — promotion and deploy are separate outcomes.
+
+**`deployStatus: 'pending'` is NEVER a terminal, reportable state (#3322).** A release that returns
+`pending` has an UNRESOLVED deploy, not a clean one. The report now prints `deploy: UNVERIFIED` instead of
+omitting the deploy line entirely — which is exactly how a failed deploy once hid behind a "successful"
+release (Jerv-PowerTools v1.22.0: the release-triggered `publish.yml` went green, a separate `push: main`
+SAM deploy FAILED, and the train returned `deployStatus: pending`, so the run read as clean). Resolve it,
+or report it as unverified-RED. Never as success.
+
+**Read the `--apply` result's `workflowRuns` array — the train already enumerates every run on the release
+SHA (#3699).** That enumeration includes `push: main` infra deploys (`deploy.yml`, SAM) the deploy model does
+not name, and `deployStatus` is held at `pending` until they resolve. Any non-success entry — including
+`pending` — keeps the release unverified: watch those listed runs to conclusion:
+```bash
+gh run watch <run-id> --repo {owner}/{repo} --exit-status
+```
+The one remaining caveat: `--watch` blocks only on deploy-model-named runs, not extra push-triggered
+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.
+
+**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`
+on a product), watch or dispatch `ds-propagate.yml`, run `design-system` / `doctor` design-system heals for
+consumers, or treat a product's deploy state as part of this release — those belong to that product's own
+`/release` or `/rcand`, never a Hub train.
+
+Before running `--apply` for MMI-Hub, resolve the real tag first:
+`TAG=$(MMI_BUMP_INTENT=minor node scripts/next-version.mjs cycle)` — always print `$TAG` (e.g.
+`v2.43.0`) in summaries, Slack, chat, and the final report; never a placeholder like `vX.Y.0` or
+`v0.x.0`.
+
+Write a curated summary — 3-6 very short plain lines, one change per line, dev-readable, no PR-dump —
+to a fresh temp file (`f=$(mktemp tmp/release-summary.XXXXXX)`, so a stale prior summary is never reused).
+Source from **Hub PR titles only** (`origin/main..origin/development` on `mutmutco/MMI-Hub`), but **rewrite**
+each line in neutral Hub-subsystem terms (CLI, skills, plugin, workflows, registry, deploy hub) — **never**
+a product or brand name (FoFu, Katip, etc.) anywhere in the summary file, Slack post, chat, or release
+report. Product names are allowed only when releasing **that product's repo**. Then pass the file through:
+`mmi-cli devops release --apply --announce-summary-file "$f"`. After the GitHub Release publishes, the CLI posts
+the summary to the org alerts channel as the MMI-Future Slack app (token + channel from SSM at run time).
+For a new MMI-Hub `--apply`, the CLI refuses before promotion when the file is missing, unreadable, or does
+not contain 3–6 non-empty lines; generated-note fallback is not an agent release path. `--resume` never
+requires or republishes a summary, and non-Hub repos skip the announcement automatically. After a valid
+summary is accepted, Slack delivery remains best-effort: a transport failure is reported in the result and
+never rolls back an otherwise completed release.
+
+**Don't block on the deploy.** Start the watch as a background task and proceed to Steps 4b–5 (docs, project
+info, branch alignment) while prod deploys. The verdict is collected in Step 6 — verification is not
+skipped, only un-blocked. Deploy failure → report plainly, then **retry the existing promoted ref by deploy
+model** once the runtime is repaired — never a re-tag or republish (`main` is already at the release, which is
+correct). Read the model from the registry (`mmi-cli oracle org project get {owner}/{repo}` → `deployModel`):
+- **tenant-container** — the central tenant deployer owns the redeploy: `mmi-cli devops runtime tenant redeploy
+  {owner}/{repo} main --watch`.
+- **repository-owned serverless / registry-publish** (e.g. Jerv-PowerTools' `Deploy Jerv Memory`) — there is
+  no `runtime tenant redeploy` for these; re-run the repo's OWN declared `workflow_dispatch` deploy workflow at
+  the promoted-equivalent ref: `gh workflow run <deploy-workflow> --repo {owner}/{repo} --ref <ref>`.
+
+Name the sanctioned dispatch mechanism you used in the train report.
+
+## Step 4b — re-sync project info (no in-repo docs pass)
+
+In-repo README/architecture freshness is **not** a train step (Step 0d retired, Hub#4164).
+`mmi-cli devops release --apply` re-syncs the GitHub **Project** short description + thin README from the
+released commit and the registry member list through the command ladder. For a manual repair or preview use:
+```bash
+mmi-cli oracle org project sync-info --apply   # omit --apply for the read-only plan
+```
+
+## Step 5 — roll development forward
+
+- Keep branches aligned: `mmi-cli devops release --apply` back-merges the released `main` (incl. the version
+  fold) into `development` and reports it as `devRollForward`. When `development` has no required checks it
+  pushes directly (`status: pushed`). When `development` *requires* checks (e.g. MMI-Hub needs
+  `cli`/`infra`/`docs`), the fresh merge commit carries no passing checks, so a direct push is structurally
+  rejected — the train instead **opens an alignment PR** `main → development` (`status: pr-pending`) and the
+  release report prints the exact land command. The release itself has already shipped; **land the alignment
+  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.
+- 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.
+- **Local branches never left stale (#2582).** A release advances `main`/`development`/`rc` on **origin**;
+  `mmi-cli devops release --apply` also fast-forwards the LOCAL train branches to match, so the checkout you
+  released from does not lag what you just pushed. The train restores + fast-forwards the start branch
+  (`checkout`, #2340) and fast-forwards the others (`localSync`) — non-destructively: only a true
+  fast-forward moves a branch; a diverged local branch is reported and left untouched (never a force).
+  The one branch it **cannot** sync at release time is a check-gated `development` whose roll-forward is a
+  `pr-pending` alignment PR (Hub) — that PR merges on origin *after* the release returns. That case is
+  healed automatically by the **next session**: `mmi-cli plugin session-start` (invoked by the resume
+  channel — #3630 took SessionStart off the hook surface) runs the
+  same fast-forward first thing, so a stale local `development`/`main`/`rc` self-heals to origin before you
+  work — no manual `git pull`. Nothing here ever blocks or fails the release.
+- **Read the `checkout:` clause — it does not always say "returned" (#4006).** The report always prints
+  one, and restoration is deliberately skipped rather than forced when the repo is not in a fit state.
+  A release leaves the repo on `main` until the train moves it back, so a non-`returned` outcome means
+  you are still there and must return by hand once the cause is cleared:
+  - `checkout restoration skipped: working tree changed after release` — the tree went dirty DURING the
+    train, so the train declined to move you. Diagnose those paths with the Step 0 clean-tree rules,
+    then `git checkout <start branch>` yourself. The release itself already shipped; this is a
+    deliberate, harmless decline, not a failed release.
+  - `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.
+
+## Step 6 — collect deploy verdict + report
+
+The `release --apply` exit code is **not** the release verdict. A nonzero exit with
+`releaseStatus=succeeded` and `followUpStatus=pending` is the unresolved-follow-up case from Step 3 —
+the release shipped; the runs enumerated in `workflowRuns` are the outstanding verdict, so watch them
+to conclusion here rather than re-running or alarming. Report the live release verdict from
+the four checks that matter: the `main..development` count, the tag on `origin`, `gh release view`,
+and the runs on the release SHA; an alignment PR is normal follow-up work when those checks confirm
+the release shipped.
+
+Collect the backgrounded prod-deploy watch from Step 4 (it has typically finished by now). Confirm prod is
+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).
+
+**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.
+
+Hub releases always carry a distribution bump (the Step 1b fold), so the **publish workflow**
+(`publish.yml`) ships every registry-declared public npm artifact on the GitHub Release from Step 4 —
+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
+```
+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"`
+from a machine with npm auth.
+
+**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
+reads. Before verifying ANY npm publish (Hub's own, a `registry-publish` product repo's own `publish.yml`,
+or a `publishRequired` product repo's companion `tenant-publish.yml`), check that surface's
+`publishVisibility` in the target repo's `surfaces.json`
+(`node -e "console.log(require('./surfaces.json').surfaces.find(s=>s.id==='<id>').publishVisibility)"`, or
+the repo-agnostic reader `scripts/release-distribution.mjs` exports as `npmVerifyModeFor`):
+- `public` → an unauthenticated `npm view <pkg>@<version> version` is a trustworthy verify signal.
+- `private` → do **not** run a bare `npm view`. Verify from an authenticated source instead: the
+  release-triggered run's conclusion (`gh run watch … --exit-status` — the repo's own `publish.yml` for
+  `registry-publish`, #2428; the central `tenant-publish.yml` for a `publishRequired` companion publish) and
+  its logged `+ pkg@ver` / `"already on npm — nothing to do"` / `"already on npm ... treating as idempotent
+  success"` output (`gh run view <id> --log`), or `npm view` with a registry auth token in env. A 404 here is
+  "unverifiable from here", never "not published" — report it as such, don't block or alarm on it.
+- `n/a` → nothing publishes to npm for that surface; skip.
+Hub's registry-declared npm surfaces are public today, so `release-distribution.mjs verify` uses a bare
+`npm view` for them — this changes only if a package's declared visibility changes.
+
+**tenant-publish.yml E409 belt-and-braces (#2428).** The central `tenant-publish.yml` lane (the
+`publishRequired` companion publish only — never dispatched for `registry-publish`, see above) already
+treats a lost `npm publish` race as idempotent inside the run (a re-check `npm view` after a failed publish;
+see the workflow file). `mmi-cli devops release --apply --watch` mirrors that at the CLI layer: a watched
+`tenant-publish.yml` run that concludes `failure` is re-checked against that SAME run's own log (bounded
+retries, visibility-agnostic — never a bare `npm view`) for the idempotent-success marker before the CLI
+reports the publish as failed. A run whose log never shows the version landed stays a loud failure.
+
+Report: Release `$TAG` (the resolved tag from Step 2 — never a placeholder) + the GitHub Release URL · prod
+deploy run + URL + **green/red** · branch-alignment note · npm publish run + CLI version (Hub releases).
+
+## Notes
+
+- `/hotfix` stays the cherry-pick promotion lane (a hotfix always skips rc — it cherry-picks
+  `development → main` directly), but a `/release patch` from development is a legitimate ordinary
+  release (#4929). Never force-push `main`.
+- **`MMI_BUMP_INTENT=major|minor|patch` comes from the bare `/release` argument; unstated it defaults to
+  `patch`** (#4929). Export it for the whole run, not a one-off prefix on `next-version.mjs cycle`:
+  `mmi-cli devops release --apply` (and `rcand --apply`) resolve intent themselves **before any merge,
+  tag, or fold** — direct-track included — defaulting to `patch` when the env is absent and failing closed
+  there with `MMI_BUMP_INTENT must be one of major|minor|patch` on an invalid value, so the tree stays
+  clean on the start branch. `MMI_RELEASE_VERSION`
+  below is a different knob: it overrides the computed version; it does not replace the intent export
+  unless you set that exact-target env instead.
+- **`--dev` (full-track only):** releases `development → main` skipping rc, with the same fold/tag/Release/
+  deploy machinery plus the post-release rc retirement and rc alignment. Refuses (fail closed) when
+  `origin/rc` carries commits not in `development`; on direct-track repos it's a no-op (they already
+  release from `development`).
+- **MAJOR / exact-target release:** to ship a version the tag math can't derive (a MAJOR like `2.0.0`, or
+  skipping a version already on npm), product repos export `MMI_RELEASE_VERSION=X.Y.Z` for **both** `/rcand`
+  and `/release`; MMI-Hub exports it for `/release` only. Steps 1b/2 then fold and tag exactly that
+  version. Unset, the train uses the declared `MMI_BUMP_INTENT` increment, defaulting to `patch` when
+  neither the argument nor the env declares one (#4929).
+
+## Retro — one check before you finish
+Before your final report, answer one question honestly: did **this skill's own instructions** misfire
+this run — ambiguous wording, a misleading message, or an environment failure it should have warned
+about? (Process only — never the user's code or task; e.g. a misleading authority or gate message, or an
+ambiguous version-fold or back-merge step.) If yes, file **one** lesson and move on; a clean run is silent
+(hard cap: one per run). It lands on the Hub board (deduped) and is fixed only via a reviewed PR — never
+edit the skill live; the retro is advisory, so if the call fails, note it and continue:
+`mmi-cli learning skill-lesson --skill release --title "<what misfired>" --body "<what; evidence; proposed amendment>"`