@mutmutco/hermes-plugin 3.139.1

package/skills/mmi-resume/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: mmi-resume
+description: Open a session — self-check, repo status, and the next actionable board item in one pass.
+---
+
+**Host-native invocation:** Claude `/mmi:mmi-resume` · Codex `$mmi:mmi-resume` · jervcode/Kimi `/skill:mmi-resume` · Kilo `skill` tool. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
+
+# /mmi-resume — start of session
+
+One flow to re-anchor at the top of a session: is the toolchain sound, what does this repo/worktree look
+like right now, and what is the single next thing worth doing. Read-only — it renders the picture and gets
+out of the way. `/mmi` is the board-only hello-to-work; `/mmi-resume` is the wider session open that folds in
+the toolchain self-check and the current-branch snapshot.
+
+## Step 0 — toolchain self-check
+
+```bash
+mmi-cli doctor --self
+```
+
+`doctor --self` verifies the two things that silently break a session: CLI/plugin version parity against
+the published version, and whether the active `gh` token can resolve this repo. It is fast, but it reads
+npm and GitHub — it is not offline-safe, and it checks neither PATH nor hook wiring (#3485). On a **hard**
+gap it points at the heal path — relay it and run it before working:
+
+```bash
+mmi-cli plugin heal      # only on a hard version/plugin gap; then restart Claude Code / reopen the workspace
+```
+
+A clean self-check is silent-enough — move straight on. Do not block the snapshot on a soft/advisory note.
+
+## Step 1 — repo snapshot
+
+```bash
+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`. 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 oracle next --repo <repo reported by status>
+```
+
+Never the retired flat `mmi-cli next` — Wave 3 (#4316) removed that alias; a `flat 'next' alias was
+removed` exit means follow the printed `oracle next` path (and `mmi-cli plugin heal` when
+`doctor --self` says the plugin is behind). 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 oracle 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`.
+
+## Step 3 — render, then stop
+
+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 harbour org schedules` / `--json` |
+| Boxes / IPs | `mmi-cli devops runtime box list` |
+| Registry / projects | `mmi-cli oracle org project list\|get` |
+| Board | `mmi-cli oracle board read` / `mmi-cli oracle next` |
+| Docs index freshness | `mmi-cli oracle docs index --check` |
+| Path / symbol / meaning pointers | `mmi-cli oracle repo-index search <q>` (Hub cloud; `--semantic` optional) |
+
+## Notes
+
+- `/mmi-resume` is read-only session orientation. It never claims, moves, or writes.
+- Board status moves are automatic (claim, PR open, merge). Never suggest a manual status move.
+- Slower, board-partition view → `/mmi`. Readiness-gate view for a new repo/first session → `/onboard`.
+
+## 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 self-check that reported a false gap, or a
+snapshot that named the wrong 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 learning skill-lesson --skill mmi-resume --title "<what misfired>" --body "<what; evidence; proposed amendment>"`
+(never the retired flat `mmi-cli skill-lesson`).

package/skills/onboard/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: onboard
+description: Guided first session — readiness check, repo status, and the first command to run.
+---
+
+**Host-native invocation:** Claude `/mmi:onboard` · Codex `$mmi:onboard` · jervcode/Kimi `/skill:onboard` · Kilo `skill` tool. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
+
+# /onboard — guided first session
+
+For a developer's first session in a repo (or a fresh checkout): confirm the repo is wired into the org,
+show what state it's in, and hand over the one concrete next command. Read-only — it diagnoses and points,
+it does not change anything.
+
+## Step 0 — readiness gate
+
+```bash
+mmi-cli onboard
+```
+
+`onboard` reports the five things a machine needs to be workable and the exact next command to fix the
+first gap:
+
+- **Track** — the repo's branch + origin (is this an org checkout at all).
+- **Board** — is the Project board reachable, and how many items are on it.
+- **Registry** — is the repo registered in the Hub (`PROJECT#<slug>` META).
+- **Secrets** — is a GitHub token available for the vault path.
+- **MMI Hub** — does `mmi-hub status` find the installed CLI and every present host surface at the
+  gated fleet version, with hourly automatic updates healthy.
+
+The **Plugin** row is per machine, not per repo. The Hub's thin Claude/Codex catalogs pin exact npm
+packages; Git no longer transports plugin content, and background marketplace auto-update stays **off**
+so it cannot race Hub maintenance. `mmi-hub` gates a release tag+BOM, converges each present host,
+and records last-run evidence. A red row names `mmi-hub install`, `mmi-hub update`, or
+`mmi-hub autoupdate on`; no marketplace ref or hand-edited auto-update ceremony remains.
+
+A `✗` on any line comes with a `Next command:` — run **that** first. Common ones:
+
+- Hub maintenance missing or stale → `npm install -g @mutmutco/hub` then `mmi-hub install`.
+- Hub API URL not configured → `mmi-cli doctor` (safe tooling wiring only; no repository cleanup).
+- Repo not registered → a master-admin runs `/bootstrap` (or `mmi-cli oracle org project set <owner/repo>`).
+- GitHub auth missing → the dev runs `gh auth login --hostname github.com --git-protocol https --web --scopes "project"`.
+
+## Step 1 — the picture
+
+Once the gates are green:
+
+```bash
+mmi-cli status        # branch, worktrees, your PRs, your claimed items, stage
+mmi-cli oracle next          # the first claimable item + its claim command
+```
+
+## Step 2 — hand over the first move
+
+Close with one grounding line: gates green (or the one gate to fix), and the single first command —
+usually `mmi-cli oracle 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 oracle repo-index search <path-or-symbol-or-meaning>   # Hub cloud pointers (default)
+mmi-cli oracle repo-index search "where …" --semantic          # Titan meaning over embeddings
+mmi-cli oracle 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, `/mmi-resume` is the
+  faster daily open and `/mmi` is the board.
+- Everything here is read-only. The heavier setup (`/bootstrap`) is master-admin only.
+
+## 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 readiness gate that reported green while a
+board read actually failed, or a next command that pointed at the wrong fix.) 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 onboard --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/rcand/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: rcand
+description: Promote development to a release-candidate branch.
+---
+
+**Host-native invocation:** Claude `/mmi:rcand` · Codex `$mmi:rcand` · jervcode/Kimi `/skill:rcand` · Kilo `skill` tool. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
+
+# /rcand — promote development to release-candidate
+
+Merge `development → rc`, tag `vX.Y.0-rc.N`, push (the GitHub authority gate), then dispatch the rc deploy
+path. **Train-authority gated (D14):** the repo's project-admin or the master. Direct-track repos
+(product repos with `releaseTrack: direct`, plus MMI-Hub via the `isHubControlRepo` special-case) are the exception: they skip rc and `/rcand` refuses there;
+run `/release` from `development` instead. The board needs no touch
+here — items reach `Done` when their PR merges to `development` (native close → Done); `rc` is a deploy
+stage, not a lane.
+
+Authority is **structural + server-checked**: step 0 asks the Hub (`mmi-cli oracle org access role`), and step 4
+pushes to the protected `rc` branch, whose per-repo allowlist carries the same people (master + that repo's
+project-admins). No `.env` role marker. Gate ordering: the tag lands the rc SHA
+for checks, and every deploy side-effect waits until the protected `rc` push accepts that checked SHA.
+
+## Step 0 — train-authority probe (server-side, D14)
+
+```bash
+mmi-cli oracle org access role {owner}/{repo} --json   # Hub-verified: { role, train }
+```
+`train: false` — or ANY error (fail closed) → stop: a product repo's train belongs to that repo's
+**project-admin** (repo write + registry `projectAdmins`) or the master. When `project-admin` + `train`,
+proceed — do not redirect to the master (`AGENTS.md` § Authority). Errors → fix `gh auth` first,
+never proceed unverified.
+
+**CLI freshness (#2562):** check the running CLI is current BEFORE step 1 — `mmi-cli devops 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 --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
+a shared-branch train operation (merge/tag/push against origin's protected `rc`), not an isolated
+feature-branch edit. A background-job harness that isolates every task into a fresh worktree by default
+breaks here: `git worktree`s cannot have the same branch checked out twice, so a fresh worktree can't check
+out `development` while the primary checkout already has it. Exit any such worktree first and run from the
+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
+--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
+```
+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 --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.
+
+## Step 1b — registry + rc secret-name preflight
+
+Resolve the project META first; its `deployModel` decides the deploy path. `tenant-container` repos use the
+central tenant deployer and therefore need DEPLOY# coords. Serverless, `registry-publish`, and
+`solo-container` repos deploy from their own workflow, so do **not** dispatch `tenant-deploy.yml` for them.
+Direct-track repos (`releaseTrack: direct`, e.g. MMI-Hub) have no rc candidate path; `mmi-cli devops rcand --apply`
+refuses after this preflight.
+Verify META + required SSM secret names before touching `rc`:
+```bash
+mmi-cli oracle org project get {owner}/{repo}
+mmi-cli vault secrets preflight --stage rc --repo {owner}/{repo}
+```
+Missing META or secret names → stop and repair the registry/secrets first.
+
+## Step 2 — merge development → rc (never force)
+
+```bash
+git checkout rc
+git pull --ff-only origin rc
+git merge development --no-edit
+```
+Conflict → `git merge --abort`, report paths, resolve on `development`, re-run.
+
+**Exception — version manifests only.** When every conflicted path is a version manifest
+(`package.json` · `package-lock.json`), the incoming `development` side carries the org truth — the
+`/release` version fold (#976) bumps manifests on `main` and the release back-merge brings them to
+`development`, so `development` is always the newer side. Take it deterministically and continue (no
+hand-resolution, no abort):
+```bash
+git checkout --theirs package.json package-lock.json && git add package.json package-lock.json
+git commit --no-edit
+```
+Any other conflicted path in the same merge → abort as above. Tag (step 3) only AFTER the merge commit
+exists — a tag minted before the conflict resolution points at the wrong SHA.
+
+## Step 3 — tag the rc
+
+The shared helper derives the next rc tag from existing tags (re-run-safe — `-rc.N` increments). `rc` mode
+reads `MMI_BUMP_INTENT`; unset it resolves to `patch` (#4929) — declare `minor`/`major` explicitly for a
+planned feature cycle:
+```bash
+TAG=$(MMI_BUMP_INTENT=minor node scripts/next-version.mjs rc)   # -> vX.Y.0-rc.N
+git tag "$TAG"
+```
+
+## Step 4 — push tag, wait for the REQUIRED checks, then push rc (the gate)
+
+Required status checks are **per-repo branch protection, not a fixed list** — MMI-Hub requires `cli` ·
+`infra` · `docs`, but a product repo may require different contexts or none at all (#1045). A fresh merge
+SHA has no check-runs yet, so when checks ARE required, pushing the branch *first* is structurally rejected
+until CI catches up (it then succeeds on a retry — avoidable noise). Push the **tag first**: it lands the
+SHA and triggers the repo's CI without touching the protected branch ref. Then probe what `rc` actually
+requires and wait only for those contexts:
+
+```bash
+git push origin "vX.Y.0-rc.N"                 # lands the SHA + triggers the repo's CI
+SHA=$(git rev-parse rc)
+# discover the REQUIRED contexts on rc (classic protection + rulesets; 404 = none from that source):
+gh api repos/{owner}/{repo}/branches/rc/protection/required_status_checks --jq '[.contexts[]]'
+gh api repos/{owner}/{repo}/rules/branches/rc \
+  --jq '[.[]|select(.type=="required_status_checks")|.parameters.required_status_checks[].context]'
+# ZERO required contexts -> push rc immediately (the GitHub push gate is the backstop).
+# Otherwise poll until every required context is "success" on $SHA — never a hard-coded list, and bound
+# the wait (~10 min): on timeout, stop with a clear failure naming the pending/failed contexts.
+gh api repos/{owner}/{repo}/commits/$SHA/check-runs \
+  --jq '[.check_runs[]|{name:.name,conclusion:.conclusion}]'
+git push origin rc
+```
+(`mmi-cli devops rcand --apply` performs this discovery + bounded wait itself.)
+Rejected (protected / not a bypass actor) → stop, nothing deployed, no board writes; leave the local tag
+for an authorized re-push, never force. Non-fast-forward → re-pull, re-run from step 1.
+
+## Step 5 — rc deploy (model-specific, non-blocking)
+
+For `tenant-container` repos, dispatch the Hub **tenant-deploy.yml** workflow for rc (OIDC, keyless). Don't
+deploy by hand, and **don't block on it** — start the watch as a background task and move straight to
+Step 6:
+```bash
+gh workflow run tenant-deploy.yml --repo mutmutco/MMI-Hub \
+  -f slug={slug} -f repo={owner}/{repo} -f ref=rc -f stage=rc
+gh run watch "$(gh run list --workflow tenant-deploy.yml --limit 1 --json databaseId -q '.[0].databaseId')" \
+  --exit-status   # run this in the BACKGROUND (Bash run_in_background) — capture its URL for the report
+```
+
+For serverless repos, do **not** dispatch `tenant-deploy.yml`: their own push-triggered workflow owns the
+rc deploy.
+
+`mmi-cli devops rcand --apply --json` returns the relevant run `runId` + `runUrl` (alongside `deployStatus`), so
+you never hand-correlate Actions. For tenant-container repos, that is the dispatched `tenant-deploy.yml`
+run. For Hub serverless, that is the auto-fired `deploy.yml` run from the protected `rc` push. Add
+`--watch` to block on the run and have `deployStatus` resolve to `success`/`failure`; `promoted: true`
+stays set either way — a failed **deploy** never undoes the **promotion**.
+
+The deploy runs while you report. When the background watch returns, surface the outcome:
+**green** → note the run + rc env URL; **red** → report plainly. The rc tag is already pushed, so the
+correct next action is a **deploy retry of the existing rc ref** after the Hub runtime is repaired — never
+a re-tag/re-merge:
+```bash
+mmi-cli devops runtime tenant redeploy {owner}/{repo} rc --watch   # re-dispatch tenant-deploy.yml for the promoted rc
+```
+**Branch the recovery by failure class — a bare redeploy is NOT always the whole recovery.** For **exit 78**
+(`compose is fileless but DEPLOY#<stage>.noEnvFile is not true`) a plain redeploy fails identically: the
+box's baked `/opt/mmi-control/<slug>.sh` still carries the stale `noEnvFile`, so it writes no `.env` while
+the fileless compose expects passthrough. Fix the registry AND re-render the box control script first, then
+redeploy (`set-deploy` alone is not enough — the reconcile is the discoverable-but-non-obvious middle step):
+```bash
+mmi-cli oracle org project set-deploy {owner}/{repo} --stage rc --no-env-file true   # register the DEPLOY#rc fileless flag
+mmi-cli devops runtime tenant reconcile {owner}/{repo} rc --watch                    # Hub-authorized; project-admin needs no MMI-Hub Actions access
+mmi-cli devops runtime tenant redeploy {owner}/{repo} rc --watch                     # NOW the redeploy reads the corrected control script
+mmi-cli devops runtime tenant control {owner}/{repo} rc verify-broker --watch        # value-free broker proof for runtime consumers
+```
+The reconcile must finish green before redeploy starts; `--watch` enforces that ordering. A failed rc
+dispatch stays fail-loud — rc is ephemeral and re-runnable, so the redeploy (after the reconcile step above
+for an exit-78 fileless mismatch) re-runs it.
+
+## Step 6 — report
+
+Version `vX.Y.0-rc.N` · merged commits · rc deploy run + env URL.
+
+## Notes
+
+- `rc` is NOT prod. Shipping `rc → main → prod` is `/release` (ships exactly what's on `rc`; never pulls
+  `development`). Never force-push `rc`; never commit to `rc` outside the step-2 merge.
+- `rc` is **ephemeral**: `/rcand` creates the rc runtime, `/release` retires it after a confirmed prod
+  deploy. A full-track repo can skip rc entirely with `/release --dev` (`development → main`); `/hotfix`
+  always skips rc (it cherry-picks `development → main` directly).
+- **MAJOR / exact-target cycle:** for a release the tag math can't derive (a MAJOR like `2.0.0`, or skipping
+  a version already on npm), export `MMI_RELEASE_VERSION=X.Y.Z` before `/rcand` — `next-version.mjs rc` then
+  opens that exact cycle (validated to move strictly forward). Keep it exported through `/release`.
+- **`MMI_BUMP_INTENT=major|minor|patch` selects the increment for `next-version.mjs rc`** (Step 3); absent,
+  it defaults to `patch` (#4929). **Export it for the whole run:** `mmi-cli devops rcand --apply` resolves
+  the intent itself with the same default, so a one-off prefix on the `next-version.mjs` command leaves the
+  apply deriving a different increment than the tag you minted. This is
+  a different knob from `MMI_RELEASE_VERSION` above: `MMI_BUMP_INTENT` picks the increment,
+  `MMI_RELEASE_VERSION` overrides the computed version entirely and is for the exceptional case only.
+
+## 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 misleading authority or gate message, or an
+ambiguous tag or push-order step.) 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 rcand --title "<what misfired>" --body "<what; evidence; proposed amendment>"`