@mutmutco/kilo-plugin 3.81.0 → 3.83.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/kilo-plugin",
-  "version": "3.81.0",
+  "version": "3.83.0",
   "description": "MMI workflow skills and org gates delivery.",
   "author": {
     "name": "MMI Future",

package/skills/bootstrap/SKILL.md

@@ -128,6 +128,8 @@ for `rc`/`main` (#3433). `$FIRST` is the track's first branch: `development` for
 FIRST=development     # full / direct
 FIRST=main            # trunk (content)
 
+# One-time namespace + first-ref creation uses the authenticated master-admin GitHub session. The current
+# mmi-cli has no App-backed command for a repository that does not exist; this is the named exception.
 gh repo create "$OWNER/$REPO" --private
 gh api -X PUT "repos/$OWNER/$REPO/contents/.gitkeep" \
   -f message="chore: initial commit" -f content="Cg==" -f branch="$FIRST"
@@ -136,6 +138,11 @@ gh api -X PUT "repos/$OWNER/$REPO/contents/.gitkeep" \
 On an empty repo that PUT creates `$FIRST` **and leaves it the default branch**, so no `gh repo edit
 --default-branch` is needed here. Skip this step when the repo already exists with the track's default branch.
 
+The two `gh` writes above are authorized by the authenticated master-admin login and are the one-time
+bootstrap exception while no App-backed `mmi-cli` command owns a repository that does not yet exist. They
+are not a general write lane: after the namespace and first ref exist, use the App-backed
+`mmi-cli bootstrap apply --execute` path for managed seeds, labels, rulesets, and registry state.
+
 For a **content** repo the API form is not merely tidier, it is the only thing that works: `main` is that
 track's first and only branch, so the initial commit IS a push to `main` and the #1660 guard fences it — and
 the deny's own advice ("land through a CI-gated PR to development") is meaningless on a repo with no commits,

package/skills/epic/SKILL.md

@@ -9,6 +9,14 @@ Turn one large item — a vision issue, an epic, an umbrella issue — into a se
 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
@@ -28,7 +36,7 @@ Write a JSON array (one object per child) to a scratch path under `tmp/`. Each r
 ```json
 [
   { "type": "task", "title": "C1: extract the shared frame", "body": "…", "priority": "high",
-    "parent": "owner/repo#42" },
+    "surface": "cli", "parent": "owner/repo#42" },
   { "type": "feature", "title": "C2: wire the new command", "body": "…", "priority": "medium",
     "parent": "owner/repo#42" }
 ]
@@ -40,6 +48,8 @@ Write a JSON array (one object per child) to a scratch path under `tmp/`. Each r
   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**.
+- `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.
@@ -47,13 +57,18 @@ aggregate error, so you fix all of them once. Get the user's go on the drafted s
 ## Step 2 — create the children
 
 ```bash
-mmi-cli issue create --type task --batch tmp/epic-children.json
+mmi-cli 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

package/skills/hotfix/SKILL.md

@@ -34,7 +34,7 @@ and CLI health before starting:
 
 ```bash
 mmi-cli org access role <owner/repo> --json
-mmi-cli doctor --apply --no-repo-writes
+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

package/skills/mmi/SKILL.md

@@ -52,7 +52,7 @@ preflight that reports "skipped — lock busy" has healed nothing, and an agent
 line will carry on believing its tooling was fixed.
 
 `doctor --preflight` detects a stale npm global or a stale/unresolved plugin install and runs the **env**
-half of the interactive `doctor --apply` self-heal (#3485) — it never touches the repo working tree, and
+half of the interactive doctor self-heal (#3485/#3975) — it never touches the repo working tree, and
 never pays the train-branch sync or the gc sweep. It still belongs off the critical board path unless it
 has proof it must heal. When it prints `↻ Updating mmi tooling, one moment…`, relay that before waiting;
 when it prints `↻ MMI tooling updated — …`, relay the reload/restart guidance.

package/skills/rcand/SKILL.md

@@ -30,7 +30,7 @@ never proceed unverified.
 **CLI freshness (#2562):** check the running CLI is current BEFORE step 1 — `mmi-cli rcand --apply` refuses
 a stale CLI at its own step 0 (pre-mutation), but the manual steps below mutate local state earlier, so a
 stale CLI discovered late reads as a mid-train abort. When another train just published a new CLI (e.g. a
-Hub release), run `mmi-cli doctor --apply --no-repo-writes` first. A stale-CLI refusal itself changes
+Hub release), run `mmi-cli doctor --no-repo-writes` first. A stale-CLI refusal itself changes
 nothing; after updating, the rerun resumes any partial train state safely.
 
 **Run from the checkout that already has `development` — never a fresh isolated worktree (#2770).** This is
@@ -51,7 +51,7 @@ git rev-list --count origin/rc..origin/development
 ```
 Dirty → stop. Count `0` → stop ("nothing to promote"). `>0` → capture the commit list for the report.
 
-> Verifying CLI/plugin-health before a train? Use `mmi-cli doctor --apply --no-repo-writes`: it runs the
+> Verifying CLI/plugin-health before a train? Use `mmi-cli doctor --no-repo-writes`: it runs the
 > env/plugin repairs but never mutates the working tree, so a pending org-managed `.gitignore` repair is
 > reported with its follow-up command instead of dirtying the product checkout right before promotion.
 > Apply that follow-up after the train.

package/skills/release/SKILL.md

@@ -93,28 +93,25 @@ git rev-list --count origin/main..origin/development
 
 Before local gates or `release --apply`, ensure the repo-local / PATH `mmi-cli` matches the released train
 path — a stale checkout (e.g. 2.32.0 while 2.32.4 is released) fails release gates with opaque errors.
-Self-heal in place without repo writes:
+Self-heal in place without repo writes (heals run by default since #3975; the flag suppresses only
+mutations of the working tree you are about to release from):
 ```bash
-mmi-cli doctor --apply --no-repo-writes
+mmi-cli doctor --no-repo-writes
 ```
 **Read the checks, not the exit code.** `doctor` exits non-zero on any failed check it could have healed —
 not just a version gap — so a red exit here does not by itself mean the train is blocked (#2962). The
-inverse is also true since #3485: a run can exit **0** while printing ✗ lines, because three rows
-(`worktree roots`, `schedules`, `docs-audit`) are ruled report-only — real faults the design deliberately
-declines to gate on, since their remedy is a human review or lives in the owning repo. Neither direction
-is a gate. Read the rows.
+inverse is also true: a run can exit **0** while printing ✗ lines (report-only rows, #3485). Neither
+direction is a gate. Read the rows.
 
-- **Blocking:** a red `mmi-cli` / `Claude plugin` version line, or a reported `minClientVersion` gap. Since
-  #3485 `--no-repo-writes` no longer blocks the env heals — the step above self-updates the npm global CLI
+- **Blocking:** a red `mmi-cli` / `Claude plugin` version line, or a reported `minClientVersion` gap.
+  `--no-repo-writes` does not block the env heals — the step above self-updates the npm global CLI
   (#3272) and reinstalls the plugin (#3282), suppressing only repo-file writes — so the re-run should clear
-  it. If a gap persists, fix it — `mmi-cli doctor --apply`, or `npm install -g @mutmutco/cli` — before
+  it. If a gap persists, fix it — `mmi-cli doctor`, or `npm install -g @mutmutco/cli` — before
   continuing. Do **not** proceed to Step 0b while the installed CLI is behind the Hub's `minClientVersion`.
 - **Not blocking:** every other red check is hygiene, not a train gate. Stale branches and scratch heal with
-  `mmi-cli doctor --apply`; `plugin cache` needs a different verb, `mmi-cli plugin prune --apply` — saying
-  `doctor --apply` cleared it was wrong. All three still exit 1 until you run the right verb. The three
-  report-only rows (`worktree roots`, `schedules`, `docs-audit`) print ✗ without moving the exit code
-  since #3485 — not because no verb exists, but because the design refuses to gate on a human review or
-  on a fault owned by another repo. Read them, then proceed.
+  a plain `mmi-cli doctor` (after the release); `plugin cache` needs a different verb,
+  `mmi-cli plugin prune --apply` — saying doctor cleared it was wrong. Both still exit 1 until you run the
+  right verb. Read them, then proceed.
 
 Treating doctor's exit code as the gate halts a healthy train on cosmetic drift — or, worse, teaches an
 operator to ignore doctor's exit code entirely.
@@ -142,7 +139,10 @@ Verify META + required SSM secret names before touching `main`:
 mmi-cli org project get {owner}/{repo}
 mmi-cli secrets preflight --stage main --repo {owner}/{repo}
 ```
-Missing META or secret names → stop and repair the registry/secrets first.
+An enumerated missing META row or missing secret name → stop and repair the registry/secrets first. An
+HTTP 5xx, timeout, DNS, socket, or other transport failure is **unverified**, not evidence that a name is
+missing: retry the read/preflight and repair connectivity if it persists. Never provision or rename a
+secret from a transport-error response.
 
 ## Step 0c — hotfix-coverage guard (fail closed, #839, #958)
 

package/skills/resume/SKILL.md

@@ -35,14 +35,16 @@ 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`.
+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 next
+mmi-cli next --repo <repo reported by status>
 ```
 
+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 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`.