Finishing a Branch
Take the state under check (the script calls it the candidate) or a named PR through one branch transition the user chooses. Green checks and "seems done" authorize no change to history or to a remote, and no discard or cleanup.
When to use
- Present the permitted choices even without a Git request.
- Skip ordinary mid-development checkpoints;
using-git-worktreesowns those. Skip an unchanged state with an already settled branch choice unless the user requests another transition.
Available scripts
scripts/branch-state.sh— the local git state as JSON, read-only.--helpdocuments its fields and exit codes.
Step 1: Read the state
Run the script and keep its output; if it exits non-zero, stop and report. Use its numbers verbatim later; never hand-count commits.
bash scripts/branch-state.shIdentify the requested transition. If it is an explicit keep-as-is, discard, or PR-only close or reopen, apply that action's identity, ownership, and authority rules below; readiness evidence is not an entry condition for those actions.
For materialization (committing the reviewed working tree), publication, or integration, bind the
verification-before-completionevidence record (the ledger: add to it, never rewrite it) and therequesting-code-reviewverdict (shallowself-reviewed: ready, or the required independent review with no blocker) to one identity for the state under check: the full revision when the script reportsdirty.clean: true, the working-tree hash (dirty.digest) otherwise. Bind the live remote or PR state as well.If a required readiness verdict is missing, keep the requested action pending; offer keep-as-is or obtain the missing review under current authority.
For a PR-only close or reopen, record the live PR, its head and base refs, and the resources that stay in place.
List the resources this task created (branch, worktree, remote ref, PR) from the
using-git-worktreesworkspace record. Only those may be cleaned up. A task-looking path proves nothing.For publication or integration, read
base.resolved. If it isfalse, resolve the base before acting. A direct instruction, the project's contribution rules, or the base theusing-git-worktreesworkspace record holds override the detected default; pass that base as--base, and a PR targets it. Check remote freshness yourself; the script does not fetch. If the base is stale, has moved, or is ambiguous, do not integrate.Read
candidate.published. If it istrueornull, or afalseread from remote-tracking refs that were not refreshed under the network authority you hold now, get separate direct permission for each of squash, rebase, and amend. Never force-push as a repair. After any history change, rerun the script; if the content moved, go back torequesting-code-review.For PR creation or update, prepare the description from the project's contribution rules and the template the base branch carries; if there is none, open
assets/pr-description.mdbefore writing it. Fill the evidence fields only from the bound ledger and verdict; add whichever of the check results, the review verdict, and what was not verified the project's template has no place for.
Step 2: Present the choices
Read
references/branch-state.mdbefore preparing the transition descriptor that applies. If a direct instruction, or a trusted receipt, already covers the descriptor's current targets, action, and payload, record that choice and go on to Step 3. Otherwise, offer only the entries the state permits, then stop (Gates:summarizes the checks bound in Step 1.3):Branch {{branch}} → {{base}}. Gates: {{summary}}. Review: {{verdict}}. 1. Commit and keep 2. Push the branch 3. Push and open a PR 4. Integrate locally into {{base}} 5. Keep as-is Recommendation: {{least-mutating option meeting the stated delivery intent}} — {{one sentence}}.If the workspace is detached or host-owned, offer only publish as a new branch and keep as-is.
If a PR already exists, offer only the transitions its state and its policy permit: for a merged PR, clean up owned resources or keep as-is. Never conflate, retarget, rewrite, delete, or duplicate a PR.
Never put discard on this menu.
Wait for one listed entry. If the reply is praise, a constraint, a partial answer, silence, "looks good", or a decision about something adjacent, present the menu again unchanged.
Bind the answer to a descriptor prepared for that entry. If the target or payload changes materially, show the changed choice; do not reuse the approval given for the old one.
Step 3: Execute
- Read
references/branch-state.mdbefore executing, and execute through it. - Run the required checks on the exact integrated result before the base
advances. A failure after the advance is an
integrated-regression; follow the reference's recovery for it. - Remove an owned worktree only after confirmed integration. Leave detached, shared, user-owned, and host-owned resources in place.
- REQUIRED SUB-SKILL: if a releasable or running artifact is
involved, invoke
release-readiness. Canary, deploy, publish, and distribute are its verdict, not this skill's.
Discard is a separate destructive path
Enter only on a direct request. Never offer discard because work looks unwanted.
Rerun
bash scripts/branch-state.sh --fullbefore filling the block. Ifbase.resolvedis false, take the base theusing-git-worktreesworkspace record holds, or get it from the user or the project, rerun with--base, and fill nothing until it resolves. Then fill the block from the output and print it:This will permanently delete: - Branch {{name}} ({{n}} unique commits: {{list}}) - Staged {{n}}, unstaged {{n}}, untracked {{n}} changes - Ignored {{n}}: {{list}} (lost only with a removed worktree; never recoverable) - Worktree {{path}}; remote {{live state}}; PR {{live state}} Recovery: {{possible | not possible}} Recommendation: {{preserve unless current authority clearly calls for deletion}}. Type `discard {{candidate.id}}` to confirm.Stop. If the reply is "yes", "go ahead", "get rid of it", or a numbered or clicked choice, touch nothing.
Only after that exact token, rerun the same command. A changed
candidate.id, a non-zero exit, or nocandidate.idvoids the token. Otherwise close or delete the listed task-owned resources, and nothing else.
Gotchas
- A local-only repository has no resolvable base: its commit counts are
null, not 0, and a block filled from them hides commits. - A tip-only check, a branch's own upstream taken as its base, or stale remote-tracking refs each read pushed history as unpublished.