@mutmutco/codex-plugin 4.3.5 → 4.3.6

package/skills/release/SKILL.md

@@ -5,964 +5,83 @@ description: Ship rc or direct-track development to main and production.
 
 **Host-native invocation:** Claude `/mmi:release` · Codex `$mmi:release` · Cursor `/release` · jervcode `/release` · Hermes skill_view. 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.
+**Argument:** `/release minor`, `/release major`, or `/release patch` — a bare bump word, never a `--flag` or env var. No argument → `patch`; a `/release patch` from development is a legitimate ordinary release, `/hotfix` stays 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.
+Full-track repos ship exactly what is on `rc` (never `development`): merge `rc → main`, tag `vX.Y.0`, publish the GitHub Release, deploy prod, roll `development` forward. Direct-track repos ship `development → main`, and the release event fires the repo's own deploy/publish workflow (MMI-Hub: `deploy.yml` + `publish.yml`). `rc` is ephemeral: `/rcand` creates its runtime, `/release` retires it after a confirmed prod deploy (`rcRetirement`). A prod release needs the authorized human's explicit go in the current turn — an agent never self-initiates it. The board needs no touch: items reached `Done` when their PRs merged to `development`.
 
-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.
+## Lane
 
-## Merge floor (#3167 — non-negotiable, applies to every step below)
+Read META and name the lane before describing or executing anything:
 
-- **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.
-  `--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
-  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.)
-- **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
-
-Before describing or executing any release lane, read the project META and name the lane:
 ```bash
 mmi-cli oracle org project get {owner}/{repo} --json
 ```
-`releaseTrack: direct` means `development → main` and **no `/rcand`**. An absent `releaseTrack` means full-track
-(`rc → main`) except for MMI-Hub itself, whose Hub-control special case is direct. Stop on an unreadable META record;
-never infer the lane from branch names, release history, or the existence of an `rc` branch.
-
-Then 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. For `?? .jerv/` / `?? .pi/` (org-managed agent scratch), run
-  `mmi-cli doctor --apply` to write the managed `.gitignore` block — do not hand-edit `.gitignore`
-  (#5409). The train CLI already ignores those live-session dirs (#5397); doctor is the durable heal.
-  For other `??` paths, gitignore them, or move them 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").
-
-**Checkout topology — verify the lane's refs exist locally before apply (#5624).** A fresh single-branch
-`development` clone has no local `main`; the train then fails or rolls back at `git checkout main`. Before
-any merge or `--apply`, confirm every ref the lane will touch is present as a local tracking branch:
-
-```bash
-git branch --list development main   # direct-track (and full-track --dev)
-git branch --list rc main            # full-track rc → main
-```
-
-A missing ref is a topology gap, not a train failure — materialize it from origin, never force past it:
-
-```bash
-git fetch origin main:main           # (or development:development / rc:rc) — creates the local ref
-```
-
-Re-run the `--list` until every ref the lane touches is present, then proceed.
-
-## 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.
-Read the gap on the compatibility-safe no-repository-write lane:
-```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.
-  **Doctor does not update the CLI (#4954).** `mmi-hub` owns release-gated version convergence; doctor
-  reports lag and last-run evidence only. The remedy is `mmi-hub update`, not a doctor re-run or a bare
-  CLI install. Plain doctor/`--no-repo-writes` may safely repair active plugin wiring but never repository
-  state. 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 require
-  explicit `mmi-cli doctor --apply` 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.
-
-**`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, 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.
+`releaseTrack: direct` → `development → main`, no `/rcand`. Absent → full (`rc → main`), except MMI-Hub, which is direct by the Hub-control special case. Full-track `--dev` ships `development → main` skipping rc and fails closed when `origin/rc` carries content not in `development`. Unreadable META → stop; never infer the lane from branch names, tags or release history.
 
-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.
+## Preflight
 
-**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
-# 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).
+mmi-cli devops train doctor --lane release --heal --json
 ```
-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 pre-tag `npm publish --dry-run` failure whose stack trace is inside npm internals — e.g.
-libnpmpublish cannot find its declared sigstore dependency (`MODULE_NOT_FOUND`) — is toolchain
-corruption / an npm-major mismatch, not a malformed publish surface (#5616).** Compare toolchains
-BEFORE inspecting package contents (deleted dir, malformed `package.json`, missing `files`):
-```bash
-npm -v
-# green gate npm from the gate log's `node -v && npm -v` toolchain-preflight line (#3446),
-# 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 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.
+Read `ready`, then `findings[]`: each carries `code`, `severity` (`blocker` · `warning` · `healed` · `info`), `source` (`local` · `origin`), `remedy` and `anchor`. `ready: false` → stop and quote every blocker's `code` and `remedy`; an unread origin is never green. `--apply` re-runs this doctor as its step 0 with heal on.
 
-**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.
+## Apply
 
-**Repeated `EPERM` or `EBUSY` unlink errors during the fold's npm install on Windows are one race window,
-not a lockfile failure (#4982).** Rename `node_modules` aside once into a gitignored `tmp/` path, then rerun
-the identical train command. `npm ci` extracts into the now-empty tree and performs no unlinks; do not retry
-this workaround repeatedly.
+Run from the primary checkout on the lane's start branch (`rc`; `development` for direct-track and `--dev`). Export the bump intent once from the bare argument — `MMI_BUMP_INTENT=minor|major|patch`, unset → `patch`; `MMI_RELEASE_VERSION=X.Y.Z` only for an exact target the tag math cannot derive.
 
-**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`.
+MMI-Hub only: write a fresh 3–6 line neutral summary to `f=$(mktemp tmp/release-summary.XXXXXX)` — sourced from Hub PR titles only (`origin/main..origin/development`), rewritten in Hub-subsystem terms, never a product or brand name. Hub scope is only `mutmutco/MMI-Hub`: never a product's board, `ds-propagate.yml`, or a product's deploy state.
 
-**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
+r=$(mktemp tmp/release-receipt.XXXXXX)
+mmi-cli devops release --apply --json --out "$r"                                  # product repos
+mmi-cli devops release --apply --announce-summary-file "$f" --json --out "$r"     # MMI-Hub
 ```
-Mismatch → run `mmi-hub update`, then repeat both reads 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.
-
-**GitHub Actions billing/spending (#5604).** Those checks do not prove a *hosted* Actions job can start.
-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
-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)
-
-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 comes from code and live CLI 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. 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
-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).
+Add `--dev` for a full-track dev → main release and `--watch` to block on the deploy/publish runs. `mmi-cli devops release --apply --ack <sha>[,<sha>…]` only when the authorized human has verified that a main-only commit the hotfix-coverage guard refused is already in the candidate — never ack to save time. The one command merges, runs the version fold (automatic, inside `mmi-cli devops release --apply`) that bumps the manifests unconditionally before the tag, pushes the tag first (`gate.yml` runs on `v*` tags, so the fold commit earns its required checks), waits for the required contexts, pushes `main`, publishes the Release, dispatches or correlates the deploy (`tenant-deploy.yml` only for tenant-container), announces (Hub), re-syncs project info, and rolls `development` and `rc` forward. Nothing here is done by hand.
 
-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`). That prepare path runs
-  `scripts/check-hook-contract.mjs`, which executes host adapter commands as a native argv without a
-  shell (#5605), so a checkout path that contains spaces is supported; the spaced-path argv regression
-  is pinned in `infra/plugin-set.test.mjs`. Publication and staging both derive from `surfaces.json`;
-  there is no second package list. Claude, Codex, Cursor, jervcode, and Hermes 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.
+## Verify
 
-Nothing to do by hand; the `--apply` result reports the fold outcome (`versionFold`).
+Read the receipt at `$r`, never the exit code (exit `2` = shipped with a follow-up pending; exit `1` can also mean a follow-up failed after promotion):
 
-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`.
+- `releaseVerdict.releaseStatus` + `followUpStatus` — `succeeded` + `pending` is shipped with the follow-up unresolved: neither failed nor done.
+- `deployStatus` — `pending` is never terminal; `promoted: true` holds even when a deploy failed.
+- `workflowRuns` — every run on the release SHA (deploy-model runs, any `push: main` deploy, the repo's own `gate`). Watch each non-success entry to conclusion: `gh run watch <run-id> --repo {owner}/{repo} --exit-status`. Name which run is red: `deploy.yml` / `publish.yml` / `tenant-deploy.yml` / `jerv-gateway` is a deploy or publish verdict; a `gate` push run is ordinary CI sharing the SHA.
+- `announceNote` (Hub) — `announced`, `skipped`, or the failure note.
+- `devRollForward` / `rcAlignment` — `pushed`, or `pr-pending` with the alignment PR to land by true merge (Merge floor).
+- `versionFold`, `rcRetirement`, `checkout` — `returned`, or the named reason you are still on `main`.
 
-## Step 2 — tag the release
+Then the bounded Latest Release read; its `tagName` must equal the resolved tag:
 
-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`, the bounded Latest Release read in
-Step 6, 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.
-
-**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.
-
-**Resuming a resumable partial state? The recovery form is `--resume --watch --json`, and nothing
-else (#5815).** `--resume` and `--apply` are **mutually exclusive** and the CLI refuses the pair:
-`--apply cuts the NEXT version, --resume finishes the immutable tag already on origin`
-(`cli/src/index.ts`, the #3851 guard). A continuation that reaches for
-`--resume --apply --watch` is asking the train to mint a new version while finishing an old one —
-it refuses before any mutation, so nothing is lost, but the operator has spent a turn on a form that
-can never run. `--apply` belongs to a **new** release cut, never to recovery.
-```bash
-mmi-cli devops release --resume --watch --json --repo <owner/repo>
-```
-
-## 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
-```
-
-On PowerShell, read the run as a structured receipt and filter it natively; do not nest a
-`gh run list` query inside `gh run watch`:
-```powershell
-$runs = gh run list --workflow tenant-deploy.yml --limit 10 --json databaseId,createdAt,url,status,conclusion | ConvertFrom-Json
-$run = $runs |
-  Where-Object { $_.databaseId -and $_.createdAt } |
-  Sort-Object { [DateTimeOffset]$_.createdAt } -Descending |
-  Select-Object -First 1
-if (-not $run) { throw 'tenant-deploy workflow run was not found' }
-$run | Select-Object databaseId,createdAt,url,status,conclusion | ConvertTo-Json -Compress
-# Run this in the BACKGROUND (PowerShell Start-Job / task runner).
-gh run watch $run.databaseId --exit-status
-```
-
-When several run receipts need collecting, assign the loop output before serializing it; a top-level
-`foreach (...) { ... } | ConvertTo-Json` is a PowerShell parser trap:
-```powershell
-$out = foreach ($run in $runs) {
-  gh run view $run.databaseId --json databaseId,url,status,conclusion,createdAt | ConvertFrom-Json
-}
-$out | ConvertTo-Json -Compress
-```
-
-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.
-
-**Jerv-Hub has one additional fail-closed operator-host phase (#5699).** Only for exact repository
-`mutmutco/Jerv-Hub`, after its release-triggered `publish.yml` is proven green, the train runs
-`scripts/jerv-gateway-release-deploy.sh --tag <resolved-tag>`. That repository helper keeps root SSH in
-Jerv Vault custody, deploys the exact tagged commit to jerv-central, and requires systemd, `/livez`, and
-`/readyz` health. Its validated receipt is appended to `workflowRuns` as `jerv-gateway`; a missing helper,
-refusal, malformed receipt, unhealthy activation, or failed rollback sets `deployStatus: failure`. An
-unwatched/pending publish defers Gateway deployment and keeps `deployStatus: pending` — it never runs the
-host mutation before publication is proven. `release --resume --watch` re-derives the historical publish
-verdict and invokes the idempotent helper once it is green; it never re-tags or republishes the release.
-Do not move this phase into GitHub Actions: no supported Actions identity reaches personal jerv-central
-without moving root SSH custody out of its owning vault.
-
-`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.
-
-**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`
-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 the announcement from the actual release evidence** — summarize the user-visible change, required action, and recovery path before posting. Key rules:
-
-- **Audience is the whole org** — no issue/PR numbers, repo names, commit SHAs, or internal tool jargon.
-- **Scale length and depth by release type** (major > minor > patch > hotfix): a major is a broad,
-  migration-focused announcement; a minor is scannable grouped bullets; a patch is factual and minimal;
-  a hotfix is incident-style (impact/status/workaround) with a concise durable note.
-- **Front-load**: one lead sentence stating the most important thing, then grouped bold sections;
-  breaking changes and required actions get their own visible section.
-- **Benefits, active voice, addressed to the reader** — no hype, no internal identifiers.
-
-Write the curated summary to a fresh temp file (`f=$(mktemp tmp/release-summary.XXXXXX)`, so a stale prior
-summary is never reused) and point `--out` at an equally fresh result receipt
-(`r=$(mktemp tmp/release-receipt.XXXXXX)`, #5983). 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) and to the release-type depth the guide demands — **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" --json --out "$r"`. 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.
-
-**Write the result receipt before bounded monitoring (#5983).** A background-task harness that bounds its
-output retains only the tail of the apply run — exactly where the accepted announcement outcome
-(`announceNote`) can be dropped. With `--out <path>`, the CLI itself writes the full apply result to the
-file as BOM-free UTF-8 (never a shell `>` redirect — see #5802), so the receipt survives any monitor
-bound. `--resume` proves the Release and deploy but does not and should not re-announce, so this receipt
-is the only durable record of the accepted Slack delivery — verify it in Step 6.
-
-**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>`.
-- **hub-serverless** (MMI-Hub) — repair the named deploy failure, then rerun the failed deploy run. Do not re-tag.
-
-Name the sanctioned dispatch mechanism you used in the train report.
-
-**Cut over after hook changes.** If this release changes or retires plugin hooks, stop this seat here.
-Complete the host's declared session/workspace reload or process restart, resume the train in that fresh
-seat, and run read-only `mmi-hub status` before any Step 4b shell/git command.
-
-## 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. 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.
-  A pre-#5903 CLI can true-merge this PR and still exit 1 with `mergeStatus: partial-cleanup` after GitHub
-  refuses to delete its protected `main` head. Classify that legacy receipt from the live PR: `MERGED` with
-  merge method `MERGE` means alignment succeeded and protected-main retention is expected. Never delete
-  `main`, retry the release, or call the alignment failed. Current CLIs report the same retention as
-  `remoteBranch.status: retained-protected` with `mergeStatus: merged`.
-- 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. Once that PR
-  lands, fast-forward the local branch yourself (`git pull --ff-only` on `development`) — #5908 retired
-  the session-start self-heal along with the rest of the hook-era plumbing. 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` 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
-
-Verify the Slack announcement from the receipt, not from memory (#5983). The `--out` receipt written at
-Step 4 is the durable record of the initial apply result; read its `announceNote` field before the final
-report and state the delivery verdict (`announced`, `skipped`, or the failure note). A monitor that kept
-only the apply output's tail may have dropped that line — the receipt is what keeps that from losing the
-outcome.
-
-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`, the bounded Latest
-Release read, and the runs on the release SHA; an alignment PR is normal follow-up work when those
-checks confirm the release shipped.
-
-Use only this bounded Latest Release read:
 ```bash
 gh api repos/{owner}/{repo}/releases/latest --jq '{tagName:.tag_name,targetCommitish:.target_commitish,publishedAt:.published_at,url:.html_url}'
 ```
-Require its `tagName` to equal the expected `$TAG`; a mismatch means Latest does not identify this
-release and is unverified.
 
-**`gh release view` has no `isLatest` field (#6019).** Never request Latest status through
-`gh release view`: the field is not in its JSON schema, so gh rejects the whole read and lists its
-supported fields — the check errors instead of answering, and Latest stays unverified. This bounded
-read is the supported Latest probe; `gh release list --json <fields>,isLatest` is the supported form
-only when a list receipt is genuinely the right shape.
+Four facts close the verdict: the `origin/main..origin/development` count, the tag on origin, Latest, and green runs on the release SHA.
 
-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).
+## Recovery
 
-**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.
+Every refusal and every doctor blocker names its `code` and `anchor`: open `docs/Guides/train-troubleshooting.md#<code>` and follow that entry, nothing else. A partial release (tag on origin, later phases pending or failed) continues with `mmi-cli devops release --resume --watch --json --out <fresh-receipt>` — the only continuation form: `--resume` never re-tags, republishes or re-announces, and `--apply` belongs to a new cut only. A refused train is a stop (Merge floor): fix the cause on `development` through a normal PR, then rerun.
 
-**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.
+## Merge floor
 
-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 the release-triggered `publish.yml` receipt with the same structured PowerShell probe above
-(`--workflow publish.yml --event release`), then confirm npm caught up:
-```powershell
-$runs = gh run list --workflow publish.yml --event release --limit 10 --json databaseId,createdAt,url,status,conclusion | ConvertFrom-Json
-$run = $runs |
-  Where-Object { $_.databaseId -and $_.createdAt } |
-  Sort-Object { [DateTimeOffset]$_.createdAt } -Descending |
-  Select-Object -First 1
-if (-not $run) { throw 'release-triggered publish workflow run was not found' }
-$run | Select-Object databaseId,createdAt,url,status,conclusion | ConvertTo-Json -Compress
-gh run watch $run.databaseId --exit-status
-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.
+- **Never squash-merge a tagged commit (#3167).** A squash re-mints the SHA and orphans the tag from the branch lineage, so every tag-anchored check mis-reads forever after. Any merge that carries an already-tagged commit — the `main → development` roll-forward, an alignment PR, a hotfix fold PR — lands as a true merge: `mmi-cli devops pr merge <number> --auto --merge` (or `--wait --merge`); `--wait` alone still squashes. The hotfix main-base PR itself may squash: its tag lands after, on the merged `main` HEAD, and the `-x` trailer must survive the squash message.
+- **A refused train is a stop, never a license to finish by hand.** Every fail-closed halt — doctor blocker, authority probe, coverage guard, untolerated conflict, required checks, stray tag, ledger — ends the run. Fix the cause on `development` through a normal PR and rerun the train; never hand-resolve on `main`, hand-cherry-pick, bare-push a train branch, ack to save time, or bypass a check.
+- **Version probes anchor on the latest Release tag, not a branch (#2734).** A branch manifest or a stale local tag is not a version source; a surviving local tag silently mints the next version.
+- **One train at a time on a repo (#5380).** Two overlapping runs race the shared tag namespace; the ledger refuses the second — never start one to help the first.
+- **Tag and Release deletion are deletion-class:** the authorized human's explicit per-turn go, named in the guide entry that prescribes it.
 
-**Build the tag checkout before verifying, or it refuses deterministically (#5814).** `verify` (without
-`--skip-npm-view`) runs a live `npm pack` per public surface, and `npm pack` refuses a package whose
-declared `bin` target is absent — e.g. `updater publishes bin jerv-hub -> dist/index.cjs, which npm pack
-does not ship — run npm run build`. Whether that bites depends on the repo: a build output that is
-**tracked** (MMI-Hub commits `updater/dist/index.cjs`) is present in a clean tag checkout, one that is
-**gitignored** is not, and a fresh clone has no `node_modules` either way. So provision the tag worktree
-first, and check the declared bin targets rather than assuming:
-```bash
-git worktree add "$PROOF" "vX.Y.0"      # $PROOF outside the repo — see the scratch note below
-cd "$PROOF" && npm ci && npm run build  # build only if a declared bin target is missing from the checkout
-node scripts/release-distribution.mjs verify "X.Y.0"
-```
-Removing that proof tree afterwards: `npm ci` writes `node_modules`, which `git status --porcelain`
-never shows and which makes `git worktree remove` refuse with `Directory not empty`. Delete
-`node_modules` first, then remove the worktree. On Windows a global install made from a worktree leaves
-a junction there, so delete the directory rather than following it. In a guarded agent shell pass the
-**literal absolute** proof path to `git worktree remove` — the checkout guard refuses a variable-held
-target (`Blocked git worktree remove with an unanalyzable variable-held target`, #2492 / #6060); only an
-interactive shell may pass `"$PROOF"`.
-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 "X.Y.0"`
-from a machine with npm auth.
+## Report
 
-**Windows WebAuthn/passkey exception (#5920).** Normal publishing remains non-interactive and token-based;
-headless and CI hosts keep using automation tokens. When any npm write requires a human desktop passkey on
-Windows, **never run it from the agent shell**. Write the package loop to a durable `.cmd` outside disposable
-worktrees (for example, `C:\Users\<you>\Documents\mmi-npm-write.cmd`):
-```bat
-@echo off
-set "failures=%~dpn0.failures.txt"
-del "%failures%" 2>nul
-for %%P in (@scope/package-a @scope/package-b) do (
-  call npm deprecate "%%P@*" "replacement message"
-  if errorlevel 1 >>"%failures%" echo %%P
-)
-if exist "%failures%" type "%failures%"
-```
-Launch it visibly and leave the window open, then let the human tap once for each npm invocation:
-```powershell
-Start-Process cmd -ArgumentList '/k', 'C:\Users\<you>\Documents\mmi-npm-write.cmd'
-```
-Ignore any EOTP browser URL npm prints; it does not complete this passkey flow. Treat the failure file as the
-per-package receipt and verify the corresponding registry state, for example
-`npm view <pkg> deprecated --prefer-online` after `npm deprecate`.
+Title first, verdict first. Name the resolved tag (never a placeholder like `vX.Y.0`) and the Release URL, the receipt's status fields (`releaseStatus`, `followUpStatus`, `deployStatus`, `promoted`), every `workflowRuns` entry with its conclusion and URL — saying which run is red, and whether it is a deploy/publish verdict or ordinary CI — `announceNote`, the alignment note (`devRollForward`, `rcAlignment`, or the hotfix fold PR and whether it landed), the `checkout` clause, and the sanctioned dispatch mechanism you used. A pending follow-up is reported as unverified, never as success. Product names appear only when releasing that product's repo.
 
-**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 for surfaces with no publish-time staged payload, 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
-  compare the trees (do not alarm on SSRI alone). On Windows unpack with the native
-  `%SystemRoot%\System32\tar.exe` named explicitly — a bare `tar.exe` can resolve to Git's GNU tar
-  through PATH, which reads a drive-letter path as a remote host (`Cannot connect to C: resolve
-  failed`, #6059) — and run `npm pack` from the package directory (`cd` there; no positional path
-  and no `--pack-destination` under a path with spaces), since routing npm through `cmd.exe /c`
-  reparses quoted paths (#6058). Hub host-plugin npm surfaces stage the canonical
-  `skills/` tree and declared hook-policy `scripts/` into the package at publish time via
-  `assembleDeclaredPayloads` (#5471); those paths are gitignored and absent from a plain tag checkout,
-  so a local `npm pack` without staging cannot reproduce them and an empty `diff -r` is an unreachable
-  bar (#5677), not evidence of substitution. For those surfaces, prove identity in two parts:
-  1. **Committed package content** — `diff -r` the unpacked trees while excluding each publish-time
-     staged path relative to the package root (for `@mutmutco/claude-plugin`:
-     `diff -r -x skills -x scripts …`; list all staged targets with
-     `node --input-type=module -e "import { generatedPayloadPaths } from './scripts/distribution-assembly.mjs'; console.log(generatedPayloadPaths().join('\\n'))"` and strip each surface's `assembly.rootPath` prefix). Empty diff ⇒ the committed package matches.
-  2. **Staged payload** — for each excluded path, compare the registry unpacked copy against the tag
-     checkout repo source named in that surface's `surfaces.json` assembly sync (`directories` sync:
-     `diff -r reg/package/skills skills/`; `files` sync: `cmp` each `include` entry against
-     `<sourcePath>/<name>`). Alternatively, run
-     `node --input-type=module -e "import { assembleDeclaredPayloads } from './scripts/distribution-assembly.mjs'; assembleDeclaredPayloads()"` on the tag checkout before the local `npm pack` so a plain `diff -r` compares the full publish payload.
-  Surfaces with no publish-time staged payload still use a plain `diff -r` (empty diff ⇒ identity OK), 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 (including the staged-payload split above when applicable).
+## Retro
 
-**Unpacked proof scratch must not pollute the checkout (#5702).** npm unpack copies full package trees
-including staged `skills/` into whatever directory you choose. Those copies are **not** registered skill
-payloads — if they remain anywhere scannable under the repo root when the next release fold runs
-`check-skill-payload`, the gate fails with `unregistered authored or copied skills`. Prefer unpacking
-**outside** the repository:
-```bash
-PROOF=$(mktemp -d "${TMPDIR:-/tmp}/mmi-release-proof.XXXXXX")
-# unpack both tarballs under $PROOF, diff -r, then:
-rm -rf "$PROOF"
-```
-If you must unpack inside the checkout, use the org-managed gitignored scratch at repo-root `tmp/`
-(`mktemp -d tmp/mmi-release-proof.XXXXXX`) — **not** `.jerv/tmp/` (agent session scratch still lives on
-disk and must not carry npm proof trees between releases). Remove the proof tree **immediately** after the
-diff succeeds; do not leave it for the next `--apply`.
+Before the 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. If yes, file one lesson and move on; a clean run is silent (hard cap: one per run). It lands on the Hub board, deduplicated, and is fixed only through a reviewed PR — never edit the skill live. The retro is advisory: if the call fails, note it and continue.
 
-Before the next `release --apply`, confirm no leftover proof copies remain outside org scratch:
 ```bash
-node scripts/check-skill-payload.mjs --contract
+mmi-cli learning skill-lesson --skill release --title "<what misfired>" --body "<what; evidence; proposed amendment>"
 ```
-A failure naming `unregistered authored or copied skills` means a proof tree (or other rogue copy) is
-still on disk — delete it and rerun the contract check before retrying the train.
-
-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
-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).
-For Jerv-Hub, also report the `jerv-gateway` exact-commit deployment and health verdict; npm green without
-Gateway green is a failed follow-up, never a complete Jerv-Hub release.
-
-## 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>"`