@mutmutco/codex-plugin 3.131.0

package/skills/bootstrap/seeds/architecture.template.md

@@ -0,0 +1,34 @@
+# {{REPO_NAME}} — Architecture
+
+> How this repo is **built** — a short, stable entry, not a runtime inventory. Pair with `README.md`
+> (what it *is*). State current truth, inspect don't narrate: no change-comments or version-era labels
+> (history is in git). (Write fresh — D35.)
+
+## What this repo produces
+
+(What ships from this repo — the product/service/library, in one or two bullets.)
+
+## Layout
+
+```
+(top-level dir)     (what it is, one line)
+(top-level dir)     (what it is, one line)
+```
+
+## Stack
+
+(Languages, frameworks, datastores, major services — inspect the lockfile/manifest, don't assume.)
+
+## Build & deploy
+
+- **Class + release track + stages:** `mmi-cli oracle org project get` (registry SSOT — full = development/rc/main,
+  direct = development/main, trunk = main; never copied here, so it cannot go stale).
+- **Deploys run centrally** via the Hub (`tenant-deploy.yml`); this repo carries no deploy files, unless
+  noted otherwise below.
+- (Build/test commands, CI gate, deploy target.)
+
+## Conventions
+
+Follows the org spine (carried by the MMI plugin per machine). Repo-specific agent guidance:
+`README.md` § Agent context — no agent guide is committed to the repo (the org `mmi-no-agent-files-org`
+ruleset blocks every agent-guide path).

package/skills/bootstrap/seeds/decisions-readme.template.md

@@ -0,0 +1,45 @@
+# Decision records
+
+Prose in this tree is only for **why** — why we chose a shape, what we rejected, what constraint
+bound us. It never describes current implementation and never claims to be current. Code (and
+generated refs) are the only truth about *what is*.
+
+## One file per decision
+
+`docs/decisions/YYYY-MM-DD-<slug>.md`
+
+- **Date** in the filename is the day the decision was recorded (UTC calendar date).
+- **Slug** is a short kebab-case label for the subject (`single-aws-account`, `cowork-plugin-boundary`).
+
+## Frontmatter
+
+```yaml
+---
+date: YYYY-MM-DD
+sha: <git commit sha at which this was true>
+status: decided | superseded
+subjects:
+  - <topic or path this decision binds>
+---
+```
+
+| Field | Meaning |
+| --- | --- |
+| `date` | Same calendar day as the filename prefix. |
+| `sha` | The commit that embodies or records the decision — a pin in history, not a claim that the tree still looks like that. |
+| `status` | `decided` (in force) or `superseded` (replaced by a later record; leave the old file in place). |
+| `subjects` | Short list of topics, paths, or surfaces the decision constrains. |
+
+## Body
+
+1. `# <Title>` — the decision in one line (what was chosen, not how it works today).
+2. `## Why` — the rationale and the binding constraints.
+3. `## Rejected alternatives` — each alternative as a bullet: what it was, why it lost.
+
+Do not narrate live topology, versions, box coordinates, or "how to run it." If a reader needs
+current state, they read the code or a generated ref — not this file.
+
+## Ownership
+
+Bootstrap seeds this README once (`ownership: repo`) and never clobbers it. Individual decision
+files are authored in the same PR as the change and merged by a human. There is no scheduled docs-janitor backstop (Hub#4119/#4164).

package/skills/bootstrap/seeds/docker-compose.template.yml

@@ -0,0 +1,26 @@
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      # Build-time secret opt-in:
+      # secrets:
+      #   - NODE_AUTH_TOKEN
+    restart: unless-stopped
+    # The box control document writes registry coords + stage-scoped SSM secret values into the
+    # release ./.env before `docker compose up`; env_file is what delivers them into the container.
+    env_file: .env
+    environment:
+      NODE_ENV: production
+      MMI_STAGE: ${MMI_STAGE:-dev}
+      MMI_PORT: ${MMI_PORT:-3000}
+      PORT: ${PORT:-3000}
+      MMI_EDGE_DOMAIN: ${MMI_EDGE_DOMAIN:-}
+    ports:
+      - "${MMI_PORT:-3000}:${PORT:-3000}"
+
+# Build-time secret opt-in. Requires registry META:
+# requiredBuildSecrets: ["NODE_AUTH_TOKEN=@github-packages-token"]
+# secrets:
+#   NODE_AUTH_TOKEN:
+#     environment: NODE_AUTH_TOKEN

package/skills/bootstrap/seeds/gate.template.yml

@@ -0,0 +1,85 @@
+name: gate
+# Org-standard green-before-merge gate for product repos (#1333). Runs on PRs, train-branch pushes,
+# and v* tags so /release and /hotfix can discover required contexts on the tagged SHA.
+#
+# Runner: self-hosted mmi-runner (mmi-live) — see docs/Guides/gh-runner-runbook.md in MMI-Hub.
+# #4118: if GATE_CMD runs tsgo or other memory-heavy typecheck / browser work, pin this job to
+#   runs-on: [self-hosted, linux, x64, mmi-heavy]
+# instead — standard lanes are MemoryMax=1200M and will cgroup-OOM those workloads.
+# Stack-aware (#1550): the runtime is rendered into the setup-step `if:` — both the Node and Python
+# setup steps live in the file but only the one matching GATE_RUNTIME runs. Knobs (override at
+# bootstrap with --var):
+#   GATE_RUNTIME       — node | python (selects which setup step fires)
+#   GATE_CMD           — the check command ({{GATE_CMD}})
+#   GATE_INSTALL_CMD   — the dependency-install command ({{GATE_INSTALL_CMD}})
+#   GATE_WORKDIR       — app working directory when not the repo root ({{GATE_WORKDIR}})
+#   GATE_CACHE_DEP_PATH— npm lockfile path for the setup-node cache ({{GATE_CACHE_DEP_PATH}})
+#   GATE_PY_VERSION    — Python version for setup-python ({{GATE_PY_VERSION}})
+#   GATE_MAX_SECONDS   — run-with-budget wall-clock ceiling in seconds ({{GATE_MAX_SECONDS}}); 300 default,
+#                        tighten per repo (org project set --var gate={"maxSeconds":N}) once measured (#3178)
+#   GATE_PUSH_BRANCHES_YAML — YAML list of push branches that trigger the workflow file (rendered by
+#                        bootstrap from the release track; not usually hand-passed)
+#   GATE_FULL_RUN_BRANCH — train branch whose PUSHES run the full gate job (development on full/direct;
+#                        main on trunk). `main` is ALWAYS included in the job `if:` below so a required-
+#                        checks ruleset on main cannot be silently skipped by a future bootstrap (#4113).
+# GATE_BUDGET_SHA is rendered by the CLI from its blessed run-with-budget pin — not an operator knob.
+# (seed touch: keep kilo mirror + BOM digests in lockstep after classifier land.)
+on:
+  pull_request:
+  push:
+    branches: {{GATE_PUSH_BRANCHES_YAML}}
+    tags: ['v*']
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+# #3001: cancel superseded runs — agent push-bursts queue a full fresh run per push.
+# Per-PR group only (a repo-wide group hits GitHub's one-pending-slot limit and cancels
+# innocent queued runs — MMC-ZuberShade#880). Pushes group by ref: each tag and the train
+# branch supersede only themselves.
+concurrency:
+  group: gate-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  gate:
+    # #4113: bake `main` into the template permanently. GATE_FULL_RUN_BRANCH selects the train push
+    # that runs the full job; main must never become skippable via bootstrap vars alone while the
+    # org ruleset still requires `gate` on main.
+    if: ${{ github.event_name != 'push' || github.ref_name == '{{GATE_FULL_RUN_BRANCH}}' || github.ref_name == 'main' || github.ref_type == 'tag' }}
+    runs-on: [self-hosted, linux, x64, mmi-live]
+    defaults:
+      run: { working-directory: {{GATE_WORKDIR}} }
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - if: ${{ '{{GATE_RUNTIME}}' == 'node' }}
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with: { node-version: 24, cache: npm, cache-dependency-path: {{GATE_CACHE_DEP_PATH}} }
+      - if: ${{ '{{GATE_RUNTIME}}' == 'python' }}
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with: { python-version: '{{GATE_PY_VERSION}}' }
+      # MMI-Hub#3446: assert the runtime toolchain is on PATH BEFORE the install step. A runner whose
+      # node/npm (or python) is missing, or whose setup step raced, fails `{{GATE_INSTALL_CMD}}` with a
+      # bare `command not found` (exit 127) that reads like a broken diff and abandons a correct PR in an
+      # autonomous merge loop. This names the RUNNER instead — a distinguishable infra failure that
+      # `mmi-cli devops pr checks-wait` classifies as rerunnable (title `CI runner toolchain`), mirroring the
+      # disk (#3366) and browser (#808) preflights. No test ran; the diff is not implicated.
+      - name: Toolchain preflight
+        if: ${{ '{{GATE_RUNTIME}}' == 'node' }}
+        run: |
+          node -v && npm -v || { echo "::error title=CI runner toolchain::RUNNER NOT PROVISIONED — node/npm not on PATH after setup-node. This is the runner, not your diff; no install or test ran. Re-run the job (a fresh lane usually clears it); if it persists the mmi-runner node toolchain needs attention (docs/Guides/gh-runner-runbook.md in MMI-Hub)."; exit 1; }
+      - name: Toolchain preflight
+        if: ${{ '{{GATE_RUNTIME}}' == 'python' }}
+        run: |
+          python3 --version || { echo "::error title=CI runner toolchain::RUNNER NOT PROVISIONED — python3 not on PATH after setup-python. This is the runner, not your diff; no install or test ran. Re-run the job; if it persists the mmi-runner python toolchain needs attention (docs/Guides/gh-runner-runbook.md in MMI-Hub)."; exit 1; }
+      - run: {{GATE_INSTALL_CMD}}
+      # #3178: the check runs under the org wall-clock budget — a hung suite dies at the ceiling instead
+      # of squatting a runner lane for GitHub's 6h default. ci-audit + the release train enforce this step.
+      - uses: mutmutco/MMI-Hub/.github/actions/run-with-budget@{{GATE_BUDGET_SHA}}
+        with:
+          command: {{GATE_CMD}}
+          max-seconds: {{GATE_MAX_SECONDS}}
+          working-directory: {{GATE_WORKDIR}}

package/skills/bootstrap/seeds/google-login.template.md

@@ -0,0 +1,33 @@
+# Google login — {{REPO_NAME}}
+
+This repo has a Google OAuth client provisioned by the org — one client spanning local/`/stage`, dev, rc, and
+prod. Adding Google login here is **self-serve**: you do not need master-admin help.
+
+## Reach the creds (from SSM — never in git, never printed)
+```bash
+# Confirm they resolve for your repo (names only, no value):
+mmi-cli vault secrets list
+# Consume them keyless in a command — injected into its env, never printed (raw `secrets get` was removed, #2844):
+mmi-cli vault secrets use GOOGLE_CLIENT_ID -- <cmd>
+mmi-cli vault secrets use GOOGLE_CLIENT_SECRET -- <cmd>
+```
+The canonical keys are the stageless `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` pair at the project vault
+root. The project-admin can manage them for their own repo; runtime and CI read them keylessly. Never bake a secret into an
+image or commit it. The remote fileless deploy writes no release `.env`; **do not commit or hand-edit a `.env`**.
+The only `.env` you may create is the gitignored one `/stage` makes from `.env.example` for local dev.
+
+## The one rule that makes every environment work
+Build the OAuth `redirect_uri` from the **incoming request** — never a hardcoded base URL:
+- callback path: `/api/auth/callback`
+- derive scheme + host from `X-Forwarded-Proto` / `X-Forwarded-Host` (set by the Caddy proxy), falling back
+  to the `Host` header.
+
+The client's loopback redirect URIs are registered **port-agnostic**, so any local port works; dev/rc/prod
+URIs are registered for both `mutatismutandis.co` and `mutmut.co`, so the deploy train works unchanged.
+
+## Reference implementation + full guide
+Inspect this repo's expected URIs and confirm the client is port-agnostic:
+```bash
+mmi-cli vault org oauth plan      # the canonical JS origins + redirect URIs + SSM cred params
+mmi-cli vault org oauth verify    # probes an arbitrary :9123 loopback — no redirect_uri_mismatch = good
+```

package/skills/bootstrap/seeds/manifest.json

@@ -0,0 +1,26 @@
+{
+  "_comment": "Bootstrap seed manifest (#201) — the machine-readable contract of what /bootstrap and `mmi-cli devops bootstrap --apply` (#202) stamp into a target repo. Consumed by the CLI (loadBootstrapSeeds). ownership: 'org' = org-delivered, OVERWRITTEN on upgrade (the org owns it); 'repo' = created ONCE on a fresh bootstrap, never clobbered on upgrade (the repo owns its content). source: 'self' = copy MMI-Hub's own current file verbatim; 'seed:<file>' = render the named template in this dir with {{PLACEHOLDERS}}; 'managed-block' = merge the org-managed .gitignore block in place (preserves the repo's own ignore lines) — this is how the org-managed .gitignore block reaches every repo now that the fanout pipeline is retired (Hub#3010); the doctor SessionStart heal keeps it current thereafter. NOTE: this manifest seeds org-managed PRODUCT assets only — it never seeds AGENTS.md / CLAUDE.md / .claude/settings.json (personal agent guides) or a legacy repo-local control-plane marker. classes: which repo classes receive this seed.",
+  "placeholders": ["OWNER", "REPO", "REPO_SLUG", "REPO_NAME", "CLASS", "GATE_CMD", "GATE_PUSH_BRANCHES_YAML", "GATE_FULL_RUN_BRANCH", "GATE_RULESET_BRANCH_REFS_JSON", "PROJECT_OWNER", "PROJECT_NUMBER", "PROJECT_ID", "STATUS_FIELD_ID", "STATUS_TODO", "STATUS_IN_PROGRESS", "STATUS_IN_REVIEW", "STATUS_DONE", "STACK", "REGION"],
+  "seeds": [
+    { "target": ".github/ISSUE_TEMPLATE/bug.yml", "source": "self", "ownership": "org", "classes": ["deployable", "content"] },
+    { "target": ".github/ISSUE_TEMPLATE/feature.yml", "source": "self", "ownership": "org", "classes": ["deployable", "content"] },
+    { "target": ".github/ISSUE_TEMPLATE/task.yml", "source": "self", "ownership": "org", "classes": ["deployable", "content"] },
+    { "target": ".github/ISSUE_TEMPLATE/config.yml", "source": "self", "ownership": "repo", "classes": ["deployable", "content"] },
+    { "target": "scripts/next-version.mjs", "source": "self", "ownership": "org", "classes": ["deployable"] },
+    { "target": ".github/workflows/gate.yml", "source": "seed:gate.template.yml", "ownership": "repo", "classes": ["deployable"] },
+    { "target": ".github/workflows/agent-pr.yml", "source": "self", "ownership": "org", "classes": ["deployable"], "waivers": { "jerv-jervcode": "pins this workflow's EXACT step shapes in its own scripts/workflow-boundary-core.mjs — a literal repositories: Jerv-JervCode token scope, and whole-step equality for the surface and verdict legs. #4040 widened the org seed to the same hardened boundary (pull_request_target off the trusted base, an immutable BASE..HEAD compare with a file-count equality wall, a per-repo App token scope, and a certified-head merge), so the two now agree on substance. They cannot agree on bytes: a seed serving 16 repos resolves its token scope and its required contexts at run time, which exact-step equality rejects by construction. The waiver is permanent by design, not a deferral — lifting it would mean weakening the strictest repo to match a fleet file." } },
+    { "target": ".github/rulesets/mmi-product-required-checks.json", "source": "seed:mmi-product-required-checks.template.json", "ownership": "org", "classes": ["deployable"] },
+    { "target": ".gitignore", "source": "managed-block", "ownership": "org", "classes": ["deployable", "content"] },
+    { "target": "README.md", "source": "seed:README.template.md", "ownership": "repo", "classes": ["deployable", "content"] },
+    { "target": "architecture.md", "source": "seed:architecture.template.md", "ownership": "repo", "classes": ["deployable", "content"] },
+    { "target": "docs/decisions/README.md", "source": "seed:decisions-readme.template.md", "ownership": "repo", "classes": ["deployable", "content"] },
+    { "target": "docs/Guides/google-login.md", "source": "seed:google-login.template.md", "ownership": "repo", "classes": ["deployable"], "projectTypes": ["web-app"] },
+    { "target": "docker-compose.yml", "source": "seed:docker-compose.template.yml", "ownership": "repo", "classes": ["deployable"], "deployModels": ["tenant-container"] },
+    { "target": "Dockerfile", "source": "seed:Dockerfile.template", "ownership": "repo", "classes": ["deployable"], "deployModels": ["tenant-container"] }
+  ],
+  "labels": [
+    { "name": "bug", "color": "d73a4a", "description": "Something is broken or behaving wrong" },
+    { "name": "feature", "color": "a2eeef", "description": "New capability or enhancement" },
+    { "name": "task", "color": "0052cc", "description": "Task, chore, or improvement" }
+  ]
+}

package/skills/bootstrap/seeds/mmi-product-required-checks.template.json

@@ -0,0 +1,23 @@
+{
+  "_comment": "Repository-level ruleset requiring the product gate job (#1333). Apply via GitHub repo rulesets (master-admin) after bootstrap seeds gate.yml — the job name gate must match this context.",
+  "name": "mmi-product-required-checks",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "include": {{GATE_RULESET_BRANCH_REFS_JSON}},
+      "exclude": []
+    }
+  },
+  "rules": [
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": false,
+        "required_status_checks": [
+          { "context": "gate" }
+        ]
+      }
+    }
+  ]
+}

package/skills/browser-automation/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: browser-automation
+description: Use DOM-first Playwright MCP for browser work.
+---
+
+**Host-native invocation:** Claude `/mmi:browser-automation` · Codex `$mmi:browser-automation` · jervcode/Kimi `/skill:browser-automation` · Kilo `skill` tool. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
+
+# Browser automation — DOM-first Playwright MCP
+
+Org standard for agent browser work on Claude Code. **Playwright** is the engine; agents interact through **structure-first** MCP tools, not pixels-first defaults.
+
+## Doctrine (non-negotiable)
+
+1. **Accessibility tree first** — semantic structure the agent can reason about (`browser_snapshot`, a11y refs).
+2. **DOM second** — selectors, snapshots, network when the tree is not enough.
+3. **Vision last** — screenshots only when tree + DOM cannot answer the question.
+4. **Prefer HTTP/OpenAPI** — call APIs directly when discovery or the task allows; do not drive UI for data you can fetch.
+
+**Never** pass `--caps=vision` (or equivalent vision-first defaults) on Playwright MCP org-wide. Vision caps burn tokens, hide structure, and break on theme/layout drift.
+
+## When to use what
+
+| Need | Use |
+|------|-----|
+| Local dev server + smoke on current branch | **`/stage`** — gitignored stack under `tmp/stage/`; see `skills/stage/SKILL.md` |
+| Personal cloud dev preview of your branch | **`/stage --live`** — IP-gated dev stage; not rc/prod |
+| Interactive UI debug, one-off flow, agent-driven clicks | **Playwright MCP** (this skill) — DOM-first, artifacts under `tmp/` |
+| Durable hosted automation outside dev machines | **Stagehand + Browserbase** (production path) — explicit choice, not the default for every local task |
+
+`/stage` and Playwright MCP **complement** each other. `/stage` spins the app; MCP drives the browser against a URL (often the stage URL).
+
+## MCP configuration (no vision)
+
+### Claude Code
+
+Enable the official Playwright plugin (`playwright@claude-plugins-official`) via `/plugin`. Follow its DOM-first tools; do not enable vision-first modes for routine agent work. Point MCP output at `tmp/playwright-mcp` when the server accepts `--output-dir`.
+
+Editor-host MCP configs (Cursor `.cursor/mcp.json`, Codex `config.toml`) are retired org surfaces (#2741/#2808) — bootstrap no longer seeds them; do not reintroduce them.
+
+## Playwright availability
+
+Check the configured/global CLI before adding a temporary local dependency. On Windows PowerShell:
+
+```powershell
+Get-Command playwright
+playwright --version
+```
+
+`node -e "require.resolve('playwright')"` only proves a Node module is installed in the current package; it
+can fail while the global or editor-configured Playwright CLI works. Use the available CLI for smoke checks
+and MCP setup. Temporary per-worktree installs are fallback-only, and should stay untracked.
+
+## Agent workflow (MCP)
+
+1. **Goal** — what observable outcome proves success?
+2. **Navigate** — open the target URL (often from `/stage` JSON: `mmi-cli stage --json`).
+3. **Snapshot** — a11y tree / DOM snapshot before interacting.
+4. **Act** — click, type, select using refs from the latest snapshot.
+5. **Re-snapshot** after navigation or major DOM changes (refs go stale).
+6. **Vision only if stuck** — one screenshot to disambiguate; then return to tree/DOM.
+
+Core MCP loop:
+
+```
+browser_navigate → browser_snapshot → browser_click / browser_type → browser_snapshot
+```
+
+## Artifacts and hygiene
+
+- **All Playwright MCP output → `tmp/playwright-mcp/`** (pass `--output-dir tmp/playwright-mcp` when the MCP server supports it).
+- **Never** leave traces, screenshots, or reports at the repo root.
+- `.playwright-mcp/` at repo root is gitignored as a **safety net only** — not the canonical path.
+- The housekeeping gate refuses tracked browser artifacts (`.playwright-mcp/`, `playwright-report/`, `test-results/`).
+
+## Anti-patterns (org-wide avoid)
+
+- `--caps=vision` or screenshot-first wrappers for routine tasks
+- Skyvern, Magnitude, LaVague, or other vision-first agent browsers as org defaults
+- Committing `.playwright-mcp/`, `playwright-report/`, or `test-results/` from agent runs
+- Replacing `/stage` with ad-hoc MCP servers for branch smoke (use `/stage` for the stack, MCP for the browser)
+
+## Related
+
+- **`/stage`** — `skills/stage/SKILL.md`
+- **`/grind`** (optional external tool) — use DOM-first browser checks in verification when criteria need UI proof
+
+## 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 MCP snippet, or an artifact path it should have warned
+about? (Process only — never the user's code or task.) 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 browser-automation --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/epic/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: epic
+description: Decompose a vision or umbrella issue into linked child issues via one batch create.
+---
+
+# /epic — decompose an umbrella into children
+
+Turn one large item — a vision issue, an epic, an umbrella issue — into a set of native sub-issues in a
+single pre-validated batch, each already linked to its parent. This is the slice-and-fan-out act done by
+hand today: draft the children, validate them all, create them, confirm the tree.
+
+## Opening branch — create a new umbrella when none exists
+
+When the request is a product intent rather than an existing issue, gather the intent first, read the
+repo's live issue templates, draft the umbrella from the matching feature/task template, and show that
+draft for the user's go. Only then create one issue with the `epic` label and an explicit Priority field;
+re-read it from the board to prove the body, label, and priority landed. Stop there unless the user also
+asked for and approved child decomposition.
+
+## Step 0 — load the umbrella whole
+
+Read the parent end-to-end before slicing — body **and every comment**, treating later comments as
+superseding:
+
+```bash
+mmi-cli oracle board show <owner/repo#N>       # status, body, and every comment for the umbrella
+```
+
+Slice by deliverable, not by phase: each child must be independently claimable and land in its own PR.
+Keep the parent as the umbrella — do not close it until the last child merges.
+
+## Step 1 — draft the batch file
+
+Write a JSON array (one object per child) to a scratch path under `tmp/`. Each row:
+
+```json
+[
+  { "type": "task", "title": "C1: extract the shared frame", "body": "…", "priority": "high",
+    "surface": "cli", "parent": "owner/repo#42" },
+  { "type": "feature", "title": "C2: wire the new command", "body": "…", "priority": "medium",
+    "parent": "owner/repo#42" }
+]
+```
+
+- `type` — `bug` · `feature` · `task` (required; maps to the repo's issue-template label).
+- `title` — required, non-empty; keep it a short, greppable deliverable.
+- `parent` — the umbrella ref (`#N`, `owner/repo#N`, or URL); links each child as a native sub-issue on
+  create, so you do not need a separate `link-child` pass. Cross-repo is fine (a Hub umbrella can parent
+  product-repo children).
+- `priority` — `urgent|high|medium|low` (defaults to `medium`); sets the board Priority **field**.
+- `repo` — optional per-row target repo (`owner/repo`); defaults to `--repo`, then the current repo.
+  This is how one batch fans children out across repos under a single umbrella.
+- `surface` — required when the target repo uses `surface:*` taxonomy; accepts the value with or without
+  the prefix. A top-level `--surface <value>` may supply the default for every applicable row.
+
+The batch **pre-validates every row before creating any** — one bad row fails the whole set with an
+aggregate error, so you fix all of them once. Get the user's go on the drafted set before writing.
+
+## Step 2 — create the children
+
+```bash
+mmi-cli oracle issue create --type task --batch tmp/epic-children.json --surface cli
+```
+
+`--type` is required by the create command but each row's own `type` governs; pass any valid type as the
+placeholder. It prints per-row `{number,url}` results and fails loud on any misfire. Add
+`--idempotency-key <key>` when a retried loop must not duplicate.
+
+The idempotency lookup is find-before-create, not an atomic reservation. Run one batch writer at a time:
+never submit concurrent creates with the same key. Size the calling command's wall-clock budget for the
+whole sequential batch. If the command times out, its outcome is unknown — confirm the process has ended,
+wait for writes to quiesce, inspect the children, then retry the missing rows with the same key.
+
+## Step 3 — confirm the tree
+
+```bash
+mmi-cli oracle issue children <owner/repo#N>        # each child: number/title/state/repo/boardStatus/linkedPrs
+```
+
+Verify every intended child is linked and on the board as Todo. To link a child that already existed (not
+part of the batch), use the inverse-friendly single link:
+
+```bash
+mmi-cli oracle issue link-child <parent> <child>
+```
+
+Each child is now a parallel item — fan them out one worktree + PR each. **When the last child merges,
+close the umbrella** (its board `Done` follows automatically).
+
+## Notes
+
+- Native sub-issues, not a body task-list: the parent renders a sub-issue checklist and each child renders
+  its parent — nothing to hand-maintain.
+- Never free-type children with raw `gh issue create` — the batch path carries validation, board attach,
+  and structured output.
+
+## 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 batch schema that rejected a valid row, or a
+link that attached to the wrong parent.) 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 epic --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

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>"
+```