fix(release,capitalize): finish runs in the main loop under the ask prompt; a declined prompt stops the flow (BLK-018 b)

This commit is contained in:
bchanot committed 2026-11-02 18:45:26 +01:00
1 parent dc780efb65
commit 536d39e811
3 files changed
+35 -63

No files matched your search

+13 -45
View File
@@ -1,28 +1,25 @@
--- ---
name: release-executor 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 tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet model: sonnet
effort: low effort: low
--- ---
# RELEASE-EXECUTOR — mechanical release spans # RELEASE-EXECUTOR — mechanical release prep
You execute the mechanical parts of a gitflow release. The `/release-candidate` 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 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 release" decision, the finish, the tag and the tag push. It also owns the human
your two spans. You are dispatched fresh, once per span, never both in one gate that follows your span. You are dispatched fresh, once: after
call: after `SPAN: prep` reports, the dispatcher stops for a human go before `SPAN: prep` reports, the dispatcher stops for a human go.
it ever dispatches `SPAN: finish`.
## Dispatch spans ## Dispatch span
The dispatch prompt names exactly one span; do only that span's work, then The dispatch prompt names the span; do only that work, then stop and report.
stop and report — never chain into the other span yourself.
- `SPAN: prep <X.Y.Z>` — branch, version bump, CHANGELOG, test gate, commit. - `SPAN: prep <X.Y.Z>` — branch, version bump, CHANGELOG, test gate, commit.
No merge, no tag, no push. No merge, no tag, no push.
- `SPAN: finish <X.Y.Z>` — gitflow fan-out, then tag. Never push.
--- ---
@@ -65,44 +62,15 @@ when-to-release decision, attribution trailers of any kind.
--- ---
## SPAN: finish <X.Y.Z>
### Preconditions
Verify with `git branch --show-current` that you are on `release/<X.Y.Z>`
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/<X.Y.Z>` 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<X.Y.Z> main -m "release <X.Y.Z>"` (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) ## OUTPUT — end with exactly this report (your final message)
``` ```
RELEASE-EXEC REPORT RELEASE-EXEC REPORT
SPAN : prep <X.Y.Z> | finish <X.Y.Z> SPAN : prep <X.Y.Z>
STATUS : DONE | NEED-DECISION | BLOCKED STATUS : DONE | NEED-DECISION | BLOCKED
BRANCH : <release/<X.Y.Z> for prep | main for finish> BRANCH : release/<X.Y.Z>
TAG : <v<X.Y.Z> | n/a — prep never tags> TAG : n/a — prep never tags
TESTS : <verbatim suite result | n/a — finish never runs tests> TESTS : <verbatim suite result>
NOTES : <DONE: none | NEED-DECISION: exact question + options | NOTES : <DONE: none | NEED-DECISION: exact question + options |
BLOCKED: the blocker verbatim> BLOCKED: the blocker verbatim>
``` ```
+2 -2
View File
@@ -331,7 +331,7 @@ Skip this step entirely (go to STEP 6, which prints the hold note) on
Otherwise, from the `chore/<name>` 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. Otherwise, from the `chore/<name>` 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 <name>` — 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/<name>` 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/<name> develop` and report `merged, branch not deleted (rc <n>)` when it holds, `NOT merged` otherwise. Never say "merged" without that check. 1. `bash "$HOME/.claude/lib/gitflow.sh" finish chore <name>` — 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/<name>` 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/<name> develop` and report `merged, branch not deleted (rc <n>)` 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). 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). 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 — <YYYY-MM-DD> (<pre-wipe flush | session-close>)
TODO.md : checked <N>, added <M> TODO.md : checked <N>, added <M>
journal.md : +1 line under ## <date> journal.md : +1 line under ## <date>
committed : <mem_hash> (chore(memory): …) | ⚠️ NOT committed (rc 3 — see closing line) committed : <mem_hash> (chore(memory): …) | ⚠️ NOT committed (rc 3 — see closing line)
persisted : develop <short> pushed | merged, manual push mode: not pushed | merged, not on origin (no origin/develop) | merged, push FAILED | merged, autopush invalid, nothing pushed (<ahead> behind) | merged, autopush invalid, pushed anyway (stale hook or manual push) | finish rc <n>, not merged | merged, branch not deleted (rc <n>) | on chore/<name>, not merged (--no-push) persisted : develop <short> 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 (<ahead> behind) | merged, autopush invalid, pushed anyway (stale hook or manual push) | finish rc <n>, not merged | merged, branch not deleted (rc <n>) | on chore/<name>, not merged (--no-push)
dropped as already-captured: LRN-023, BLK-006 dropped as already-captured: LRN-023, BLK-006
ignored as noise: push/tag release ignored as noise: push/tag release
``` ```
+20 -16
View File
@@ -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. **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 The prep span runs on the sonnet-pinned `release-executor` subagent
`release-executor` subagent (dispatch makes the pin effective) — no model (dispatch makes the pin effective) — no model gate needed here, dispatch
gate needed here, dispatch does the job. This dispatcher keeps everything does the job. This dispatcher keeps everything the executor must never own:
the executor must never own: the version-NUMBER decision (judgment — derives the version-NUMBER decision (judgment — derives from semver change nature),
from semver change nature), and the two human gates (when to release, and 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, 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 develop and the tag in one command)). A human gate sits between the prep
spans by construction, so the executor is never dispatched twice in one call. span and the finish (STEP 4), so the executor is never dispatched twice.
## When to use ## When to use
- `develop` is ahead of `main` and you want to publish a version. - `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. - 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 ## 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 ### STEP 1 — Preconditions
```bash ```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; green suite means ready to release, not authorized to. `hold` → stop here;
the prepped `release/<X.Y.Z>` branch stays as-is for a later run. the prepped `release/<X.Y.Z>` 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/<X.Y.Z>, else STOP
bash "$HOME/.claude/lib/gitflow.sh" finish
``` ```
Agent(subagent_type="release-executor") Prompt declined → nothing merged, the release branch kept: say so and STOP.
prompt: "SPAN: finish <X.Y.Z>" A merge conflict → STOP, surface it verbatim (a human call). Then, on main:
```bash
git tag -a v<X.Y.Z> main -m "release <X.Y.Z>"
``` ```
Parse the `RELEASE-EXEC REPORT`: The tag stays local until STEP 6. Carry `TAG=v<X.Y.Z>` forward.
- `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.
### STEP 6 — Tag push GATE (ASK) ### STEP 6 — Tag push GATE (ASK)
Read the state, separate Bash calls: Read the state, separate Bash calls: