@mutmutco/cursor-plugin 4.2.7 → 4.3.0

package/skills/mmi/SKILL.md

@@ -1,544 +0,0 @@
----
-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.
-
-## Hard invariants (#5552 — load before any write)
-
-Two rules sit above every later step. Read them before claiming, filing, or guessing a CLI route:
-
-1. **Claims are board mutations.** The only valid claim write is
-   `mmi-cli oracle board claim <ref>` (optional `--json` / `--for` / `--check`). Never infer or guess an
-   `oracle issue claim` route — that path does not exist under `oracle issue` (create/view/edit/… only).
-   If the exact write route was not already grounded in this skill or a live
-   `mmi-cli commands` / `mmi-cli explain` result, read one of those before invoking it. Do not retry a
-   guessed `issue …` spelling after a refusal; take the suggested `oracle board claim` form.
-2. **`learning`-tagged reports are cloud-agent work.** After `mmi-cli learning report` (or
-   `learning skill-lesson`), file and forget: return to the current task immediately. Never claim, poll,
-   wait on, force-take, or duplicate implementation of the filed learning issue. Consume eventual
-   propagation separately when it lands; do not own that fix in this session.
-
-## 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`. Do not assume the entire captured stdout is
-> one JSON document: older `oracle org project get --json` and `oracle board read --json` builds appended a human
-> summary after the object (#5173). Extract the first balanced object, then parse it:
->
-> ```js
-> function firstJsonObject(stdout) {
->   const start = stdout.indexOf('{');
->   if (start < 0) throw new Error('stdout contains no JSON object');
->   let depth = 0;
->   let inString = false;
->   let escaped = false;
->   for (let index = start; index < stdout.length; index += 1) {
->     const char = stdout[index];
->     if (inString) {
->       if (escaped) escaped = false;
->       else if (char === '\\') escaped = true;
->       else if (char === '"') inString = false;
->       continue;
->     }
->     if (char === '"') inString = true;
->     else if (char === '{') depth += 1;
->     else if (char === '}' && --depth === 0) return JSON.parse(stdout.slice(start, index + 1));
->   }
->   throw new Error('stdout contains incomplete JSON');
-> }
-> ```
->
-> Never truncate at the last `}`; trailing prose can contain braces, and malformed/incomplete JSON must fail closed.
-
-> **Never capture board JSON with a shell redirect on Windows** (#5802). PowerShell 5.1's `> file.json` is
-> `Out-File`, which writes **UTF-16LE with a BOM**, so the file starts `FF FE` and the next step —
-> `readFileSync(path, 'utf8')` + `JSON.parse` — dies at position 1. Pass `--out <path>` instead: the CLI
-> writes the file itself as UTF-8 with no BOM, so the bytes never reach the shell.
->
-> ```bash
-> mmi-cli oracle board read --json --out .jerv/tmp/board.json   # UTF-8, parses everywhere
-> ```
-
-(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. **Route (hard):** `oracle board claim` only — never `oracle issue claim` (#5552).
-  ```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`.
-  Every claim also stamps a lane-identity marker comment on the issue (`<!-- mmi-claim: … -->`,
-  surface/session@host) so other agents can attribute the hold (#3727): the session is the
-  host-exported id when the surface provides one, otherwise a per-process `synth-` fallback — a
-  claim is never anonymous (#5245).
-  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).
-     The **surface contract is a repo board rule, not a template field** (#5187): the repo enforces
-     exactly one `surface:*` label on every open issue even when `<type>.yml` carries no surface
-     dropdown, so `oracle issue create` rejects a filing that omits it regardless of the template.
-     Never infer the surface from the template alone — discover the repo's valid values first
-     (`gh label list --search 'surface:'`, or reuse a known surface for that repo) and always pass
-     `--surface` in Step 5.3.
-  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.
-  **Learning fire-and-forget (#5552):** the filed issue carries the `learning` label and is owned by
-  cloud agents. After a successful file (or dedup +1), print the `{number,url}` receipt if useful, then
-  **return to the current task** — do not `board claim` it, poll it, wait on a PR, force-take it, or open
-  a second implementation issue for the same friction.
-- 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. On Windows, set `git config core.longpaths true` on the
-  main checkout before the first `git worktree add` (#5499; see `docs/Architecture/worktrees.md`). Linked
-  worktrees of one clone still share `.git`: serialize `git branch -m` / other ref renames across those
-  worktrees, or retry serially when the error names `.git/logs/refs/.tmp-renamed-log` (#5485; see
-  `docs/Architecture/worktrees.md`).
-- **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.
-
-## Host-owned landing and cleanup (#5182)
-
-MMI owns the PR/CI/merge/board facts; the host agent owns local worktrees and branches. Neither `pr land`
-nor `pr merge` deletes a local worktree or local branch, and no MMI command should do so. The distinction:
-
-**Release-track before branch hygiene (#5244):** before hunting `rc` branches, rc worktrees, or retired rc refs
-for cleanup, read the repo's release track (`mmi-cli status`, or `mmi-cli oracle org project get` when
-status omits it). Direct-track repos have only `development` and `main` — an old rc promotion PR does not
-imply a live `rc` branch or worktree exists.
-
-- `mmi-cli devops pr land <pr>` is the normal agent path for a `development` PR: train-authority probe →
-  checks wait → squash auto-merge/poll → board advance. GitHub may delete the **remote** feature branch.
-- `mmi-cli devops pr merge <pr>` is the lower-level merge primitive. It is not a shortcut around checks
-  and it does not own local cleanup either.
-
-Remote deletion is intentionally immediate and is not the cause of a local Windows lock. Do not delay it
-or keep remote branches as cleanup leases. A local squash branch is not an ancestor of `development`, so
-`git branch -d` cannot prove delivery even when the PR merged; use the exact merged-PR/head receipt below.
-
-### Before `pr land` — release the worktree
-
-1. Record the PR number, main-checkout path, task-worktree path, local branch, and local branch OID
-   (`git rev-parse refs/heads/<branch>`). `git status --porcelain` in the task worktree must be empty;
-   dirty/untracked means **retain and report**, never clean or overwrite it.
-2. Finish/stop every worker, subagent, monitor, shell, editor terminal, or debugger whose current directory
-   is inside the task worktree. A completed agent can still leave a Windows directory handle behind.
-3. Change the orchestrating shell/current directory to the main checkout **before** landing. Never invoke
-   worktree removal while this process or a child still stands inside that tree.
-4. Run `mmi-cli devops pr land <pr> --json` and require a merged status. Enqueued, failed, unknown, or an
-   unreadable receipt means **no cleanup**.
-
-### After a confirmed merge — exact, bounded cleanup
-
-Read the durable PR receipt and compare it with what is local:
-
-```bash
-gh pr view <pr> --repo <owner/repo> --json state,headRefName,headRefOid,mergeCommit
-git rev-parse refs/heads/<branch>
-git -C <task-worktree> status --porcelain
-git worktree list --porcelain
-```
-
-Proceed only when `state` is `MERGED`, `headRefName` equals the local task branch, `headRefOid` equals the
-local branch OID, the worktree is registered to that branch, and its status is empty. Branch name, missing
-remote ref, patch-id, or PR state **alone** is not proof. Then, from the main checkout:
-
-A clean `git status --porcelain` is **not** proof the physical directory is empty: gitignored payload such
-as `node_modules` (from `npm ci`) and this session's own scratch (e.g. `.jerv/tmp`) is invisible to it,
-and `git worktree remove` refuses a non-empty tree with `Directory not empty` (#5239). Once the receipt
-above proves delivery, delete `node_modules` and this session's own scratch first, then remove:
-
-```bash
-rm -rf <task-worktree>/node_modules   # gitignored payload — porcelain never shows it
-rm -rf <task-worktree>/.jerv/tmp      # this session's own scratch, if this run created it
-git worktree remove <task-worktree>
-git branch -D <branch>       # deliberate: squash merge makes -d ancestry proof impossible
-git worktree prune
-```
-
-`-D` is permitted only after the exact receipt above. Never use it for a mismatched OID, an open/unreadable
-PR, a dirty tree, another owner's tree, or an ambiguous branch. The pre-removal deletes follow the same
-rule: only artifacts this session created inside this task worktree.
-
-On Windows `Directory not empty` with a clean porcelain, suspect leftover gitignored payload: delete it as
-above and retry. On `EBUSY`, `EPERM`, or WinError 32: re-check that every context has left the path and
-make **one bounded retry** of `git worktree remove` when it is still registered. If the retry reports
-`is not a working tree`, the first failed remove already unregistered the tree; when the exact receipt
-above proves the leftover directory is this session's own merged branch, that leftover may be deleted
-(`rm -rf <task-worktree>`) — own-session artifacts only, never another session's tree, never on a
-mismatched OID or unreadable PR (#5239). Otherwise, or when the retry is still locked, stop: do not kill
-unrelated processes, recursively delete the directory, or guess. Report `deferred-lock` with the exact
-path, branch, local OID, PR, and whether the tree remains registered. Report any failed proof as
-`retained-ambiguous`. Only report `clean` after the path, registration, and local task branch are all gone.
-A later host session can drain a deferred lock using the same proof; MMI never owns that sweep.
-
-## 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>"`
-The lesson is `learning`-tagged cloud-agent work (#5552): file it, then finish your current report —
-do not claim, poll, or implement that lesson in this session.

package/skills/mmi-doctor/SKILL.md

@@ -1,66 +0,0 @@
----
-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>"`