@mutmutco/codex-plugin 3.131.0

package/skills/resume/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: resume
+description: Open a session — self-check, repo status, and the next actionable board item in one pass.
+---
+
+**Host-native invocation:** Claude `/mmi:resume` · Codex `$mmi:resume` · jervcode/Kimi `/skill:resume` · Kilo `skill` tool. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
+
+# /resume — start of session
+
+One flow to re-anchor at the top of a session: is the toolchain sound, what does this repo/worktree look
+like right now, and what is the single next thing worth doing. Read-only — it renders the picture and gets
+out of the way. `/mmi` is the board-only hello-to-work; `/resume` is the wider session open that folds in
+the toolchain self-check and the current-branch snapshot.
+
+## Step 0 — toolchain self-check
+
+```bash
+mmi-cli doctor --self
+```
+
+`doctor --self` verifies the two things that silently break a session: CLI/plugin version parity against
+the published version, and whether the active `gh` token can resolve this repo. It is fast, but it reads
+npm and GitHub — it is not offline-safe, and it checks neither PATH nor hook wiring (#3485). On a **hard**
+gap it points at the heal path — relay it and run it before working:
+
+```bash
+mmi-cli plugin heal      # only on a hard version/plugin gap; then restart Claude Code / reopen the workspace
+```
+
+A clean self-check is silent-enough — move straight on. Do not block the snapshot on a soft/advisory note.
+
+## Step 1 — repo snapshot
+
+```bash
+mmi-cli status
+```
+
+`status` is the unified current-state read for **this** checkout: branch, linked worktrees, your open PRs,
+your claimed board items, and whether a local stage is running. It is the "where am I" line — render it,
+don't re-derive it from raw `git`/`gh`. Keep the case-preserving `repo` value it reports; that is the
+workspace identity the next step must use (for example `mutmutco/MMC-ZuberShade`).
+
+## Step 2 — the next move
+
+```bash
+mmi-cli oracle next --repo <repo reported by status>
+```
+
+Never the retired flat `mmi-cli next` — Wave 3 (#4316) removed that alias; a `flat 'next' alias was
+removed` exit means follow the printed `oracle next` path (and `mmi-cli plugin heal` when
+`doctor --self` says the plugin is behind). Pass the repository from `status` explicitly; never
+reconstruct it by changing case or punctuation. `next` recommends the single most actionable
+claimable board item (unblocked, priority-ranked) and prints the exact
+`mmi-cli oracle board claim <n>` to take it. Offer it; do not claim on the user's behalf without a go.
+For the full board partition (yours / claimable / taken) run `/mmi`.
+
+## Step 3 — render, then stop
+
+Lead with one line: toolchain OK (or the heal to run), the branch + what's in flight, and the one next
+item with its claim command. Then stop. The user drives — claim, continue, or file when they say so.
+
+## Current-state doors (Hub#4120)
+
+When answering “what is true now”, **ask the CLI**, not committed markdown inventories or weekly
+janitor prose. Catalog: `docs/Architecture/compute-at-read.md` (in MMI-Hub).
+
+| Ask | Verb |
+| --- | --- |
+| Schedules / harbour lanes | `mmi-cli harbour org schedules` / `--json` |
+| Boxes / IPs | `mmi-cli devops runtime box list` |
+| Registry / projects | `mmi-cli oracle org project list\|get` |
+| Board | `mmi-cli oracle board read` / `mmi-cli oracle next` |
+| Docs index freshness | `mmi-cli oracle docs index --check` |
+| Path / symbol / meaning pointers | `mmi-cli oracle repo-index search <q>` (Hub cloud; `--semantic` optional) |
+
+## Notes
+
+- `/resume` is read-only session orientation. It never claims, moves, or writes.
+- Board status moves are automatic (claim, PR open, merge). Never suggest a manual status move.
+- Slower, board-partition view → `/mmi`. Readiness-gate view for a new repo/first session → `/onboard`.
+
+## Retro — one check before you finish
+Before your final report, answer one question honestly: did **this skill's own instructions** misfire
+this run — ambiguous wording, a misleading message, or an environment failure it should have warned
+about? (Process only — never the user's code or task; e.g. a self-check that reported a false gap, or a
+snapshot that named the wrong branch.) If yes, file **one** lesson and move on; a clean run is silent
+(hard cap: one per run). It lands on the Hub board (deduped) and is fixed only via a reviewed PR — never
+edit the skill live; the retro is advisory, so if the call fails, note it and continue:
+`mmi-cli learning skill-lesson --skill resume --title "<what misfired>" --body "<what; evidence; proposed amendment>"`
+(never the retired flat `mmi-cli skill-lesson`).

package/skills/secrets/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: secrets
+description: Manage the full own-project vault and granted org-infra secret names.
+---
+
+**Host-native invocation:** Claude `/mmi:secrets` · Codex `$mmi:secrets` · jervcode/Kimi `/skill:secrets` · Kilo `skill` tool. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
+
+# /secrets — two-tier project secrets
+
+**Authority:** a project-admin self-serves their own product repo's full vault tree (`mmi-cli oracle org access
+role` → `project-admin` + `train`): stageless, `dev`, `rc`, and `main`. Do not redirect them to master for
+an own-project coordinate. Only org-infra grants and cross-project administration stay master-only.
+
+Secrets in the org split by **blast radius + who manages them** (not by storage — both tiers are SSM
+SecureString + KMS, and **a value is never echoed to chat or logs**):
+
+- **YOUR REPO** — `/mmi-future/<slug>/<KEY>` (the stageless canonical) plus
+  `/mmi-future/<slug>/{dev,rc,main}/*` (staged per-stage overrides) for a repo you are project-admin of.
+  You **self-serve your own repo's full tree** — the canonical root, dev, rc, AND main prod secrets — via
+  `/secrets`, on your **GitHub role alone**, no AWS, no waiting on the master (#2032).
+- **ORG-INFRA** — the shared/infra namespaces (`/mmi-future/{shared,cloudflare,docs,mmi-hub}/*`), at
+  **every** tier (their `dev/` holds Hetzner/AWS/CF tokens + Hub tooling). **Crown jewels, master-only.**
+  A project-admin reaches one of these only via a master **grant**; the master is unrestricted (master ⊇
+  project-admin).
+
+**Grant scope (#3652).** A grant is `rw` by default — it opens both keyless `use` and `set`/`rm` on that
+key. `mmi-cli vault secrets grant <repo> <login> <key> --read` grants **consume-only** reach: keyless `use`
+works, rotate and remove still refuse. Only a `--read` grant may name a **wildcard** key — `*` for the
+whole namespace, `<provider>/*` for one provider group — so "may read every crown jewel" is one grant
+instead of forty. A wildcard never confers write; asking for one as `rw` is refused, not narrowed.
+`mmi-cli oracle org access capabilities` prints `grant (read)` or `grant (rw)` next to each name.
+
+A bare `<KEY>` is the **stageless canonical** at the slug root — one value every stage shares (#2244)
+and the path deploys resolve (#2523). A staged `dev/<KEY>` is a **per-stage override** and WINS for that
+stage at deploy (#2522); `set`/`use` warn (names only) when an override shadows the canonical. The
+`dev`/non-`dev` `tier` field in older JSON is compatibility metadata, not an authority boundary: an
+own-project `main/SECRET_KEY_BASE` or `rc/DB_URL` remains project-admin self-service.
+
+**Declare-first (#2528):** the registry catalog is the SSOT; SSM is a projection of it. A `set` to a
+coordinate not declared in the catalog is **rejected** — the error names the attempted path and the fix.
+Declare the key first via `mmi-cli oracle org project set <owner/repo> --secrets-file <catalog.json>` (`stages: []`
+= the shared stageless canonical, `stages: ["dev"]` = a per-stage override), then retry. See what is
+declared with `mmi-cli vault secrets catalog` or `secrets list`; ask for a key you lack via `mmi-cli vault secrets
+request <KEY>`. There is no master bypass. `rm` of an undeclared path stays allowed, so cleanup keeps
+working. Google OAuth is one stageless pair per repo: bare `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET`
+at the slug root (the staged `{dev,rc,main}/GOOGLE_*` shape is retired; `org oauth set-creds` writes the
+bare keys).
+
+All ops run through `mmi-cli vault secrets …`, which calls the org backend with the caller's `gh` token; the
+backend re-verifies **project-admin-of-this-repo** and the **vault namespace** server-side and does the scoped
+SSM op. This skill never touches AWS.
+
+## Step 0 — orient
+
+Read the current repo + slug; the tier of a key follows from its name (above). `secrets list` shows what
+exists and which ones **you** can manage (a `*`), never values.
+
+```bash
+mmi-cli vault secrets list                 # names + tier + a * on the ones you can write. NEVER values.
+```
+
+`secrets: no registry META` or `Hub API unreachable` → the repo is not registered with the Hub, GitHub auth
+is missing, or the Hub API is unavailable. Run `mmi-cli oracle org project get <owner/repo>` to distinguish those cases;
+a master-admin backfills the registry before secrets can be resolved.
+
+## Step 1 — the verb
+
+Default to the **current repo**; pass `--repo owner/Name` to target another (you must be its project-admin).
+
+```bash
+# CONSUME a secret keyless — injected into the command's env, NEVER printed (raw `secrets get` was
+# removed, the floor wins, #2844):
+mmi-cli vault secrets use SCRAPER_API_KEY -- <cmd>
+
+# Write / rotate — the VALUE is read from stdin, NEVER an argument (so it can't leak into shell history
+# or process args). Pipe it in:
+printf %s "$THE_VALUE" | mmi-cli vault secrets set SCRAPER_API_KEY
+
+# Validate a known provider key without printing its value:
+mmi-cli vault secrets verify RECALL_API_KEY
+
+# Remove:
+mmi-cli vault secrets rm SCRAPER_API_KEY
+```
+
+**Never** pass a value as an argument (`secrets set KEY thevalue` is wrong — there is no value arg). The
+confirmation prints the **name and tier only**, never the value.
+
+## Rotation checklist
+
+Before rotating, enumerate every copy of the key so no tier stays stale:
+
+```bash
+mmi-cli vault secrets list --repo owner/Repo
+```
+
+Check the bare canonical plus any `dev/`, `rc/`, `main/` overrides the list shows. Rotate the provider-side
+key first, then write every declared coordinate that still needs that key. For keys with a provider probe
+(`RECALL_API_KEY` today), `secrets set` validates the new value before printing success; `secrets verify
+<KEY>` repeats the same probe later without printing the value. If the verifier fails, treat the rotation as
+incomplete even if the vault write itself succeeded.
+
+## Step 2 — org-infra elevation (master-only)
+
+Your own repo's full tree (dev/rc/main) is already self-serve (#2032). The **org-infra** namespaces
+(`shared`/`cloudflare`/`docs`/`mmi-hub`, every tier) stay master-only. A project-admin who needs one of
+those keys asks the master, who grants a **scoped, auditable** standing access to that one key (or revokes
+it). These verbs are **master-only** — the backend 403s anyone else.
+
+```bash
+# MASTER: let @oguz-mut consume one _org provider key from their MM-Chat project
+mmi-cli vault secrets grant mutmutco/MM-Chat oguz-mut google/SOME_SHARED_KEY
+# MASTER: withdraw it
+mmi-cli vault secrets revoke mutmutco/MM-Chat oguz-mut google/SOME_SHARED_KEY
+```
+
+The master can also operate the org-infra key directly while guiding (master ⊇ project-admin). Org-infra
+access by a project-admin **always originates from the master** — own-project access does not.
+
+## Coordinate — where does a new project secret belong?
+
+- Shared across stages → bare `<KEY>` at the project slug root (the usual canonical value).
+- Genuinely stage-distinct → `<stage>/<KEY>` override for `dev`, `rc`, or `main`.
+- The project-admin owns both shapes across their own project. A path under `_org`/shared infrastructure is
+  not a project coordinate and stays master-managed.
+
+## Tier-to-tier copy (provider keys, #1433)
+
+**Encryption / stage-distinct keys** (`*_ENC_KEY`, `SECRET_KEY_BASE`, etc.) must be **generated per stage** —
+never copied. **Provider sandbox keys** (e.g. Recall/Gemini for Katip dev/rc) **may** be shared across dev/rc
+when they point at the same sandbox project; prod should stay distinct when the provider contract requires it.
+
+Sanctioned copy within the own-project vault (org-infra/cross-project sources remain master-gated):
+```bash
+mmi-cli vault secrets copy --from rc --to dev --keys RECALL_API_KEY,GEMINI_API_KEY
+mmi-cli vault secrets copy --from rc --to dev --keys RECALL_API_KEY --dry-run   # plan only
+```
+Prefer this over manual copy piping — audit-logged, blocklist enforced.
+
+## Notes
+
+- **Never echo a value** — not in chat, a commit, a log, or an issue. No command emits a value to stdout;
+  consume one keyless with `secrets use <KEY> -- <cmd>` (#2844). Treat every secret as write-once.
+- Authority is **GitHub**: project-admin = repo `write` plus the registry `projectAdmins` entry, master =
+  org owner. The backend checks both with the org App token, so the decision is server-side (your token
+  scope can't widen it).
+- Runtime consumes declared keys through its scoped broker token (and central deploy injects the declared
+  stage set without a repo `.env`); CI reads keylessly through its OIDC role. Neither uses raw `/secrets`
+  output. `secrets use <KEY>` is the safe local command-consumption path.
+- Every self-service write is **attributable** — the backend logs actor + repo + KEY name (never the value).
+
+## 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 canonical-name or tier mix-up, or a step
+that risked echoing a value.) 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 secrets --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/stage/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: stage
+description: Run a local test stage, or a personal cloud dev stage with --live.
+---
+
+**Host-native invocation:** Claude `/mmi:stage` · Codex `$mmi:stage` · jervcode/Kimi `/skill:stage` · Kilo `skill` tool. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
+
+# /stage — local test environment
+
+A throwaway **local** environment to exercise the current branch — a dev server / local stack, plus
+Playwright or other tools where the project uses them. It is **off the promotion train**: any developer,
+no version effect, no deploy. It lives in a **gitignored** workspace, **force-kills the previous stage**
+before starting, and **auto-decommissions** when done.
+
+Use `/stage` as the normal path for local previews, smoke tests, and Playwright targets. If the user
+already asked to run or preview the app, that is enough authorization to start it; when intent is unclear,
+ask before creating or destroying a stage. Manual dev-server commands are allowed when the user explicitly
+wants a bypass or when a bounded diagnostic needs one, but say why. If the stage path itself fails, diagnose
+from `mmi-cli stage --json`, `tmp/stage/state.json`, process/port/container evidence, and file Hub/org-default
+friction instead of silently working around it.
+
+The stage recipe is the **registry-derived default** for plumbing-free product repos: a `tenant-container`
+repo that ships `docker-compose.yml` and has a Hub registry `portRange` needs **no committed config**.
+`mmi-cli stage` derives a default compose stage — run `docker compose build --no-cache`, run `docker compose
+up -d`, choose a free port from the registry range, and report the local URL (e.g. `http://127.0.0.1:3700/`).
+The commands are shell-aware and `--apply` runs them cross-shell. Board, deploy, secret, and project registry
+facts all live in the Hub registry — no repo-local control-plane file.
+
+**Secrets are vault-native — no `.env` on disk (#2655).** The org forbids *using* `.env` files, not just
+committing them. A repo **without** `.env.example` stages vault-native: `mmi-cli stage --apply` resolves the
+declared dev runtime secrets (registry `requiredRuntimeSecrets[dev]`) from the vault and injects them straight
+into the compose **process environment** — the compose file reads them via `environment:` passthrough, and no
+secret ever touches disk. A repo that still ships `.env.example` keeps the legacy `.env` bootstrap for
+back-compat until its compose migrates to passthrough; new repos should ship **no** `.env.example`.
+
+## Step 0 — inspect the plan
+
+```bash
+mmi-cli stage --json
+```
+
+The JSON reports `source` (`derived` / `local` / `none`) and, when derived, the local `url`. `source: none`
+means neither a usable local recipe nor a derivable default exists — the message names the missing fact
+(deployModel, `docker-compose.yml`, or registry `portRange`; `.env.example` is **not** required — #2655).
+That gap does not mean the repo's Hub registry/org project setup is missing.
+
+## Step 1 — run the stage
+
+A stage is **per worktree**. The CLI force-stops only the previous stage **in this worktree**, runs
+`stage.build`, starts `stage.up`, records `tmp/stage/state.json`, picks a free port from the registry
+range (skipping ports reserved by sibling worktrees), and polls `stage.healthUrl` when configured.
+Use `--port` to pin a port when needed:
+
+```bash
+mmi-cli stage run --apply
+mmi-cli stage run --apply --port 5180
+```
+
+Use a larger bound when the repo's local stack is known to be slow:
+```bash
+mmi-cli stage run --apply --timeout-ms 120000
+```
+
+All stage artifacts (build output, screenshots, Playwright traces, local DB files) stay under `tmp/stage/`
+— never tracked.
+
+A local stage is bound to the worktree that started it. Concurrent worktrees on one machine each keep
+their own stage on separate ports — you do not need to stop one before starting another. For `jervaise`, continuity
+keys on branch; use a distinct North Star slug per parallel grind or feature. Stage JSON/state records
+the starting `cwd` plus git branch/commit when available.
+
+### Step 1a — post-smoke panel (when criteria exist)
+
+When grinding or the user supplied **acceptance criteria** (from the issue body at Gate 1 — not
+ad-hoc chat text), run a **Budget-routing panel** on observable stage signals before teardown:
+
+1. **Panel** (parallel):
+   - **requirements-match** (budget tier) — does the staged URL/behavior meet the criteria?
+   - **runtime-health** (budget tier) — console errors, failed `healthUrl`, broken UI signals
+     *(smoke observability — not the grind `correctness` hard lens)*
+   - **tests-actually-test** (budget tier) — if Playwright ran, did it exercise the changed path?
+2. **Confirm** — get an independent second model to verify the staged URL or behavior meets the acceptance criteria.
+3. Feed the result back to the active loop or report to the human. A blocker
+   means the stage failed smoke — do not claim the grind criterion met.
+   This panel is **not** a security clearance — grind Phase 2 still runs the `security` hard lens.
+
+Skip when `/stage` is ad-hoc preview with no criteria.
+
+## Step 2 — stop when done
+
+```bash
+mmi-cli stage stop --apply
+```
+
+Stop the stage when the work is done, before switching context, or before replacing it with another stage.
+If the user clearly wants the preview to stay up, leave it running and report that. The next `/stage` also
+stops the previous recorded stage before starting, so a stale server does not linger between runs. For the
+registry-derived Docker Compose default, stop also runs the recorded compose teardown (`docker compose down`)
+from the original stage working directory.
+
+## /stage --live — personal cloud dev stage
+
+dev.x stages are **not standing environments**: without `--live` the dev stage is dark. `--live`
+deploys the **current branch** to the project's dev runtime and serves it **only to your public IP** —
+gated at the **Cloudflare edge** (#1761). The CLI detects your IP, dispatches the central
+`tenant-deploy.yml` (stage=dev), then `tenant-control.yml` `cf-gate-allow` (an ephemeral Cloudflare WAF
+rule scoped to your dev host + IP). The box no longer IP-gates dev. No SSH from your machine; everything
+moves through the central workflows.
+
+```bash
+mmi-cli stage --live           # dry-run plan
+mmi-cli stage --live --apply   # deploy + gate your IP at the Cloudflare edge
+```
+
+Tear it down when done — the runtime stops and the Cloudflare edge gate is removed:
+
+```bash
+mmi-cli stage --live --down --apply
+```
+
+Personal dev stages only — rc/live environments still move exclusively through the promotion train.
+
+## Step 3 — report
+
+The stage URL, what's running (server + tools), the workspace path (`tmp/stage/`), and the teardown command.
+
+## Notes
+
+- `/stage` is local — no AWS, no deploy, no board or version effect. The one cloud exception is
+  `--live`: an on-demand **dev** stage of your branch, gated to your IP at the Cloudflare edge (above).
+- `/stage-live` is not an org command: remote rc/live environments move only through `/rcand`, `/release`, and `/hotfix`.
+- Everything is gitignored; `/stage` never produces a tracked change.
+- **Playwright MCP output goes to `tmp/`**, never the repo root: if you drive the Playwright MCP server,
+  pass `--output-dir tmp/playwright-mcp` (or point its output there). `.playwright-mcp/` is kept gitignored
+  by the org `.gitignore` managed block (`mmi-cli doctor`) as a safety net, so a stray default capture is
+  never tracked.
+- `tools[]` is declarative for now; stage hardening starts/stops the main configured process. Repos with
+  extra local services should encode them behind `stage.up` until a tool runner is added.
+- **Stale Docker bundle:** the registry-derived Docker Compose default builds with `docker compose build
+  --no-cache` before `up`. If the browser still serves an old bundle, run `mmi-cli stage stop --apply`, rerun
+  `/stage`, then inspect `tmp/stage/state.json` identity, container image labels, and compose build inputs.
+- **Stale `.env`:** when `.env` already exists from a prior `/stage` run, `stage run` does **not** refresh it
+  from an updated `.env.example` — it warns on stderr and keeps the stale file. Delete `.env` (or merge in the
+  new keys by hand) when `.env.example` changes, then re-run `/stage`.
+
+## 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 teardown that left a port bound, or a
+Playwright output path aimed at the repo root.) 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 stage --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/worktree/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: worktree
+description: Orchestrate a worktree from create to landed PR, tied to board status.
+---
+
+**Host-native invocation:** Claude `/mmi:worktree` · Codex `$mmi:worktree` · jervcode/Kimi `/skill:worktree` · Kilo `skill` tool. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
+
+# /worktree — create → work → land
+
+Drive an item through an isolated worktree: cut it from latest `development`, claim the board item, do the
+work, open and land the PR, and clean up — with the board moving automatically at each boundary. One
+worktree per session; everything under `../mmi-worktrees/` is ephemeral and sweepable.
+
+## Step 1 — create + provision
+
+```bash
+mmi-cli worktree create <owner/repo#N> --claim --from origin/development
+```
+
+`worktree create` cuts the branch from `origin/development` (fetched first) and provisions it: installs
+deps (`npm ci`) and copies local-only config (`.claude/settings.local.json`) a fresh checkout lacks. Use
+`--from <ref>` for a non-default base, `--path <path>` to override the location. An existing worktree that
+lost its deps re-provisions with `mmi-cli worktree setup [path]` (the SessionStart hook fires this
+automatically).
+
+The issue-ref form derives `<issue-number>-<short-slug>`, assigns the item, and moves it to In Progress.
+
+`worktree create` also leases the tree to the **creating session** (#4328). A later `jerv-cli lane submit
+--dir` (or any governed seat) refuses an already-held host lease and will not commandeer it. Before handing
+the tree to a governed seat, release that lease first — safe once the session's own edits in that tree are
+committed and pushed: `jerv-cli lease close --ref <worktree path>` (closes every lease on that ref; no id
+lookup needed). To inspect what's held before closing, `jerv-cli lease list` shows id, ref, and owner.
+
+## Step 2 — claim + work
+
+Work in the provisioned worktree. Exercise the change with `/stage` (a local stage is bound to the worktree that
+started it — stop it before switching worktrees). Sequential related items in one session reuse the active
+worktree; do not churn one worktree per issue unless a true parallel or PR boundary needs it.
+
+## Step 3 — open the PR
+
+Push the branch and open the PR against `development`. The board moves to In Review automatically on PR
+open — never move it by hand.
+
+```bash
+git push origin <branch>:<branch>              # explicit feature refspec — see below
+mmi-cli devops pr create --title "<title>" --body-file .jerv/PR_BODY.md --base development
+mmi-cli devops pr checks-wait <PR-number>              # wait for required CI to go green
+```
+
+Write the PR body under `.jerv/` (#4405), never at the worktree root. `.jerv/` is the agent-artifact
+prefix `worktree land` treats as removable; a stray untracked `PR_BODY.md` anywhere else classifies the
+tree as `untracked-files` and Step 4 then skips cleanup entirely.
+
+The push must be the explicit `<branch>:<branch>` refspec (the branch Step 1 derived, e.g.
+`git push origin 3795-my-slice:3795-my-slice`). The #1660 protected-push gate denies the
+`HEAD`/remote-only form (`git push -u origin HEAD`) — its target cannot be proven safe. And never
+share the push with staging or commit verbs in one compound command: the deny applies to the whole
+command, so a refused `git add … && git commit … && git push …` chain discards the add and commit
+with it. Stage, commit, and push as separate commands.
+
+If the branch adds, removes, or renames any `docs/` file, `pr create` refuses with a stale
+`docs/index.md` (#4092) — run `mmi-cli oracle docs index --write`, commit `docs/index.md`, and push again
+before retrying.
+
+## Step 4 — land + clean up
+
+Under standing go (green CI, CI-gated PR) land to `development`. **Invoke `mmi-cli devops pr land` from the
+primary checkout** (or any cwd that is not the PR worktree) (#4549). Landing while cwd is still inside
+the worktree that cleanup removes can merge successfully and still exit 1 with
+`cleanupError: … Unable to read current working directory` — post-merge `gh`/`git` follow-ups then have
+no readable cwd even when removal itself chdir'd away (#4140).
+
+```bash
+cd <primary-checkout>   # e.g. the main MMI-Hub clone — not the slice worktree
+mmi-cli devops pr land <PR-number>
+```
+
+`pr land` waits for checks, squash-merges, and does the full cleanup at the branch boundary: removes the
+worktree, deletes the merged branch (local + origin), and prunes tracking refs. A worktree the IDE has
+locked is queued and retried by `mmi-cli worktree gc sweep-deferred`. Self-authored merges need an explicit
+per-session merge grant — ask early if you don't have one.
+
+**`not-attempted (untracked-files)` (#3500 / #4405):** the usual cause of a merged PR that left its
+worktree behind. Any untracked path outside `.jerv/` — a hand-written `PR_BODY.md`, notes, a scratch
+script — makes removal refuse, because an unadded file can be real work. Delete or move the file, then
+re-run cleanup **from inside the worktree** (`worktree land` has no `--path`; it acts on the tree you
+are standing in):
+
+```bash
+mmi-cli worktree land --apply
+```
+
+**Cwd-safe removal (#4140):** `worktree land --apply` (what `pr land` runs) releases the process cwd to
+the primary checkout before deleting the tree (#1444/#2747) so Windows `rmdir` is not `EBUSY`. That does
+**not** replace the agent rule above: still start `pr land` from the primary checkout (#4549). Prefer
+primary cwd also when running `worktree land` manually outside `pr land`. If removal still fails (IDE
+lock, antivirus), the deferred sweep retries from a safe cwd.
+
+**No main lineage on a squashable development PR (#4365 / #4371):** never `git merge -s ours` (or otherwise
+merge) a main-parented port commit into a development PR that will squash. Squash folds second-parent
+trailers — including foreign `Closes #N` — into the development squash body, closes the wrong issues, and
+trips the closing-keyword land guard. Keep the cherry-pick / main-clean source on a separate branch or ref;
+land only development-tree changes on the development PR. To record a pushed main-clean SHA for a later
+`/hotfix --from` without polluting squash parents, prefer a marker-only commit on the development branch
+that references that SHA in the message — do not pull the main commit into the squashable parent list.
+This does not weaken the `#3167` merge floor on `/hotfix` and `/release` (never squash a tagged commit;
+alignment / roll-forward stays a true merge).
+
+**Stay-open phrasing (JC#495 / #3718):** GitHub's closing-keyword parser is negation-blind. `Does not
+close #N` still contains `close #N` and **closes the issue** on merge/squash (measured: Jerv-JervCode
+PR #493 closed #487). When an issue must stay open, never put `close`/`closes`/`fix`/`resolve` + `#N`
+in the PR body, commit message, or merge message — use `Part of #N`, `Refs #N`, or `leaves #N open` only.
+`mmi-cli devops pr create` rewrites common negated phrases; `pr land` / `pr merge` still refuse any remaining
+negation-blind close. `--force` only when those targets should actually close.
+
+If a PR already inherited closed-issue `Closes` keywords from that anti-pattern and `pr land` / `pr merge`
+refuses, land with `--force` only when those inherited targets are already closed — prefer preventing the
+pollution above over relying on `--force`.
+
+## Step 5 — record + next
+
+Record durable decisions on the issue or PR, then check the board again:
+
+```bash
+mmi-cli oracle wave status        # remaining worktrees, open PRs, local stages at a glance
+mmi-cli oracle next               # the next actionable item
+```
+
+## Notes
+
+- Cut worktrees only at `../mmi-worktrees/<RepoName>/<branch>` (#3471) — generic helpers that force `.claude/worktrees/` or
+  `.worktrees/` are not the MMI path.
+- Multiple independent items → one worktree each, run in parallel, one PR per item (`/mmi` Leverage).
+- Never land to a protected/release branch here — that is `/rcand` and `/release`.
+- **Keep Cursor on the primary checkout (#4489 / #4901).** Edit the worktree without
+  `move_agent_to_root` into the slice — moving the workspace root pins the session so land/gc
+  refuse forever. If Cursor’s agent workspace is still rooted at the slice, `worktree land` /
+  `worktree gc --apply` / doctor gc **refuse** to delete that directory (and queue deferred
+  removal). On a Cursor agent host, land/gc fail closed when the active root cannot be resolved:
+  open the primary first, or set `MMI_ACTIVE_WORKSPACE_ROOT` to the primary path. After Cursor is
+  on the primary, `mmi-cli worktree gc sweep-deferred` finishes cleanup.
+
+## 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 create that branched from a stale base, or a
+land that left a worktree behind.) 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 worktree --title "<what misfired>" --body "<what; evidence; proposed amendment>"`