@mutmutco/codex-plugin 4.3.5 → 4.3.7

package/skills/rcand/SKILL.md

@@ -5,224 +5,76 @@ description: Promote development to a release-candidate branch.
 
 **Host-native invocation:** Claude `/mmi:rcand` · Codex `$mmi:rcand` · Cursor `/rcand` · jervcode `/rcand` · Hermes skill_view. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
 
+**Argument:** `/rcand minor`, `/rcand major`, or `/rcand patch` — a bare bump word, never a `--flag` or env var. No argument → `patch`; declare `minor` or `major` for a planned feature cycle.
+
 # /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.
+Merge `development → rc`, tag `vX.Y.0-rc.N`, push the tag first, wait for the required checks, push the protected `rc` (the GitHub authority gate), then start the rc deploy. `rc` is a deploy stage, not a lane, and it is ephemeral: `/rcand` creates its runtime, `/release` ships exactly what is on `rc` and retires it. Train-authority gated: the repo's project-admin or the master. The board needs no touch: items reached `Done` when their PRs merged to `development`.
 
-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.
+## Lane
 
-## Step 0 — confirm lane + train-authority probe (server-side, D14)
+Read META and name the lane before describing or executing anything:
 
-Before describing or executing any rc promotion, read the project META and name the lane (#5244):
 ```bash
 mmi-cli oracle org project get {owner}/{repo} --json
 ```
-`releaseTrack: direct` (product repos with explicit META, plus MMI-Hub via the `isHubControlRepo`
-special-case) means **no `rc` branch** — stop here and run `/release` from `development` instead.
-`mmi-cli devops rcand --apply` refuses direct-track after its own preflight; do not reach Step 1 on direct.
-Stop on an unreadable META record; never infer the lane from branch names or the existence of a stale `rc` ref.
 
-Then probe train authority:
+`releaseTrack: direct` (product repos with explicit META, plus MMI-Hub) has no `rc`: stop here and run `/release` from `development`; `rcand --apply` refuses direct-track at its own preflight. Full-track runs from `development`, and a full-track repo may skip rc entirely with `/release --dev`. Unreadable META → stop; never infer the lane from branch names, a stale `rc` ref, or release history.
+
+Authority is structural and server-checked: the doctor asks the Hub, and the protected `rc` push allowlist carries the same people (master + that repo's project-admins). 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.
+
+## Preflight
 
 ```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. For `?? .jerv/` / `?? .pi/` (org-managed agent
-scratch), run `mmi-cli doctor --apply` to write the managed `.gitignore` block — do not hand-edit
-`.gitignore` (#5409). The train CLI already ignores those live-session dirs (#5397); doctor is the durable
-heal so `git status` stays clean. For other `??` scratch, gitignore it (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
+mmi-cli devops train doctor --lane rcand --heal --json
 ```
-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.
+Read `ready`, then `findings[]`: each carries `code`, `severity` (`blocker` · `warning` · `healed` · `info`), `source` (`local` · `origin`), `remedy` and `anchor`. `ready: false` → stop and quote every blocker's `code` and `remedy`; an unread origin is never green. `--apply` re-runs this doctor as its step 0 with heal on.
 
-## Step 1b — registry + rc secret-name preflight
+## Apply
+
+Run from the primary checkout on `development`. Export the bump intent once from the bare argument — `MMI_BUMP_INTENT=minor|major|patch`, unset → `patch` — and keep it exported through the following `/release`; `MMI_RELEASE_VERSION=X.Y.Z` opens an exact cycle for both `/rcand` and `/release` only when the tag math cannot derive it.
 
-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}
+r=$(mktemp tmp/rcand-receipt.XXXXXX)
+mmi-cli devops rcand --apply --json --out "$r"
 ```
-Missing META or secret names → stop and repair the registry/secrets first.
 
-## Step 2 — merge development → rc (never force)
+Add `--watch` to block on the rc deploy; without it the deploy runs while you report and its verdict is
+collected in Verify — verification is never skipped, only un-blocked. The one command fetches, merges `development → rc` (version-manifest conflicts resolve to the `development` side; any other conflicted path refuses), tags the next `-rc.N` (re-run-safe), pushes the tag first, discovers and waits for the required contexts on `rc`, pushes `rc`, and starts the deploy by model — `tenant-deploy.yml` centrally (keyless) for tenant-container; nothing for serverless, registry-publish or solo-container, whose own push-triggered workflow deploys. Never `git push` rc by hand, never force, never commit to `rc` outside that merge.
 
-```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.
+## Verify
 
-**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.
+Read the receipt at `$r`, never the exit code (exit `2` = promoted with the deploy unresolved; exit `1` = the deploy failed after promotion):
 
-## Step 3 — tag the rc
+- `promoted` — `true` even when the deploy failed; promotion and deploy are separate outcomes.
+- `tag` — the minted `vX.Y.0-rc.N`; `resumeNote` says an existing rc tag was resumed rather than minted.
+- `deployStatus` — `pending` is never terminal. `runId` / `runUrl` / `workflowRuns` name the run: the dispatched `tenant-deploy.yml` for tenant-container, the auto-fired `deploy.yml` for serverless. Watch each non-success entry to conclusion: `gh run watch <run-id> --repo {owner}/{repo} --exit-status`.
+- `environments` — the rc edge domain(s) from META, the env URL the report names.
+- `checkout`, `localSync`, `ledger` — `returned` and phases-green, or the named reason you are still on `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"
-```
+Then confirm origin: `git rev-list --count origin/rc..origin/development` is `0` and the rc tag is on origin. There is no GitHub Release at rc; the bounded Latest read belongs to `/release`. A red deploy after a green promotion is a deploy retry of the existing rc ref, never a re-tag or re-merge.
 
-## Step 4 — push tag, wait for the REQUIRED checks, then push rc (the gate)
+## Recovery
 
-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.
+Every refusal and every doctor blocker names its `code` and `anchor`: open `docs/Guides/train-troubleshooting.md#<code>` and follow that entry, nothing else. A candidate whose immutable rc tag passed policy but whose `origin/rc` was not pushed continues with `mmi-cli devops rcand --resume --watch --json --out <fresh-receipt>` — the only continuation form: `--resume` never re-tags, and `--apply` mints the next `-rc.N` for a new cut only. A refused train is a stop (Merge floor): fix the cause on `development` through a normal PR, then rerun; a rejected protected push leaves the local tag for an authorized rerun, never a force.
 
-**Preflight (#5428):** before the immutable tag, `mmi-cli devops rcand --apply` inspects each required
-context's workflow `on:` triggers. If a required context (e.g. `py-gate` / `web-gate`) is pull_request-only
-and cannot fire on a tag push, the train **refuses before tagging** with a teaching error — never publish a
-candidate tag then wait on an event that cannot fire. Fix the gate to also trigger on `push: tags: ['v*']`
-(see MMI-Hub `gate.yml`), or remove those contexts from the rc ruleset (`ci audit` / reconcile).
+## Merge floor
 
-```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.
+- **Never squash-merge a tagged commit (#3167).** A squash re-mints the SHA and orphans the tag from the branch lineage, so every tag-anchored check mis-reads forever after. Any merge that carries an already-tagged commit — the `main → development` roll-forward, an alignment PR, a hotfix fold PR — lands as a true merge: `mmi-cli devops pr merge <number> --auto --merge` (or `--wait --merge`); `--wait` alone still squashes. The hotfix main-base PR itself may squash: its tag lands after, on the merged `main` HEAD, and the `-x` trailer must survive the squash message.
+- **A refused train is a stop, never a license to finish by hand.** Every fail-closed halt — doctor blocker, authority probe, coverage guard, untolerated conflict, required checks, stray tag, ledger — ends the run. Fix the cause on `development` through a normal PR and rerun the train; never hand-resolve on `main`, hand-cherry-pick, bare-push a train branch, ack to save time, or bypass a check.
+- **Version probes anchor on the latest Release tag, not a branch (#2734).** A branch manifest or a stale local tag is not a version source; a surviving local tag silently mints the next version.
+- **One train at a time on a repo (#5380).** Two overlapping runs race the shared tag namespace; the ledger refuses the second — never start one to help the first.
+- **Tag and Release deletion are deletion-class:** the authorized human's explicit per-turn go, named in the guide entry that prescribes it.
 
-## Step 5 — rc deploy (model-specific, non-blocking)
+## Report
 
-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
-```
+Title first, verdict first. Name the resolved tag (never a placeholder like `vX.Y.0`) and the Release URL, the receipt's status fields (`releaseStatus`, `followUpStatus`, `deployStatus`, `promoted`), and every workflow run row with its conclusion and evidence — use its URL when emitted, otherwise the receipt's explicit no-run-URL note — saying which run is red, and whether it is a deploy/publish verdict or ordinary CI — `announceNote`, the alignment note (`devRollForward`, `rcAlignment`, or the hotfix fold PR and whether it landed), the `checkout` clause, and the sanctioned dispatch mechanism you used. A pending follow-up is reported as unverified, never as success. Product names appear only when releasing that product's repo.
 
-For serverless repos, do **not** dispatch `tenant-deploy.yml`: their own push-triggered workflow owns the
-rc deploy.
+## Retro
 
-`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**.
+Before the 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. If yes, file one lesson and move on; a clean run is silent (hard cap: one per run). It lands on the Hub board, deduplicated, and is fixed only through a reviewed PR — never edit the skill live. The retro is advisory: if the call fails, note it and continue.
 
-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
+mmi-cli learning skill-lesson --skill rcand --title "<what misfired>" --body "<what; evidence; proposed amendment>"
 ```
-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>"`