@mutmutco/kilo-plugin 3.94.0 → 3.96.0

package/package.json

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

package/skills/bootstrap/SKILL.md

@@ -413,11 +413,11 @@ collaborator list + the per-branch allowlist are the record — no separate rost
   Step-0 axes (class, project-type, deploy-model). Do **not** write the release track, board number, or deploy
   coords as a value — the templates point at `mmi-cli org project get` (registry SSOT, never copied, so it cannot drift).
   Do not write `AGENTS.md` / `CLAUDE.md` — these are developer-owned, gitignored agent guides, never a bootstrapped repo file (the `mmi-no-agent-files-org` ruleset blocks committing them).
-- **`docs/index.md` is generated by `bootstrap apply`, once (#3545).** The seeded README's first agent
-  instruction is to read it, so it exists from the first commit and `bootstrap verify` requires it. Apply
-  **creates** it and never rewrites it: apply sees the seed list, not the tree, so regenerating an index in a
-  repo that has since added its own docs would silently drop every hand-authored entry. Once the repo has
-  docs of its own, `mmi-cli docs index --write` owns it — that reads the whole tree, and `--check` gates drift.
+- **`docs/index.md` is an optional generated routing index (#3545 / Hub#4133).** Agent entrypoints prefer
+  `mmi-cli repo-index search` + compute-at-read CLI over living prose under `docs/`. Apply may still create
+  `docs/index.md` once for link routing; it never rewrites it. Once the repo has docs of its own,
+  `mmi-cli docs index --write` owns the routing artifact and `--check` gates drift — it is not product
+  current-state SSOT. Decision records under `docs/decisions/` remain append-only *why*.
 - **Push the mandated fill past the active ruleset (#1807).** Deployable repos activate
   `mmi-product-required-checks` during apply (its `bypass_actors` is empty by design), so the `gate` check is
   required on `development`/`main` before the seeded README + architecture have ever produced a green run. The

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

@@ -18,12 +18,13 @@ access runbook → [repo-access](https://github.com/mutmutco/MMI-Hub/blob/develo
 
 Read this section at the start of agent work in this repo.
 
-- **Docs entry point:** read `docs/index.md` first — the generated routing index (`mmi-cli docs index
-  --write`); `--check` gates drift, so it can never fall out of sync with the `docs/` tree.
+- **Structure search:** `mmi-cli repo-index search <path|symbol|meaning>` — Hub cloud pointer hits
+  (Hub#4133). Prefer this over inventing wiki pages or trusting stale inventories under `docs/`.
 - **Durable WHY:** `docs/decisions/` — one file per decision, prose only for what was chosen and
-  rejected; never a description of current state.
-- **Current state:** code + `mmi-cli org project get` — release track, board, and deploy coords are
-  registry facts, resolved live, never copied into a doc where they can go stale.
+  rejected; never a description of current state. Do not maintain living current-state under `docs/`.
+- **Current state:** code + compute-at-read CLI (`mmi-cli org project get`, `board`, `status`,
+  `org schedules`, …) — registry facts, resolved live. Optional generated `docs/index.md` is a
+  **routing** index only (`mmi-cli docs index --check`), not product truth.
 - **GitHub wikis are retired org-wide** — this repo does not publish to a `.wiki.git`; do not create one.
 - **Stack:** (languages, frameworks, major services)
 - **Run locally:** (install, dev server, `/stage` if non-obvious)

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

@@ -42,5 +42,4 @@ 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 (or by the docs janitor as a backstop) and merged
-by a human.
+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/gate.template.yml

@@ -3,6 +3,9 @@ name: gate
 # 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):
@@ -14,7 +17,13 @@ name: gate
 #   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:
@@ -37,7 +46,10 @@ permissions:
 
 jobs:
   gate:
-    if: ${{ github.event_name != 'push' || github.ref_name == '{{GATE_FULL_RUN_BRANCH}}' || github.ref_type == 'tag' }}
+    # #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}} }
@@ -73,8 +85,8 @@ jobs:
           working-directory: {{GATE_WORKDIR}}
       # MMI-Hub#3329: the deterministic doc ref-gate — every file:line ref, command name,
       # relative link, and pin comment in docs/** + README.md + architecture.md must resolve.
-      # This is the gate that makes the docs-janitor's unattended write surface safe (topology D,
-      # MMI-Hub epic #3325). Fleet-portable via the released CLI; runs from the repo root.
+      # Routing-index + ref integrity only — not a living-docs keeper (topology D retired, Hub#4119/#4164).
+      # Fleet-portable via the released CLI; runs from the repo root.
       # MMI-Hub#3406: check the GENERATED index before resolving refs. docs/index.md is produced by
       # `mmi-cli docs index --write`, and a stale one silently re-hosts child docs' relative links and
       # backticked paths at the index's own depth — where they no longer resolve. Every finding it

package/skills/doctor/SKILL.md

@@ -1,76 +1,55 @@
 ---
 name: doctor
-description: One hygiene pass — board drift fix, secrets diff, stale-worktree sweep, and plugin-heal.
+description: One hygiene pass — mmi-cli doctor heals and cleans by default.
 ---
 
 # /doctor — one hygiene pass
 
-A single sweep that clears the residue a working repo accumulates: board invariant drift, secret-catalog
-gaps, merged/closed worktrees and branches left behind, and a stale plugin/CLI. Run it when a session
-opens messy or before a handoff. Each step wraps a real `mmi-cli` command — inspect first, fix on a go.
-
-## Step 0 — toolchain integrity
+One command. Run it when a session opens messy or before a handoff.
 
 ```bash
-mmi-cli doctor --self
+mmi-cli doctor
 ```
 
-Checks CLI/plugin version parity against the published version, and that the active `gh` token can
-actually resolve this repo. It reads npm and GitHub, so it is not offline-safe. It does not check PATH or
-hook wiring — no such check exists (#3485). On a hard gap:
-
-```bash
-mmi-cli plugin heal      # reinstall + re-enable the MMI plugin; then restart Claude Code / reopen the workspace
-```
+By default this **heals and cleans** (MMI-Hub#3975): CLI/plugin/marketplace env repairs, managed
+`.gitignore`, merged-branch / dead-worktree reap (including deferred IDE-locked removals), light board
+mechanical fixes, docs-index working-tree heal, and related full-lane checks. Secrets stay **out** of
+default doctor — use `mmi-cli secrets diff` when you need a catalog gap check.
 
-## Step 1 — board drift
+## Flags
 
-```bash
-mmi-cli board doctor            # detect: transfer ghosts, closed-not-Done, assignee/status mismatch, stray priority:* labels
-mmi-cli board doctor --fix      # apply the automatic fixes once the findings look right
-```
+| Flag | Role |
+|------|------|
+| *(none)* | Heal + clean (default). |
+| `--verbose` | Full checklist + per-row evidence. |
+| `--no-repo-writes` | Env/plugin repairs only — no working-tree mutates (train preflight). |
+| `--self` / `--fast` / `--banner` / `--preflight` | Cheap / read-oriented lanes (see `docs/doctor-contract.md`). |
+| `--apply` | **Deprecated no-op** — kept so older instructions still parse. |
 
-`board doctor` (no `--fix`) exits nonzero when it finds drift and prints each finding. Review, then re-run
-with `--fix` to apply. Never hand-move a board item — the fixer does the mechanical writes.
+## Do not run the old multi-step ritual
 
-## Step 2 — secret-catalog diff (deployable repos)
+Do **not** chain these as a `/doctor` substitute:
 
 ```bash
-mmi-cli secrets diff --stage dev        # required-vs-vault gap + catalog drift; values never shown
-```
-
-Runs the project-side view: declared-missing / orphan / off-scheme secrets for a stage, before any deploy.
-Repeat `--stage rc` / `--stage main` for a repo that promotes. A clean diff exits 0. **Values are never
-printed** — this only names keys. Skip for a repo with no runtime-secret contract.
-
-## Step 3 — stale worktree + branch sweep
-
-```bash
-mmi-cli worktree gc                      # dry-run (default): merged/closed-PR local+remote branches, linked worktrees, stale refs
-mmi-cli worktree gc --apply              # remove only the listed clean items
-mmi-cli worktree gc sweep-deferred       # retry any IDE-locked worktree removals queued from a prior land
+mmi-cli doctor --self
+mmi-cli board doctor
+mmi-cli secrets diff
+mmi-cli worktree gc
 ```
 
-`gc` inspects merged/closed PRs and lists exactly what is safe to delete; `--apply` removes only those. It
-never touches a branch with an open PR. Pair with `mmi-cli wave status` to see worktrees, open PRs, and
-local stages at a glance before sweeping.
-
-## Step 4 — report
-
-One line per step: toolchain OK/healed, board findings fixed, secret gaps by stage, worktrees/branches
-swept. Name anything that needs a human decision (an unowned drift, a secret only the master can grant).
+Plain `mmi-cli doctor` already covers heal + clean. Reach for the individual verbs only when you want
+that surface alone (e.g. a secrets catalog review, or an interactive `board doctor` without the rest).
 
 ## Notes
 
-- `/doctor` is the hygiene pass; `/resume` is the lighter read-only session open. Reach for `/doctor` when
-  the repo is messy, not on every session.
-- `secrets diff` and `board doctor` read live state — never cache their output; re-run to confirm a fix.
+- `/doctor` is the hygiene pass; `/resume` is the lighter read-only session open.
+- Prefer one doctor run over hand-editing board items, gitignore blocks, or marketplace pins.
 
 ## 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 `gc` dry-run that proposed deleting a live
-branch, or a secrets diff that flagged a key that is present.) 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:
+about? (Process only — never the user's code or task; e.g. a doctor run that proposed deleting a live
+branch.) If yes, file **one** lesson and move on; a clean run is silent (hard cap: one per run). It
+lands on the Hub board (deduped) and is fixed only via a reviewed PR — never edit the skill live; the
+retro is advisory, so if the call fails, note it and continue:
 `mmi-cli skill-lesson --skill doctor --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/onboard/SKILL.md

@@ -53,6 +53,20 @@ Close with one grounding line: gates green (or the one gate to fix), and the sin
 usually `mmi-cli board claim <n>` for the recommended item, or the readiness fix if a gate is red. Don't
 claim on the user's behalf; let them take the first item when ready.
 
+## Step 2b — structure door (compute-at-read)
+
+Before treating `docs/**` as current-state, teach the Hub door (Hub#4133 / #4148):
+
+```bash
+mmi-cli repo-index search <path-or-symbol-or-meaning>   # Hub cloud pointers (default)
+mmi-cli repo-index search "where …" --semantic          # Titan meaning over embeddings
+mmi-cli repo-index status --cloud                        # is the estate index live?
+```
+
+Host indexes (Cursor / Kilo) stay local helpers; **Hub `repo-index` is the org SSOT structure door**.
+Living current-state still comes from live verbs (`org schedules`, `board read`, …) — see
+`docs/Architecture/compute-at-read.md`. Do not invent wiki prose from pointer hits.
+
 ## Notes
 
 - `/onboard` is the first-session, readiness-first wrapper. Once a repo is known-good, `/resume` is the

package/skills/release/SKILL.md

@@ -192,61 +192,16 @@ ancestor of `origin/rc` (immune to conflict-resolved ports); a matching `git pat
 the authorized human has manually verified the content is in the candidate, rerun with
 `mmi-cli release --apply --ack <sha>[,<sha>…]` — the ack is recorded in the verdict. Never ack to save time.
 
-## Step 0d — release-time surface freshness (repo-owned, source-only docs gate)
-
-As early as the probe — the released diff (`origin/main..origin/development`, or `..rc`) is already
-known — refresh the repo's own docs against **exactly what is shipping**. An agent reads the
-shipping PRs and quickly scans the surfaces; most releases change nothing they describe, so most
-releases do nothing here. It is **model-agnostic** — describe the work, not the model; under Claude,
-**Sonnet latest (`claude-sonnet-5`)** is the right tier (never the release model, never Haiku).
-Reviewed, repo-owned + release-triggered — never a central, scheduled, cross-repo keeper (that stays
-retired, #2135).
-
-**The two in-repo docs (`README.md`, `architecture.md`): in the released commit.**
-Run this **at the probe, before Step 1**. First scan both against the shipping diff. **If nothing a
-shipped change touches made them drift, skip this docs pass entirely — no PR, no wait** (the common case).
-
-When a shipped change did make a doc drift, establish **where the drifted text comes from** before editing
-it — from the repo's own tooling: a generator script, a "do not edit" header, a generated-region marker.
-**If you cannot establish that a region is hand-written, treat it as generated.** Hand-written prose takes
-the fast path below; a generated region does not, and never lands by hand.
-
-**Hand-written prose — the fast docs-only path:**
-- Edit the doc to current truth (no change-comments — AGENTS docs rule).
-- Land it on `development`: open a PR touching **only** `README.md` /
-  `architecture.md` and auto-merge it (`mmi-cli pr merge <n> --auto --squash` — raw `gh pr merge` is
-  denied by the org command ladder, #2347). Because the PR touches only
-  those two docs, it runs **only the checks its paths trigger** — the repo's gate skips the code/test
-  jobs a docs change can't affect — so it normally goes green + merges in about a minute, with no
-  force-push and no protected-branch bypass (CI stays honest). (On the Hub that is the fast `docs` job
-  while `cli` / `infra` no-op; a single-gate repo short-circuits its one gate the same way.) A
-  docs-only PR also can't expand the release scope (it touches only those two files).
-
-**Generated surface — fix the source, and default to the next cycle** (#2916). The Hub's compact README
-agent loop and `docs/Architecture/agent-playbook.md` come from the CLI loop definitions via
-`scripts/generate-agent-playbook.mjs`; CLI `--help` comes from Commander descriptions. There, the fast path
-does not apply:
-- **Never hand-edit the generated file.** It is a band-aid the next regen silently overwrites, and it
-  leaves `--help` — the surface users actually hit — still wrong.
-- **Fix the source, not the artifact:** edit the loop in `cli/src/explain-command.ts` or the relevant
-  `.description()` in `cli/src/index.ts`, then rebuild/regenerate.
-- **Do not race the train with it.** That fix touches code + built artifacts, so it runs the **full** gate,
-  and it would add a **code commit to the very diff Step 1 is about to cut**. This docs pass is freshness, not
-  a scope hatch. So **default to deferring it**: land the source fix on `development` as an ordinary
-  CI-gated PR **after** the release, note the deferral in the release report, and let it ship next cycle.
-  The drift is cosmetic and already shipped; one more cycle costs nothing.
-- Only the **human release owner** may pull a generated-surface fix into the current release, and only by
-  saying so explicitly. An agent never makes that call on its own drift judgment, and never `--auto`-merges
-  a code-bearing PR at the probe.
-
-**Bounded, never a hang (fast path):** wait for that docs-only auto-merge up to a short bound (~5 min). If
-CI is contended and it has not merged in time, **do not block the train** — proceed with the release as-is.
-Leave the auto-merge armed: the doc fix is not lost, it just lands whenever CI clears. Docs freshness
-improves the release; it never holds it hostage.
-
-Then **Step 1** cuts `development → main` from the current HEAD. Because an armed auto-merge can still land
-between the bound and the cut, **re-check the PR's state right before Step 1** and report what actually
-shipped — never predict it from the bound.
+## Step 0d — no docs-keeping on the release train (Hub#4164)
+
+Scheduled docs-janitor / wiki-keeper / living-docs freshness passes are **retired** (#4117/#4119).
+The release train does **not** open docs-only PRs, wait on README/architecture auto-merges, or
+treat prose refresh as a gate.
+
+Current state is compute-at-read + the estate repo-index (`mmi-cli repo-index search`,
+`mmi-cli org project`, board/schedules verbs). Durable WHY stays in `docs/decisions/`.
+If shipping code made a hand-written surface wrong, fix it on `development` as an ordinary PR
+**outside** the train — never as a release Step.
 
 ## Step 1 — merge to main (never force)
 
@@ -450,16 +405,11 @@ correct). Read the model from the registry (`mmi-cli org project get {owner}/{re
 
 Name the sanctioned dispatch mechanism you used in the train report.
 
-## Step 4b — re-sync project info (in-repo docs handled in Step 0d)
+## Step 4b — re-sync project info (no in-repo docs pass)
 
-The two in-repo docs were already scanned against the shipping diff and, if they drifted, refreshed +
-merged in **Step 0d** (fast docs-only path for hand-written prose; generated regions are fixed at
-their source and deferred to the next cycle) — so the released commit already carries
-current `README.md` / `architecture.md` (and, in the hub, `docs/org-readme.md` /
-`docs/org-architecture.md`). The `distribution` gate also blocks empty/retired-term descriptions at PR
-time. Nothing to author here. `mmi-cli release --apply` now re-syncs the **Project** short description +
-thin README from those docs and the registry's current member repos through the command ladder. For a
-manual repair or preview use:
+In-repo README/architecture freshness is **not** a train step (Step 0d retired, Hub#4164).
+`mmi-cli release --apply` re-syncs the GitHub **Project** short description + thin README from the
+released commit and the registry member list through the command ladder. For a manual repair or preview use:
 ```bash
 mmi-cli org project sync-info --apply   # omit --apply for the read-only plan
 ```

package/skills/resume/SKILL.md

@@ -54,6 +54,20 @@ For the full board partition (yours / claimable / taken) run `/mmi`.
 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 org schedules` / `--json` |
+| Boxes / IPs | `mmi-cli runtime box list` |
+| Registry / projects | `mmi-cli org project list\|get` |
+| Board | `mmi-cli board read` / `mmi-cli next` |
+| Docs index freshness | `mmi-cli docs index --check` |
+| Path / symbol / meaning pointers | `mmi-cli repo-index search <q>` (Hub cloud; `--semantic` optional) |
+
 ## Notes
 
 - `/resume` is read-only session orientation. It never claims, moves, or writes.

package/skills/worktree/SKILL.md

@@ -60,6 +60,13 @@ worktree, deletes the merged branch (local + origin), and prunes tracking refs.
 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.
 
+**Cwd-safe land (#4140):** `worktree land --apply` (what `pr land` runs) is designed to be invoked from
+inside the worktree you are landing. Before removal it releases the process cwd to the primary checkout
+(#1444/#2747) — on Windows, leaving cwd inside the target tree makes `rmdir` fail with `EBUSY` and leaks
+branch refs. You do not need to `cd` out first; if removal still fails (IDE lock, antivirus), the deferred
+sweep retries from a safe cwd. Prefer the primary checkout cwd only when you are running `worktree land`
+manually outside `pr land`.
+
 ## Step 5 — record + next
 
 Record durable decisions on the issue or PR, then check the board again: