@mutmutco/kilo-plugin 4.1.3 → 4.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/kilo-plugin",
-  "version": "4.1.3",
+  "version": "4.1.4",
   "mmiCompat": "4.x",
   "description": "MMI workflow skills and org gates delivery.",
   "author": {

package/scripts/hook-run.mjs

@@ -65,6 +65,14 @@ export function parseHookArgv(argv) {
   return parsed;
 }
 
+/** When PowerShell `--%` turns Cursor's POSIX `< payload` into argv instead of a redirect (#5580). */
+export function stdinRedirectPath(argv) {
+  const at = argv.indexOf('<');
+  if (at === -1 || at + 1 >= argv.length) return '';
+  const path = argv[at + 1];
+  return path && !path.startsWith('-') ? path : '';
+}
+
 export function pluginRoot(surfaceToken, env = process.env, here = HERE) {
   const surface = hookSurface(surfaceToken);
   for (const name of surface.rootEnv) {
@@ -384,19 +392,29 @@ function stripUtf8Bom(input) {
   return buffer[0] === 0xef && buffer[1] === 0xbb && buffer[2] === 0xbf ? buffer.subarray(3) : buffer;
 }
 
-function readStdin() {
+function readStdin(argv = process.argv.slice(2)) {
   try {
-    return readFileSync(0);
+    const piped = readFileSync(0);
+    if (piped.length) return piped;
   } catch {
-    return Buffer.alloc(0);
+    // fall through to a `--%`-preserved payload path
+  }
+  const redirect = stdinRedirectPath(argv);
+  if (redirect && existsSync(redirect)) {
+    try {
+      return readFileSync(redirect);
+    } catch {
+      return Buffer.alloc(0);
+    }
   }
+  return Buffer.alloc(0);
 }
 
 export async function main(argv = process.argv.slice(2)) {
   const { surface, gate } = parseHookArgv(argv);
   let result;
   try {
-    result = await runPolicyGate({ surface, gate, input: readStdin() });
+    result = await runPolicyGate({ surface, gate, input: readStdin(argv) });
   } catch (error) {
     process.stderr.write(`[mmi-hook] ${error.message}\n`);
     process.exit(1);

package/scripts/throttle-core.mjs

@@ -225,6 +225,14 @@ export function analyzeShellDialect(command, shellFamily, platform = process.pla
           + '`>/dev/null` for stdout suppression, or Bash variables instead.',
       );
     }
+    // #5561: Windows device name NUL as a relative redirect creates ./NUL under Git Bash / MSYS.
+    if (/(?:^|[\s;&|])(?:\d*>+|>>)\s*NUL\b/i.test(bashCmd)) {
+      return dialectReason(
+        'shell_dialect_nul_redirect_in_bash',
+        'Redirecting to relative `NUL` creates a `./NUL` file under Git Bash / MSYS. '
+          + 'Use `>/dev/null` (or `2>/dev/null`) instead.',
+      );
+    }
     if (/\bSelect-Object\b/i.test(bashCmd)) {
       return dialectReason(
         'shell_dialect_select_object_in_bash',

package/skills/bootstrap/SKILL.md

@@ -531,9 +531,13 @@ variant; the runtime reads only the canonical names and declare-first rejects th
 Local `/stage` is optional product-owned configuration. A repo that wants `/stage` may carry a local
 `stage` block, but that file must not contain board, deploy, or secret registry facts.
 
-**Stage port block:** run `mmi-cli stage port-range <Repo>` to assign (idempotently) the repo's local port block
-from the central registry. Use `$STAGE_PORT` in `stage.up` / `healthUrl`; `/stage` then picks a free port
-inside the block so a dev can run several projects/versions locally without collisions.
+**Stage port block (required for central-container):** run `mmi-cli stage port-range <Repo>` to assign
+(idempotently) the repo's local port block from the central registry. `tenant-container` and
+`solo-container` **must** have Hub registry `portRange` — `mmi-cli devops bootstrap verify` fails without
+it (#5539), and `mmi-cli stage` cannot derive a local preview until the block exists. `bootstrap apply
+--execute` assigns the block automatically after DDB register for those models; for older META holes,
+run `stage port-range` explicitly. Use `$STAGE_PORT` in `stage.up` / `healthUrl`; `/stage` then picks a
+free port inside the block so a dev can run several projects/versions locally without collisions.
 
 ## Step 7 — seed the org-managed .gitignore block
 

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

@@ -22,11 +22,11 @@ name: gate
 #   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_WINDOWS_COMPAT  — `true` opts the repo into the informational windows-latest compat job
-#                        (#5113: registry gate={"windowsCompat":true} or --var). Default OFF: Windows
-#                        minutes cost more than Linux and the required gate stays the Linux lane.
 # GATE_BUDGET_SHA is rendered by the CLI from its blessed run-with-budget pin — not an operator knob.
-# GATE_WINDOWS_COMPAT_JOB_YAML is rendered by the CLI from the final layered vars — not an operator knob.
+# Estate policy 2026-08-23: GitHub-hosted Windows (`windows-latest` / windows-*) is forbidden org-wide.
+# Do not add a windows-compat (or any other) job that runs-on GH-hosted Windows. Linux self-hosted
+# (mmi-live / mmi-heavy) is the only CI merge gate. Rare Windows proof stays on the owner's machine or
+# a future self-hosted Windows runner — never windows-latest.
 # (seed touch: keep kilo mirror + BOM digests in lockstep after classifier land.)
 on:
   pull_request:
@@ -118,4 +118,3 @@ jobs:
           command: {{GATE_CMD}}
           max-seconds: {{GATE_MAX_SECONDS}}
           working-directory: {{GATE_WORKDIR}}
-{{GATE_WINDOWS_COMPAT_JOB_YAML}}

package/skills/browser-automation/SKILL.md

@@ -1,43 +1,54 @@
 ---
 name: browser-automation
-description: Use DOM-first Playwright MCP for browser work.
+description: Route browser work by host — JervCode lanes or Claude Code Playwright MCP.
 ---
 
 **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
+# Browser automation — host lanes
+
+Org browser skill. **Choose the host lane first.** JervCode and Kimi use the native three-lane browser contract; Claude Code uses DOM-first Playwright MCP. Do not install or select Playwright MCP on JervCode.
+
+## Host routing (non-negotiable)
+
+| Host | Path |
+|------|------|
+| **JervCode / Kimi** | Three lanes below — never Playwright MCP |
+| **Claude Code** | DOM-first Playwright MCP (Claude-only section) |
+| Local app stack | **`/stage`** — see `skills/stage/SKILL.md` |
+
+### JervCode / Kimi — three lanes
+
+Authoritative for native JervCode browser work (Jerv-JervCode `product/runbooks/browser.md`, #1694). Pick by need:
+
+| Need | Tool |
+|------|------|
+| Plain read (no interaction) | `fetch_content` |
+| Public interaction (clicks/types on public pages) | `agent_browser` |
+| Authenticated interaction | `trusted_browser` |
+
+**Do not** install or select Playwright MCP for JervCode. Public interaction goes to `agent_browser`, not Playwright.
+
+### Claude Code — 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)
+#### Doctrine (non-negotiable on Claude Code)
 
 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.
+**Never** pass `--caps=vision` (or equivalent vision-first defaults) on Playwright MCP. 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
+#### MCP configuration (Claude Code, no vision)
 
 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
+#### Playwright availability
 
 Check the configured/global CLI before adding a temporary local dependency. On Windows PowerShell:
 
@@ -50,7 +61,7 @@ playwright --version
 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)
+#### Agent workflow (MCP) (Claude Code)
 
 1. **Goal** — what observable outcome proves success?
 2. **Navigate** — open the target URL (often from `/stage` JSON: `mmi-cli stage --json`).
@@ -65,24 +76,40 @@ Core MCP loop:
 browser_navigate → browser_snapshot → browser_click / browser_type → browser_snapshot
 ```
 
-## Artifacts and hygiene
+#### Artifacts and hygiene (Claude Code)
 
 - **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/`).
 
+## 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 on **Claude Code** | **Playwright MCP** (Claude-only section) — DOM-first, artifacts under `tmp/` |
+| Interactive UI on **JervCode / Kimi** (public) | **`agent_browser`** |
+| Interactive UI on **JervCode / Kimi** (authenticated) | **`trusted_browser`** |
+| Plain page/content read on **JervCode / Kimi** | **`fetch_content`** |
+| Durable hosted automation outside dev machines | **Stagehand + Browserbase** (production path) — explicit choice, not the default for every local task |
+
+`/stage` and the host browser path **complement** each other. `/stage` spins the app; the host lane drives the browser against a URL (often the stage URL).
+
 ## Anti-patterns (org-wide avoid)
 
-- `--caps=vision` or screenshot-first wrappers for routine tasks
+- Installing or selecting Playwright MCP on JervCode (use `fetch_content` / `agent_browser` / `trusted_browser`)
+- `--caps=vision` or screenshot-first wrappers for routine Claude Code 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)
+- Replacing `/stage` with ad-hoc MCP servers for branch smoke (use `/stage` for the stack, the host lane 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
+- JervCode browser contract — Jerv-JervCode `product/runbooks/browser.md` (#1694)
 
 ## Retro — one check before you finish
 

package/skills/epic/SKILL.md

@@ -78,7 +78,10 @@ When creating through `mmi-cli vault secrets use GH_TOKEN -- …`, the `GH_TOKEN
 disrupt Hub session discovery and print `board attach skipped — no Hub session token` for batch rows. That
 warning can appear when placement is correct, but it is not harmless or proof of placement: final verification
 must prove every intended child is linked and on the board as Todo with `mmi-cli oracle issue children
-<owner/repo#N> --json`.
+<owner/repo#N> --json`. `boardStatus: null` is **inconclusive** (the children walk can miss org-board
+Status that `board show` still sees) — it is not proof the child is off the board. A non-null Status
+(Todo / In Progress / …) is the placement proof; if Status stays null after this command, investigate
+with `board show` rather than treating null as "not on board".
 
 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
@@ -91,7 +94,8 @@ wait for writes to quiesce, inspect the children, then retry the missing rows wi
 mmi-cli oracle issue children <owner/repo#N> --json # each child: number/title/state/repo/assignee/boardStatus/linkedPrs
 ```
 
-This JSON is the final placement authority: verify every intended child is linked and on the board as Todo.
+This JSON is the final placement authority: verify every intended child is linked and on the board as Todo
+(`boardStatus` names Todo). `boardStatus: null` is inconclusive, not "not on board".
 If it does not prove that placement, investigate and correct the misfire. To link a child that already existed (not
 part of the batch), use the inverse-friendly single link:
 

package/skills/hotfix/SKILL.md

@@ -53,7 +53,14 @@ 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
+Stop on a red authority or CLI-version result. **Hub hotfix release runs the same distribution fold as
+`/release`:** if `process.cwd()` contains whitespace, stop before `hotfix start` / `hotfix release`
+touches local `main` (#5603). Relocate the clone to a real no-space path. A subst / junction /
+drive-letter alias that hides spaces is not a valid workaround — canonical-root containment still
+sees the physical path, so materialization inputs resolve outside the alias root. See `/release`
+Step 0e.
+
+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

package/skills/mmi/SKILL.md

@@ -16,6 +16,21 @@ universal literal command.
 Status values: `Todo · In Progress · In Review · Done` (GitHub enforces who can move what — don't re-explain
 it on every move). Closed/finished items auto-archive after they go quiet; archived ones aren't on the board.
 
+## Hard invariants (#5552 — load before any write)
+
+Two rules sit above every later step. Read them before claiming, filing, or guessing a CLI route:
+
+1. **Claims are board mutations.** The only valid claim write is
+   `mmi-cli oracle board claim <ref>` (optional `--json` / `--for` / `--check`). Never infer or guess an
+   `oracle issue claim` route — that path does not exist under `oracle issue` (create/view/edit/… only).
+   If the exact write route was not already grounded in this skill or a live
+   `mmi-cli commands` / `mmi-cli explain` result, read one of those before invoking it. Do not retry a
+   guessed `issue …` spelling after a refusal; take the suggested `oracle board claim` form.
+2. **`learning`-tagged reports are cloud-agent work.** After `mmi-cli learning report` (or
+   `learning skill-lesson`), file and forget: return to the current task immediately. Never claim, poll,
+   wait on, force-take, or duplicate implementation of the filed learning issue. Consume eventual
+   propagation separately when it lands; do not own that fix in this session.
+
 ## Step 0 — identity, greet, eager preflight when stale
 
 `/mmi` is the dev's hello-to-work — the most common command they run. Three pacing rules before anything else:
@@ -293,7 +308,7 @@ something else* paths.)
 - **Claim:** when the dev takes an item, assign them + set `In Progress` in one go. This is the only status
   write `/mmi` makes, and only as the mechanical side of claiming — never as a standalone "move" the dev
   is offered. Every later transition (In Review on PR open, Done on merge) flows automatically from the
-  work, not from here.
+  work, not from here. **Route (hard):** `oracle board claim` only — never `oracle issue claim` (#5552).
   ```bash
   mmi-cli oracle board claim <owner/repo#N> --json
   ```
@@ -348,6 +363,10 @@ something else* paths.)
   Hub App's own token (#263), so no MMI-Hub repo access is required to file. Never read Hub coordinates or
   keys from a repo-local `.env`, call a repo-local report script, or POST the Hub API directly — the CLI
   carries the endpoint and your Hub session intrinsically.
+  **Learning fire-and-forget (#5552):** the filed issue carries the `learning` label and is owned by
+  cloud agents. After a successful file (or dedup +1), print the `{number,url}` receipt if useful, then
+  **return to the current task** — do not `board claim` it, poll it, wait on a PR, force-take it, or open
+  a second implementation issue for the same friction.
 - Surface any `gh`/`mmi-cli` error verbatim.
 
 ## Step 6 — Leverage (offer where it fits)
@@ -512,3 +531,5 @@ claimable, or a claim that moved the wrong item.) If yes, file **one** lesson an
 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 mmi --title "<what misfired>" --body "<what; evidence; proposed amendment>"`
+The lesson is `learning`-tagged cloud-agent work (#5552): file it, then finish your current report —
+do not claim, poll, or implement that lesson in this session.

package/skills/release/SKILL.md

@@ -108,6 +108,9 @@ 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.
+
+**Hub `/release` also refuses a checkout path that contains spaces — prove that in Step 0e before touching local `main`.** A subst/junction/alias that hides the spaces is not a workaround.
+
 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):
@@ -232,6 +235,12 @@ HTTP 5xx, timeout, DNS, socket, or other transport failure is **unverified**, no
 missing: retry the read/preflight and repair connectivity if it persists. Never provision or rename a
 secret from a transport-error response.
 
+**GitHub Actions billing/spending (#5604).** Those checks do not prove a *hosted* Actions job can start.
+The train dispatches `actions-job-start-canary.yml` on MMI-Hub (Linux hosted, not `windows-latest`) and
+refuses to mint a tag if the canary job never starts (empty steps / billing refusal). If a tag is already
+on origin, do **not** recut: `mmi-cli devops release --retry-publish <run-id> --apply` retries that exact
+run.
+
 ## Step 0c — hotfix-coverage guard (fail closed, #839, #958)
 
 Full-track repos only. Direct-track repos skip this specific guard — not because they are exposed to no
@@ -278,6 +287,33 @@ Current state is compute-at-read + the estate repo-index (`mmi-cli oracle repo-i
 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 0e — Hub checkout path must not contain spaces (#5603)
+
+**Hub `/release` only. Do this before Step 1 — before any `git checkout main`, merge, or `--apply`.**
+The Hub fold runs `scripts/check-hook-contract.mjs`. That verifier's Cursor probe still executes the
+adapter command through `shell: true`. An unquoted launcher path is then split at the first space
+(`E:\AI Projects\Mutatis Mutandis\MMI-Hub` → `E:\AI`), so the fold never gets a coherent argv. Stop
+when the checkout path contains whitespace; do not discover this after local `main` has already moved.
+
+Prove it from the release checkout:
+
+```bash
+node -e "const p = process.cwd(); if (/\s/.test(p)) { console.error('Hub /release: checkout path contains spaces:\\n' + p + '\\nStop. Clone or move MMI-Hub to a path with no spaces. subst/junction/alias is not a workaround.'); process.exit(1); }"
+```
+
+Non-zero → **stop**. Relocate the clone to a real path without spaces (for example `C:\src\MMI-Hub` or
+`/opt/mmi/MMI-Hub`) and re-run `/release` from that checkout. Do not reset, merge, or fold on the
+spaced tree.
+
+**A subst / junction / directory-junction / drive-letter alias that hides spaces is not a valid
+workaround.** Mapping `E:\AI Projects\Mutatis Mutandis\MMI-Hub` onto `M:\` only hides spaces in the
+*logical* cwd. Canonical-root containment still sees the physical path: the fold's materialization
+inputs resolve through that physical location, which then sits outside the alias root and fails
+containment. Clone or move the repository; do not alias around the spaces.
+
+This constraint is Hub-fold specific (the hook-contract verifier). Product-repo `/release` does not
+run that script; still prefer a no-space checkout.
+
 ## Step 1 — merge to main (never force)
 
 Full-track repos:
@@ -324,9 +360,10 @@ What the fold bumps, by repo:
 - **Hub (`hub-serverless`):** the full locked distribution set via `scripts/release-distribution.mjs
   prepare` — spine dogfood (`scripts/spine-dogfood.mjs`: verify docs/surfaces + the managed `.gitignore` block),
   every registry-declared version holder, adapter payload synchronization, build output, and the public
-  artifact bill of materials — then verifies the set (`verify --skip-npm-view`). Publication and staging
-  both derive from `surfaces.json`; there is no second package list. Claude, Codex, Kimi, Cursor, and
-  Kilo are active.
+  artifact bill of materials — then verifies the set (`verify --skip-npm-view`). That prepare path runs
+  `scripts/check-hook-contract.mjs`; Step 0e must already have passed, or the Cursor probe splits on a
+  spaced checkout. Publication and staging both derive from `surfaces.json`; there is no second package
+  list. Claude, Codex, Kimi, Cursor, and Kilo are active.
 - **App-style repos with a root `package.json`** (most products): the manifest + lockfile version via
   `npm version --no-git-tag-version`, kept in lockstep with the release tag.
 - **Repos with neither:** nothing to fold — the tag is the version.

package/skills/repo-index-audit/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: repo-index-audit
+description: Audit repository indexing with live probes, receipts, and lexical/semantic/hybrid round-trips.
+---
+
+# MMI repository-index estate audit
+
+Canonical counterpart to `jerv-memory-audit`. Each run verifies every layer live and proves every result with a receipt.
+
+**Vision:** MMI repository orientation works across the whole registered estate without anyone managing indexes by hand.
+
+**Mission:** End-to-end reliability audit **with remediation**. Verify every layer live, fix every approved in-scope defect, and prove each fix before closing it.
+
+## Start here
+
+1. Read shipped help before using a verb: `mmi-cli --help`, `mmi-cli explain oracle repo-index --json`, and `mmi-cli explain oracle find --json`.
+2. Read `docs/Guides/repo-index-runbook.md` and `docs/Architecture/compute-at-read.md` from the current MMI-Hub checkout.
+3. Create a dated receipt file in task-local ignored scratch. Record command, UTC time, exit code, and the bounded JSON fields that prove each verdict. Never record query text, source bodies, credentials, hostnames, vectors, or secrets.
+4. Treat `mmi-cli oracle repo-index status --cloud --json`, live health, and each result's retrieval metadata as runtime authority. Do not carry a recalled migration state into a new audit.
+
+## Layers — each needs a live probe this session, not a code read
+
+1. **Cloud backend health; full estate integrity** — run `mmi-cli oracle repo-index status --cloud --json`, `mmi-cli oracle repo-index health --live --json`, and `mmi-cli doctor --json`. PASS requires: endpoint reachable; registry roster present; active and ready authorities equal the roster; `nOfN` true; lexical, semantic, and hybrid readiness ready; citation validity and embedding coverage complete; no unaccounted integrity failure. Record the active provenance token and material layout reported now, never a hard-coded expected migration state.
+2. **`mmi-cli` command surface vs shipped help** — compare `mmi-cli commands --json` and `mmi-cli commands --all --json` with `mmi-cli oracle repo-index --help` and `mmi-cli explain` for `rebuild`, `publish`, `search`, `status`, `graph`, `health`, `gc`, `sync-estate`, and `oracle find`. Exercise `status`, `health`, `search`, and `find` as documented. PASS requires manifest, help, examples, and behavior to agree; agents can discover every supported verb and flag.
+3. **Guidance on every shipped surface** — verify the canonical `skills/onboard/SKILL.md`, `skills/mmi-resume/SKILL.md`, README, compute-at-read guide, and materialized plugin payloads carry the current rule: `oracle find` is semantic orientation, `oracle repo-index search` is hybrid orientation, cloud is default, `--local` is explicit checkout-only, and every hit is verified against repository, indexed commit, path, symbol, and lines. PASS requires `node scripts/check-skill-payload.mjs` to succeed.
+4. **Automated ingestion and fail-loud alarms** — run `mmi-cli harbour org schedules --json` and `gh run list --repo mutmutco/MMI-Hub --workflow repo-index-reconcile.yml --limit 20 --json databaseId,status,conclusion,createdAt,headSha`. Inspect the installed/current workflow for default-branch push dispatch plus Harbour reconcile dispatch. PASS requires: current successful push and scheduled receipts; the exact pushed commit is checked out; drift reconciliation is delta-first; failures emit a structured alarm and deduplicated board filing; no failure dies silently.
+5. **Build → lexical-search round-trip** — in an isolated clean checkout of one registered authority, choose a fresh unique marker already present at its current default-branch commit. Run `mmi-cli oracle repo-index rebuild --json`, then `mmi-cli oracle repo-index search "<marker>" --local --lexical --json`. Local `RepoIndexHit` owns only `repo`, `path`, `kind`, `why`, `score`, and optional `symbol` — it has no commit or line fields. PASS requires those local fields intact for the expected repository and path (and symbol when the hit is kind `symbol`), then verify commit and path directly against the isolated checkout (`git rev-parse HEAD` and that the cited path exists there). Then run `mmi-cli oracle repo-index search "<marker>" --cloud --lexical --json` for a unique marker at an active authority's reported commit; PASS requires the cloud commit-pinned citation (repository, commit, path, symbol, and lines). Never publish a canary commit without the execution handshake below.
+6. **Indexed material → semantic/hybrid round-trip** — choose a concept whose wording differs from the target symbol in an active authority. Run `mmi-cli oracle find "<concept>" --json`, `mmi-cli oracle repo-index search "<concept>" --cloud --semantic --json`, and default hybrid search with `mmi-cli oracle repo-index search "<concept>" --cloud --json`. PASS requires: semantic retrieval is used rather than silently claimed; hybrid reports its lexical and semantic retrieval/fallback metadata; citations resolve at the reported indexed commit; semantic and hybrid return a relevant cited target. A lexical fallback is evidence of degradation, not a semantic PASS.
+7. **Structural extraction and embeddings** — run the cloud status and live-health probes from layer 1 plus the semantic query from layer 6. Compare their current authority/retrieval metadata with the checked-in v4 schema, path policy, grammar lock, and embedder model lock. PASS requires: pinned grammar/model provenance; expected dimensions; normalized embedding coverage; typed degradation when query embedding is unavailable; successful live semantic inference; the designated local/self-hosted BGE lane; no metered LLM key or developer-laptop model path. Never print environment values; record presence/absence and provider metadata only.
+8. **Delta, layout, rollback, and reconciliation** — run `mmi-cli oracle repo-index sync-estate --plan --json`. PASS requires: no unexpected authority drift; current layout/provenance is explicit; unchanged authorities plan no rebuild; changed authorities are delta candidates where compatible; active pointers remain valid; rollback material is retained; no retired serving fallback is implied. After any separately approved rebuild or migration, require **successful snapshot verification**, not a second reconcile that is a no-op: the run completed against its chosen commits, published safely, left all authorities ready (N-of-N lexical, semantic, hybrid, and rollback verification), and recorded any later tip commits as normal next-cycle freshness work. Never FAIL or rerun solely to chase a globally motionless estate — product commits that land during or after the run are expected freshness, not failed reconciliation. Unchanged-authority rebuild idempotency is a separate defect track; do not conflate it with this gate.
+9. **Telemetry and schedules** — verify status query-usage rollups, readiness/shadow receipts, failure alarms, and `mmi-cli harbour org schedules --json`. PASS requires: query telemetry stores only allowlisted coarse caller/source labels; readiness stores hashes rather than query text; the reconcile schedule is present, enabled, recently firing, idempotent, and has no silent death. Zero ordinary query count is valid data but must be reported as zero adoption evidence, never as proof that search is exercised.
+
+## Round-trip rules
+
+- Use a different marker/query pair for lexical and semantic/hybrid probes.
+- Record retrieval mode, fallback/degraded reason, and every field the hit surface actually returns. Local hits: `repo`, `path`, `kind`, `why`, `score`, optional `symbol`, then confirm commit and path against the isolated checkout. Cloud hits: repository, indexed commit, path, symbol, and lines.
+- For cloud citations, verify cited files against the exact indexed commit, not a moving checkout HEAD. For local citations, verify path against the isolated checkout whose HEAD you just rebuilt.
+- Local rebuilds stay in disposable task scratch. Remove them after receipts are captured.
+- A cloud publish, full rebuild, migration, rollback activation, schedule dispatch, or production change is an external mutation. Stop and ask for explicit approval naming the repositories and effect before running it.
+
+## Rules
+
+- **Evidence-first** — nothing is healthy without a current receipt.
+- **Runtime-first** — live status and retrieval metadata outrank memory and static docs for current state.
+- Every defect gets a named cause, severity, and either an approved in-scope fix or a board filing on MMI-Hub.
+- Never weaken a test or accept lexical fallback as semantic success.
+- Use bounded receipts. Keep full raw output in task-local ignored scratch, not the report.
+
+## Done when
+
+- Every layer has PASS-with-receipt or a filed issue.
+- Both round-trips (build→lexical search and indexed material→semantic/hybrid search) are verified end to end.
+- Push ingestion and the scheduled reconcile each have current firing evidence.
+- Post-rebuild or migration layers close on successful snapshot verification (chosen-commit completion, safe publish, authorities ready), not on a motionless-estate / no-op second reconcile.
+- The dated estate summary records N/N layers, roster N-of-N, active provenance/layout, lexical/semantic/hybrid verdicts, adoption count, schedule state, defects, fixes, issue links, and receipt paths — including any post-snapshot tip commits noted as next-cycle freshness.
+- Save the durable summary in the owning MMI-Hub issue or audit artifact. Save only the settled cross-session lesson or handoff to JervCoding; never copy raw query or index material into memory.
+
+## Out of scope
+
+New index features; production mutation without approval; fresh secrets; storing source bodies, query text, vectors, credentials, or secret values in receipts.
+
+## House rules
+
+- Audit read-only by default. Inspection, local disposable rebuilds, and reporting are allowed; any cloud write or external dispatch needs a fresh execution handshake.
+- Repository fixes and board filings follow the standard issue, branch, worktree, PR, and `development` landing flow.
+
+## Retro — one check before you finish
+
+Before the final report, ask whether this skill's instructions misfired through ambiguous wording, a misleading message, or a missing environment warning. Process only, never the user's code or task. If yes, file one lesson and move on; a clean run is silent. The retro is advisory, so note a filing failure and continue:
+`mmi-cli learning skill-lesson --skill repo-index-audit --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/stage/SKILL.md

@@ -51,7 +51,10 @@ 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.
+When the gap is a missing Hub registry `portRange`, the JSON receipt also carries `recovery` with
+`mmi-cli stage port-range <owner/repo>` (#5539) — assign the block, then re-run `/stage`. That gap does not
+mean the repo's Hub registry/org project setup is missing; it means local stage derivation cannot pick a
+collision-safe port until META.portRange exists.
 
 ## Step 1 — run the stage