@mutmutco/opencode-mmi 2.48.0

package/skills/rcand/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: rcand
+description: Promote development → rc for full-track deployable repos — merge, tag (vX.Y.0-rc.N), push, dispatch the rc deploy. Direct-track repos (releaseTrack=direct, incl. MMI-Hub) skip rc and release from development via /release. Train-authority gated. Use when an authorized user wants to cut/promote a release candidate, ship development to rc, stage work for release, or invokes /rcand.
+---
+
+# /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 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 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.
+
+## 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).
+```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 --apply --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 rcand --apply`
+refuses after this preflight.
+Verify META + required SSM secret names before touching `rc`:
+```bash
+mmi-cli project get {owner}/{repo}
+mmi-cli 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):
+```bash
+TAG=$(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 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 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 tenant redeploy {owner}/{repo} rc --watch   # re-dispatch tenant-deploy.yml for the promoted rc
+```
+Don't hold the session open waiting. Unlike `/release`, a failed rc **dispatch** stays fail-loud — rc is
+ephemeral and re-runnable, so the same `tenant redeploy … rc` retry is the whole recovery.
+
+## 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`.
+
+## 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 skill-lesson --skill rcand --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/release/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: release
+description: Ship to main + prod. Full-track repos ship rc → main; direct-track (releaseTrack=direct, incl. MMI-Hub) skip rc and ship development → main. Train-authority gated; the only prod path. Use when an authorized user wants to release to production, cut/publish a version, or invokes /release.
+---
+
+# /release — ship to main + prod
+
+Full-track repos ship **exactly what is on `rc`** (never pulls `development`): merge `rc → main`, tag
+`vX.Y.0`, publish a GitHub Release, dispatch the Hub central tenant deploy workflow for prod, then roll
+`development` forward. Direct-track repos — product repos with `releaseTrack: direct`, plus MMI-Hub via the `isHubControlRepo` special-case (its `releaseTrack` stays unset) — skip rc: release
+merges `development → main`, tags, publishes the GitHub Release, and the release event fires the repo's own
+deploy/publish workflow (for MMI-Hub, `deploy.yml` + `publish.yml`).
+`rc` is **ephemeral**: `/rcand` creates the rc runtime, `/release` retires it — after a confirmed full-track
+prod deploy the train stops the rc stage (reported as `rcRetirement` in the result; never fatal to the
+release). Full-track repos may also pass **`--dev`** to release `development → main` directly, skipping rc —
+the default stays `rc → main`. `--dev` **fails closed** when `origin/rc` carries content not yet in
+`development` (a dev → main release would drop it), and is a friendly no-op on direct-track repos.
+**Train-authority gated (D14):** the repo's project-admin or the master; the Hub repo's train is
+master-only. This is the **only** sanctioned prod path; a prod release still needs the authorized human's
+explicit per-turn go — an agent never self-initiates it. The board needs no
+touch — items reached `Done` when their PRs merged to `development`; `rc`/`main` are deploy stages, not lanes.
+
+Authority is structural + server-checked: step 0 asks the Hub (`mmi-cli access role`), and step 3 pushes
+to the protected `main` branch, whose per-repo allowlist carries the same people (master + that repo's
+project-admins; Hub: master + App only). Gate ordering: the tag lands the release SHA for checks, and
+nothing deploys before the protected `main` push accepts that checked SHA.
+
+## Step 0 — confirm + probe
+
+Confirm the human holding train authority for THIS repo authorized a prod release this turn. Probe:
+```bash
+mmi-cli 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 or the master; the Hub train is master-only. Then preconditions: clean tree; full-track repos
+run from `rc` (or from `development` with `--dev`), while direct-track repos run from `development`.
+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).
+
+Full-track repos:
+```bash
+git fetch origin
+git rev-list --count origin/main..origin/rc
+```
+
+Direct-track repos (e.g. MMI-Hub):
+```bash
+git fetch origin
+git rev-list --count origin/main..origin/development
+```
+`0` → stop ("nothing to release").
+
+## Step 0a — stale CLI preflight (#1410)
+
+Before local gates or `release --apply`, ensure the repo-local / PATH `mmi-cli` matches the released train
+path — a stale checkout (e.g. 2.32.0 while 2.32.4 is released) fails release gates with opaque errors.
+Self-heal in place without repo writes:
+```bash
+mmi-cli doctor --apply --no-repo-writes
+```
+If doctor reports a version gap it cannot auto-apply (e.g. `--no-repo-writes` blocks the npm bump), stop and
+run `mmi-cli doctor --apply` (or `npm install -g @mutmutco/cli`) before continuing. Do **not** proceed to
+Step 0b while the installed CLI is behind the Hub's `minClientVersion`.
+
+## Step 0b — registry + main 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. `hub-serverless` (MMI-Hub), `serverless`,
+`registry-publish`, and `solo-container` repos deploy from their own branch/release-triggered or model
+workflow, so do **not** dispatch `tenant-deploy.yml` for them.
+Verify META + required SSM secret names before touching `main`:
+```bash
+mmi-cli 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.
+
+## Step 0c — hotfix-coverage guard (fail closed, #839, #958)
+
+Full-track repos only. Direct-track repos skip this guard because their release candidate is `development` itself.
+
+Hotfixes are cherry-picked from `development` to `main` with **no back-merge** (see `/hotfix`), so a
+candidate cut *before* a fix landed on `development` would silently revert that hotfix in prod. The guard
+proves every main-only commit is in the candidate before the `rc → main` merge.
+
+It runs **automatically inside `mmi-cli release --apply`** (Step 1+ below) — built into the CLI so it
+works in every product repo with no repo-local script. You do not invoke it separately.
+
+Per main-only commit it accepts: the `(cherry picked from commit <sha>)` trailer with that dev SHA an
+ancestor of `origin/rc` (immune to conflict-resolved ports); a matching `git patch-id` on the rc side
+(trailer-less picks); or a distribution-manifest-only bump (exempt — rc carries its own). Anything else
+**fails the release closed** → **stop**: the right fix is a re-cut `/rcand` from `development`. Only when
+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 1 — merge to main (never force)
+
+Full-track repos:
+
+```bash
+git checkout main
+git pull --ff-only origin main
+git merge rc --no-edit
+```
+
+Direct-track repos (e.g. MMI-Hub):
+```bash
+git checkout main
+git pull --ff-only origin main
+git merge development --no-edit
+```
+Conflict → abort + stop (the train is misaligned — investigate; don't hand-resolve on `main`).
+Alignment PRs are the exception to the org's squash default: land them with a true merge commit
+(`gh pr merge --merge`) — a squash discards the merge parentage, so the misalignment guard re-flags the
+same divergence on the next run.
+
+**Exception — spine, version-manifest, and `.gitignore` paths.** `mmi-cli release --apply` tolerates
+conflicts confined to the org spine files, the version-fold paths (Step 1b), and `.gitignore` (#1037 — a
+repo bootstrapped before the managed-gitignore era still carries the legacy file on `main`; the candidate
+carries the Hub-managed copy with project-local entries preserved). A hotfix bumps the manifests +
+committed CLI bundle on `main` only, so the next merge re-conflicts there even when the train is healthy —
+and the fold rewrites those exact paths right after the merge. For all tolerated paths the CLI takes the
+incoming side deterministically and continues. Any other conflicted path → abort + stop as above.
+
+## Step 1b — version fold (automatic, inside `mmi-cli release --apply`)
+
+Every release folds the version bump into the release itself (#976): after the merge onto local `main` and
+before the tag, the CLI bumps the version manifests to the release version and commits — **unconditionally,
+changed or not** — then the tag-first push (Step 3) earns that fresh commit its required checks. There is
+no separate bump PR, no `development` prep cycle, and `development` never sits ahead of the published
+version (the back-merge in Step 5 carries the bump back).
+
+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`: regenerate rule packs, verify docs/mirror/surfaces),
+  Claude/Codex/Cursor plugin manifests + marketplaces, `cli/package.json` + lockfile,
+  `plugins/opencode-mmi/package.json` + lockfile, and the rebuilt CLI + OpenCode adapter dist — then verifies
+  the set (`verify --skip-npm-view`). The Claude marketplace
+  `source` is pinned to `ref: main`, so the release is *how* a plugin change reaches devs.
+- **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.
+
+Nothing to do by hand; the `--apply` result reports the fold outcome (`versionFold`).
+
+## Step 2 — tag the release
+
+Full-track repos drop the `-rc.N` suffix from the open cycle. Direct-track repos use the next cycle directly
+because they have no rc tag:
+```bash
+TAG=$(node scripts/next-version.mjs release)   # full-track repos -> vX.Y.0
+TAG=$(node scripts/next-version.mjs cycle)     # direct-track repos -> vX.Y.0
+git tag "$TAG"
+```
+
+## Step 3 — push tag, wait for the REQUIRED checks, then push main (the gate)
+
+Required status checks are **per-repo branch protection, not a fixed list** — MMI-Hub's `main` requires
+`cli` · `infra` · `docs`, but a product repo may require different contexts or none at all (#1045). The
+release SHA is always fresh (the Step 1b fold commits on local `main`), so when checks ARE required,
+pushing the branch *first* is structurally rejected until CI catches up. Push the **tag first** (it lands
+the SHA and triggers the repo's CI — in MMI-Hub `gate.yml` runs on `v*` tags — without touching the
+protected ref), then probe what `main` actually requires and wait only for those contexts:
+
+```bash
+git push origin "vX.Y.0"                       # lands the SHA + triggers the repo's CI
+SHA=$(git rev-parse main)
+# discover the REQUIRED contexts on main (classic protection + rulesets; 404 = none from that source):
+gh api repos/{owner}/{repo}/branches/main/protection/required_status_checks --jq '[.contexts[]]'
+gh api repos/{owner}/{repo}/rules/branches/main \
+  --jq '[.[]|select(.type=="required_status_checks")|.parameters.required_status_checks[].context]'
+# ZERO required contexts -> push main 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 main
+```
+(`mmi-cli release --apply` performs this discovery + bounded wait itself.)
+Rejected → stop (nothing released).
+
+## Step 4 — GitHub Release + start prod deploy (non-blocking)
+
+For `tenant-container` repos, publish the GitHub Release, dispatch the central tenant deploy, and dispatch
+the release-scoped wiki refresh (release events never leave the releasing repo, so the keeper must be
+dispatched centrally — #759):
+```bash
+gh release create "vX.Y.0" --target main --generate-notes --latest
+gh workflow run tenant-deploy.yml --repo mutmutco/MMI-Hub \
+  -f slug={slug} -f repo={owner}/{repo} -f ref=main -f stage=main
+gh workflow run cursor-agents.yml --repo mutmutco/MMI-Hub \
+  -f agent=wiki-keeper -f only_repo={owner}/{repo}   # wiki-keeper, scoped to the released repo
+gh run watch "$(gh run list --workflow tenant-deploy.yml --limit 1 --json databaseId -q '.[0].databaseId')" \
+  --exit-status   # the central prod-deploy run — run this in the BACKGROUND (Bash run_in_background)
+```
+
+For `hub-serverless` (MMI-Hub), publish the GitHub Release but do **not** dispatch `tenant-deploy.yml` or
+`cursor-agents.yml`: the release event auto-fires `deploy.yml` for prod, `publish.yml` for the plugin/CLI
+package, and `cursor-agents.yml` for the Hub-scoped wiki refresh. A missing `DEPLOY#main` registry row for
+MMI-Hub is expected, not a tenant stack repair task. Watch/report the release-triggered `deploy.yml` and
+`publish.yml` runs instead.
+
+For other direct-track repos, the train dispatches nothing centrally: a `registry-publish` repo's release
+event fires its own `publish.yml` (npm / plugin marketplace); a `solo-container` repo deploys via its own
+workflow. Publish the GitHub Release, then watch/report that repo's own release-triggered run.
+
+`mmi-cli release --apply --json` returns the relevant run id/url data with `deployStatus`; `--watch` blocks
+on the run(s) and resolves `deployStatus` to `success`/`failure`. For tenant-container repos, that is the
+dispatched `tenant-deploy.yml` run. For Hub serverless, that is the auto-fired release `deploy.yml` and
+`publish.yml` workflow pair.
+`promoted: true` stays set even on a failed deploy — promotion and deploy are separate outcomes.
+
+**Hub releases announce to Slack (#883).** Hub scope is **only** `mutmutco/MMI-Hub`: the commits/PRs on
+`origin/main..origin/development`, this repo's `deploy.yml` + `publish.yml`, and Hub tooling (`mmi-cli`,
+skills, plugin, registry, central workflows). Do **not** read another repo's board (`mmi-cli board` / `/mmi`
+on a product), watch or dispatch `ds-propagate.yml`, run `design-system` / `doctor` design-system heals for
+consumers, or treat a product's deploy state as part of this release — those belong to that product's own
+`/release` or `/rcand`, never a Hub train.
+
+Before running `--apply` for MMI-Hub, resolve the real tag first:
+`TAG=$(node scripts/next-version.mjs cycle)` — always print `$TAG` (e.g. `v2.43.0`) in summaries, Slack,
+chat, and the final report; never a placeholder like `vX.Y.0` or `v0.x.0`.
+
+Write a curated summary — 3-6 very short plain lines, one change per line, dev-readable, no PR-dump —
+to a fresh temp file (`f=$(mktemp tmp/release-summary.XXXXXX)`, so a stale prior summary is never reused).
+Source from **Hub PR titles only** (`origin/main..origin/development` on `mutmutco/MMI-Hub`), but **rewrite**
+each line in neutral Hub-subsystem terms (CLI, skills, plugin, workflows, registry, deploy hub) — **never**
+a product or brand name (FoFu, Katip, etc.) anywhere in the summary file, Slack post, chat, or release
+report. Product names are allowed only when releasing **that product's repo**. Then pass the file through:
+`mmi-cli release --apply --announce-summary-file "$f"`. After the GitHub Release publishes, the CLI posts
+the summary to the org alerts channel as the MMI-Future Slack app (token + channel from SSM at run time).
+Without the file it falls back to a deterministic distillation of the generated notes (product brands are
+stripped there too). The announcement is best-effort: a Slack failure is reported in the result and never
+fails the release. Non-Hub repos skip the announcement automatically.
+
+**Don't block on the deploy.** Start the watch as a background task and proceed to Steps 4b–5 (docs, project
+info, branch alignment) while prod deploys. The verdict is collected in Step 6 — verification is not
+skipped, only un-blocked. Deploy failure → report plainly; `main` is already at the release (correct), so
+the correct next action is a **deploy retry of the existing main ref** after the runtime is repaired — never
+a re-tag: `mmi-cli tenant redeploy {owner}/{repo} main --watch`.
+
+## Step 4b — refresh docs + project info
+
+A release is the heartbeat that keeps docs true. Before advancing items:
+- Verify the repo's `README.md` / `architecture.md` (and, in the hub, `docs/org-readme.md` / `docs/org-architecture.md`)
+  state **present truth** for what just shipped; rewrite any drift (no change-comments — see AGENTS docs rule).
+- Re-sync the **Project** info from those docs + current member repos: set the project's short description +
+  README (the thin dashboard — it *links* the docs, never duplicates them) via the `updateProjectV2`
+  mutation (`shortDescription`, `readme`).
+
+## Step 5 — roll development forward
+
+- Keep branches aligned: `mmi-cli release --apply` back-merges the released `main` (incl. the version
+  fold) into `development` and reports it as `devRollForward`. When `development` has no required checks it
+  pushes directly (`status: pushed`). When `development` *requires* checks (e.g. MMI-Hub needs
+  `cli`/`infra`/`docs`), the fresh merge commit carries no passing checks, so a direct push is structurally
+  rejected — the train instead **opens an alignment PR** `main → development` (`status: pr-pending`) and the
+  release report prints the exact land command. The release itself has already shipped; **land the alignment
+  PR with a true merge** — `gh pr merge <number> --merge` (never squash — a squash drops the merge parentage
+  and the misalignment guard re-flags the divergence). Never force.
+- Full-track repos: `mmi-cli release --apply` already aligned `rc` to the released `main` (#1036 — the
+  push runs inside the authority-gated train; the result reports it as `rcAlignment`). No manual `rc`
+  push — if the result reports a failed alignment, investigate and rerun via the train, never bare-push.
+
+## Step 6 — collect deploy verdict + report
+
+Collect the backgrounded prod-deploy watch from Step 4 (it has typically finished by now). Confirm prod is
+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).
+
+Hub releases always carry a distribution bump (the Step 1b fold), so the **publish workflow**
+(`publish.yml`) ships `@mutmutco/cli` and `@mutmutco/opencode-mmi` to npm on the GitHub Release from Step 4 — don't publish by hand.
+Watch it, then confirm npm caught up:
+```bash
+gh run watch "$(gh run list --workflow publish.yml --event release --limit 1 --json databaseId -q '.[0].databaseId')" --exit-status
+node scripts/release-distribution.mjs verify "vX.Y.0"   # asserts Claude/Codex/Cursor/OpenCode surfaces and npm == the release version
+```
+Run that verify from a checkout **at the tag** (`main` right after the release merge, `git checkout
+"vX.Y.0"`, or a worktree at the tag) — verify checks the working tree and refuses any other commit once
+the tag exists, so a stale `development`/`rc` checkout can't masquerade as a broken release.
+Release-blocking for Hub tooling changes: Claude plugin, Codex plugin, Cursor plugin, OpenCode plugin, and npm users must see the same
+version. Manual fallback if CI can't publish: `node scripts/release-distribution.mjs publish "vX.Y.0"` from a
+machine with npm auth.
+
+Report: Release `$TAG` (the resolved tag from Step 2 — never a placeholder) + the GitHub Release URL · prod
+deploy run + URL + **green/red** · branch-alignment note · npm publish run + CLI version (Hub releases).
+
+## Notes
+
+- PATCH-level releases are `/hotfix` only (a hotfix always skips rc — it cherry-picks `development → main`
+  directly); planned releases are MINOR or MAJOR. Never force-push `main`.
+- **`--dev` (full-track only):** releases `development → main` skipping rc, with the same fold/tag/Release/
+  deploy machinery plus the post-release rc retirement and rc alignment. Refuses (fail closed) when
+  `origin/rc` carries commits not in `development`; on direct-track repos it's a no-op (they already
+  release from `development`).
+- **MAJOR / exact-target release:** to ship a version the tag math can't derive (a MAJOR like `2.0.0`, or
+  skipping a version already on npm), product repos export `MMI_RELEASE_VERSION=X.Y.Z` for **both** `/rcand`
+  and `/release`; MMI-Hub exports it for `/release` only. Steps 1b/2 then fold and tag exactly that
+  version. Unset, the train ships the open cycle.
+
+## 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 version-fold or back-merge 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 skill-lesson --skill release --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/secrets/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: secrets
+description: Manage this repo's secrets — list/get/set/edit/rm/use the PROJECT tier you self-serve (your /mmi-future/<slug>/dev/* keys), plus the master-only grant/revoke into an ORG-tier secret. Use when a dev wants to add, rotate, read, remove, or consume a project secret/key, asks where a secret lives or which tier it's in, the master wants org-tier grant/revoke, or invokes /secrets. Never echo a secret value.
+---
+
+# /secrets — two-tier project secrets
+
+**Authority:** project-tier ops are self-serve for the repo's project-admin (`mmi-cli access role` →
+`project-admin` + `train` on that repo). Do not redirect an authorized project-admin to the master for
+`dev/*` keys — use this skill. Org-tier grant/revoke stays master-only (`AGENTS.md` § Authority).
+
+Secrets in the org split by **blast radius + who manages them** (not by storage — both tiers are SSM
+SecureString + KMS, and **a value is never echoed to chat or logs**):
+
+- **PROJECT tier** — `/mmi-future/<slug>/dev/*`. Lower-blast dev/throwaway working secrets (a scraper key,
+  a third-party API key, a throwaway SaaS account). The repo's **project-admin self-serves** these via
+  `/secrets`, on their **GitHub role alone** — no AWS, no waiting on the master.
+- **ORG tier** — everything else under the slug (`rc/*`, `main/*` prod secrets) plus shared/infra
+  (`/mmi-future/{shared,cloudflare,docs,mmi-hub}/*`). **Crown jewels, master-gated.** A project-admin
+  reaches an org-tier secret only via a master **grant**; the master is unrestricted (and **is** a
+  project-admin of every repo — master ⊇ project-admin).
+
+A bare `<KEY>` defaults into the **project tier** (`dev/`). To touch the org tier you name the env
+explicitly: `main/GOOGLE_CLIENT_SECRET`, `rc/DB_URL`.
+
+All ops run through `mmi-cli secrets …`, which calls the org backend with the caller's `gh` token; the
+backend re-verifies **project-admin-of-this-repo** and the **tier scope** server-side and does the scoped
+SSM op. This skill never touches AWS.
+
+## Step 0 — orient
+
+Read the current repo + slug; the tier of a key follows from its name (above). `secrets list` shows what
+exists and which ones **you** can manage (a `*`), never values.
+
+```bash
+mmi-cli secrets list                 # names + tier + a * on the ones you can write. NEVER values.
+```
+
+`secrets: no registry META` or `Hub API unreachable` → the repo is not registered with the Hub, GitHub auth
+is missing, or the Hub API is unavailable. Run `mmi-cli project get <owner/repo>` to distinguish those cases;
+a master-admin backfills the registry before secrets can be resolved.
+
+## Step 1 — the verb
+
+Default to the **current repo**; pass `--repo owner/Name` to target another (you must be its project-admin).
+
+```bash
+# Read one value — printed ONCE, raw (so it pipes). Do not paste it into chat, a file, or a log.
+mmi-cli secrets get SCRAPER_API_KEY
+
+# Write / rotate — the VALUE is read from stdin, NEVER an argument (so it can't leak into shell history
+# or process args). Pipe it in:
+printf %s "$THE_VALUE" | mmi-cli secrets set SCRAPER_API_KEY
+mmi-cli secrets edit SCRAPER_API_KEY   # alias for set — same stdin path
+
+# Validate a known provider key without printing its value:
+mmi-cli secrets verify RECALL_API_KEY
+
+# Remove:
+mmi-cli secrets rm SCRAPER_API_KEY
+
+# How to CONSUME a secret without committing it (no value printed):
+mmi-cli secrets use SCRAPER_API_KEY
+```
+
+**Never** pass a value as an argument (`secrets set KEY thevalue` is wrong — there is no value arg). The
+confirmation prints the **name and tier only**, never the value.
+
+## Rotation checklist
+
+Before rotating, enumerate every copy of the key so no tier stays stale:
+
+```bash
+mmi-cli secrets list --repo owner/Repo
+```
+
+Check bare/dev, `rc/`, `main/`, and any legacy unprefixed copy the list shows. Rotate the provider-side key
+first, then write every canonical vault tier that still needs that key. For keys with a provider probe
+(`RECALL_API_KEY` today), `secrets set` validates the new value before printing success; `secrets verify
+<KEY>` repeats the same probe later without printing the value. If the verifier fails, treat the rotation as
+incomplete even if the vault write itself succeeded.
+
+## Step 2 — org-tier elevation (master-only)
+
+A project-admin who needs a specific **org-tier** secret asks the master. The master grants a **scoped,
+auditable** standing access to that one key (or revokes it). These verbs are **master-only** — the backend
+403s anyone else.
+
+```bash
+# MASTER: let @oguz-mut manage one org-tier secret in Pulse
+mmi-cli secrets grant mutmutco/Pulse oguz-mut main/GOOGLE_CLIENT_SECRET
+# MASTER: withdraw it
+mmi-cli secrets revoke mutmutco/Pulse oguz-mut main/GOOGLE_CLIENT_SECRET
+```
+
+The master can also just operate the org-tier op directly while guiding (master ⊇ project-admin). Org-tier
+access by a project-admin **always originates from the master** — never unilaterally.
+
+## Tier — which one does a new secret belong in?
+
+- A **dev/throwaway** working credential (rotatable, project-scoped blast radius) → **project tier**: a bare
+  `<KEY>` (lands in `dev/`). The project-admin owns it.
+- A **real production** credential (prod OAuth client, prod DB, deploy role) → **org tier**: `main/<KEY>` or
+  `rc/<KEY>`, master-managed. If a dev secret graduates to prod, ask the master to promote it.
+
+## Tier-to-tier copy (provider keys, #1433)
+
+**Encryption / stage-distinct keys** (`*_ENC_KEY`, `SECRET_KEY_BASE`, etc.) must be **generated per stage** —
+never copied. **Provider sandbox keys** (e.g. Recall/Gemini for Katip dev/rc) **may** be shared across dev/rc
+when they point at the same sandbox project; prod stays org-tier and distinct.
+
+Sanctioned copy (master-gated when the source tier is org):
+```bash
+mmi-cli secrets copy --from rc --to dev --keys RECALL_API_KEY,GEMINI_API_KEY
+mmi-cli secrets copy --from rc --to dev --keys RECALL_API_KEY --dry-run   # plan only
+```
+Prefer this over manual `secrets get | secrets set` piping — audit-logged, blocklist enforced.
+
+## Notes
+
+- **Never echo a value** — not in chat, a commit, a log, or an issue. Only `secrets get` emits a value, once,
+  to stdout for piping. Treat every secret as write-once.
+- Authority is **GitHub**: project-admin = repo `write` plus the registry `projectAdmins` entry, master =
+  org owner. The backend checks both with the org App token, so the decision is server-side (your token
+  scope can't widen it).
+- Runtime + CI read their own tiers **keylessly via OIDC** — they don't use `/secrets`. `secrets use <KEY>`
+  prints the consumption guidance (runtime OIDC read · CI `aws ssm get-parameter` · local gitignored `.env`).
+- Every self-service write is **attributable** — the backend logs actor + repo + KEY name (never the value).
+
+## 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 canonical-name or tier mix-up, or a step
+that risked echoing a value.) 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 secrets --title "<what misfired>" --body "<what; evidence; proposed amendment>"`