@mutmutco/codex-plugin 4.3.5 → 4.3.7

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mmi",
-  "version": "4.3.5",
+  "version": "4.3.7",
   "mmiCompat": "4.x",
   "description": "MMI workflow skills and org gates delivery.",
   "author": {

package/package.json

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

package/skills/bootstrap/SKILL.md

@@ -125,15 +125,18 @@ mmi-cli devops bootstrap verify "$OWNER/$REPO" --class content --json
 ```
 
 Run it again after Step 7. A repo is not ready for real developers until every check is green, or the report
-names an explicitly manual-only item that the master has accepted for that repo.
+names an explicitly manual-only item that the master has accepted for that repo. For a deployable repo the
+report ends with the train doctor verdict per lane (`release`; plus `rcand` on a full track) — the same
+`mmi-cli devops train doctor` door `/release` and `/rcand` open (#6070); a `ready: false` there is an
+unfinished repo.
 
-**Two verify FAILs are un-run manual steps or API lag, not code bugs — diagnose them as such, but never as
+**Two verify FAILs are un-run apply steps or API lag, not code bugs — diagnose them as such, but never as
 acceptable end states (#2928):**
-- `branch protection exists` / `push allowlist configured` — **`bootstrap apply` does not apply branch
-  protection.** That is **Step 2b**, and it is manual, so these FAIL until you run it. **Step 2b is
-  mandatory**: these are security controls, and they must go green (or be an explicitly master-accepted
-  manual item per the rule above) before the bootstrap is complete. A red branch-protection or
-  push-allowlist check is an **unfinished repo**, never a known-benign FAIL to sign off around.
+- `branch protection exists` / `push allowlist configured` — **`bootstrap apply --execute` applies the
+  train-branch push allowlist (Step 2b)**, so these FAIL until the live apply has run. They are security
+  controls and must go green (or be an explicitly master-accepted manual item per the rule above) before
+  the bootstrap is complete. A red branch-protection or push-allowlist check is an **unfinished repo**,
+  never a known-benign FAIL to sign off around.
 - `README has Agent context section — README.md not readable via API` on a README that demonstrably has the
   section — GitHub's contents API lags for a minute or so right after a merge. **Re-run before believing a
   content-read failure**; it clears on its own.
@@ -193,29 +196,21 @@ so a direct-track repo never gets a stray `rc` the `mmi-train-floor` ruleset can
 Ensure exactly the track's permanent branches exist and set the default branch — create only what the track
 uses; never create an `rc` for a direct-track repo.
 
-**Create `rc`/`main` server-side, not with `git push` (#3433).** The local **#1660 protected-branch push
-guard** fences every push to `main`/`master`/`rc`, including the legitimate *creation* of those refs on a
-brand-new repo — so a `git push origin development rc main` cannot be run as written. Creating the refs
-through the API is not a force-push, so both the #1660 guard and the `mmi-train-floor` ruleset allow it, and
-it behaves the same on every machine. `development` (or `main`, for a content repo) already exists from
-Step 0b:
+**`bootstrap apply --execute` creates `rc`/`main` server-side from the track's first branch (#6070).** The
+local **#1660 protected-branch push guard** fences every push to `main`/`master`/`rc`, including the
+legitimate *creation* of those refs on a brand-new repo (#3433); a ref created through the API is not a
+force-push, so both the guard and the `mmi-train-floor` ruleset allow it. The apply's train-readiness plan
+prints one `lane-branch` row per track branch — `CREATE` (missing), `SKIP` (already exists), or `GAP`
+(`bootstrap-gap`: the first branch from Step 0b is missing, so there is no source ref) — and the live apply
+creates every `CREATE` row; a `422 Reference already exists` reply is the idempotent no-op, not a failure.
+`development` (or `main`, for a content repo) already exists from Step 0b. Only the default branch stays a
+`gh` write:
 ```bash
-sha=$(gh api "repos/$OWNER/$REPO/git/ref/heads/development" --jq '.object.sha')
-
-# full — development (Step 0b) + rc + main
-gh api "repos/$OWNER/$REPO/git/refs" -f ref=refs/heads/rc   -f sha="$sha"
-gh api "repos/$OWNER/$REPO/git/refs" -f ref=refs/heads/main -f sha="$sha"
-gh repo edit "$OWNER/$REPO" --default-branch development
-
-# direct — development (Step 0b) + main, NO rc
-gh api "repos/$OWNER/$REPO/git/refs" -f ref=refs/heads/main -f sha="$sha"
-gh repo edit "$OWNER/$REPO" --default-branch development
-
-# trunk (content) — main only; Step 0b already created it with `-b main`
-gh repo edit "$OWNER/$REPO" --default-branch main
+gh repo edit "$OWNER/$REPO" --default-branch development   # full / direct
+gh repo edit "$OWNER/$REPO" --default-branch main          # trunk (content)
 ```
-Re-running a create on a ref that already exists returns `422 Reference already exists` — that is the
-idempotent no-op, not a failure. Verify with `gh api "repos/$OWNER/$REPO/branches" --jq '.[].name'`.
+Verify with `gh api "repos/$OWNER/$REPO/branches" --jq '.[].name'`, or read the `lane-branch` rows of the
+next dry-run `bootstrap apply`.
 
 ## Step 2 — authority (org Ruleset)
 
@@ -229,39 +224,19 @@ apply those contexts org-wide unless every target repo exposes them.
 
 ## Step 2b — lock the train branches (who can push)
 
-The ruleset says *a PR is required*; this says *who may merge it*. Apply classic branch protection on
-`development`/`rc`/`main` for deployable repos, or just `main` for content repos, with **"Restrict who can
-push"** = the master + the App (the repo's full-write people get added at Step 4b). Everyone else is
-`write`-locked on protected branches: they push feature branches and open PRs but cannot merge there. Run per
-protected branch (App token):
+The ruleset says *a PR is required*; this says *who may merge it*. `bootstrap apply --execute` applies the
+classic branch protection on `development`/`rc`/`main` for deployable repos, or just `main` for content
+repos, with **"Restrict who can push"** = the org owners + the App (#6070): the owners are resolved live
+from the GitHub org admins (`orgs/$OWNER/members?role=admin`), never a hard-coded user list — an empty
+resolution refuses to write an empty allowlist — and the App is `mmi-github-app`. The repo's full-write
+people get added at Step 4b. Everyone else is `write`-locked on protected branches: they push feature
+branches and open PRs but cannot merge there.
 
-```bash
-BRANCHES="development rc main"           # full
-BRANCHES="development main"               # direct (no rc)
-BRANCHES="main"                          # trunk / content
-
-mapfile -t MASTER_USERS < <(gh api --paginate "orgs/$OWNER/members?role=admin" --jq '.[].login')
-if [ "${#MASTER_USERS[@]}" -eq 0 ]; then
-  echo "No org owners resolved for $OWNER; stop before writing branch protection." >&2
-  exit 1
-fi
-USERS_JSON=$(printf '%s\n' "${MASTER_USERS[@]}" | node -e "const fs=require('fs'); const users=fs.readFileSync(0,'utf8').trim().split(/\r?\n/).filter(Boolean); process.stdout.write(JSON.stringify(users));")
-
-for b in $BRANCHES; do
-  node - "$USERS_JSON" <<'NODE' | gh api --method PUT repos/$OWNER/$REPO/branches/$b/protection --input -
-const users = JSON.parse(process.argv[2]);
-process.stdout.write(JSON.stringify({
-  required_status_checks: null,
-  enforce_admins: false,
-  required_pull_request_reviews: null,
-  restrictions: { users, teams: [], apps: ['mmi-github-app'] },
-}, null, 2));
-NODE
-done
-```
-
-Only the master (sole repo `admin`) can change this afterward. Full grant/lock mechanics + inspect commands:
-`docs/Guides/repo-access.md`.
+The plan prints one `push-allowlist` row per track branch — `UPDATE` (preserve every existing
+review/status/admin/force-push bit and replace only the push restriction), `SKIP` (exact owners + App
+already present), or `GAP` (`bootstrap-gap`: the protection read failed; zero writes are performed while any
+control-plane read is unverified). Only the master (sole repo `admin`) can change this afterward. Full
+grant/lock mechanics + inspect commands: `docs/Guides/repo-access.md`.
 
 ## Step 3 — attach to the repo's Project (one board per repo; confirm)
 
@@ -336,6 +311,9 @@ box assignment** — the `sshHost` (and the loopback port) per stage — then wr
 `mmi-cli oracle org project set-deploy <owner/repo> --stage <dev|rc|main> --ssh-host <host> [--port <p>]` (defaults:
 `substrate: hetzner-ssh`, deploy path `/opt/mmi/<slug>/<stage>`, service = slug, ssh-user `root`). Without those
 rows the tenant cannot deploy (`tenant-deploy.yml` errors on missing `DEPLOY#` coords), so do not skip this.
+`bootstrap apply` prints one `deploy-row` row per track stage for container models (#6070): `SKIP` when the
+registry row exists, `GAP` (`bootstrap-gap`) with the exact `set-deploy` command otherwise — a box
+assignment cannot be invented, so this row is the one train-readiness fact the apply never writes itself.
 Keep every runtime config value in the vault; never paste secret values into logs.
 
 Only an AWS `tenant-container` (the exception) provisions the reusable tenant stack: release bucket,
@@ -390,13 +368,15 @@ collaborator list + the per-branch allowlist are the record — no separate rost
   under the org **wall-clock budget** (#3178): the render pins `run-with-budget` to the CLI's blessed SHA
   with `--var GATE_MAX_SECONDS=` (300s onboarding default — tighten once the gate is measured, via
   `--var` or `org project set <repo> --var gate={"maxSeconds":N}`); `ci audit` and the release train
-  both enforce the step, so do not remove it. After apply,
-  master-admin must **activate** that JSON as a repository ruleset (GitHub → Settings → Rules → Rulesets →
-  Import/create from the committed reference) so the `gate` context is required on train branches. Once the
-  gate is green on `development`, `mmi-cli devops ci reconcile --apply --repo $OWNER/$REPO` should flip enforcement
-  to **Active**; if it does not, use the Step 5 PUT fallback and confirm with `bootstrap verify` before
-  reporting bootstrap complete. MMI-Hub keeps its own three-job gate (`cli`/`infra`/`docs`) — never apply the
-  product ruleset there.
+  both enforce the step, so do not remove it. `bootstrap apply --execute` installs that JSON as the
+  repository ruleset itself (#6070) and reports one `product-ruleset` row: `PARK` (the gate file is not on
+  the base branch yet — installed disabled), `WAIT` (the gate exists but has not emitted a proven-green
+  `gate` context — kept disabled; re-run apply after the gate passes), `ACTIVATE` (gate green — enforcement
+  active), or `SKIP` (already exact). The activation boundary is fail-closed on purpose: a required context
+  that cannot pass yet would lock the seed PR behind itself. `mmi-cli devops ci reconcile --apply --repo
+  $OWNER/$REPO` remains the supported fallback; confirm `product required-check ruleset enforcement active`
+  with `bootstrap verify` before reporting bootstrap complete. MMI-Hub keeps its own three-job gate
+  (`cli`/`infra`/`docs`) — never apply the product ruleset there.
 - **A brand-new repo cannot pass the gate you just installed — its first commit must carry a real project
   (#2928).** The seeded `gate.yml` runs `GATE_INSTALL_CMD` + `GATE_CMD` (`npm ci` + `npm run check` by
   default) **unconditionally**. An empty repo has no `package.json`, so the gate **fails on the seed PR
@@ -552,7 +532,16 @@ Repo, default branch, ruleset applied, train branches locked (push allowlist), r
 provisioned per track (plan-gated protections named in apply output), project attached/created
 (+ info seeded, Status lanes and Labels field verified), secrets set (names only), developer access, plugin
 installed, docs seeded, registry META written, issue templates committed, org App credentials registered,
-org-managed `.gitignore` block seeded, and the final `mmi-cli devops bootstrap verify "$OWNER/$REPO" --class ... --json` result.
+org-managed `.gitignore` block seeded, the final `mmi-cli devops bootstrap verify "$OWNER/$REPO" --class ... --json` result,
+and — for a deployable repo — the train door itself, run from the repo's own checkout on `development`:
+
+```bash
+mmi-cli devops train doctor --lane release --repo "$OWNER/$REPO" --json
+```
+
+`ready: true` is the bootstrap's train-readiness proof; every finding carries `code`, `severity`, `source`,
+`remedy` and a `docs/Guides/train-troubleshooting.md#<code>` anchor. A full-track repo runs
+`--lane rcand` as well. A `bootstrap-gap` blocker names the apply row still missing.
 
 ## Retro — one check before you finish
 Before your final report, answer one question honestly: did **this skill's own instructions** misfire

package/skills/hotfix/SKILL.md

@@ -5,172 +5,97 @@ description: Promote an already-merged development fix to main and production th
 
 **Host-native invocation:** Claude `/mmi:hotfix` · Codex `$mmi:hotfix` · Cursor `/hotfix` · jervcode `/hotfix` · Hermes skill_view. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
 
+**Argument:** none. A hotfix is PATCH-only; leave `MMI_BUMP_INTENT` and `MMI_RELEASE_VERSION` unset — a non-patch declaration refuses.
+
 # /hotfix — promote a development fix to main + prod
 
-A hotfix is promotion, not authoring. The fix must land on `development` through a normal issue,
-worktree, PR, review, and CI gate first. Hub then ports that merged PR or SHA to a main-base hotfix PR,
-preserves the cherry-pick audit trail, and performs the PATCH release. Never author directly from `main`.
-Never author the fix on a branch off `main`. The main-base branch is only the orchestrated port of a fix
-that is already merged to `development`.
-
-The FIX is never back-merged: `development` already contains it, and `rc` absorbs it at the next
-`/rcand`. The release hotfix-coverage guard blocks a later candidate that omits the production fix.
-
-The VERSION FOLD is different, and `hotfix release` ports it for you (#4410). `hotfix start` commits the
-fold onto the main-base branch, so after the tag `main` declares the new version while `development`
-still declares the old one. The Hub's catalogs now pin exact npm packages (#4948), so there is no
-branch/content lockstep red; the fold still must land so the next release starts from production's real
-version, BOM, and package pins. Step 3 opens that development-base fold PR automatically; land it.
-
-## Merge floor (#3167 — non-negotiable)
-
-- **Never squash-merge a tagged commit.** The hotfix PR itself may squash (step 2 — the tag lands *after*,
-  on the merged `main` HEAD, and the `-x` trailer must survive the squash message). But any merge that
-  carries an already-tagged commit — an alignment PR, a later `main → development` roll-forward — lands as a
-  true merge, never squash: a squash re-mints the SHA and orphans the tag from the branch lineage.
-- **A refused release train is a stop, never a license to finish by hand.** A conflict on the port, a red
-  authority probe, a failed required check, a refused `hotfix release` — each ends the run. Fix the cause on
-  `development` through a normal PR and re-run the orchestrator; never hand-cherry-pick, bare-push, or
-  bypass the gate to finish.
-- **Version probes anchor on the latest Release tag, not a branch.** `hotfix status` derives the PATCH from
-  the latest Release tag; branch manifests and stale local tags are not version sources.
-
-## Authority and preflight
-
-Production changes require the authorized human's explicit approval in the current turn. Before describing
-or executing any hotfix lane, read the project META and name the lane (#5244 — same gate as `/release`):
+A hotfix is promotion, not authoring. The fix lands on `development` first through a normal issue, worktree, PR, review and CI gate; Hub then ports that merged PR or SHA onto a main-base branch as a cherry-pick with `-x`, keeps the audit trail, and performs the PATCH release. Never author the fix on a branch off `main`. The FIX is never back-merged: `development` already has it, `rc` absorbs it at the next `/rcand`, and the release hotfix-coverage guard blocks a later candidate that omits it. The VERSION FOLD is different: `hotfix release` ports it to `development` as a fold PR — NOT a back-merge, nothing from `main` is merged into `development`.
+
+## Lane
+
+Read META and name the lane before describing or executing anything:
+
 ```bash
 mmi-cli oracle org project get {owner}/{repo} --json
 ```
-`releaseTrack: direct` means `development → main` only — **no `rc` branch** (MMI-Hub included via the
-Hub-control special case). Stop on an unreadable META record; never infer the lane from branch names or
-release history.
 
-Verify authority and CLI health before starting:
+A hotfix always skips rc on every track: it cherry-picks `development → main` directly, MMI-Hub included. `deployModel` decides the release-triggered runs the train watches. Unreadable META → stop; never infer the lane from branch names, tags or release history.
+
+## Preflight
 
 ```bash
-mmi-cli oracle org access role <owner/repo> --json
-mmi-cli doctor --no-repo-writes
+mmi-cli devops train doctor --lane hotfix --heal --json
 ```
 
-Stop on a red authority or CLI-version result. Hub hotfix release runs the same distribution fold as
-`/release`; its hook-contract verifier executes adapter commands as a native argv without a shell
-(#5605), so a checkout path containing spaces is supported.
+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. `hotfix start` and `hotfix release` re-run this doctor as their step 0 with heal on.
 
-The worktree must be clean; move scratch into `tmp/` or
-gitignore it rather than widening the hotfix diff. A TRACKED path named in a `working tree must be clean
-before …` refusal is not scratch: read both `git status --porcelain` columns, treat every state except
-exactly ` M` as real work to commit or stash, and for ` M` discard only when
-`git diff HEAD --numstat -- <paths>` is empty, and only with `git checkout -- <paths>`. Plain
-`git diff --numstat` prints nothing for a merely staged change, so it cannot make that call (#4004).
+## Apply
 
-## 1. Start from the merged development fix
+Run from the primary checkout. One cycle carries as many merged fixes as you name, in pick order.
 
-Use the orchestrator with an explicit source every time:
+1. Start from the merged development fix(es):
 
 ```bash
-mmi-cli devops hotfix start --from <development-pr-or-sha>[,<development-pr-or-sha>...] --json
+r1=$(mktemp tmp/hotfix-start.XXXXXX)
+mmi-cli devops hotfix start --from <pr|sha>[,<pr|sha>…] --json --out "$r1"
 ```
 
-**One hotfix cycle carries as many merged fixes as you name.** `--from` takes a comma-separated list in
-pick order, and every sha it picks goes into the PR's carries marker, so the release proves each one
-present before tagging. Do not open one hotfix per fix: batch everything ready for production into the
-single PATCH. A fix that only becomes ready mid-cycle rides the same tag — cherry-pick it with `-x` onto
-a `hotfix/<tag>-<n>` continuation branch, merge that PR, and rerun `hotfix release` with the full
-`--carries` list; the release pins the newest merged SHA (#1025).
-
-`hotfix start` resolves the PATCH version, branches from `origin/main`, performs the cherry-pick with `-x`,
-prepares Hub distribution artifacts when applicable (stamping BOM `sourceCommit` at the durable
-`origin/main` merge-base so a squash merge cannot orphan it — #4361; and for `registry-publish`
-consumers, folds the package version so upgrade probes observe the PATCH), pushes the branch, and opens
-the main-base PR. Do not duplicate those steps with raw branch commands, manual cherry-picks, or raw
-GitHub PR creation.
-
-Conflicts confined to regenerable distribution / version-fold paths (e.g. Hub `distribution-bom.json`,
-locked plugin manifests, consumer `package.json`) — and, for hub-serverless + registry-publish, the
-canonical skill root `skills/` (#4363 / #4471) — are auto-resolved (take the picked side) and regenerated
-by the bump/fold step. Source TS under `src/` / `cli/src/` is never auto-resolved.
-
-Before cutting the hotfix branch, `hotfix start` preflights every `--from` pick on an accumulating
-`origin/main` tree (#4472). If any pick would hard-stop, it refuses with every failing pick and path and
-prescribes **one** development-based cite-only synthesis PR for the whole batch (#4643; the old
-"cut from origin/main" pattern #4467 wording is retired — a main-parented branch must never merge
-into development, #4365/#4371): cut from `origin/development`, regenerate the conflicting content so
-it cherry-picks cleanly onto `origin/main`, land it with the cite-only marker (the #5096 flow) — not N
-serial ports. Behavior changes still land on `development` first through a normal PR, then rerun hotfix
-start from the port merge SHA(s) — never hand-resolve onto main.
-
-## 2. Verify the hotfix PR
-
-Run the repo's local gate against the hotfix branch, then obtain the independent reviewer required by the
-active agent doctrine. Review the actual main-base diff and the original issue acceptance criteria.
-
-Wait for required CI through Hub:
+`hotfix start` derives the PATCH from the latest Release tag on `origin/main`, branches `hotfix/vX.Y.Z` from `origin/main`, cherry-picks with `-x`, folds the version, pushes, and opens the main-base PR with its carries marker. Never duplicate those steps with raw branch, cherry-pick or PR commands.
+
+2. Verify the main-base PR: the repo's local gate on the hotfix branch, the independent review the active agent doctrine requires, and the original issue's acceptance criteria. Then wait for required CI and merge through Hub — the PR may squash, and the `-x` trailer must survive in the squash message:
 
 ```bash
-mmi-cli devops pr checks-wait <hotfix-pr-number>
+mmi-cli devops pr checks-wait <number>
 mmi-cli devops pr merge <number> --squash
 ```
 
-The main-base PR is the production gate. Do not bypass checks or protected-branch authority. After the
-authorized merge, verify the merged main commit still carries the cherry-pick provenance; if the PR was
-squashed, the source trailer must survive in the squash message so future coverage checks remain exact.
-Because Hub's default branch is `development`, the main-base hotfix PR does not close a separate tracking
-issue. The development PR should already have closed the work item; do not add raw GitHub issue operations.
+Because Hub's default branch is `development`, the main-base PR closes no tracking issue — the development PR already did; add no raw GitHub issue operations.
 
-## 3. Run the gated release
-
-Derive the tag from `mmi-cli devops hotfix status`, then release with the same declared source:
+3. Release, naming every fix the cycle carries (each is proven an ancestor of the tagged SHA before tagging):
 
 ```bash
-mmi-cli devops hotfix status
-mmi-cli devops hotfix release <vX.Y.Z> --carries <development-pr-or-sha>[,<development-pr-or-sha>...]
+r2=$(mktemp tmp/hotfix-release.XXXXXX)
+mmi-cli devops hotfix status --json
+mmi-cli devops hotfix release vX.Y.Z --carries <pr|sha>[,<pr|sha>…] --json --out "$r2"
 ```
 
-Name **every** fix the cycle carries. Each is proven an ancestor of the tagged SHA before tagging; a
-missing one refuses the release and names the continuation path.
+MMI-Hub adds `--announce-summary-file "$f"` with a fresh 3–6 line neutral summary — never a product or brand name; Hub scope is only `mutmutco/MMI-Hub`, never a product's board or `ds-propagate.yml`. `hotfix release` tags, publishes the Release, watches the release-triggered runs, verifies distribution, announces (Hub), and opens the `hotfix-fold/<tag>` development fold PR. Do not hand-dispatch a second publish or deploy path: duplicate release events race or double-publish.
+
+## Verify
+
+Read the receipts, never the exit code (exit `2` = a follow-up pending; exit `1` = a follow-up failed after the tag):
 
-For MMI-Hub, pass a fresh 2-4 line neutral summary file with `--announce-summary-file`; never reuse a
-stale file and never put a product or brand name in the summary. Hub release scope never includes another
-repo's board or `ds-propagate.yml`. The orchestrator creates the tag and GitHub Release, selects the
-registry-declared deploy path, watches the release-triggered or central deployment, verifies distribution,
-and announces best-effort. Do not hand-dispatch a second publish/deploy path: duplicate release events can
-race or double-publish.
+- `runs[]` — the release-triggered runs on the tagged SHA (workflow, conclusion, url). 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` is a deploy or publish verdict; a `gate` push run is ordinary CI sharing the SHA.
+- `foldStatus` + `foldNote` — the `hotfix-fold/<tag>` development PR; land it by true merge (Merge floor) and say whether it landed.
+- `announceNote` (Hub), `verifyNote`, `checkout`, `localSync`, `ledger` — the durable phase legs; a pending or failed leg is unresolved, never done.
 
-For a private package, trust the authenticated publish job and its logged package/version result; a bare
-unauthenticated `npm view` cannot distinguish private from missing.
+`mmi-cli devops hotfix status vX.Y.Z --json` re-derives the whole pipeline from live reads (`state`, `tagPushed`, `releaseExists`, `runs`, `alignmentStatus`, `npmVersion`, `next`). Then the bounded Latest Release read; its `tagName` must equal the tag:
 
-## 4. Verify and report
+```bash
+gh api repos/{owner}/{repo}/releases/latest --jq '{tagName:.tag_name,targetCommitish:.target_commitish,publishedAt:.published_at,url:.html_url}'
+```
 
-Report the tag and Release URL, production run and URL, source development PR/SHA, hotfix PR, and these
-branch facts:
+Branch facts close the verdict: the tag commit is on `origin/main`; `development` already had the fix before the hotfix began; `rc` is untouched by design; the fold PR landed or is named as pending.
 
-- `main`: the tag commit is on `origin/main`.
-- `development`: the source fix was already merged before the hotfix began.
-- `rc`: intentionally untouched; the next release coverage gate prevents regression.
-- the development fold PR the release opened (`hotfix-fold/<tag>`), and whether it landed.
+## Recovery
 
-Do not hand-open a manifest-alignment PR: the version fold is already ported by `hotfix release` — land
-its PR instead of authoring one. That port is explicitly NOT a back-merge — nothing from `main` is
-merged into `development`; the fold is regenerated on a branch cut from `development` itself. If the run
-reported `development fold port FAILED`, follow the manual remedy it named; never improvise a merge from
-`main`.
+Every refusal and every doctor blocker names its `code` and `anchor`: open `docs/Guides/train-troubleshooting.md#<code>` and follow that entry, nothing else. The hotfix subcommands are idempotent, so after an interruption rerun the identical `mmi-cli devops hotfix release vX.Y.Z --carries …` — each effect is checked before it is re-attempted, and the ledger names that rerun as this lane's continuation; `--resume --watch --json` is the release and rcand ledgers' only continuation form and never a hotfix one. A refused pick, a port conflict, a red authority probe, a failed check, a missing carry, or `development fold port FAILED` each ends the run (Merge floor): fix the cause on `development` through a normal PR, then rerun from the port merge SHA — never improvise a merge from `main`.
 
-### Development fold after a hotfix (#4517 / #4948)
+## Merge floor
 
-The Hub's thin catalogs now pin exact npm packages, so the old main-anchored catalog-lockstep gate is
-retired: an unreleased branch cannot deliver a package version the release train has not published.
-Hotfix versioning still belongs on the main-base train, never in an improvised development prepare PR:
+- **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.
 
-1. `mmi-cli devops hotfix start --from <merged-dev-pr-or-sha>` (prepare + distribution bump on `hotfix/vX.Y.Z` from `main`)
-2. merge the hotfix PR → `mmi-cli devops hotfix release vX.Y.Z` (publish)
-3. land the automatic `hotfix-fold/<tag>` development fold PR (or follow its printed remedy)
+## Report
 
-The fold is now required for version/BOM/package-pin continuity, not to clear a branch-content gate.
+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`), and every workflow run row with its conclusion and evidence — use its URL when emitted, otherwise the receipt's explicit no-run-URL note — 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.
 
 ## Retro
 
-If this skill's instructions themselves misfired, file one deduplicated lesson and continue:
+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.
 
 ```bash
 mmi-cli learning skill-lesson --skill hotfix --title "<what misfired>" --body "<what; evidence; proposed amendment>"