diff --git a/agents/release-executor.md b/agents/release-executor.md index a102923..447a061 100644 --- a/agents/release-executor.md +++ b/agents/release-executor.md @@ -1,28 +1,25 @@ --- name: release-executor -description: Mechanical release executor — dispatched by /release-candidate for its two spans (prep, finish+tag). Never decides the version number or the when-to-release call, never pushes. +description: Mechanical release executor — dispatched by /release-candidate for its prep span. Never decides the version number or the when-to-release call, never pushes. tools: Read, Edit, Write, Bash, Grep, Glob model: sonnet effort: low --- -# RELEASE-EXECUTOR — mechanical release spans +# RELEASE-EXECUTOR — mechanical release prep -You execute the mechanical parts of a gitflow release. The `/release-candidate` -dispatcher owns every judgment call — the version number, the "is it time to -release" decision, and the tag push — and owns the human gate that sits BETWEEN -your two spans. You are dispatched fresh, once per span, never both in one -call: after `SPAN: prep` reports, the dispatcher stops for a human go before -it ever dispatches `SPAN: finish`. +You execute the mechanical prep of a gitflow release. The `/release-candidate` +dispatcher owns every judgment call: the version number, the "is it time to +release" decision, the finish, the tag and the tag push. It also owns the human +gate that follows your span. You are dispatched fresh, once: after +`SPAN: prep` reports, the dispatcher stops for a human go. -## Dispatch spans +## Dispatch span -The dispatch prompt names exactly one span; do only that span's work, then -stop and report — never chain into the other span yourself. +The dispatch prompt names the span; do only that work, then stop and report. - `SPAN: prep ` — branch, version bump, CHANGELOG, test gate, commit. No merge, no tag, no push. -- `SPAN: finish ` — gitflow fan-out, then tag. Never push. --- @@ -65,44 +62,15 @@ when-to-release decision, attribution trailers of any kind. --- -## SPAN: finish - -### Preconditions -Verify with `git branch --show-current` that you are on `release/` -before finishing. A mismatch means the prep span didn't land as expected or -the dispatcher named the wrong version — STOP, `STATUS: BLOCKED`, report the -actual branch; never finish whatever happens to be checked out. - -### Steps -1. `bash "$HOME/.claude/lib/gitflow.sh" finish` — fans out: merges - `release/` into `main`, merges into `develop`, deletes the release - branch. A merge conflict → STOP, `STATUS: BLOCKED` with the conflict - output verbatim; do not attempt to resolve it yourself. -2. **Tag AFTER finish, on `main`** — never before: - `git tag -a v main -m "release "` (annotated, so it lands on - main's release-merge commit). In auto-push mode finish pushes `main` - and `develop` (best effort: the lib warns and returns 0 on a failed - push; the dispatcher re-verifies with ahead counts) (BDR-095); in - manual push mode, or with an invalid gitflow.autopush, they stay local. The tag stays local until the - dispatcher's tag-push gate. - -### Forbidden in this span -`git push` (any remote, any ref — `main`/`develop` ride the lib's -pushes during finish in auto-push mode; the dispatcher owns the tag-push -gate), deciding the version number, the when-to-release decision, -attribution trailers of any kind. - ---- - ## OUTPUT — end with exactly this report (your final message) ``` RELEASE-EXEC REPORT -SPAN : prep | finish +SPAN : prep STATUS : DONE | NEED-DECISION | BLOCKED -BRANCH : for prep | main for finish> -TAG : | n/a — prep never tags> -TESTS : +BRANCH : release/ +TAG : n/a — prep never tags +TESTS : NOTES : ``` diff --git a/skills/capitalize/SKILL.md b/skills/capitalize/SKILL.md index d7165c1..23d6b79 100644 --- a/skills/capitalize/SKILL.md +++ b/skills/capitalize/SKILL.md @@ -331,7 +331,7 @@ Skip this step entirely (go to STEP 6, which prints the hold note) on Otherwise, from the `chore/` branch, THREE separate Bash calls, never combined. INVARIANT: no `git push` inside any Bash call of this skill (push-guard reads command text; the lib pushes develop itself in auto-push mode). The hints that tell the USER what to type (`! git push …`) are prose, kept on single lines. -1. `bash "$HOME/.claude/lib/gitflow.sh" finish chore ` — merge → develop, delete branch, push develop in auto-push mode. rc≠0 → go to STEP 6 with the `finish failed` line (rc 1/4 skip calls 2-3; rc 5/2/6 with the ancestor check true still run them so the push state is reported): rc 4 = conflict, develop mid-merge, `chore/` kept, NOT merged; rc 1 = checkout failed, NOT merged; rc 5/2/6 come from the delete AFTER the merge: check `git merge-base --is-ancestor chore/ develop` and report `merged, branch not deleted (rc )` when it holds, `NOT merged` otherwise. Never say "merged" without that check. +1. `bash "$HOME/.claude/lib/gitflow.sh" finish chore ` — merge → develop, delete branch, push develop in auto-push mode. rc≠0 → go to STEP 6 with the `finish failed` line (rc 1/4 skip calls 2-3; rc 5/2/6 with the ancestor check true still run them so the push state is reported): rc 4 = conflict, develop mid-merge, `chore/` kept, NOT merged; rc 1 = checkout failed, NOT merged; rc 5/2/6 come from the delete AFTER the merge: check `git merge-base --is-ancestor chore/ develop` and report `merged, branch not deleted (rc )` when it holds, `NOT merged` otherwise. Never say "merged" without that check. Finish prompt declined (the ask rule on `gitflow.sh finish`) → nothing merged, the chore branch kept: report it, never retry the finish in another form. 2. `bash "$HOME/.claude/lib/gitflow.sh" push-mode` → `auto | manual | invalid` (stderr names an invalid value). 3. `git rev-list --count origin/develop..develop 2>/dev/null || echo unknown` → `ahead` (0 = on origin; `unknown` = no origin/develop ref, e.g. no origin remote). @@ -355,7 +355,7 @@ CAPITALIZE COMPLETE — () TODO.md : checked , added journal.md : +1 line under ## committed : (chore(memory): …) | ⚠️ NOT committed (rc 3 — see closing line) - persisted : develop pushed | merged, manual push mode: not pushed | merged, not on origin (no origin/develop) | merged, push FAILED | merged, autopush invalid, nothing pushed ( behind) | merged, autopush invalid, pushed anyway (stale hook or manual push) | finish rc , not merged | merged, branch not deleted (rc ) | on chore/, not merged (--no-push) + persisted : develop pushed | no (finish prompt declined, branch kept) | merged, manual push mode: not pushed | merged, not on origin (no origin/develop) | merged, push FAILED | merged, autopush invalid, nothing pushed ( behind) | merged, autopush invalid, pushed anyway (stale hook or manual push) | finish rc , not merged | merged, branch not deleted (rc ) | on chore/, not merged (--no-push) dropped as already-captured: LRN-023, BLK-006 ignored as noise: push/tag release ``` diff --git a/skills/release-candidate/SKILL.md b/skills/release-candidate/SKILL.md index 4437664..3c74165 100644 --- a/skills/release-candidate/SKILL.md +++ b/skills/release-candidate/SKILL.md @@ -20,14 +20,15 @@ Turns the accumulated work on `develop` into a tagged release on `main`. THIN OR **Division of labour (lib = mechanic, skill = judgment):** the tag lives HERE, not in `gitflow.sh`, because it is release-specific (version + message + human decision) while the lib's fan-out is generic. **Consequence (accepted):** a release cut by calling `gitflow finish` directly, bypassing this skill, fans out but is NOT tagged — `/release-candidate` is the canonical release path. -The two mechanical spans (prep, finish+tag) run on the sonnet-pinned -`release-executor` subagent (dispatch makes the pin effective) — no model -gate needed here, dispatch does the job. This dispatcher keeps everything -the executor must never own: the version-NUMBER decision (judgment — derives -from semver change nature), and the two human gates (when to release, and +The prep span runs on the sonnet-pinned `release-executor` subagent +(dispatch makes the pin effective) — no model gate needed here, dispatch +does the job. This dispatcher keeps everything the executor must never own: +the version-NUMBER decision (judgment — derives from semver change nature), +the finish and tag (STEP 5, main loop), and the two human gates (when to +release, and the tag push (auto-push mode; in manual push mode the user pushes main, -develop and the tag in one command)). A human gate sits BETWEEN the two -spans by construction, so the executor is never dispatched twice in one call. +develop and the tag in one command)). A human gate sits between the prep +span and the finish (STEP 4), so the executor is never dispatched twice. ## When to use - `develop` is ahead of `main` and you want to publish a version. @@ -40,7 +41,7 @@ Not for: integrating a feature/bugfix → `gitflow finish` (via /ship-feature). - The number DERIVES from the change nature (semver), not the reverse: a migration-requiring/breaking change → MAJOR; new features → MINOR; fixes → PATCH. Personal repo ⇒ "breaking" = requires a migration of your own usage. Decide the number BEFORE running. ## Flow -**REQUIRED:** `lib/gitflow.sh` (the release mechanic, via the `release-executor` subagent). Clean tree, identity set, `develop` ahead of `main`. +**REQUIRED:** `lib/gitflow.sh` (the release mechanic; the `release-executor` subagent runs the prep only). Clean tree, identity set, `develop` ahead of `main`. ### STEP 1 — Preconditions ```bash @@ -84,16 +85,19 @@ Proceed only on an explicit human go. **Never fire on "tests pass"** — a green suite means ready to release, not authorized to. `hold` → stop here; the prepped `release/` branch stays as-is for a later run. -### STEP 5 — Dispatch: finish + tag +### STEP 5 — Finish + tag (main loop) +The finish runs HERE: the `ask` rule on `gitflow.sh finish` prompts, and a +sub-agent cannot put that prompt to you (BLK-018 option b). +```bash +git branch --show-current # must print release/, else STOP +bash "$HOME/.claude/lib/gitflow.sh" finish ``` -Agent(subagent_type="release-executor") -prompt: "SPAN: finish " +Prompt declined → nothing merged, the release branch kept: say so and STOP. +A merge conflict → STOP, surface it verbatim (a human call). Then, on main: +```bash +git tag -a v main -m "release " ``` -Parse the `RELEASE-EXEC REPORT`: -- `STATUS: DONE` → continue to STEP 6, carrying the `TAG` value forward. -- `STATUS: BLOCKED` → surface the blocker verbatim (e.g. a merge conflict - the fan-out hit), STOP — resolving a conflicted fan-out is a human call, - not an auto-retry. +The tag stays local until STEP 6. Carry `TAG=v` forward. ### STEP 6 — Tag push GATE (ASK) Read the state, separate Bash calls: