@mutmutco/hermes-plugin 3.139.1

package/skills/hotfix/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: hotfix
+description: Promote an already-merged development fix to main and production through the gated Hub train.
+---
+
+**Host-native invocation:** Claude `/mmi:hotfix` · Codex `$mmi:hotfix` · jervcode/Kimi `/skill:hotfix` · Kilo `skill` tool. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
+
+# /hotfix — promote a development fix to main + prod
+
+A hotfix is promotion, not authoring. The fix must land on `development` through a normal issue,
+worktree, PR, review, and CI gate first. Hub then ports that merged PR or SHA to a main-base hotfix PR,
+preserves the cherry-pick audit trail, and performs the PATCH release. Never author directly from `main`.
+Never author the fix on a branch off `main`. The main-base branch is only the orchestrated port of a fix
+that is already merged to `development`.
+
+The FIX is never back-merged: `development` already contains it, and `rc` absorbs it at the next
+`/rcand`. The release hotfix-coverage guard blocks a later candidate that omits the production fix.
+
+The VERSION FOLD is different, and `hotfix release` ports it for you (#4410). `hotfix start` commits the
+fold onto the main-base branch, so after the tag `main` declares the new version while `development`
+still declares the old one. The Hub's catalogs now pin exact npm packages (#4948), so there is no
+branch/content lockstep red; the fold still must land so the next release starts from production's real
+version, BOM, and package pins. Step 3 opens that development-base fold PR automatically; land it.
+
+## Merge floor (#3167 — non-negotiable)
+
+- **Never squash-merge a tagged commit.** The hotfix PR itself may squash (step 2 — the tag lands *after*,
+  on the merged `main` HEAD, and the `-x` trailer must survive the squash message). But any merge that
+  carries an already-tagged commit — an alignment PR, a later `main → development` roll-forward — lands as a
+  true merge, never squash: a squash re-mints the SHA and orphans the tag from the branch lineage.
+- **A refused release train is a stop, never a license to finish by hand.** A conflict on the port, a red
+  authority probe, a failed required check, a refused `hotfix release` — each ends the run. Fix the cause on
+  `development` through a normal PR and re-run the orchestrator; never hand-cherry-pick, bare-push, or
+  bypass the gate to finish.
+- **Version probes anchor on the latest Release tag, not a branch.** `hotfix status` derives the PATCH from
+  the latest Release tag; branch manifests and stale local tags are not version sources.
+
+## Authority and preflight
+
+Production changes require the authorized human's explicit approval in the current turn. Verify authority
+and CLI health before starting:
+
+```bash
+mmi-cli oracle org access role <owner/repo> --json
+mmi-cli doctor --no-repo-writes
+```
+
+Stop on a red authority or CLI-version result. The worktree must be clean; move scratch into `tmp/` or
+gitignore it rather than widening the hotfix diff. A TRACKED path named in a `working tree must be clean
+before …` refusal is not scratch: read both `git status --porcelain` columns, treat every state except
+exactly ` M` as real work to commit or stash, and for ` M` discard only when
+`git diff HEAD --numstat -- <paths>` is empty, and only with `git checkout -- <paths>`. Plain
+`git diff --numstat` prints nothing for a merely staged change, so it cannot make that call (#4004).
+
+## 1. Start from the merged development fix
+
+Use the orchestrator with an explicit source every time:
+
+```bash
+mmi-cli devops hotfix start --from <development-pr-or-sha>[,<development-pr-or-sha>...] --json
+```
+
+**One hotfix cycle carries as many merged fixes as you name.** `--from` takes a comma-separated list in
+pick order, and every sha it picks goes into the PR's carries marker, so the release proves each one
+present before tagging. Do not open one hotfix per fix: batch everything ready for production into the
+single PATCH. A fix that only becomes ready mid-cycle rides the same tag — cherry-pick it with `-x` onto
+a `hotfix/<tag>-<n>` continuation branch, merge that PR, and rerun `hotfix release` with the full
+`--carries` list; the release pins the newest merged SHA (#1025).
+
+`hotfix start` resolves the PATCH version, branches from `origin/main`, performs the cherry-pick with `-x`,
+prepares Hub distribution artifacts when applicable (stamping BOM `sourceCommit` at the durable
+`origin/main` merge-base so a squash merge cannot orphan it — #4361; and for `registry-publish`
+consumers, folds the package version so upgrade probes observe the PATCH), pushes the branch, and opens
+the main-base PR. Do not duplicate those steps with raw branch commands, manual cherry-picks, or raw
+GitHub PR creation.
+
+Conflicts confined to regenerable distribution / version-fold paths (e.g. Hub `distribution-bom.json`,
+locked plugin manifests, consumer `package.json`) — and, for hub-serverless + registry-publish, shipped
+skill roots `skills/` and `.kilo-plugin/skills/` (#4363 / #4471) — are auto-resolved (take the picked
+side) and regenerated by the bump/fold step. Source TS under `src/` / `cli/src/` is never auto-resolved.
+
+Before cutting the hotfix branch, `hotfix start` preflights every `--from` pick on an accumulating
+`origin/main` tree (#4472). If any pick would hard-stop, it refuses with every failing pick and path and
+prescribes **one** development-based cite-only synthesis PR for the whole batch (#4643; the old
+"cut from origin/main" pattern #4467 wording is retired — a main-parented branch must never merge
+into development, #4365/#4371): cut from `origin/development`, regenerate the conflicting content so
+it cherry-picks cleanly onto `origin/main`, land it with the cite-only marker (the #5096 flow) — not N
+serial ports. Behavior changes still land on `development` first through a normal PR, then rerun hotfix
+start from the port merge SHA(s) — never hand-resolve onto main.
+
+## 2. Verify the hotfix PR
+
+Run the repo's local gate against the hotfix branch, then obtain the independent reviewer required by the
+active agent doctrine. Review the actual main-base diff and the original issue acceptance criteria.
+
+Wait for required CI through Hub:
+
+```bash
+mmi-cli devops pr checks-wait <hotfix-pr-number>
+mmi-cli devops pr merge <number> --squash
+```
+
+The main-base PR is the production gate. Do not bypass checks or protected-branch authority. After the
+authorized merge, verify the merged main commit still carries the cherry-pick provenance; if the PR was
+squashed, the source trailer must survive in the squash message so future coverage checks remain exact.
+Because Hub's default branch is `development`, the main-base hotfix PR does not close a separate tracking
+issue. The development PR should already have closed the work item; do not add raw GitHub issue operations.
+
+## 3. Run the gated release
+
+Derive the tag from `mmi-cli devops hotfix status`, then release with the same declared source:
+
+```bash
+mmi-cli devops hotfix status
+mmi-cli devops hotfix release <vX.Y.Z> --carries <development-pr-or-sha>[,<development-pr-or-sha>...]
+```
+
+Name **every** fix the cycle carries. Each is proven an ancestor of the tagged SHA before tagging; a
+missing one refuses the release and names the continuation path.
+
+For MMI-Hub, pass a fresh 2-4 line neutral summary file with `--announce-summary-file`; never reuse a
+stale file and never put a product or brand name in the summary. Hub release scope never includes another
+repo's board or `ds-propagate.yml`. The orchestrator creates the tag and GitHub Release, selects the
+registry-declared deploy path, watches the release-triggered or central deployment, verifies distribution,
+and announces best-effort. Do not hand-dispatch a second publish/deploy path: duplicate release events can
+race or double-publish.
+
+For a private package, trust the authenticated publish job and its logged package/version result; a bare
+unauthenticated `npm view` cannot distinguish private from missing.
+
+## 4. Verify and report
+
+Report the tag and Release URL, production run and URL, source development PR/SHA, hotfix PR, and these
+branch facts:
+
+- `main`: the tag commit is on `origin/main`.
+- `development`: the source fix was already merged before the hotfix began.
+- `rc`: intentionally untouched; the next release coverage gate prevents regression.
+- the development fold PR the release opened (`hotfix-fold/<tag>`), and whether it landed.
+
+Do not hand-open a manifest-alignment PR: the version fold is already ported by `hotfix release` — land
+its PR instead of authoring one. That port is explicitly NOT a back-merge — nothing from `main` is
+merged into `development`; the fold is regenerated on a branch cut from `development` itself. If the run
+reported `development fold port FAILED`, follow the manual remedy it named; never improvise a merge from
+`main`.
+
+### Development fold after a hotfix (#4517 / #4948)
+
+The Hub's thin catalogs now pin exact npm packages, so the old main-anchored catalog-lockstep gate is
+retired: an unreleased branch cannot deliver a package version the release train has not published.
+Hotfix versioning still belongs on the main-base train, never in an improvised development prepare PR:
+
+1. `mmi-cli devops hotfix start --from <merged-dev-pr-or-sha>` (prepare + distribution bump on `hotfix/vX.Y.Z` from `main`)
+2. merge the hotfix PR → `mmi-cli devops hotfix release vX.Y.Z` (publish)
+3. land the automatic `hotfix-fold/<tag>` development fold PR (or follow its printed remedy)
+
+The fold is now required for version/BOM/package-pin continuity, not to clear a branch-content gate.
+
+## Retro
+
+If this skill's instructions themselves misfired, file one deduplicated lesson and continue:
+
+```bash
+mmi-cli learning skill-lesson --skill hotfix --title "<what misfired>" --body "<what; evidence; proposed amendment>"
+```

package/skills/mmi/SKILL.md

@@ -0,0 +1,398 @@
+---
+name: mmi
+description: Show, claim, move, or file work on the repo board.
+---
+
+# mmi — start of work
+
+Shows a dev their workboard for this repo: what they're working on, what's free to pick up, and what others
+have claimed. Read-only by default — render the board, then get out of the way.
+
+Explicit invocation is host-native: `/mmi:mmi` in Claude Code, `$mmi:mmi` in Codex, `/mmi`
+(canonical `/skill:mmi`) in Kimi Code CLI, and the `mmi` skill (listed in Kilo's `/` picker, invoked via
+the `skill` tool) in Kilo Code. The `/mmi` label used below names this workflow; it is not a
+universal literal command.
+
+Status values: `Todo · In Progress · In Review · Done` (GitHub enforces who can move what — don't re-explain
+it on every move). Closed/finished items auto-archive after they go quiet; archived ones aren't on the board.
+
+## Step 0 — identity, greet, eager preflight when stale
+
+`/mmi` is the dev's hello-to-work — the most common command they run. Three pacing rules before anything else:
+
+1. **Resolve login, then greet immediately** (before `board read` or doctor — still the first lines in
+   the response so the dev never stares at silent tool output). One emoji max in the whole response.
+   The greeting addresses the dev, never claims to *be* them (not "I'm @<login>"):
+   - **SessionStart banner** — if context carries `current human: <login>`, use that login.
+   - **Else** one fast call: `mmi-cli whoami --json` (cached Hub session in `hub-session.json` when
+     valid — no network; `gh` fallback only when the cache lacks `login`; exit 0 on `unknown`). Do
+     **not** call `gh api user` separately — `whoami` already covers it. Do **not** wait on `board read`
+     for identity — `viewer` is for work items only (Step 1).
+   - Known login → `👋 Welcome back, @<login> — pulling up your board…`
+   - `source: unknown` → generic `👋 Welcome back — pulling up your board…`
+2. **Keep the board fast: read first, run doctor only when evidence says it can change this render (#2112).**
+   The normal happy path is identity → board read. Do **not** block the board on a doctor run just to
+   check freshness. Run doctor synchronously only after a hard signal that the current setup may be broken:
+   `mmi-cli` is missing, `board read` reports missing auth/project scope, the command surface is absent, or a
+   cached/session-start health line explicitly says a heal is needed.
+
+```bash
+mmi-cli oracle board read --json    # Step 1 — first useful render on the happy path
+mmi-cli doctor --no-repo-writes   # only after a hard setup signal — foreground, one at a time
+```
+
+Since #4199 `--preflight` is **READ-ONLY** (docs/doctor-contract.md § Flag Grammar — the canon
+reversal; jerv semantics win estate-wide): it measures and reports with the shared exit code and performs
+zero writes. The heal lane for "fix my env before work" is `doctor --no-repo-writes` — the default heal
+run minus repo working-tree mutation. Its heals are `npm install -g` and a marketplace remove → add →
+install, both machine-global, serialised behind a machine-wide lock (#3489), so two concurrent runs no
+longer interleave inside the npm prefix or the marketplace clone — the second waits, and if the first is
+still installing after two minutes the second reports the heal as skipped rather than forcing it.
+
+Still run it in the foreground and wait. The lock stops corruption, not confusion: a backgrounded run
+that reports "skipped — lock busy" has healed nothing, and an agent that does not read that line will
+carry on believing its tooling was fixed.
+
+`doctor --no-repo-writes` heals a stale/unresolved plugin install (the **env** half of the interactive
+doctor, #3485/#3975) — it never touches the repo working tree. When it prints
+`↻ Updating mmi tooling, one moment…`, relay that before waiting; when it prints `↻ MMI tooling
+updated — …`, relay the reload/restart guidance.
+
+What the env half heals:
+
+- a stale or unresolved Claude plugin → `claude plugin marketplace remove mmi` → `… remove mutmutco` →
+  `claude plugin marketplace add mutmutco/MMI-Hub` → `claude plugin install mmi@mutmutco`. A fresh
+  reinstall, never `claude plugin update`, which nests into itself past MAX_PATH on Windows and wipes the
+  marketplace clone (#1126). Effective after a reload: **restart Claude Code / run `/reload-plugins`**
+  (native), or **reopen the workspace** (VS Code extension).
+- superseded plugin cache versions → the guarded auto-prune (#4199, canon per
+  docs/doctor-contract.md § Guarded cache prune): never the running/newest/installed version, a cache a
+  live session holds is named "still held" and never forced.
+
+What it does **not** do since #4954: converge CLI or host versions. A behind npm global is REPORTED
+and the `fleet` row reads MMI Hub's last-run journal evidence. `mmi-hub update` is the single safe
+version-convergence writer; plain doctor and `/mmi` never run repository cleanup.
+
+- **Fast path** → `whoami` then `board read`; no foreground doctor.
+- **Hard setup signal** → run `doctor --no-repo-writes`, relay `↻` lines, then retry `board read` when appropriate.
+- **`mmi-cli: command not found`** → plugin PATH provisioning has not applied, or the standalone CLI is not installed.
+  In Claude Code, reopen the session; if it persists, install the MMI plugin:
+  `/plugin marketplace add mutmutco/MMI-Hub` → `/plugin install mmi@mutmutco` → `/reload-plugins`.
+  On Codex, install the Hub-shipped plugin: `codex plugin marketplace add mutmutco/MMI-Hub` →
+  `codex plugin add mmi@mutmutco`, then trust the bundled hooks via `/hooks`. On Kimi Code CLI:
+  `/plugins install https://github.com/mutmutco/MMI-Hub` → `/reload`. On Cursor, run
+  `mmi-cli plugin heal`, then reload the Cursor window. On OpenCode and plain shell install the
+  maintenance package; it provisions the standalone CLI:
+  ```powershell
+  npm install -g @mutmutco/hub
+  mmi-hub install
+  ```
+  In PowerShell from an `MMI-Hub` checkout, or when diagnosing a stale plugin cache, use the repo-local fallback:
+  ```powershell
+  node cli/dist/index.cjs doctor --json
+  ```
+- **The host-native skill entry is missing** — `/mmi:mmi` is absent in Claude, `$mmi:mmi` is absent in
+  Codex, or `/skill:mmi` is absent in Kimi (the auto-heal below is Claude-only; Codex and Kimi ship the
+  same skills but repair is a manual reinstall — see their recipes above) → the plugin is stale,
+  duplicated, or disabled, so the skill surface is gone and you can't reach this workflow through the
+  host UI. Recover from the shell with the repo-local doctor, which detects and self-heals it:
+  ```powershell
+  node cli/dist/index.cjs doctor      # from an MMI-Hub checkout — auto-heals + prints the reload action
+  ```
+  If `claude` isn't on PATH for the auto-heal, run the reinstall by hand (never `/plugin` in VS Code — it
+  isn't an updateable path there):
+  ```bash
+  # Claude Code (native or VS Code extension)
+  claude plugin marketplace remove mmi && claude plugin marketplace remove mutmutco && claude plugin marketplace add mutmutco/MMI-Hub && claude plugin install mmi@mutmutco
+  # then: restart Claude Code / run /reload-plugins  (VS Code: reopen the workspace)
+  ```
+- **A gate is ✗** → walk them through the printed fix; don't just echo it:
+  - **GitHub auth** (the usual one) — the board uses its `gh` token. Give them the
+    command to run **in their own terminal** (the browser step is theirs — an agent can't log in as them):
+    ```bash
+    gh auth login --hostname github.com --git-protocol https --web --scopes "project"
+    ```
+    The `project` scope is what lets `/mmi` read + move the board, granted here once. When they're back,
+    re-run `mmi-cli doctor --preflight` to confirm green without writes.
+  - **Hub registry / board META** — `mmi-cli oracle org project get <owner/repo>` or `mmi-cli oracle board read` reports
+    missing project/board coords → a master-admin registers or backfills the repo's `PROJECT#<slug>` META.
+    There's no reliable project to read until that is fixed, so stop here.
+
+A broken setup surfaces from `doctor --preflight` (read-only), a failed `board read`, or a gate that still fails after
+heal — handle it then. A `command not found` from **either** command routes into the recovery paths above.
+Don't block the all-green path on doctor noise.
+
+## Authority (org-wide)
+
+`/mmi` is the usual session start — agents should know the dev's role before any later train, vault, or
+tenant request surfaces. After the board read (Step 1), you already have `viewer` in the JSON; for train
+authority on this or another repo, run:
+
+```bash
+mmi-cli oracle org access role <owner/repo> --json   # { role, train } — Hub-verified from registry projectAdmins
+```
+
+When `role` is `project-admin` and `train` is true on **that** repo, the dev holds D14 authority there —
+guide or execute via the matching skill (`/secrets`, `/rcand`, `/release`, `/hotfix`, `runtime tenant control`).
+**Do not** redirect them to the master. Hub train is master-only; org-tier vault and access grants stay
+master-only. Full matrix: `AGENTS.md` § Authority.
+
+## Config
+
+The project this repo is on lives in the Hub registry (`PROJECT#<slug>`: `projectOwner`, `projectNumber`,
+`projectId`, `statusFieldId`, `statusOptions{}`, and optional Priority field ids), set by `/bootstrap`
+(repos and projects are not 1:1 — a repo attaches to a chosen project). Refresh the registry META if a
+lookup misses; do not read or repair committed repo-local board config.
+
+## Step 1 — read the board (one call, caller-scoped)
+
+SessionStart injects a **bounded board slice** (assigned + top claimable items, max five lines,
+3s timeout, fail-soft) and, when task relevance is high-confidence, up to **two North Star context
+cards** (title + compact intent, PRIOR-not-instruction framing — silent when ambiguous). For the
+complete partition — secondary repos, taken items, bundle details — run the full command below.
+
+```bash
+mmi-cli oracle board read --json
+```
+
+This is the **only foreground call** on the happy path for **work items** (not identity — Step 0 already
+resolved login). Its JSON carries `viewer`, `repo`, and the project title — do **not** run separate
+`gh api user` / `gh repo view` calls; they just delay the board. If `repo` is missing from the JSON,
+keep the board header generic. The CLI resolves the project from the Hub registry; to inspect it
+directly, `mmi-cli oracle org project get --json`.
+
+Use the returned `primary` group for current-repo items and `secondary` for other repos on the same Project.
+Within each group, render `userOwned`, `claimable`, and `taken`.
+
+CLI partition:
+- **Yours** — assignee includes the viewer AND `Status ∈ {Todo, In Progress, In Review}`.
+- **Free to claim** — `Status == Todo` AND unassigned AND the viewer has repo write permission
+  (`repos/<owner>/<repo>.permissions.push == true`). Issue filing stays available to any authenticated
+  org member; claiming work is gated by write access.
+- **Taken** — assigned to someone else (any active status). Render id + status + owner ONLY — no title.
+
+Do not cache claimable state. Every `/mmi` board is a fresh Project v2 read. Partial reads exit nonzero by
+default; use `--allow-partial` only when the dev explicitly accepts an incomplete board. If the read fails
+for a missing `read:project` scope, surface that verbatim — the dev grants it once at `gh auth login`.
+
+## Step 2 — show the board
+
+This render is the product: welcoming, guiding, clear — and gone in one glance. Plain **markdown**,
+never a fenced code block (monospace hard-wraps long titles and the structure is lost). The shape:
+
+- **Short refs.** `[RepoName#N](issue-url) · short title` — repo name + number only, no `owner/`
+  prefix, no `[type]` brackets. The ref is the clickable link; the title follows after `·`, trimmed
+  to its essence (drop boilerplate prefixes, keep it under ~8 words).
+- **Flat `-` lists** under bold head lines — never `##` headings (too heavy for a three-section
+  board), never nested bullet trees, never tables, never a literal `•` glyph (it breaks GFM list
+  parsing).
+- **Three heads, each with one factual clause** appended after an em dash — a fact the dev can act
+  on ("two train fixes in flight"), not cheerleading. Encouragement lives once, in the close.
+  - **On your plate** — the dev's items, status noted inline after the title (`· in review`) when
+    not In Progress. In Review means *awaiting admin review & merge* — caption it that way, never
+    "ready to move".
+  - **Up for grabs** — claimable items.
+  - **Taken** — id · status · owner ONLY, never the title. No commentary clause; it's reference.
+- **Skip empty sections silently** — no "nothing here" filler. Empty board entirely → one warm line:
+  nothing assigned, point at Up for grabs or filing a new item.
+- **Close with one grounding line** — no question, no hype, no pressure: `Pick one and claim it
+  when you're ready.` plus the standing quiet affordance `Or file a new item — say the word.`
+- **One screen total.** Greeting + sections + optional Leverage (Step 6) + close.
+
+Full example (greeting printed earlier, before the read):
+
+> 👋 Welcome back, @dev — here's your board on **MMI-Hub**.
+>
+> **On your plate** — two train fixes in flight:
+> - [MMI-Hub#834](https://github.com/mutmutco/MMI-Hub/issues/834) · automated hotfix apply path
+> - [MMI-Hub#841](https://github.com/mutmutco/MMI-Hub/issues/841) · rcand stuck on required checks
+>
+> **Up for grabs** — ready when you are:
+> - [MMI-Hub#821](https://github.com/mutmutco/MMI-Hub/issues/821) · redesign tenant env-writer
+> - [MMI-Hub#839](https://github.com/mutmutco/MMI-Hub/issues/839) · revisit hotfix back-merge policy
+>
+> **Taken**
+> - MMI-Hub#827 · In Progress · @otherdev
+>
+> **Leverage**
+> - #834 and #841 are both train-lane — I can run them side by side, one PR each.
+>
+> Pick one and claim it when you're ready. Or file a new item — say the word.
+
+Only an admin merges (a project-admin on their own project, the master-admin everywhere); the dev who
+opened the PR waits on that review, they don't move it themselves.
+
+## Step 3 — stop (act only on request)
+
+Render the board and stop. Don't prompt for a choice, don't recommend a next move, don't ask "what now?".
+The dev drives: when they say claim / continue / file — or accept a Leverage offer (Step 6) — do it.
+Otherwise the board alone is the answer.
+
+**Status moves happen automatically** as the work flows (claim, PR open, merge, release). The dev never
+moves an item by hand, so **never suggest a status move** — not "advance to Test", not "mark this PR",
+not "ready to move?". The board reflects state; it doesn't ask the dev to change it.
+
+The one standing affordance is **filing a new item** — always available, no item needed. The Step 2
+close line already carries it (`Or file a new item — say the word.`); never turn it into a status
+nudge. If the dev takes it, run the guided flow in Step 5.
+
+## Step 4 — load the full item before working it
+
+The moment the dev commits to an item (continue or claim), read the **whole** work item before planning or
+acting — never from the board title alone. Body **and every comment**, end-to-end; treat later comments as
+potentially **superseding** the body. Only then greet into the work or propose a plan.
+
+```bash
+# One shot — status, assignees, type, body, and every comment for one board item:
+mmi-cli oracle board show <owner/repo#N>          # add --json for machine-readable output
+```
+For an item **not on the board**, `mmi-cli oracle issue view <N> --comments` is the board-independent one-shot:
+it returns the body **and** every comment as JSON in a single call (add `--context` for `linkedPrs` and, on
+an epic, a `children` summary). Prefer it over raw `gh issue view --comments`, which in a non-TTY shell (every
+agent/CI context) prints only the comments, hides the body, and prints nothing at all on a zero-comment issue.
+```bash
+mmi-cli oracle issue view <N> --repo <owner/repo> --comments   # body + every comment, one call
+```
+
+> **Never reach for standalone `jq`** — it isn't installed on Windows dev machines, so each attempt burns a
+> failed call (#230). `mmi-cli oracle board read|show` is already human-readable (drop `--json`); to parse JSON use
+> `mmi-cli … --json` piped to `node`, or `gh`'s **built-in** `--jq`.
+
+(Triggers only when a dev commits to an existing item — no-op for the *report a bug / request a feature /
+something else* paths.)
+
+## Step 5 — act
+
+- **Claim:** when the dev takes an item, assign them + set `In Progress` in one go. This is the only status
+  write `/mmi` makes, and only as the mechanical side of claiming — never as a standalone "move" the dev
+  is offered. Every later transition (In Review on PR open, Done on merge) flows automatically from the
+  work, not from here.
+  ```bash
+  mmi-cli oracle board claim <owner/repo#N> --json
+  ```
+  The command validates `Todo` + unassigned, assigns the viewer, and moves the Project v2 `Status` to
+  `In Progress`. A partial claim exits nonzero unless the dev explicitly accepted `--allow-partial`.
+  Claiming several items (batch/parallel act-paths) takes them in **one call** — `board claim <ref> <ref> …`
+  — which shares the setup cost and reports per-item results (any per-item failure → nonzero exit).
+- **File a new item (guided by type → template):** don't free-type an issue. Walk the dev through it:
+  1. **Pick the type** — `bug` · `feature` · `task` (the repo's three `.github/ISSUE_TEMPLATE/` forms;
+     each carries its own label). Offer the choice with the structured-question UI, one line each:
+     bug = something's broken · feature = new capability · task = chore/improvement.
+  2. **Fill that type's template.** Read its fields from `.github/ISSUE_TEMPLATE/<type>.yml` and gather
+     answers from the dev for each — draft where you can, ask where you can't (the template form is
+     interactive and won't drive in a non-TTY agent shell, so collect the fields, then create directly).
+  3. **Submit via `mmi-cli oracle issue create`** — the canonical create path. Before filing, read the live
+     command contract from `mmi-cli explain oracle issue create --json`; flags change, and a missing documented flag means
+     the installed CLI is stale until a fresh local build proves otherwise. It maps `--type` to the label,
+     `--priority` sets the board Priority **field** (never a `priority:*` label — #416), and `--surface`
+     supplies the repository's required single surface label. It always prints `{number,url}` JSON. Never
+     use `gh issue create`; it bypasses these board contracts:
+     ```bash
+     mmi-cli oracle issue create --type <bug|feature|task> --title "<title>" --body "<filled template>" \
+       --priority <high|medium|low> --surface <surface>
+     ```
+     For long markdown, materialize a temporary UTF-8 body file, pass its real path with
+     `--body-file <path>`, then remove it after the write succeeds. Do not pipe multiline markdown to
+     `--body-file -` on a guarded host.
+     A title with backticks needs `--title-file` (#3381). On Windows Git Bash, a title that starts
+     with `/` (or contains an MSYS-path-shaped token) is rewritten before `mmi-cli` sees it — e.g.
+     `--title "/update …"` becomes `C:/Program Files/Git/update …`. Prefer `--title-file <path>`, or
+     prefix the create with `MSYS_NO_PATHCONV=1` (#4373).
+     The command starts bounded related-issue discovery off-path. It auto-comments only high-confidence,
+     idempotent links. To inspect candidates manually before writing anything else:
+     ```bash
+     mmi-cli oracle issue discover-related --repo <owner/repo> --number <number> --title "<title>" --body "<body>" --json
+     ```
+  It lands on the board as Todo automatically — confirm the link from the JSON. (Templates differ per
+  repo; read the actual `.yml` set rather than assuming bug/feature/task.)
+- **File a friction report (org-tooling pain):** `mmi-cli learning report --title "<one-line>" --body "<what hurt>"`
+  files it on the Hub board via your Hub session and dedups against the open reports (a confident
+  duplicate becomes a +1 comment, not a new issue). The actual GitHub write runs server-side with the
+  Hub App's own token (#263), so no MMI-Hub repo access is required to file. Never read Hub coordinates or
+  keys from a repo-local `.env`, call a repo-local report script, or POST the Hub API directly — the CLI
+  carries the endpoint and your Hub session intrinsically.
+- Surface any `gh`/`mmi-cli` error verbatim.
+
+## Step 6 — Leverage (offer where it fits)
+
+`/mmi` is an agentic coding board — every item is written by an LLM agent, so the board can do more than
+hand over one item at a time. Between the Taken section and the close, render an optional **Leverage**
+block: **up to two** offers, one line each, under a bold `**Leverage**` head (see the Step 2 example).
+**Default to silence:** if nothing below crisply fits, omit the whole block — never pad it. Never use a
+question-UI, never pressure — the dev acts or ignores.
+
+Pick up to two, in priority order:
+
+1. **Split + fan out** — a single item plainly too large for one PR (body is multi-part, an umbrella or
+   epic). Offer to slice it into child issues. (First because it *creates* the items the rest act on.)
+2. **Batch** — 2+ claimable items that are one coherent unit (shared title-prefix family, same subsystem)
+   **and** touch overlapping/adjacent paths. Coupled → **one PR**.
+3. **Parallel** — 2+ items that are mutually independent and touch **disjoint paths**. Independent → **one PR each**, run concurrently.
+4. **Background** — a single long-running item (broad refactor, large build/sweep). Kick it off in the
+   background so the dev isn't blocked.
+
+Disjoint paths is the deciding signal between batch (overlap → one PR) and parallel (disjoint → N PRs).
+When unsure which fits, prefer the more conservative offer — a marginal call is worse than a quiet board.
+Two offers must not overlap (never the same item in both); a second marginal offer is worse than one
+crisp one.
+
+Bundling detail boundary: start from the metadata board. Only if there are multiple viable
+`userOwned`/`claimable` candidates, fetch bodies/comments with:
+
+```bash
+mmi-cli oracle board read --json --bundle-details
+```
+
+That detail path may fetch bodies/comments only for `userOwned` and `claimable` issues. `taken` stays
+metadata-only, always. Do not fetch Done items, do not cache claimables, and do not pass `--allow-partial`
+unless the dev explicitly accepts an incomplete Leverage read. If detail lookup exits nonzero, render
+the board without a Leverage block.
+
+Offer lines — one line each, no UI, no "(Recommended)", phrased as available leverage:
+
+- **Batch** — `These read like one change — I can take #66–#70 together in a single PR if you'd like.`
+- **Parallel** — `#17 and #18 are independent — I can run them side by side, one PR each, if that helps.`
+- **Background** — `#22 looks long-running — I can take it in the background so you're not blocked.`
+- **Split** — `#60 looks large — I can slice it into child issues and fan them out, if you want.`
+
+Act-paths run only on the dev's explicit go. MMI coordinates board and PR outcomes, while the host owns
+workspace mechanics:
+
+- **PR metadata:** read `mmi-cli explain devops pr create --json` or `mmi-cli explain devops pr edit --json` before the
+  write. For multiline Markdown, materialize a temporary UTF-8 body file, pass its real path with
+  `--body-file <path>`, and remove it after the write succeeds. Do not pipe the body to `--body-file -`;
+  host prose guards require the materialized-file path.
+- **Batch:** claim each item (the Step 5 claim loop), make the coupled edits, and open **one** PR
+  (`Closes #…, #…`). When an issue must stay open (HOLD/prep), never write `Does not close #N` — GitHub
+  still closes it; use `Part of #N` / `Refs #N` / `leaves #N open` only (JC#495).
+- **Parallel:** run independent work concurrently, **one PR per item**. If two would touch the same file,
+  serialize them or fold them into a batch instead.
+- **Background:** run off the hot path (a background task or CI job); poll with `/loop` if useful. Bound it
+  — never block silently.
+- **Split:** keep the original as the umbrella; file each child as a **native sub-issue** of it with
+  `mmi-cli oracle issue create --parent <umbrella-ref> …` (or `mmi-cli oracle issue link-child <umbrella> <child>` for a
+  child that already exists). The parent then renders a sub-issue checklist with each child's state and the
+  child renders its parent — no title prefix or body task-list to maintain. Refs are `#NN`, `owner/repo#NN`,
+  or a URL, and it works cross-repo (a Hub umbrella can track product-repo children). Get the dev's go before
+  filing the children; each child then becomes a parallel item. **When the last child merges, close the
+  umbrella** — its `Done` follows automatically.
+
+## Notes
+
+- Reads/moves use **your** `gh` token (needs `read:project`/`project`, granted once at `gh auth login`).
+- Promotion (`/rcand`, `/release`, `/hotfix`) and the local test env (`/stage`) are their own skills — `/mmi`
+  is the board + start-of-work, not the train.
+- **Board verbs:** `board read` · `board show <id>` · `board claim <id>` · `board move <status> <id>`.
+  `move` exists for an agent's own mechanical bookkeeping when **no PR rides the automation** — e.g.
+  setting `Done` on a no-PR `task` or closed-out item that will not auto-advance. It is a tool, not a
+  dev-facing offer: the "never suggest a status move" rule (Step 3) still governs the human flow. The verb
+  hides the `gh project item-edit` + option-id wiring, so reach for it, not raw `gh`.
+
+## 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 board read that misreported what's
+claimable, or a claim that moved the wrong item.) If yes, file **one** lesson and move on; a clean run is
+silent (hard cap: one per run). It lands on the Hub board (deduped) and is fixed only via a reviewed PR —
+never edit the skill live; the retro is advisory, so if the call fails, note it and continue:
+`mmi-cli learning skill-lesson --skill mmi --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/mmi-doctor/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: mmi-doctor
+description: Diagnose hygiene and safely heal tooling; repository cleanup is explicit.
+---
+
+**Host-native invocation:** Claude `/mmi:mmi-doctor` · Codex `$mmi:mmi-doctor` · jervcode/Kimi `/skill:mmi-doctor` · Kilo `skill` tool. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
+
+# /mmi-doctor — one hygiene pass
+
+Run the safe default when a session opens messy or before a handoff:
+
+```bash
+mmi-cli doctor
+```
+
+A plain run may repair machine-global plugin wiring and guarded caches, but **never mutates the
+repository** (#5023). It reports managed `.gitignore`, docs-index, board mechanics, and aged scratch.
+Local workspace lifecycle is host-owned; doctor does not relocate or delete worktrees. Run
+`mmi-cli doctor --apply` only when the operator explicitly wants guarded repository maintenance. Secrets
+stay out of doctor; use `mmi-cli vault secrets diff` for a catalog gap check.
+
+Doctor does **not** converge CLI or host versions (MMI-Hub#4954). `mmi-hub update` is the single
+writer of those versions; doctor only reports lag and last-run journal evidence. `mmi-hub status`
+reads actual installed locations and versions. Doctor's active-plugin repair pass
+covers every surface from any invocation surface — including Cursor's local-checkout row, not only
+the active surface.
+
+## Flags
+
+| Flag | Role |
+|------|------|
+| *(none)* | Safely heal tooling; report repository hygiene without repo writes. |
+| `--verbose` | Full checklist + per-row evidence. |
+| `--no-repo-writes` | Compatibility spelling for the safe default. |
+| `--self` / `--fast` / `--banner` / `--preflight` | Cheap / read-oriented lanes (see `docs/doctor-contract.md`). |
+| `--apply` | Explicit advanced lane: also apply guarded repository cleanup. |
+
+## Do not run the old multi-step ritual
+
+Do **not** chain these as a `/mmi-doctor` substitute:
+
+```bash
+mmi-cli doctor --self
+mmi-cli oracle board doctor
+mmi-cli vault secrets diff
+```
+
+Plain `mmi-cli doctor` covers safe tooling repair and diagnosis. Explicit `doctor --apply` covers
+repository maintenance; the host owns workspace cleanup. Reach for individual verbs only when you want
+one surface alone.
+
+## Notes
+
+- `/mmi-doctor` is the hygiene pass; `/mmi-resume` is the lighter read-only session open.
+- Prefer one doctor run over hand-editing board items, gitignore blocks, or marketplace pins.
+- The host owns workspace roots, cleanup, and any lease policy. Doctor diagnoses MMI tooling and does
+  not relocate or delete local worktrees.
+
+## 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 doctor run that proposed deleting a live
+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 learning skill-lesson --skill doctor --title "<what misfired>" --body "<what; evidence; proposed amendment>"`