@mutmutco/kilo-plugin 3.79.0

package/skills/release/SKILL.md

@@ -0,0 +1,546 @@
+---
+name: release
+description: Ship rc or direct-track development to main and production.
+---
+
+# /release — ship to main + prod
+
+Full-track repos ship **exactly what is on `rc`** (never pulls `development`): merge `rc → main`, tag
+`vX.Y.0`, publish a GitHub Release, dispatch the Hub central tenant deploy workflow for prod, then roll
+`development` forward. Direct-track repos — product repos with `releaseTrack: direct`, plus MMI-Hub via the `isHubControlRepo` special-case (its `releaseTrack` stays unset) — skip rc: release
+merges `development → main`, tags, publishes the GitHub Release, and the release event fires the repo's own
+deploy/publish workflow (for MMI-Hub, `deploy.yml` + `publish.yml`).
+`rc` is **ephemeral**: `/rcand` creates the rc runtime, `/release` retires it — after a confirmed full-track
+prod deploy the train stops the rc stage (reported as `rcRetirement` in the result; never fatal to the
+release). Full-track repos may also pass **`--dev`** to release `development → main` directly, skipping rc —
+the default stays `rc → main`. `--dev` **fails closed** when `origin/rc` carries content not yet in
+`development` (a dev → main release would drop it), and is a friendly no-op on direct-track repos.
+**Train-authority gated (D14):** the repo's project-admin or the master; the Hub repo's train is
+master-only. This is the **only** sanctioned prod path; a prod release still needs the authorized human's
+explicit per-turn go — an agent never self-initiates it. The board needs no
+touch — items reached `Done` when their PRs merged to `development`; `rc`/`main` are deploy stages, not lanes.
+
+Authority is structural + server-checked: step 0 asks the Hub (`mmi-cli org access role`), and step 3 pushes
+to the protected `main` branch, whose per-repo allowlist carries the same people (master + that repo's
+project-admins; Hub: master + App only). Gate ordering: the tag lands the release SHA for checks, and
+nothing deploys before the protected `main` push accepts that checked SHA.
+
+## Merge floor (#3167 — non-negotiable, applies to every step below)
+
+- **Never squash-merge a tagged commit.** A squash re-mints the SHA, so the tag's commit vanishes from the
+  branch's lineage and every tag-anchored check (coverage trailers, misalignment guard, version probes)
+  re-flags or mis-reads forever after. Any merge that carries an already-tagged commit — the Step 5
+  `main → development` roll-forward, any alignment PR — lands as a **true merge** (`--merge`), never squash.
+- **A refused train is a stop, never a license to finish by hand.** Every fail-closed halt below — authority
+  probe, coverage guard, untolerated conflict, required checks, stray tag — ends the run. The recovery is
+  always to fix the cause and re-run the train; it is never hand-resolving on `main`, bare-pushing a train
+  branch, acking to save time, or bypassing a check.
+- **Version probes anchor on the latest Release tag, not a branch.** `next-version.mjs` and the fold derive
+  the next version from tags; a branch manifest or a stale local tag is not a version source. (This is why a
+  stray tag must be deleted locally too — a surviving local tag silently mints the *next* version, Step 3.)
+
+## Step 0 — confirm + probe
+
+Confirm the human holding train authority for THIS repo authorized a prod release this turn. Probe:
+```bash
+mmi-cli 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. **Two exceptions to fail-closed here, and both
+mean "unverified — retry", never an authority verdict:**
+
+- An `unknown command 'org'` error is a STALE CLI — the `org` namespace ships 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).
+- 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`.
+
+**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 — if `--apply` stops
+with `working tree must be clean before …`, run `git status` and gitignore the `??` scratch (or move it to a
+gitignored path like `tmp/`) before retrying (#1472).
+
+Full-track repos:
+```bash
+git fetch origin
+git rev-list --count origin/main..origin/rc
+```
+
+Direct-track repos (e.g. MMI-Hub):
+```bash
+git fetch origin
+git rev-list --count origin/main..origin/development
+```
+`0` → stop ("nothing to release").
+
+## Step 0a — stale CLI preflight (#1410)
+
+Before local gates or `release --apply`, ensure the repo-local / PATH `mmi-cli` matches the released train
+path — a stale checkout (e.g. 2.32.0 while 2.32.4 is released) fails release gates with opaque errors.
+Self-heal in place without repo writes:
+```bash
+mmi-cli doctor --apply --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 since #3485: a run can exit **0** while printing ✗ lines, because three rows
+(`worktree roots`, `schedules`, `docs-audit`) are ruled report-only — real faults the design deliberately
+declines to gate on, since their remedy is a human review or lives in the owning repo. Neither direction
+is a gate. Read the rows.
+
+- **Blocking:** a red `mmi-cli` / `Claude plugin` version line, or a reported `minClientVersion` gap. Since
+  #3485 `--no-repo-writes` no longer blocks the env heals — the step above self-updates the npm global CLI
+  (#3272) and reinstalls the plugin (#3282), suppressing only repo-file writes — so the re-run should clear
+  it. If a gap persists, fix it — `mmi-cli doctor --apply`, or `npm install -g @mutmutco/cli` — before
+  continuing. Do **not** proceed to Step 0b while the installed CLI is behind the Hub's `minClientVersion`.
+- **Not blocking:** every other red check is hygiene, not a train gate. Stale branches and scratch heal with
+  `mmi-cli doctor --apply`; `plugin cache` needs a different verb, `mmi-cli plugin prune --apply` — saying
+  `doctor --apply` cleared it was wrong. All three still exit 1 until you run the right verb. The three
+  report-only rows (`worktree roots`, `schedules`, `docs-audit`) print ✗ without moving the exit code
+  since #3485 — not because no verb exists, but because the design refuses to gate on a human review or
+  on a fault owned by another repo. 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.
+
+**Then check the version yourself — do not rely on doctor having printed a row (#3674).** "Read the rows"
+resolves to "proceed" when the row is *absent*, and doctor's version row is conditional. On 2026-07-27 this
+step reported healthy with no version line while the installed CLI was 3.70.0 against a released 3.71.0;
+`release --apply` refused one command later. Two lines, no dependency on another command's reporting
+completeness:
+```bash
+mmi-cli --version
+npm view @mutmutco/cli version    # public package; a bare view is trustworthy here
+```
+Mismatch → `npm install -g @mutmutco/cli@<released>` before Step 0b, **regardless of what doctor's rows
+said**. This is the check whose absence Step 0a's own title promises to cover, so it is not optional.
+
+## Step 0b — registry + main secret-name preflight
+
+Resolve the project META first; its `deployModel` decides the deploy path. `tenant-container` repos use the
+central tenant deployer and therefore need DEPLOY# coords. `hub-serverless` (MMI-Hub), `serverless`,
+`registry-publish`, and `solo-container` repos deploy from their own branch/release-triggered or model
+workflow, so do **not** dispatch `tenant-deploy.yml` for them.
+Verify META + required SSM secret names before touching `main`:
+```bash
+mmi-cli org project get {owner}/{repo}
+mmi-cli secrets preflight --stage main --repo {owner}/{repo}
+```
+Missing META or secret names → stop and repair the registry/secrets first.
+
+## 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 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 release --apply --ack <sha>[,<sha>…]` — the ack is recorded in the verdict. Never ack to save time.
+
+## Step 0d — release-time surface freshness (repo-owned, source-only docs gate)
+
+As early as the probe — the released diff (`origin/main..origin/development`, or `..rc`) is already
+known — refresh the repo's own docs against **exactly what is shipping**. An agent reads the
+shipping PRs and quickly scans the surfaces; most releases change nothing they describe, so most
+releases do nothing here. It is **model-agnostic** — describe the work, not the model; under Claude,
+**Sonnet latest (`claude-sonnet-5`)** is the right tier (never the release model, never Haiku).
+Reviewed, repo-owned + release-triggered — never a central, scheduled, cross-repo keeper (that stays
+retired, #2135).
+
+**The two in-repo docs (`README.md`, `architecture.md`): in the released commit.**
+Run this **at the probe, before Step 1**. First scan both against the shipping diff. **If nothing a
+shipped change touches made them drift, skip this docs pass entirely — no PR, no wait** (the common case).
+
+When a shipped change did make a doc drift, establish **where the drifted text comes from** before editing
+it — from the repo's own tooling: a generator script, a "do not edit" header, a generated-region marker.
+**If you cannot establish that a region is hand-written, treat it as generated.** Hand-written prose takes
+the fast path below; a generated region does not, and never lands by hand.
+
+**Hand-written prose — the fast docs-only path:**
+- Edit the doc to current truth (no change-comments — AGENTS docs rule).
+- Land it on `development`: open a PR touching **only** `README.md` /
+  `architecture.md` and auto-merge it (`mmi-cli pr merge <n> --auto --squash` — raw `gh pr merge` is
+  denied by the org command ladder, #2347). Because the PR touches only
+  those two docs, it runs **only the checks its paths trigger** — the repo's gate skips the code/test
+  jobs a docs change can't affect — so it normally goes green + merges in about a minute, with no
+  force-push and no protected-branch bypass (CI stays honest). (On the Hub that is the fast `docs` job
+  while `cli` / `infra` no-op; a single-gate repo short-circuits its one gate the same way.) A
+  docs-only PR also can't expand the release scope (it touches only those two files).
+
+**Generated surface — fix the source, and default to the next cycle** (#2916). The Hub's compact README
+agent loop and `docs/Architecture/agent-playbook.md` come from the CLI loop definitions via
+`scripts/generate-agent-playbook.mjs`; CLI `--help` comes from Commander descriptions. There, the fast path
+does not apply:
+- **Never hand-edit the generated file.** It is a band-aid the next regen silently overwrites, and it
+  leaves `--help` — the surface users actually hit — still wrong.
+- **Fix the source, not the artifact:** edit the loop in `cli/src/explain-command.ts` or the relevant
+  `.description()` in `cli/src/index.ts`, then rebuild/regenerate.
+- **Do not race the train with it.** That fix touches code + built artifacts, so it runs the **full** gate,
+  and it would add a **code commit to the very diff Step 1 is about to cut**. This docs pass is freshness, not
+  a scope hatch. So **default to deferring it**: land the source fix on `development` as an ordinary
+  CI-gated PR **after** the release, note the deferral in the release report, and let it ship next cycle.
+  The drift is cosmetic and already shipped; one more cycle costs nothing.
+- Only the **human release owner** may pull a generated-surface fix into the current release, and only by
+  saying so explicitly. An agent never makes that call on its own drift judgment, and never `--auto`-merges
+  a code-bearing PR at the probe.
+
+**Bounded, never a hang (fast path):** wait for that docs-only auto-merge up to a short bound (~5 min). If
+CI is contended and it has not merged in time, **do not block the train** — proceed with the release as-is.
+Leave the auto-merge armed: the doc fix is not lost, it just lands whenever CI clears. Docs freshness
+improves the release; it never holds it hostage.
+
+Then **Step 1** cuts `development → main` from the current HEAD. Because an armed auto-merge can still land
+between the bound and the cut, **re-check the PR's state right before Step 1** and report what actually
+shipped — never predict it from the bound.
+
+## 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 pr merge <n> --auto --merge` (not squash; a squash discards the merge parentage, so the
+misalignment guard re-flags the same divergence on the next run). `--auto` clears the checks the PR
+triggers, which block an immediate merge right after a release.
+
+**Exception — version-manifest and `.gitignore` paths.** `mmi-cli 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 release --apply`)
+
+Every release folds the version bump into the release itself (#976): after the merge onto local `main` and
+before the tag, the CLI bumps the version manifests to the release version and commits — **unconditionally,
+changed or not** — then the tag-first push (Step 3) earns that fresh commit its required checks. There is
+no separate bump PR, no `development` prep cycle, and `development` never sits ahead of the published
+version (the back-merge in Step 5 carries the bump back).
+
+What the fold bumps, by repo:
+- **Hub (`hub-serverless`):** the full locked distribution set via `scripts/release-distribution.mjs
+  prepare` — spine dogfood (`scripts/spine-dogfood.mjs`: verify docs/surfaces + the managed `.gitignore` block),
+  every registry-declared version holder, adapter payload synchronization, build output, and the public
+  artifact bill of materials — then verifies the set (`verify --skip-npm-view`). Publication and staging
+  both derive from `surfaces.json`; there is no second package list. Claude, Codex, Kimi, Cursor, and
+  Kilo are active.
+- **App-style repos with a root `package.json`** (most products): the manifest + lockfile version via
+  `npm version --no-git-tag-version`, kept in lockstep with the release tag.
+- **Repos with neither:** nothing to fold — the tag is the version.
+
+Nothing to do by hand; the `--apply` result reports the fold outcome (`versionFold`).
+
+## Step 2 — tag the release
+
+Full-track repos drop the `-rc.N` suffix from the open cycle. Direct-track repos use the next cycle directly
+because they have no rc tag:
+```bash
+TAG=$(node scripts/next-version.mjs release)   # full-track repos -> vX.Y.0
+TAG=$(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)
+
+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 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 release
+--apply` (the fold re-tags the same version on the fixed HEAD). **Tag deletion is deletion-class → it needs the
+authorized human's explicit per-turn go.** Exception: if a publish/deploy DID run off the stray tag, do **not**
+delete — mint the next version with `MMI_RELEASE_VERSION` instead. The CLI already classifies this
+(`isStrayUnreleasedTag`, `cli/src/train-apply.ts`); this note surfaces the doctrine so a halted operator does
+not re-derive it from source.
+
+## Step 4 — GitHub Release + start prod deploy (non-blocking)
+
+For `tenant-container` repos, publish the GitHub Release and dispatch the central tenant deploy.
+```bash
+gh release create "vX.Y.0" --target main --generate-notes --latest
+gh workflow run tenant-deploy.yml --repo mutmutco/MMI-Hub \
+  -f slug={slug} -f repo={owner}/{repo} -f ref=main -f stage=main
+gh run watch "$(gh run list --workflow tenant-deploy.yml --limit 1 --json databaseId -q '.[0].databaseId')" \
+  --exit-status   # the central prod-deploy run — run this in the BACKGROUND (Bash run_in_background)
+```
+
+For `hub-serverless` (MMI-Hub), publish the GitHub Release but do **not** dispatch `tenant-deploy.yml`:
+the release event auto-fires `deploy.yml` for prod and `publish.yml` for the
+plugin/CLI package. A missing `DEPLOY#main` registry row for MMI-Hub is expected, not a tenant stack repair
+task. Watch/report the release-triggered `deploy.yml` and `publish.yml` runs instead.
+
+For other direct-track repos, the train dispatches nothing centrally: a `registry-publish` repo's release
+event fires its own `publish.yml` (npm / plugin marketplace); a `solo-container` repo deploys via its own
+workflow. Publish the GitHub Release, then watch/report that repo's own release-triggered run.
+
+`mmi-cli release --apply --json` returns the relevant run id/url data with `deployStatus`; `--watch` blocks
+on the run(s) and resolves `deployStatus` to `success`/`failure`. For tenant-container repos, that is the
+dispatched `tenant-deploy.yml` run. For Hub serverless, that is the auto-fired release `deploy.yml` and
+`publish.yml` workflow pair — watched on `mutmutco/MMI-Hub`. For `registry-publish`, that is the target
+repo's own release-triggered `publish.yml` run — watched on that repo, never dispatched, and never the
+central `tenant-publish.yml` (#2428: dispatching both is a guaranteed npm E409 double-publish, since the
+repo's own release-triggered publish always wins the version race).
+`promoted: true` stays set even on a failed deploy — promotion and deploy are separate outcomes.
+
+**`deployStatus: 'pending'` is NEVER a terminal, reportable state (#3322).** A release that returns
+`pending` has an UNRESOLVED deploy, not a clean one. The report now prints `deploy: UNVERIFIED` instead of
+omitting the deploy line entirely — which is exactly how a failed deploy once hid behind a "successful"
+release (Jerv-PowerTools v1.22.0: the release-triggered `publish.yml` went green, a separate `push: main`
+SAM deploy FAILED, and the train returned `deployStatus: pending`, so the run read as clean). Resolve it,
+or report it as unverified-RED. Never as success.
+
+**Read the `--apply` result's `workflowRuns` array — the train already enumerates every run on the release
+SHA (#3699).** That enumeration includes `push: main` infra deploys (`deploy.yml`, SAM) the deploy model does
+not name, and `deployStatus` is held at `pending` until they resolve. Any non-success entry — including
+`pending` — keeps the release unverified: watch those listed runs to conclusion:
+```bash
+gh run watch <run-id> --repo {owner}/{repo} --exit-status
+```
+The one remaining caveat: `--watch` blocks only on deploy-model-named runs, not extra push-triggered
+deploys — those you conclude from the `workflowRuns` list yourself. Any `failure` there is a failed release
+deploy even when the train reported success — flag it loudly and fix it before calling the release healthy.
+
+**Hub releases announce to Slack (#883).** Hub scope is **only** `mutmutco/MMI-Hub`: the commits/PRs on
+`origin/main..origin/development`, this repo's `deploy.yml` + `publish.yml`, and Hub tooling (`mmi-cli`,
+skills, plugin, registry, central workflows). Do **not** read another repo's board (`mmi-cli 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=$(node scripts/next-version.mjs cycle)` — always print `$TAG` (e.g. `v2.43.0`) in summaries, Slack,
+chat, and the final report; never a placeholder like `vX.Y.0` or `v0.x.0`.
+
+Write a curated summary — 3-6 very short plain lines, one change per line, dev-readable, no PR-dump —
+to a fresh temp file (`f=$(mktemp tmp/release-summary.XXXXXX)`, so a stale prior summary is never reused).
+Source from **Hub PR titles only** (`origin/main..origin/development` on `mutmutco/MMI-Hub`), but **rewrite**
+each line in neutral Hub-subsystem terms (CLI, skills, plugin, workflows, registry, deploy hub) — **never**
+a product or brand name (FoFu, Katip, etc.) anywhere in the summary file, Slack post, chat, or release
+report. Product names are allowed only when releasing **that product's repo**. Then pass the file through:
+`mmi-cli release --apply --announce-summary-file "$f"`. After the GitHub Release publishes, the CLI posts
+the summary to the org alerts channel as the MMI-Future Slack app (token + channel from SSM at run time).
+For a new MMI-Hub `--apply`, the CLI refuses before promotion when the file is missing, unreadable, or does
+not contain 3–6 non-empty lines; generated-note fallback is not an agent release path. `--resume` never
+requires or republishes a summary, and non-Hub repos skip the announcement automatically. After a valid
+summary is accepted, Slack delivery remains best-effort: a transport failure is reported in the result and
+never rolls back an otherwise completed release.
+
+**Don't block on the deploy.** Start the watch as a background task and proceed to Steps 4b–5 (docs, project
+info, branch alignment) while prod deploys. The verdict is collected in Step 6 — verification is not
+skipped, only un-blocked. Deploy failure → report plainly, then **retry the existing promoted ref by deploy
+model** once the runtime is repaired — never a re-tag or republish (`main` is already at the release, which is
+correct). Read the model from the registry (`mmi-cli org project get {owner}/{repo}` → `deployModel`):
+- **tenant-container** — the central tenant deployer owns the redeploy: `mmi-cli runtime tenant redeploy
+  {owner}/{repo} main --watch`.
+- **repository-owned serverless / registry-publish** (e.g. Jerv-PowerTools' `Deploy Jerv Memory`) — there is
+  no `runtime tenant redeploy` for these; re-run the repo's OWN declared `workflow_dispatch` deploy workflow at
+  the promoted-equivalent ref: `gh workflow run <deploy-workflow> --repo {owner}/{repo} --ref <ref>`.
+
+Name the sanctioned dispatch mechanism you used in the train report.
+
+## Step 4b — re-sync project info (in-repo docs handled in Step 0d)
+
+The two in-repo docs were already scanned against the shipping diff and, if they drifted, refreshed +
+merged in **Step 0d** (fast docs-only path for hand-written prose; generated regions are fixed at
+their source and deferred to the next cycle) — so the released commit already carries
+current `README.md` / `architecture.md` (and, in the hub, `docs/org-readme.md` /
+`docs/org-architecture.md`). The `distribution` gate also blocks empty/retired-term descriptions at PR
+time. Nothing to author here. `mmi-cli release --apply` now re-syncs the **Project** short description +
+thin README from those docs and the registry's current member repos through the command ladder. For a
+manual repair or preview use:
+```bash
+mmi-cli org project sync-info --apply   # omit --apply for the read-only plan
+```
+
+## Step 5 — roll development forward
+
+- Keep branches aligned: `mmi-cli 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 pr merge <number> --auto --merge` (never squash — a squash drops the merge
+  parentage and the misalignment guard re-flags the divergence). `--auto` is what makes it land right after a
+  release: the alignment PR's own `cli`/`infra`/`docs` checks are still running, so a plain immediate merge is
+  policy-blocked — `--auto` merges once they pass. Never force.
+- Full-track repos: `mmi-cli 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 release --apply` also fast-forwards the LOCAL train branches to match, so the checkout you
+  released from does not lag what you just pushed. The train restores + fast-forwards the start branch
+  (`checkout`, #2340) and fast-forwards the others (`localSync`) — non-destructively: only a true
+  fast-forward moves a branch; a diverged local branch is reported and left untouched (never a force).
+  The one branch it **cannot** sync at release time is a check-gated `development` whose roll-forward is a
+  `pr-pending` alignment PR (Hub) — that PR merges on origin *after* the release returns. That case is
+  healed automatically by the **next session**: `mmi-cli plugin session-start` (invoked by the resume
+  channel — #3630 took SessionStart off the hook surface) runs the
+  same fast-forward first thing, so a stale local `development`/`main`/`rc` self-heals to origin before you
+  work — no manual `git pull`. Nothing here ever blocks or fails the release.
+
+## Step 6 — collect deploy verdict + report
+
+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).
+
+Hub releases always carry a distribution bump (the Step 1b fold), so the **publish workflow**
+(`publish.yml`) ships every registry-declared public npm artifact on the GitHub Release from Step 4 —
+don't publish by hand.
+Watch it, then confirm npm caught up:
+```bash
+gh run watch "$(gh run list --workflow publish.yml --event release --limit 1 --json databaseId -q '.[0].databaseId')" --exit-status
+node scripts/release-distribution.mjs verify "vX.Y.0"   # asserts registry versions, BOM identities, and published npm artifacts
+```
+Run that verify from a checkout **at the tag** (`main` right after the release merge, `git checkout
+"vX.Y.0"`, or a worktree at the tag) — verify checks the working tree and refuses any other commit once
+the tag exists, so a stale `development`/`rc` checkout can't masquerade as a broken release.
+Release-blocking for Hub tooling changes: every public artifact must match the registry version and BOM
+identity. Manual fallback if CI can't publish: `node scripts/release-distribution.mjs publish "vX.Y.0"`
+from a machine with npm auth.
+
+**Private packages (#2405) — never trust a bare `npm view` to mean "not published".** An unauthenticated
+`npm view <pkg>` returns a hard 404 on any package published with `publishConfig.access=restricted`
+(private) — indistinguishable from "not published" — because npm masks private packages from anonymous
+reads. Before verifying ANY npm publish (Hub's own, a `registry-publish` product repo's own `publish.yml`,
+or a `publishRequired` product repo's companion `tenant-publish.yml`), check that surface's
+`publishVisibility` in the target repo's `surfaces.json`
+(`node -e "console.log(require('./surfaces.json').surfaces.find(s=>s.id==='<id>').publishVisibility)"`, or
+the repo-agnostic reader `scripts/release-distribution.mjs` exports as `npmVerifyModeFor`):
+- `public` → an unauthenticated `npm view <pkg>@<version> version` is a trustworthy verify signal.
+- `private` → do **not** run a bare `npm view`. Verify from an authenticated source instead: the
+  release-triggered run's conclusion (`gh run watch … --exit-status` — the repo's own `publish.yml` for
+  `registry-publish`, #2428; the central `tenant-publish.yml` for a `publishRequired` companion publish) and
+  its logged `+ pkg@ver` / `"already on npm — nothing to do"` / `"already on npm ... treating as idempotent
+  success"` output (`gh run view <id> --log`), or `npm view` with a registry auth token in env. A 404 here is
+  "unverifiable from here", never "not published" — report it as such, don't block or alarm on it.
+- `n/a` → nothing publishes to npm for that surface; skip.
+Hub's registry-declared npm surfaces are public today, so `release-distribution.mjs verify` uses a bare
+`npm view` for them — this changes only if a package's declared visibility changes.
+
+**tenant-publish.yml E409 belt-and-braces (#2428).** The central `tenant-publish.yml` lane (the
+`publishRequired` companion publish only — never dispatched for `registry-publish`, see above) already
+treats a lost `npm publish` race as idempotent inside the run (a re-check `npm view` after a failed publish;
+see the workflow file). `mmi-cli release --apply --watch` mirrors that at the CLI layer: a watched
+`tenant-publish.yml` run that concludes `failure` is re-checked against that SAME run's own log (bounded
+retries, visibility-agnostic — never a bare `npm view`) for the idempotent-success marker before the CLI
+reports the publish as failed. A run whose log never shows the version landed stays a loud failure.
+
+Report: Release `$TAG` (the resolved tag from Step 2 — never a placeholder) + the GitHub Release URL · prod
+deploy run + URL + **green/red** · branch-alignment note · npm publish run + CLI version (Hub releases).
+
+## Notes
+
+- PATCH-level releases are `/hotfix` only (a hotfix always skips rc — it cherry-picks `development → main`
+  directly); planned releases are MINOR or MAJOR. Never force-push `main`.
+- **`--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 ships the open cycle.
+
+## 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 skill-lesson --skill release --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/resume/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: resume
+description: Open a session — self-check, repo status, and the next actionable board item in one pass.
+---
+
+# /resume — start of session
+
+One flow to re-anchor at the top of a session: is the toolchain sound, what does this repo/worktree look
+like right now, and what is the single next thing worth doing. Read-only — it renders the picture and gets
+out of the way. `/mmi` is the board-only hello-to-work; `/resume` is the wider session open that folds in
+the toolchain self-check and the current-branch snapshot.
+
+## Step 0 — toolchain self-check
+
+```bash
+mmi-cli doctor --self
+```
+
+`doctor --self` verifies the two things that silently break a session: CLI/plugin version parity against
+the published version, and whether the active `gh` token can resolve this repo. It is fast, but it reads
+npm and GitHub — it is not offline-safe, and it checks neither PATH nor hook wiring (#3485). On a **hard**
+gap it points at the heal path — relay it and run it before working:
+
+```bash
+mmi-cli plugin heal      # only on a hard version/plugin gap; then restart Claude Code / reopen the workspace
+```
+
+A clean self-check is silent-enough — move straight on. Do not block the snapshot on a soft/advisory note.
+
+## Step 1 — repo snapshot
+
+```bash
+mmi-cli status
+```
+
+`status` is the unified current-state read for **this** checkout: branch, linked worktrees, your open PRs,
+your claimed board items, and whether a local stage is running. It is the "where am I" line — render it,
+don't re-derive it from raw `git`/`gh`.
+
+## Step 2 — the next move
+
+```bash
+mmi-cli next
+```
+
+`next` recommends the single most actionable claimable board item (unblocked, priority-ranked) and prints
+the exact `mmi-cli board claim <n>` to take it. Offer it; do not claim on the user's behalf without a go.
+For the full board partition (yours / claimable / taken) run `/mmi`.
+
+## Step 3 — render, then stop
+
+Lead with one line: toolchain OK (or the heal to run), the branch + what's in flight, and the one next
+item with its claim command. Then stop. The user drives — claim, continue, or file when they say so.
+
+## Notes
+
+- `/resume` is read-only session orientation. It never claims, moves, or writes.
+- Board status moves are automatic (claim, PR open, merge). Never suggest a manual status move.
+- Slower, board-partition view → `/mmi`. Readiness-gate view for a new repo/first session → `/onboard`.
+
+## 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 self-check that reported a false gap, or a
+snapshot that named the wrong branch.) 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 skill-lesson --skill resume --title "<what misfired>" --body "<what; evidence; proposed amendment>"`