@mutmutco/codex-plugin 4.5.159 → 4.5.161

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "4.5.159",
+  "version": "4.5.161",
   "description": "MMI Future CLI — the org dev toolbox and shared cross-IDE engine for every registry-declared MMI coding surface.",
   "type": "module",
   "license": "UNLICENSED",

package/package.json

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

package/skills/board/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: board
-description: Show the repo workboard, then take it down in the fewest pull requests.
+description: Show the repo workboard and clear it in the fewest PRs.
 ---
 
 # /board — your workboard, and the fastest way through it

package/skills/bootstrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bootstrap
-description: Provision a repo into the org with board, registry, rules, and plugin setup.
+description: Provision an org repo with board, registry, rules, and plugin setup.
 ---
 
 **Host-native invocation:** Claude `/mmi:bootstrap` · Codex `$mmi:bootstrap` · jervcode `/bootstrap` · Hermes skill_view. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.

package/skills/epic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: epic
-description: Decompose a vision or umbrella issue into linked child issues via one batch create.
+description: Split a vision or umbrella issue into linked child issues in one batch.
 ---
 
 # /epic — decompose an umbrella into children

package/skills/hotfix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hotfix
-description: Promote an already-merged development fix to main and production through the gated Hub train.
+description: Promote a merged development fix to main and production via the Hub train.
 ---
 
 **Host-native invocation:** Claude `/mmi:hotfix` · Codex `$mmi: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.

package/skills/mmi-help/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mmi-help
-description: Show a short, human-readable introduction to MMI and its commands.
+description: Introduce MMI and its commands.
 ---
 
 # MMI help

package/skills/org-guide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: org-guide
-description: Read org rules for project work and reporting MMI CLI, plugin, or workflow bugs.
+description: Read org project rules and how to report MMI CLI, plugin, or workflow bugs.
 ---
 
 # MMI organization guide

package/skills/org-guide/references/work-and-releases.md

@@ -91,6 +91,8 @@ development. A trunk repository follows its single branch and declared workflow
   No box stage.
 - Trunk track: one main branch, without an rc/development promotion train. Follow the repository's
   declared publishing workflow rather than manufacturing train branches.
+- Single track (MM-Work and its modules): one environment. Every merge to development auto-deploys
+  the `main` stage; there is no rc, dev stage or release train, and release, rcand and hotfix refuse.
 - Urgent already-merged fixes: use [hotfix](../../hotfix/SKILL.md), which carries selected development
   fixes directly to main on either track.
 

package/skills/rcand/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rcand
-description: Promote development to a release-candidate branch.
+description: Promote development to a release candidate.
 ---
 
 **Host-native invocation:** Claude `/mmi:rcand` · Codex `$mmi:rcand` · jervcode `/rcand` · Hermes skill_view. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.

package/skills/release/SKILL.md

@@ -82,7 +82,7 @@ Read the saved result, never the exit code (exit `1` = a follow-up failed after
 - `deployStatus` — `pending` is never terminal; `promoted: true` holds even when a deploy failed.
 - `served-channel(<product>)` row — the release's proof that new installs get it: the public `/release/version` pointer of the releasing repo's OWN channel (the Hub's `mmi`, or the product its registry `installer` declaration names; no declaration → no row), read after deploy and publish are green. `success` names the version read. `failure` is either a channel still on the previous version or a stale served process (the route answers 401/404): the note names what moves that channel and the exact remedy; run it, then re-read the pointer. `pending` means not probed (legs not green) or unreadable, never proof. The row is receipt evidence only, never a ledger leg, so it never blocks the next train.
 - `workflowRuns` — every run on the release SHA (deploy-model runs, any `push: main` deploy, the repo's own `gate`). On this host, discover them with the bounded run-list read below; filter locally by the exact receipt SHA. If the list hits its 100-row cap or returns no matching SHA, treat the run set as unverified and stop rather than infer completeness. Watch each matching non-success entry to conclusion: `gh run watch <run-id> --repo {owner}/{repo} --exit-status --interval 30`. 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.
-- With `--watch` the train waits for its own alignment PR to land (true merge) and folds the ledger in the same run, so the receipt ends `succeeded` / `complete`. An external `gh run watch` never folds anything: if the receipt still shows a `pending` leg (no `--watch`, the alignment PR outlived the bounded wait, or a release-event `publish.yml` run on a registry-publish repo had not been correlated by the time the receipt was written — `--watch` waits for the alignment PR, not for that run, so a `publish` leg `pending` with no run URL after `--watch` is the expected direct-track shape, not a failure), fold it live before declaring the cut done or starting any new train: `mmi-cli devops release --resume --watch --json --out <fresh-receipt>`; the NEXT train's doctor otherwise refuses with `ledger-pending`.
+- With `--watch`, require every follow-up complete before declaring the cut done. For any pending ledger leg, read [recovery.md](recovery.md) before continuing or starting a new train.
 - `announceNote` — `announced` (to the alerts channel for the Hub, to the project release channel for a product repo), `skipped`, `not announced` (deploy or publish not green; the note says whether a `--resume` carrying the same `--announce-summary-file` will post it), or the failure note. The channel id itself is never printed.
 - `devRollForward` / `rcAlignment` — `pushed`, or `pr-pending` with the alignment PR to land by true merge (Merge floor). An enqueued auto-merge is not evidence of the method; before reporting, read the enqueued method back — `gh pr view <n> --json autoMergeRequest --jq .autoMergeRequest.mergeMethod` — and prove it is `MERGE`. An enqueued `SQUASH` is a stop under the Merge floor, not something to wait out.
 - `versionFold`, `rcRetirement`, `checkout` — `returned`, or the named reason you are still on `main`.
@@ -98,21 +98,7 @@ Four facts close the verdict: the `origin/main..origin/development` count, the t
 
 ## Recovery
 
-Every refusal and every doctor blocker names its `code` and `anchor`: open `docs/Guides/train-troubleshooting.md#<code>` and follow that entry, nothing else. That guide is test-parsed, never free text — the infra drift and plugin-set suites validate every anchor cited here and assert policy from its wording — so an edit to it re-runs the infra suite (`npm --prefix infra test`) in the same PR: a heading or slug change is a code change. A pre-tag abort with no finding code (for example, a transient secrets-preflight timeout) is a transient stop: nothing was promoted and no tag was cut. Confirm no tag reached origin (`git ls-remote --tags origin` or `gh api repos/{owner}/{repo}/tags`), then rerun `mmi-cli devops release --apply` as a fresh cut, never `--resume`; resume is only for a partial release with the tag already on origin. 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 or republishes, posts a deferred announcement only when it is the run that first proves deploy and publish green, and `--apply` belongs to a new cut only. A SUPERSEDED leg is not a pending one: a ledger that records a supersession is phases-green — `--resume` must not be used on it, and the deferred announcement is the next patch train's to carry. A refused train is a stop (Merge floor): fix the cause on `development` through a normal PR, then rerun.
-
-**Exactly one continuation per ledger state.** Pick the row, run its verb, never combine two:
-
-- No tag on origin (pre-tag stop): a fresh `mmi-cli devops release --apply`.
-- A `deploy`/`publish` leg `pending` whose run already concluded (the `pending`, no-run-URL shape included): `mmi-cli devops train doctor --heal` folds it from that run (`ledger-unfolded`).
-- An `alignment` leg `pending` whose PR already merged: `mmi-cli devops train doctor --heal` (`ledger-alignment-stale`).
-- Any other `pending` leg (run in flight, alignment PR open): `mmi-cli devops release --resume --watch --json --out <fresh-receipt>`.
-- A `failed` leg with a transient cause: `--resume` after the cause clears (it spends the one bounded rerun); hotfix lane: `hotfix release <tag> --retry-deploy`.
-- A `failed` leg with a content cause on a published release: `--supersede-deploy` / `--supersede-publish` with master approval, then the next patch train.
-- A superseded ledger (phases-green): the next patch train. Never `--resume`.
-
-A **content-caused failed deploy leg on a published release** has no rerun that can succeed: the promoted tag is immutable, redeploying it rebuilds the same broken SHA, and the unresolved ledger blocks every lane — release, hotfix and candidate alike — while `--abort` is unavailable because the release is published. When the doctor's ledger blocker names `deploy` as the only unresolved leg and the deploy failure is proven content-caused (the deploy-time validator rejected the shipped content itself), the sanctioned exit is `mmi-cli devops release --supersede-deploy --apply` — an explicitly master-approved closure, run only after the cause fix is merged on `development`. It closes the deploy leg as superseded (the ledger turns phases-green), and the next patch train — usually `/hotfix`, which carries the fix to main — runs normally; its lifecycle gate archives the closed ledger aside. Never hand-edit the ledger file, never delete it to unblock a train.
-
-A **content-caused failed publish leg on a fully promoted release** is the same deadlock with its own exit: the tag is on `main` and the GitHub Release is live, so `--abort` refuses (it only ever deletes a proven unpublished candidate); `--resume` only re-reads the failed publish run — the tag is immutable, so no rerun can pass; `--supersede-deploy` is deploy-hardwired. When the doctor's ledger blocker names `publish` as the only unresolved leg and the publish failure is proven content-caused (a release gate rejected the shipped content — e.g. a platform-dependent distribution BOM — not a transient npm/transport error), the sanctioned exit is `mmi-cli devops release --supersede-publish --apply`, run only after the cause fix is merged on `development`. It closes the publish leg as superseded, the next patch train carries the fix, and its lifecycle gate archives the closed ledger. A transient publish failure (credentials, network, quota) is NOT content-caused: retry `--retry-publish <run-id>` or resolve the run instead. Once a leg is superseded, `--resume` is not the continuation: the ledger is phases-green, and resume leaves a superseded leg untouched and announces nothing, because superseded content never shipped. A superseded release has no standalone announce verb on purpose: its note is carried by the NEXT patch train's own announcement (the train that ships the cause fix), and the closed ledger archives the superseded release's record. If no CLI path fits and the release must be rebuilt by hand, the manual sequence — proven on the v1.62.1 recovery — is: retire the ledger path FIRST (archive `phases.json` aside, exactly as the ledger-failed receipt names), THEN delete the failed tag and GitHub Release, THEN re-cut the same version with a fresh `--apply` which re-points the tag onto the new bump. The order is a hard constraint: deleting the tag before the ledger path is retired deadlocks both `--abort` and `--resume`, because the ledger then anchors a tag that no longer proves anything.
+On any failure, read [recovery.md](recovery.md).
 
 ## Merge floor
 

package/skills/release/recovery.md

@@ -0,0 +1,22 @@
+# Release recovery and ledger continuation
+
+
+Every refusal and every doctor blocker names its `code` and `anchor`: open `docs/Guides/train-troubleshooting.md#<code>` and follow that entry, nothing else. That guide is test-parsed, never free text — the infra drift and plugin-set suites validate every anchor cited here and assert policy from its wording — so an edit to it re-runs the infra suite (`npm --prefix infra test`) in the same PR: a heading or slug change is a code change. A pre-tag abort with no finding code (for example, a transient secrets-preflight timeout) is a transient stop: nothing was promoted and no tag was cut. Confirm no tag reached origin (`git ls-remote --tags origin` or `gh api repos/{owner}/{repo}/tags`), then rerun `mmi-cli devops release --apply` as a fresh cut, never `--resume`; resume is only for a partial release with the tag already on origin. 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 or republishes, posts a deferred announcement only when it is the run that first proves deploy and publish green, and `--apply` belongs to a new cut only. A SUPERSEDED leg is not a pending one: a ledger that records a supersession is phases-green — `--resume` must not be used on it, and the deferred announcement is the next patch train's to carry. A refused train is a stop (Merge floor): fix the cause on `development` through a normal PR, then rerun.
+
+**Exactly one continuation per ledger state.** Pick the row, run its verb, never combine two:
+
+- No tag on origin (pre-tag stop): a fresh `mmi-cli devops release --apply`.
+- A `deploy`/`publish` leg `pending` whose run already concluded (the `pending`, no-run-URL shape included): `mmi-cli devops train doctor --heal` folds it from that run (`ledger-unfolded`).
+- An `alignment` leg `pending` whose PR already merged: `mmi-cli devops train doctor --heal` (`ledger-alignment-stale`).
+- Any other `pending` leg (run in flight, alignment PR open): `mmi-cli devops release --resume --watch --json --out <fresh-receipt>`.
+- A `failed` leg with a transient cause: `--resume` after the cause clears (it spends the one bounded rerun); hotfix lane: `hotfix release <tag> --retry-deploy`.
+- A `failed` leg with a content cause on a published release: `--supersede-deploy` / `--supersede-publish` with master approval, then the next patch train.
+- A superseded ledger (phases-green): the next patch train. Never `--resume`.
+
+A **content-caused failed deploy leg on a published release** has no rerun that can succeed: the promoted tag is immutable, redeploying it rebuilds the same broken SHA, and the unresolved ledger blocks every lane — release, hotfix and candidate alike — while `--abort` is unavailable because the release is published. When the doctor's ledger blocker names `deploy` as the only unresolved leg and the deploy failure is proven content-caused (the deploy-time validator rejected the shipped content itself), the sanctioned exit is `mmi-cli devops release --supersede-deploy --apply` — an explicitly master-approved closure, run only after the cause fix is merged on `development`. It closes the deploy leg as superseded (the ledger turns phases-green), and the next patch train — usually `/hotfix`, which carries the fix to main — runs normally; its lifecycle gate archives the closed ledger aside. Never hand-edit the ledger file, never delete it to unblock a train.
+
+A **content-caused failed publish leg on a fully promoted release** is the same deadlock with its own exit: the tag is on `main` and the GitHub Release is live, so `--abort` refuses (it only ever deletes a proven unpublished candidate); `--resume` only re-reads the failed publish run — the tag is immutable, so no rerun can pass; `--supersede-deploy` is deploy-hardwired. When the doctor's ledger blocker names `publish` as the only unresolved leg and the publish failure is proven content-caused (a release gate rejected the shipped content — e.g. a platform-dependent distribution BOM — not a transient npm/transport error), the sanctioned exit is `mmi-cli devops release --supersede-publish --apply`, run only after the cause fix is merged on `development`. It closes the publish leg as superseded, the next patch train carries the fix, and its lifecycle gate archives the closed ledger. A transient publish failure (credentials, network, quota) is NOT content-caused: retry `--retry-publish <run-id>` or resolve the run instead. Once a leg is superseded, `--resume` is not the continuation: the ledger is phases-green, and resume leaves a superseded leg untouched and announces nothing, because superseded content never shipped. A superseded release has no standalone announce verb on purpose: its note is carried by the NEXT patch train's own announcement (the train that ships the cause fix), and the closed ledger archives the superseded release's record. If no CLI path fits and the release must be rebuilt by hand, the manual sequence — proven on the v1.62.1 recovery — is: retire the ledger path FIRST (archive `phases.json` aside, exactly as the ledger-failed receipt names), THEN delete the failed tag and GitHub Release, THEN re-cut the same version with a fresh `--apply` which re-points the tag onto the new bump. The order is a hard constraint: deleting the tag before the ledger path is retired deadlocks both `--abort` and `--resume`, because the ledger then anchors a tag that no longer proves anything.
+
+## Ledger reference
+
+- With `--watch` the train waits for its own alignment PR to land (true merge) and folds the ledger in the same run, so the receipt ends `succeeded` / `complete`. An external `gh run watch` never folds anything: if the receipt still shows a `pending` leg (no `--watch`, the alignment PR outlived the bounded wait, or a release-event `publish.yml` run on a registry-publish repo had not been correlated by the time the receipt was written — `--watch` waits for the alignment PR, not for that run, so a `publish` leg `pending` with no run URL after `--watch` is the expected direct-track shape, not a failure), fold it live before declaring the cut done or starting any new train: `mmi-cli devops release --resume --watch --json --out <fresh-receipt>`; the NEXT train's doctor otherwise refuses with `ledger-pending`.

package/skills/secrets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: secrets
-description: Manage the full own-project vault and granted org-infra secret names.
+description: Manage the project vault and granted org-infra secrets.
 ---
 
 **Host-native invocation:** Claude `/mmi:secrets` · Codex `$mmi:secrets` · jervcode `/secrets` · Hermes skill_view. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.

package/skills/stage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stage
-description: Run a local test stage, or a personal cloud dev stage with --live.
+description: Run a local test stage or personal cloud dev stage with --live.
 ---
 
 **Host-native invocation:** Claude `/mmi:stage` · Codex `$mmi:stage` · jervcode `/stage` · Hermes skill_view. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.