@mutmutco/codex-plugin 3.131.0

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