@mutmutco/kilo-plugin 3.82.0 → 3.84.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/kilo-plugin",
-  "version": "3.82.0",
+  "version": "3.84.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

@@ -38,7 +38,11 @@ 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.
+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
 

package/skills/rcand/SKILL.md

@@ -43,8 +43,12 @@ primary checkout.
 ## Step 1 — development ahead of rc?
 
 Preconditions: on `development`, clean tree. The clean-tree check rejects UNTRACKED scratch too, not just
-modified tracked files — if `--apply` stops with `working tree must be clean before …`, run `git status` and
-gitignore the `??` scratch (or move it to a gitignored path like `tmp/`) before retrying (#1472).
+modified tracked files — if `--apply` stops with `working tree must be clean before …`, run `git status
+--porcelain` on the paths it named and read both columns. Gitignore the `??` scratch (or move it to a
+gitignored path like `tmp/`). Treat every tracked state except exactly ` M` as real work to commit or stash;
+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 tell real work from line-ending churn (#1472, #4004).
 ```bash
 git fetch origin
 git rev-list --count origin/rc..origin/development

package/skills/release/SKILL.md

@@ -72,9 +72,22 @@ breaks here: the new worktree's branch is never literally named `development`/`r
 development` inside it fails outright when `development` is already checked out in the primary checkout (git
 worktrees cannot have the same branch checked out twice). If you are in such a worktree, exit it first and
 run the release from the primary checkout.
-The clean-tree check rejects UNTRACKED scratch too, not just modified tracked files — if `--apply` stops
-with `working tree must be clean before …`, run `git status` and gitignore the `??` scratch (or move it to a
-gitignored path like `tmp/`) before retrying (#1472).
+The clean-tree check rejects UNTRACKED scratch too, not just modified tracked files. When `--apply` or
+`--resume` stops with `working tree must be clean before …`, run `git status --porcelain` on the paths it
+named and read BOTH status columns before touching anything (#1472, #4004):
+
+- `??` — untracked scratch. Gitignore it, or move it to a gitignored path like `tmp/`, then retry.
+- exactly ` M` (blank staged column) — the only state that can be churn rather than work. Test it with
+  `git diff HEAD --numstat -- <paths>`: non-empty is a real edit to commit or stash; empty means the
+  worktree normalizes straight back to HEAD (an LF↔CRLF rewrite, say), and `git checkout -- <paths>`
+  then clears the refusal without discarding anything.
+- anything else — `M `, `MM`, `A`, `D`, `R`, `T`, or any `U` conflict — is real work or an exceptional
+  index state. Commit, stash or resolve it; do not try to classify it.
+
+Do not substitute plain `git diff --numstat` for the `HEAD` form. It compares the worktree against the
+INDEX, so a change that is merely staged prints nothing at all, and reading that emptiness as
+"line-ending churn" throws the change away. The remedy is the index form of `git checkout` for the same
+reason: `git checkout HEAD -- <paths>` would overwrite a staged edit that was misread as churn.
 
 Full-track repos:
 ```bash
@@ -139,7 +152,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)
 
@@ -468,6 +484,19 @@ mmi-cli org project sync-info --apply   # omit --apply for the read-only plan
   channel — #3630 took SessionStart off the hook surface) runs the
   same fast-forward first thing, so a stale local `development`/`main`/`rc` self-heals to origin before you
   work — no manual `git pull`. Nothing here ever blocks or fails the release.
+- **Read the `checkout:` clause — it does not always say "returned" (#4006).** The report always prints
+  one, and restoration is deliberately skipped rather than forced when the repo is not in a fit state.
+  A release leaves the repo on `main` until the train moves it back, so a non-`returned` outcome means
+  you are still there and must return by hand once the cause is cleared:
+  - `checkout restoration skipped: working tree changed after release` — the tree went dirty DURING the
+    train, so the train declined to move you. Diagnose those paths with the Step 0 clean-tree rules,
+    then `git checkout <start branch>` yourself. The release itself already shipped; this is a
+    deliberate, harmless decline, not a failed release.
+  - `checkout restoration failed while returning to …` / `origin/<branch> fast-forward failed` — the
+    checkout or the pull errored. Read the appended git message; the release is unaffected.
+
+  `--resume` prints no `checkout:` clause at all, so after a resumed release check `git branch
+  --show-current` rather than assuming you were moved back.
 
 ## Step 6 — collect deploy verdict + report
 
@@ -475,6 +504,10 @@ Collect the backgrounded prod-deploy watch from Step 4 (it has typically finishe
 healthy (the central deploy workflow smoke step / a health check); **red** → report the failure prominently and flag
 that the release shipped on a failed deploy (re-run just the deploy — `main` is already correct).
 
+**This distribution verifier is Hub-only.** It assumes the Hub release fold has already committed its
+generated artifacts. Non-Hub `registry-publish` repositories must not run `release-distribution.mjs
+verify`: use their own release-workflow evidence and the publish-visibility contract below.
+
 Hub releases always carry a distribution bump (the Step 1b fold), so the **publish workflow**
 (`publish.yml`) ships every registry-declared public npm artifact on the GitHub Release from Step 4 —
 don't publish by hand.

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`.