@mutmutco/codex-plugin 4.6.3 → 4.6.5

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "4.6.3",
+  "version": "4.6.5",
   "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.6.3",
+  "version": "4.6.5",
   "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 and clear it in the fewest PRs.
+description: Show the repo workboard and clear it in the fewest PRs. Use to see, plan or claim work, not to file one issue or release.
 ---
 
 # /board — your workboard, and the fastest way through it
@@ -12,16 +12,20 @@ permission to take anything.
 ## Step 1 — read the board
 
 ```bash
+mkdir -p .jerv/tmp
 mmi-cli oracle board read --json --out .jerv/tmp/board.json
 ```
 
 One call; the JSON carries `viewer`, `repo` and the project title. Use `primary` for this repo and
-`secondary` for other repos on the Project. Partial reads exit nonzero; `--allow-partial` only when the dev
-accepts an incomplete board. The CLI partitions rows into **Yours**, **Free to claim** and **Taken**; stale
-stamps (4 hours without work) hold nothing. Partition rules, stamp details and `--out` rationale:
-[reference.md](reference.md).
+`secondary` for other repos on the Project. Without `--flat`, `board read --json` returns an object
+`{project, viewer, repo, primary, secondary, warnings, partial}` whose `primary` and `secondary` are bucket
+objects `{userOwned, claimable, taken, unownedInFlight}` of item arrays (no top-level `items` array), so filter
+a bucket (e.g. `report.primary.claimable`) or pass `--json --flat`, never `(j.items||j).filter`. Partial reads
+exit nonzero; `--allow-partial` only when the dev accepts an incomplete board. The CLI partitions rows into
+**Yours**, **Free to claim** and **Taken**; stale stamps (4 hours without work) hold nothing. Partition rules,
+stamp details and `--out` rationale: [reference.md](reference.md).
 
-**Under the App pool, never type raw `gh` for a read** (`gh issue list/view --jq`, `gh run view --jq`, `gh api -q` all bounce). Use `MMI_ACTOR=app mmi-cli devops read issue view <n> --repo <owner/repo> --json <fields>` (or `issue list`, `pr view`, `run view`); `--jq '<expr>'` on that typed read filters locally. Those typed reads take **one** number per call, exactly like native gh: a second number is refused as `too many arguments`, so read several issues by repeating the typed read once per number (one `--jq` each, joined `&&`). Filter in a pipe or save output (`>`, `2>&1`, `--out`) under this worktree's `.jerv/tmp/` (`mkdir -p .jerv/tmp` first), never `../` or a sibling path: the workspace output guard refuses those. Body edits are read-then-edit: `MMI_ACTOR=app mmi-cli devops read issue view <n> --repo <owner/repo> --json body > .jerv/tmp/issue-body.json`, append or filter the JSON locally (`node -e`; the typed read's own `--jq` also filters locally), then write back with `gh issue edit <n> --repo <owner/repo> --body-file .jerv/tmp/issue-body.md` — `gh` writes pass under the pool. When `node -e` reads saved JSON, pass an absolute path or use `JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))`: `require()` of a relative path (e.g. `tmp\board.json` from `cygpath -w`) throws MODULE_NOT_FOUND.
+**Under the App pool, never type raw `gh` for a read** (`gh issue list/view --jq`, `gh run list --event`/`--jq`, `gh run view --jq`, `gh api -q` all bounce). Use `MMI_ACTOR=app mmi-cli devops read issue view <n> --repo <owner/repo> --json <fields>` (or `issue list`, `pr view`, `run view`, `run list --event <event>`, or `MMI_ACTOR=app mmi-cli devops api get "repos/<owner>/<repo>/actions/runs?event=<event>&per_page=<n>"`); `--jq '<expr>'` on that typed read filters locally. Those typed reads take **one** number per call, exactly like native gh: a second number is refused as `too many arguments`, so read several issues by repeating the typed read once per number (one `--jq` each, joined `&&`). Filter in a pipe or save output (`>`, `2>&1`, `--out`) under this worktree's `.jerv/tmp/` (`mkdir -p .jerv/tmp` first), never `../` or a sibling path: the workspace output guard refuses those. Body edits are read-then-edit: `MMI_ACTOR=app mmi-cli devops read issue view <n> --repo <owner/repo> --json body > .jerv/tmp/issue-body.json`, append or filter the JSON locally (`node -e`; the typed read's own `--jq` also filters locally), then write back with `mmi-cli oracle issue edit <ref> --body-file .jerv/tmp/issue-body.md`. When `node -e` reads saved JSON, pass an absolute path or use `JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))`: `require()` of a relative path (e.g. `tmp\board.json` from `cygpath -w`) throws MODULE_NOT_FOUND.
 
 ## Step 2 — render it
 
@@ -73,9 +77,7 @@ so the file form is the one that always works.
 
 Follow printed owner rulings; record new ones with `mmi-cli oracle issue decision`. One concurrent worktree per batch: [reference.md](reference.md). Always pass `--surface <value>` explicitly on every `mmi-cli oracle issue create` (surface inference is strict and bounces when the body merely mentions a path); use `--no-surface` only for genuinely exempt filings.
 
-With several task lanes in one session, pass `worktree: <the mmi-worktrees/<Repo>/<issue>-<slug> path jerv_worktree_create reported>` to `jerv_worktree_exec` / `jerv_worktree_land` every time; they refuse to guess (#5629). While any mmi-worktrees lane is registered for this repo, run focused tests/gates from the task-worktree root `jerv_worktree_create` reported — never the primary checkout; the test policy refuses it (`test-command-untrusted-worktree-cwd`).
-
-A fresh mmi worktree has no `.jerv/`: run `mkdir -p .jerv/tmp` before writing scratch files there (PR bodies, batches) or listing it.
+With several task lanes in one session, name the lane's worktree path (the `mmi-worktrees/<Repo>/<issue>-<slug>` path your host reported when it created the worktree) on every worktree exec or land call; the host refuses to guess (#5629). While any mmi-worktrees lane is registered for this repo, run focused tests/gates from the task-worktree root your host reported — never the primary checkout; the test policy refuses it (`test-command-untrusted-worktree-cwd`). A fresh worktree has no `.jerv/`, so `mkdir -p .jerv/tmp` before writing scratch files there (PR bodies, batches).
 
 ## Step 5 — land one PR per batch
 
@@ -93,8 +95,7 @@ open: `Part of #N` or `Refs #N`, never `Does not close #N`. Guidance-learning ga
 ref and OID, clean worktree); otherwise retain and report. Watch the merge by PR number (`state` reaching
 `MERGED`) or by the closing issue's `state` — never by the head branch or its remote ref: GitHub deletes a
 merged head, so a missing branch is not an unmerged verdict and a same-name branch recreated by a later
-push is not a second chance to land on it (docs/Guides/train-troubleshooting.md, section
-`merged-pr-head-reuse`). Show any `gh` / `mmi-cli` error verbatim.
+push is not a second chance to land on it ([`merged-pr-head-reuse`](https://github.com/mutmutco/MMI-Hub/blob/development/docs/Guides/train-troubleshooting.md#merged-pr-head-reuse)). Show any `gh` / `mmi-cli` error verbatim.
 
 ## Retro — one check before you finish
 

package/skills/board/reference.md

@@ -17,7 +17,11 @@ UTF-16LE with a BOM (#5802); Bash redirects preserve the CLI's UTF-8 output.
 
 One call. Its JSON carries `viewer`, `repo` and the project title — do not spend extra calls on
 `gh api user` or `gh repo view`. Use `primary` for this repo and `secondary` for other repos on the same
-Project. Partial reads exit nonzero; pass `--allow-partial` only when the dev accepts an incomplete board.
+Project. Without `--flat`, `board read --json` returns an object
+`{project, viewer, repo, primary, secondary, warnings, partial}` whose `primary` and `secondary` are bucket
+objects `{userOwned, claimable, taken, unownedInFlight}` of item arrays (no top-level `items` array), so filter
+a bucket (e.g. `report.primary.claimable`) or pass `--json --flat`, never `(j.items||j).filter`. Partial reads
+exit nonzero; pass `--allow-partial` only when the dev accepts an incomplete board.
 
 Partition, as the CLI computes it:
 

package/skills/bootstrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bootstrap
-description: Provision an org repo with board, registry, rules, and plugin setup.
+description: Provision an org repo with board, registry, rules, and plugin setup. Use when onboarding a new repo as master, not for day-to-day changes to a repo already provisioned.
 ---
 
 **Host-native invocation:** Claude `/mmi:bootstrap` · Codex `$mmi:bootstrap` · jervcode `/bootstrap` · OpenBot the `bootstrap` skill (loaded by name). A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
@@ -16,8 +16,8 @@ Read [reference.md](reference.md) for create vs upgrade, seed refresh, propagati
 Before Step 0a, state a recommended default per axis and confirm all four with Jervaise through the orchestrator; never default silently.
 
 - **`class`** — `deployable` (full or direct train) · `content` (trunk, `main` only); sets the branch model.
-- **`project-type`** — `web-app`, `cli-tool`, `worker`, `desktop-app`, `desktop-game`, `mobile-app`, `content`…; sets Hub services.
-- **`deploy-model`** — `tenant-container`, `none`, `content`…; sets the deploy path.
+- **`project-type`** — the capability shape; `mmi-cli devops bootstrap apply --help` lists the values. Sets Hub services.
+- **`deploy-model`** — how it deploys; `bootstrap apply --help` lists the values. Sets the deploy path.
 - **`release-track`** — `full` (development·rc·main) · `direct` (development·main) · `trunk` (`main`); sets the branch set.
 
 A **deployable** repo also needs gate runtime (`node` default, `python` for a Python app), check command and working directory: `--var GATE_RUNTIME=`, `GATE_CMD=`, `GATE_WORKDIR=`, and `GATE_CACHE_DEP_PATH=` for a non-root Node lockfile.
@@ -42,7 +42,7 @@ For board selection/creation, access, gate setup or manual provisioning of a new
 
 ## Step 6 — register Hub META
 
-No product repo control-plane file; `mmi-cli` resolves state from the Hub registry. For flag combinations or an MM-Work module, read [reference.md](reference.md) first. Apply with the board variables discovered earlier (or `mmi-cli oracle org project set`):
+No product repo control-plane file; `mmi-cli` resolves state from the Hub registry. For flag combinations or an MM-Work module, read [reference.md](reference.md) first. Apply with the board variables discovered earlier (or `mmi-cli oracle org project set`). Without `--execute` it is a dry run; show it to Jervaise and get his yes before adding `--execute`, which writes to GitHub and the Hub registry:
 
 ```bash
 mmi-cli devops bootstrap apply "$OWNER/$REPO" --class deployable \
@@ -69,7 +69,7 @@ Repo, default branch, ruleset, push allowlist, Environments per track, project (
 mmi-cli devops train doctor --lane release --repo "$OWNER/$REPO" --json   # full track: also --lane rcand
 ```
 
-`ready: true` is the train-readiness proof (findings: `docs/Guides/train-troubleshooting.md#<code>`). A `bootstrap-gap` finding names the missing apply row (blocker: train branch absent on origin; warning: stage with no required status check). Read warnings too: `ready: true` alone does not prove the product ruleset is active.
+`ready: true` is the train-readiness proof (open a finding's `anchor` URL). A `bootstrap-gap` finding names the missing apply row (blocker: train branch absent on origin; warning: stage with no required status check). Read warnings too: `ready: true` alone does not prove the product ruleset is active.
 
 ## Retro
 

package/skills/bootstrap/reference.md

@@ -94,8 +94,8 @@ gh api -X PUT "repos/$OWNER/$REPO/contents/.gitkeep" \
 ```
 
 `--disable-wiki` seeds `has_wiki=false` at creation: wikis are retired org-wide (compute-at-read, #4206),
-GitHub defaults new repos to `has_wiki=true`, and `bootstrap apply --execute` / `bootstrap reconcile --apply`
-enforce the same rule as drift checks afterwards.
+GitHub defaults new repos to `has_wiki=true`, and `bootstrap apply --execute` enforces the same rule
+afterwards while `bootstrap verify` checks it.
 
 On an empty repo that PUT creates `$FIRST` **and leaves it the default branch**, so no `gh repo edit
 --default-branch` is needed here. Skip this step when the repo already exists with the track's default branch.
@@ -147,7 +147,7 @@ next dry-run `bootstrap apply`.
 ## Step 2 — authority (org Ruleset)
 
 Confirm the org-level rulesets already target this repo (they apply org-wide): **`mmi-branch-protection`**
-PR-gates `development` and blocks force-push/deletion there (bypass = org admins + the GitHub App 3026732),
+PR-gates `development` and blocks force-push/deletion there (bypass = org admins + the org App),
 and **`mmi-train-floor`** blocks force-push/deletion on `rc`/`main` (no PR rule — the train pushes merges and
 tags directly; no bypass). (Definitions mirror live in `.github/rulesets/mmi-branch-protection.json` and
 `.github/rulesets/mmi-train-floor.json`.) MMI-Hub additionally has its own repository ruleset,
@@ -291,12 +291,12 @@ collaborator list + the per-branch allowlist are the record — no separate rost
   labels are allowed on every OS (`ubuntu-*`, `windows-*`, `macos-*` and their ARM variants, #8977), and
   only larger/paid images, GPU shapes and custom runner groups stay refused. Jobs needing system
   packages
-  run in a `container:`. The self-hosted fleet has **six concurrent job lanes** — independent checks belong
-  in separate parallel jobs (each with its own `runs-on`), never chained into one serial job or throttled
-  with unneeded `concurrency` groups. See `docs/Guides/gh-runner-runbook.md`.
+  run in a `container:`. Independent checks belong in separate parallel jobs
+  (each with its own `runs-on`), never chained into one serial job or throttled with unneeded
+  `concurrency` groups. See `docs/Guides/gh-runner-runbook.md`.
 - **Product gate + required checks (#1333, stack-aware #1550)** — deployable repos bootstrap-seed
   `.github/workflows/gate.yml` (single `gate` job — the simple default for one check command; a repo
-  that grows several independent suites splits them into parallel jobs across the runner's twelve lanes,
+  that grows several independent suites splits them into parallel jobs,
   as MMI-Hub's `cli`/`infra`/`docs` gate does) and a ruleset reference at
   `.github/rulesets/mmi-product-required-checks.json`. The gate is stack-aware: capture the repo's
   **runtime** (`node` | `python`), its **check command**, and its **working directory** at interview time
@@ -327,7 +327,7 @@ collaborator list + the per-branch allowlist are the record — no separate rost
   `strict_required_status_checks_policy: false`. Bootstrap and CI reconciliation preserve that policy
   when updating contexts, and converge the live ruleset to the committed setting. Repositories may
   explicitly require an up-to-date head. `pr merge` / `pr land` still update a BEHIND head from the base
-  with a merge commit and re-wait once — see `docs/Guides/train-troubleshooting.md#head-behind-base`.
+  with a merge commit and re-wait once — see [head-behind-base](https://github.com/mutmutco/MMI-Hub/blob/development/docs/Guides/train-troubleshooting.md#head-behind-base).
 - **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
@@ -371,8 +371,7 @@ collaborator list + the per-branch allowlist are the record — no separate rost
 ## Step 5 — install the plugin + seed docs
 
 - Bootstrap does **not** seed `.claude/settings.json` or any agent guide (hub-v3 WS4). The developer installs
-  the org plugins per machine: `mmi@mutmutco` (the plugin carries the org tooling + skills) and
-  `superpowers@claude-plugins-official` (Anthropic's skills framework — TDD, debugging, subagent dev).
+  the org plugin per machine: `mmi@mutmutco` (it carries the org tooling and skills).
   Personal agent guides (`AGENTS.md`/`CLAUDE.md`) are developer-owned and gitignored — MMI never delivers,
   overwrites, or deletes them; Jervaise's guide rides Jerv PowerTools.
 - Seed `README.md` + `architecture.md` from the templates, then **fill them before finishing** — `bootstrap
@@ -398,12 +397,14 @@ collaborator list + the per-branch allowlist are the record — no separate rost
   guides stay developer-owned and gitignored, carried per machine by each developer's own plugins.
 
 Choose the v2 shape explicitly. Use `--project-type web-app --deploy-model tenant-container` for ordinary
-web tenants, `--project-type desktop-game --deploy-model none --clear-web-profile` for a desktop game,
-`--project-type desktop-app --deploy-model none --clear-web-profile` for a packaged desktop application
+web tenants, `--project-type desktop-game --deploy-model none` for a desktop game,
+`--project-type desktop-app --deploy-model none` for a packaged desktop application
 (swap in `--deploy-model registry-publish` when it also publishes a package alongside its installer),
-`--project-type mobile-app --deploy-model none --clear-web-profile` for a phone app distributed through the
-app stores, and
-`--class content --project-type content --deploy-model content --clear-web-profile` for a content/KB repo.
+`--project-type mobile-app --deploy-model none` for a phone app distributed through the app stores, and
+`--class content --project-type content --deploy-model content` for a content/KB repo. A non-web repo
+carries no web profile: clear the leftover web-only registry fields with
+`mmi-cli oracle org project set <owner/repo> --clear-web-profile` (the flag belongs to `oracle org project set`,
+not to `bootstrap apply`).
 An **MM-Work module** adds `--var SUITE=mm-work` (#7944): it registers `suite: mm-work` and derives its
 own `dev.<sub>.mutmut.work` + `<sub>.mutmut.work` hosts, with no rc host (the suite serves its rc from the
 live host). Without it, apply derives the `*.mutatismutandis.co` web-app hosts, which a module never uses.
@@ -427,65 +428,3 @@ mmi-cli vault org oauth set-creds --repo "$OWNER/$REPO" < client.json   # the Co
 The keys are the one stageless pair `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` at the slug root — every
 stage reads it (#2244/#2528). Never a staged `{dev,rc,main}/GOOGLE_*`, `GOOGLE_OAUTH_CLIENT_*`, or `prod/`
 variant; the runtime reads only the canonical names and declare-first rejects the rest.
-
-
-
-## Detail moved from SKILL.md (verbatim)
-
-For a **deployable** repo, also capture the **gate runtime** (`node` | `python`), the **check command**, and
-the **working directory** — these feed the product gate (`--var GATE_RUNTIME=`, `--var GATE_CMD=`,
-`--var GATE_WORKDIR=`, and `--var GATE_CACHE_DEP_PATH=` for a non-root Node lockfile; see Step 5 / the
-"Product gate + required checks" note below). Default to `node` at the repo root; recommend `python` when the
-repo's app is Python.
-
-A **content/trunk** choice provisions: `main`-only (no `rc`), **no** `.github/workflows/gate.yml` and **no**
-product required-check ruleset, and a `projects.json` entry with `branch: main` (which marks it a content-class
-repo). A clean content repo then verifies green — `bootstrap verify --class content` no longer reports
-the deployable gate checks as FAIL (#1450).
-
-Record the confirmed axes; Step 0a runs `verify --class <confirmed>`, Step 0b creates the repo on the
-track's default branch, and the apply flags (`--project-type` / `--deploy-model` / `--release-track`) carry
-the confirmed values — no silent defaulting.
-
-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. 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, **with one expected exception**: a full track's two lanes start from different branches
-(`release` from `rc`, `rcand` from `development`) and one checkout stands on one branch, so the lane you
-are not standing on reports the never-healed `branch-mismatch` blocker (#6432). Verify is read-only and
-does not check the other branch out: a lane whose ONLY finding is that mismatch is printed `NOT EVALUATED
-from this branch` and does not fail the verify (#6677). That is the finished state, not a gap — run
-`mmi-cli devops train doctor --lane <lane> --json` from that lane's own branch for its verdict. Any other
-blocker in that lane, or an unread origin, still makes the report red.
-
-Tenant-container repos must carry a `docker-compose.yml` and Dockerfile that build from the shipped source
-archive; the train does not ship a prebuilt `dist/`. **Bootstrap seeds both files** for
-`deployModel: tenant-container` from `skills/bootstrap/seeds/` (rendered from
-the bootstrap seed Dockerfile and compose templates). The seeded compose is fileless: its service carries
-`labels: { mmi.runtime-env: "true" }`, no `env_file`, and a loopback-only port; the deploy injects the stage's
-vault values at runtime (`DEPLOY#<stage>.noEnvFile: true`) and the app reads plain env vars — it must **not** self-load SSM and must **not** ship a committed `.env`.
-
-**Stage port block (required for central-container):** run `mmi-cli stage port-range <Repo>` to assign
-(idempotently) the repo's local port block from the central registry. `tenant-container` and
-`solo-container` **must** have Hub registry `portRange` — `mmi-cli devops bootstrap verify` fails without
-it (#5539), and `mmi-cli stage` cannot derive a local preview until the block exists. `bootstrap apply
---execute` assigns the block automatically after DDB register for those models; for older META holes,
-run `stage port-range` explicitly. The block keeps local ports collision-free across projects and versions.
-
-Repo, default branch, ruleset applied, train branches locked (push allowlist), repository Environments
-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, 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` finding names the apply row still missing — a blocker for a
-train branch absent on origin, a warning for a stage with no required status check (#6136): read the
-warnings too, `ready: true` alone does not prove the product ruleset is active.

package/skills/epic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: epic
-description: Split a vision or umbrella issue into linked child issues in one batch.
+description: Split a vision or umbrella issue into linked child issues in one batch. Use for an umbrella with several deliverables, not for a single issue.
 ---
 
 # /epic — decompose an umbrella into children
@@ -9,7 +9,7 @@ Turn one large item (vision, epic, umbrella issue) into native sub-issues in one
 
 ## Opening branch — no umbrella yet
 
-For a product intent rather than an existing issue: gather the intent, read the repo's live issue templates, draft the umbrella from the matching feature/task template and show the draft for the user's go. Then create one issue with the `epic` label and an explicit Priority field; re-read it from the board to prove body, label and priority landed. Stop there unless child decomposition was also asked for and approved.
+For a product intent rather than an existing issue: gather the intent, read the repo's live issue templates, draft the umbrella from the matching feature/task template and show the draft for the user's go. Then create one issue with `mmi-cli oracle issue create --type task --label epic --priority <urgent|high|medium|low>` (the `epic` label is explicit, never implied by the type); re-read it from the board to prove body, label and priority landed. Stop there unless child decomposition was also asked for and approved.
 
 ## Step 0 — load the umbrella whole
 
@@ -70,7 +70,7 @@ This JSON is the placement authority: every intended child must be linked and on
 mmi-cli oracle issue link-child <parent> <child>
 ```
 
-Each child is now a parallel item: one worktree + PR each. With several task lanes in one session, pass `worktree: <the mmi-worktrees/<Repo>/<issue>-<slug> path jerv_worktree_create reported>` to `jerv_worktree_exec` / `jerv_worktree_land` every time; they refuse to guess (#5629). While any mmi-worktrees lane is registered for this repo, run focused tests/gates from the task-worktree root `jerv_worktree_create` reported — never the primary checkout; the test policy refuses it (`test-command-untrusted-worktree-cwd`). On Windows set `git config core.longpaths true` on the main checkout before the first `git worktree add`. When linked worktrees share a clone, serialize `git branch -m` and other ref renames (or retry serially on `.tmp-renamed-log`). **When the last child merges, close the umbrella** (board `Done` follows).
+Each child is now a parallel item: one worktree + PR each. Worktree mechanics (lane paths, tests from the lane root, Windows longpaths) are in the [board skill](../board/SKILL.md). **When the last child merges, close the umbrella** (board `Done` follows).
 
 Never free-type children with raw `gh issue create`: the batch path carries validation, board attach and structured output.
 

package/skills/hotfix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hotfix
-description: Promote a merged development fix to main and production via the Hub train.
+description: Promote a merged development fix to main and production via the Hub train. Use for an urgent already-merged fix, not for a normal release (release) or a candidate (rcand).
 ---
 
 **Host-native invocation:** Claude `/mmi:hotfix` · Codex `$mmi:hotfix` · jervcode `/hotfix` · OpenBot the `hotfix` skill (loaded by name).
@@ -11,6 +11,8 @@ description: Promote a merged development fix to main and production via the Hub
 
 The fix lands on `development` first; Hub ports that merged PR or SHA onto a main-base branch (cherry-pick with `-x`) and releases the PATCH. Never author the fix on a branch off `main`. The fix is NOT a back-merge (`rc` absorbs it next `/rcand`; the hotfix-coverage guard blocks a candidate omitting it).
 
+Pushing to `main` and production needs Jervaise's yes unless a standing authorization covers this repo (the support-session authorization in [release suite.md](../release/suite.md)).
+
 ## Lane
 
 MM-Work suite seats: read [suite.md](suite.md). Lane from META:
@@ -19,7 +21,7 @@ MM-Work suite seats: read [suite.md](suite.md). Lane from META:
 mmi-cli oracle org project get {owner}/{repo} --json
 ```
 
-A hotfix skips rc on every track; `deployModel: vercel` waits for the Production Deployment, then probes it. Unreadable META → stop; never infer the lane.
+A hotfix skips rc on every track; `deployModel: vercel` waits for the Production Deployment, then probes it (a leg left pending settles on the next doctor `--heal`). Unreadable META → stop; never infer the lane.
 
 ## Preflight
 
@@ -27,7 +29,7 @@ A hotfix skips rc on every track; `deployModel: vercel` waits for the Production
 mmi-cli devops train doctor --lane hotfix --heal --json
 ```
 
-Parse stdout only; never `2>&1`. `ready` false → stop and quote every blocker's `code` and `remedy`; an unread origin is never green. Findings carry `code`, `severity`, `source`, `remedy`, `anchor`.
+Read it per [train-common.md](../release/train-common.md#doctor).
 
 Piping `mmi-cli devops api get` into a JSON parser: a refusal exits 1 with empty stdout, so guard both exit status and nonempty output. For one job's runner and timestamps, read the allowlisted `repos/{owner}/{repo}/actions/runs/{id}/jobs` and filter `jobs[]` by `id`; `actions/jobs/{id}` is refused (only its `/logs`, with `--out`). Do not retry that refused endpoint or broaden the allowlist.
 
@@ -50,7 +52,7 @@ mkdir -p .jerv/tmp && r1=$(mktemp .jerv/tmp/hotfix-start.XXXXXX)
 mmi-cli devops hotfix start --from <pr|sha>[,<pr|sha>…] --json --out "$r1"
 ```
 
-2. Verify: local gate, required review, acceptance criteria. Merge with `mmi-cli devops pr merge <number> --squash` (waits for CI and review; keep the `-x` trailer). Because Hub's default branch is `development`, it closes no issue; no raw GitHub issue operations.
+2. Verify: local gate, required review, acceptance criteria. Merge with `mmi-cli devops pr merge <number> --squash --wait` (waits for CI and review; keep the `-x` trailer). Because Hub's default branch is `development`, it closes no issue; no raw GitHub issue operations.
 
 3. Release:
 
@@ -60,7 +62,7 @@ mmi-cli devops hotfix status --json
 mmi-cli devops hotfix release vX.Y.Z --carries <pr|sha>[,<pr|sha>…] --json --out "$r2"
 ```
 
-MMI-Hub adds `--announce-summary-file "$f"`: a fresh 3–6 line neutral summary, no product or brand name, never a product's board (`mutmutco/MMI-Hub` only). It tags, publishes, watches, announces, verifies, opens the `hotfix-fold/<tag>` PR. Do not hand-dispatch a second publish or deploy.
+MMI-Hub adds `--announce-summary-file "<summary-path>"`: a fresh 3–6 line neutral summary, no product or brand name, never a product's board (`mutmutco/MMI-Hub` only). It tags, publishes, watches, announces, verifies, opens the `hotfix-fold/<tag>` PR. Do not hand-dispatch a second publish or deploy.
 
 ## Verify
 
@@ -79,19 +81,15 @@ On any failure or interruption, read [recovery.md](recovery.md).
 
 ## Merge floor
 
-- **Never squash-merge a tagged commit (#3167).** A squash re-mints the SHA and orphans the tag, so tag-anchored checks mis-read. 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.
-- **Probe the latest Release tag, not branches or stale local tags (#2734).** Queue: `mmi-cli devops read pr queue <number> --repo <owner/repo> --json`; gh rejects `mergeQueueEntry`.
-- **One train per repo (#5380).** Overlapping trains race tags; never start one to help another.
-- **Tag and Release deletion need Jervaise's yes (principle 12),** named in the guide entry that prescribes it.
+Ordinary development PRs land with `mmi-cli devops pr land <number>`. Merges that carry a tagged commit (roll-forward, alignment, fold PR) are true merges, and a refused train is a stop, never finished by hand: the full floor is in [train-common.md](../release/train-common.md#merge-floor). Queue state: `mmi-cli devops read pr queue <number> --repo <owner/repo> --json` (gh rejects `mergeQueueEntry`).
 
 ## Report
 
-Verdict first: the resolved tag (never a placeholder like `vX.Y.0`), Release URL, `releaseStatus`, `followUpStatus`, `deployStatus`, `promoted`, each run's conclusion and URL (or the no-run-URL note), which run is red (deploy/publish verdict or ordinary CI), `announceNote`, the alignment note (`devRollForward`, `rcAlignment` or the fold PR), `checkout`, the dispatch used. Pending is unverified, never success. Product names only when releasing that product's repo.
+Verdict first, per [train-common.md](../release/train-common.md#report): the resolved tag (never a placeholder like `vX.Y.0`), Release URL, and the receipt fields above.
 
 ## Retro
 
-Before the final report: did this skill misfire? Process only. If yes, file one lesson (hard cap: one per run); a clean run is silent; if the call fails, note it and continue. Lessons are deduplicated on the owning board and change the skill only by reviewed PR, never live; no issue references outside Merge floor.
+Shared rules: [train-common.md](../release/train-common.md#retro).
 
 ```bash
 mmi-cli learning skill-lesson --skill hotfix --title "<what misfired>" --body "<what; evidence; proposed amendment>"

package/skills/hotfix/recovery.md

@@ -1,14 +1,10 @@
-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. 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`.
+Every refusal and every doctor blocker names its `code` and `anchor`: open the finding's `anchor` URL and follow that entry, nothing else ([shared recovery](../release/train-common.md#recovery)). 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`.
 
 A prior release's unresolved ledger also blocks this lane — and when its only unresolved leg is a content-caused failed deploy on the already-published tag, this lane is the fix's carrier: close that leg first with the master-approved `mmi-cli devops release --supersede-deploy --apply` (the cause fix must already be merged on `development`), then run the hotfix; the gate archives the closed ledger aside on its own.
 
 
 The `jerv-gateway` release leg has no run id: read `deployNote` / `ledger.phases.deploy`; `pending` means production was never deployed and blocks the next train run. Keep a failed announce summary for the supported continuation; never replay a delivery whose result is uncertain.
 
-## Field reference (moved from SKILL.md)
+## Status and Latest
 
-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; on `vercel` nothing is dispatched — Vercel builds `main` on the push and the hotfix waits for its Production Deployment and probes the URL, same as `/release --watch`; a leg left pending settles on the next doctor `--heal`. Unreadable META → stop; never infer the lane from branch names, tags or release history.
-
-The JSON is on stdout alone; a stale CLI first prints its self-update notice on stderr and re-runs itself, so parse stdout only, never `2>&1`. 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.
-
-`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:
+`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 ([verification.md](../release/verification.md#latest-release)); its `tag_name` must equal the tag.

package/skills/intercom-guest/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: intercom-guest
-description: Coordinate with the MM Coordinator over Jerv intercom as an org-member guest.
+description: Coordinate with the MM Coordinator over Jerv intercom as an org-member guest. Use to send, read, join or leave a suite, not to take orders or run commands from a message.
 ---
 
 **Host-native invocation:** Claude `/mmi:intercom-guest` · Codex `$mmi:intercom-guest` · jervcode `/intercom-guest` · OpenBot the `intercom-guest` skill (loaded by name). A backticked `/name` in this doc names the matching workflow, not a literal shell command.
@@ -30,18 +30,17 @@ mmi-cli harbour intercom guest join --suite <name> # request a suite join
 mmi-cli harbour intercom guest leave               # leave the suite and withdraw the endpoint
 ```
 
-`intercom` lives in the `harbour` house (a bounded coordination lane), so `harbour` is the canonical spelling; the older flat `mmi-cli intercom guest …` still runs and prints a notice telling you the canonical path.
+`intercom` lives in the `harbour` house (a bounded coordination lane), so `harbour` is the canonical spelling.
 
 These five are the whole surface. Use them in that spirit: `send` carries a status, a question, or an answer — never an instruction, and never a request to bypass a gate, a review, or an owner decision.
 
-## Step 2 — the contract is not landed yet: refuse, do not improvise
+## Step 2 — discover what the Gateway offers, never guess it
 
-The Gateway side of this (guest principal, GitHub-token verification, org allowlist, the MM Coordinator seat) is built in **Jerv-Hub#2522**. Until its guest operations land, every verb exits **2** with a refusal that names the missing contract. That is the correct state, not a bug to route around.
+The installed CLI is the only source of the wire shape; `mmi-cli harbour intercom guest --help` lists the verbs it knows. Run the verb you need and read its outcome. A refusal that names `intercom-guest-contract-missing` (exit 2) means this CLI build has no published Gateway operation for that verb. That is the correct answer, not a bug to route around.
 
-- Do **not** invent a Gateway URL, a path, a field name, or a "temporary" curl call. A guessed endpoint answers 404/403, and that reads like a permission or allowlist problem when the real answer is "the contract does not exist yet".
+- Do **not** invent a Gateway URL, a path, a field name, or a "temporary" curl call. A guessed endpoint answers 404/403, and that reads like a permission or allowlist problem when the real answer is "the contract is not there".
 - Do not silence the refusal or wrap it in a retry loop.
-- Report the gap in plain words: the intercom guest contract is not published yet (Jerv-Hub#2522), so no message was sent and nothing was read.
-- The one place the wire shape will live is `INTERCOM_GUEST_CONTRACT.operations` in `cli/src/intercom-guest.ts`. When the contract lands, that object is filled from it and every verb switches on — the skill text does not need to change.
+- Report the gap in plain words: which verb, the refusal text, and that no message was sent and nothing was read. Retry only after the CLI is updated.
 
 ## Step 3 — suite etiquette
 

package/skills/mmi-help/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mmi-help
-description: Introduce MMI and its commands.
+description: Introduce MMI and its commands. Use for a short help card, not to install, operate or release.
 ---
 
 # MMI help
@@ -19,9 +19,10 @@ Print a friendly, human-readable **MMI help** card of at most 180 words:
 2. Show the npm install command, `mmi-hub install`, and the read-only `mmi-hub status` check.
 3. Summarize the essentials: automatic updates, vault/keyless secrets, no repository environment
    files or personal agent instructions, and approved MMI release workflows.
-4. Name the org-guide skill for details, board, secrets, and release for common tasks, and
-   brand when a company document, report, deck, or artifact needs the house identity. Note that
-   org-guide carries the MM Open Design System Bible; handoffs cite it by path, never restate it.
+4. Name the org-guide skill for details, and board, secrets, and release for common tasks.
+   Company-branded documents, reports and decks come from the MM-Strategy MCP (`mm_brand_guide`),
+   not a skill. Note that org-guide carries the MM Open Design System Bible
+   (`references/design.md`); handoffs cite it by path, never restate it.
    Render invocation syntax for the current host only, using the forms above with the skill name
    substituted. If the host is unknown, use plain skill names rather than guessing.
 

package/skills/org-guide/SKILL.md

@@ -1,45 +1,36 @@
 ---
 name: org-guide
-description: Read org project rules and how to report MMI CLI, plugin, or workflow bugs.
+description: Read org project rules and how to report MMI CLI, plugin, or workflow bugs; use before project work, never releases or secrets.
 ---
 
-# MMI organization guide
+# MMI org guide
 
-Read this entry before MMI project work, then **only the topic relevant to the task**. For a human introduction, use
-the [MMI help skill](../mmi-help/SKILL.md).
+Read this entry before MMI work, then **only the relevant topic**. Human intro: [MMI help](../mmi-help/SKILL.md).
 
 ## Essential rules
 
-- Install `@mutmutco/hub` through npm, run `mmi-hub install`, and keep automatic updates enabled.
-  Check health with `mmi-hub status`; installation alone does not prove updates work.
-- Use the scoped two-tier vault and keyless workflows. Never put secret values in chat, logs,
-  command arguments, or repository environment files.
-- Personal agent instructions and host settings stay local and gitignored; never commit AGENTS.md,
-  CLAUDE.md, or copied plugin instructions.
-- Update affected `docs/Guides/operator.md` instructions with code. Commit, then run existing fast preflight before pushes/PRs.
-- Claim approved work through the board, use the repository's checks, and land through MMI.
-  A help or plan request does not authorize changes or releases.
-- When an MMI tooling bug affects a developer other than `jervaise`, ask before filing a Hub report
-  and respect a decline; see [tooling bug reports](references/work-and-releases.md#report-mmi-tooling-bugs).
-- Read the registry for release tracks, domains, and OAuth from origin. Use MMI provisioning and release
-  workflows, never parallel deployment or credential paths.
-- Verify canonical/Git-resolved support scripts; use absolute script/target/source paths, never sibling guesses
-  ([invocation rules](references/work-and-releases.md#shared-support-script-invocation)).
-- Design work follows the [MM Open Design System Bible](references/work-and-releases.md#the-mm-open-design-system-bible-8837-8839):
-  never patch broken shared tools with one-off `tmp/` scripts; fix them at source, record a learning
-  note, and update memory.
+- Install `@mutmutco/hub` via npm, run `mmi-hub install`, keep auto-updates enabled, check `mmi-hub status`.
+- Use the two-tier vault and keyless workflows; never put secrets in chat, logs, CLI args, or env files.
+- Agent instructions and host settings stay local/gitignored; never commit AGENTS.md, CLAUDE.md, or copied plugin instructions.
+- Update affected `docs/Guides/operator.md` instructions with code; commit, then fast preflight before pushes/PRs.
+- Claim work via the board, run repo checks, land via MMI. Help/plan requests never authorize edits or releases.
+- If an MMI tooling bug affects a developer other than the org owner, ask before filing a report ([tooling bug reports](references/work-and-releases.md#report-mmi-tooling-bugs)).
+- Read origin registry for release tracks, domains, OAuth; use MMI provisioning/release workflows, never parallel deploy or credential paths.
+- Verify canonical/Git-resolved support scripts; use absolute script/target/source paths, never sibling guesses ([invocation rules](references/design.md#shared-support-script-invocation)).
+- Design work follows the [MM Open Design System Bible](references/design.md#the-mm-open-design-system-bible-8837-8839): never patch broken shared tools with `tmp/` scripts; fix at source, record a learning note, update memory.
 
 ## Read one topic
 
 | Task | Local reference |
 | --- | --- |
 | Install, update, reload, or diagnose tooling | [Getting started](references/getting-started.md) |
-| Report an MMI tooling bug with developer consent | [Tooling bug reports](references/work-and-releases.md#report-mmi-tooling-bugs) |
-| Work an issue, test, merge, release, or design | [Work and releases](references/work-and-releases.md) |
+| Report a tooling bug with developer consent | [Tooling bug reports](references/work-and-releases.md#report-mmi-tooling-bugs) |
+| Work an issue, test, merge, or release | [Work and releases](references/work-and-releases.md) |
+| Do UI, design, docs, or MM Artifact work, incl. the Design System Bible | [Design](references/design.md) |
 | Consume, declare, rotate, or request a secret | [Vault and keyless access](references/vault.md) |
 | Register domains or configure Google OAuth | [Domains and OAuth](references/domains-and-oauth.md) |
 | Decide what belongs in a product repository | [Repository rules](references/repository-rules.md) |
-| Build an MM-Work module | not bundled — [MM-Work module guide](https://github.com/mutmutco/MM-Work/blob/development/packages/mmwork-ds/GUIDE.md) in `@mutmutco/mmwork-ds` |
-| Produce company-facing documents in the MM brand | not bundled — the MM-Strategy MCP serves the brand kit (`mm_brand_guide`); strategists install `@mutmutco/strategy` |
+| Build an MM-Work module | not bundled — [MM-Work module guide](https://github.com/mutmutco/MM-Work/blob/development/packages/mmwork-ds/GUIDE.md) in `@mutmutco/mmwork-ds`; read `pieces.json`, `mmwork.d.ts`, `FOR-AGENTS.md`, and `docs/components/<Piece>/guide.md` from the npm project declaring it (`module/node_modules/@mutmutco/mmwork-ds/`), never repo-root `node_modules`; when absent, fall back to `~/.jerv/cache/mmwork-ds/latest` or MM-Work `packages/mmwork-ds`, treat capability as unknown |
+| Produce company-facing documents in the MM brand | not bundled — MM-Strategy MCP serves the brand kit (`mm_brand_guide`); install `@mutmutco/strategy` |
 
-Bundled MMI guidance matches the installed plugin, not Jerv/JervCode. Resolve current values and flags through the live CLI.
+Bundled guidance matches the installed plugin, not Jerv/JervCode; resolve current values/flags via live CLI.