finishing-a-development-branch

name	finishing-a-development-branch
description	Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup

Finishing a Development Branch

Core principle: check phase -> review discipline confirmed -> final test gate -> verification evidence -> complete -> durable evidence commit -> delivery options.

Announce at start: "I'm using the finishing-a-development-branch skill to complete this work."

For "profile": "lite" tasks: same check-phase final verification and durable evidence contract. After completion, offer once to generate or refresh the tester handoff (superharness:to-tester {task}) and the developer report (superharness:to-coder {task}); if both are declined, finish. Skip the full option menu (Steps 5-8). Worktree cleanup (Step 9) applies only if a worktree was actually created.

Step 1: Confirm Check Inputs

Read task.json first. On the normal path the task is still in check when finishing starts. Entry discipline — all three must hold, or return to the Final Check in superharness:subagent-driven-development first:

• The two-axis review reports were produced in this session (rerun one two-axis review if the session lost them).
• Every Critical/Major finding is resolved.
• Every code commit after the reviewed HEAD has a fix-diff recheck verdict.

Recovery is phase-aware:

• In check, when verification.md already records this same Verified Implementation HEAD with every command passing, resume at Step 4 without rerunning the full gate.
• In complete, when completion changed only task.json and trace.jsonl and the matching successful verification.md is still uncommitted, resume the Step 4 evidence commit.
• In complete otherwise, run superharness task evidence {task} --json; a valid chain continues to delivery options. Any other phase or evidence shape stops for diagnosis.

For a new verification run: git rev-parse HEAD is the Verified Implementation HEAD; it must equal the review's effective HEAD. Base comes from implementation.base_sha. Confirm every implementation, test, documentation, and configuration change is committed; the only permitted dirty paths are the task's task.json, trace.jsonl, and an existing verification.md. Any other dirty path returns through check → implement for a tested implementation commit.

Step 2: Run the Final Test Gate

Run the project's full non-E2E gate exactly once for the captured HEAD: the full unit/integration suite plus configured typecheck, lint, skill validation, and build commands, plus every task's focused verification command and every verified slice's declared gate (independent integration commands, E2E cases, contract checklist items), deduplicated and executed or confirmed once each. QA remains an optional delivery step.

Record one global superharness task observe {task} verification-start --detail full immediately before the first command. After every command passes, close with one verification-pass. On a command failure record verification-fail --detail "<failed command>"; on an environment error record verification-error --detail "<error>". One global pair per attempt.

Before running tests, clean up leftover E2E processes from a previous QA run:

if [ -f ".superharness/tasks/{task}/.e2e-app.pid" ]; then
  superharness e2e stop-app --pid-file .superharness/tasks/{task}/.e2e-app.pid --port {port}
  agent-browser close 2>/dev/null || true
fi

Capture every exact command, exit code, and concise result. Do not reuse results from focused tests or the review session.

If any command fails: superharness task transition {task} implement, fix through TDD, commit, superharness task transition {task} check, recheck the fix diff (do not repeat the full two-axis review), then invoke finishing again for a new full gate.

Step 3: Replace Verification Evidence

Rewrite .superharness/tasks/{task}/verification.md for every new verification run, including a failed one, so it describes only this HEAD and this run. Use this exact schema:

# Verification

- Timestamp: <ISO>
- Verified Implementation HEAD: <sha>
- Base: <sha>

## Commands

- `<exact command>`: exit <code>; <concise result>

## Final Review

- Two-axis outcome and resolved Critical/Major findings; remaining Minor findings.
- Reviewed HEAD: <sha>
- Post-review fix commits, each with its fix-diff recheck verdict, or `None`.
- Effective HEAD: <sha> (must equal the Verified Implementation HEAD)

## QA Evidence

- Revision-bound QA run, verdict, decision, or `Not run`.

## Unverified

- Items not covered by the commands or review, or `None`.

## Known Risks

- Remaining risks, or `None`.

Read the file back and confirm it matches the current run. Any repair invalidates prior evidence and requires one new full gate.

Step 4: Complete and Commit Durable Evidence

Only after every command passes:

superharness task transition {task} complete
git add -- .superharness/tasks/{task}/task.json .superharness/tasks/{task}/trace.jsonl .superharness/tasks/{task}/verification.md
git diff --cached --name-only
git commit -m "chore(workflow): record final verification evidence"

The staged diff must contain exactly those three task files. Every descendant of the Verified Implementation HEAD may touch only them. Then run superharness task evidence {task} --json; the chain must report the recorded implementation HEAD with only evidence-only descendants. Do not offer delivery choices until the chain is valid and the worktree is clean. Then read task.json, verification.md, Git, optional QA evidence, and trace.jsonl; run superharness trace --task {task}.

Step 5: Determine Base Branch

git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

Or ask: "This branch split from main -- is that correct?"

Step 6: Determine Optional QA Availability

QA is a user-selected post-complete action, never a completion gate. Set qaAvailable=true only when .superharness/tasks/{task}/e2e-cases.yaml exists or .superharness/config.yaml has at least one enabled qa.services entry.

Step 7: Present Options

Implementation complete. Reviewed .superharness/tasks/{task}/trace.jsonl.

What would you like to do?

1. Run QA verification (includes discovered E2E)
2. Generate or refresh tester handoff
3. Generate or refresh developer report
4. Merge back to <base-branch> locally
5. Push and create a Pull Request
6. Keep the branch as-is (I'll handle it later)
7. Discard this work

Which option?

When qaAvailable=false, omit item 1 and renumber. Keep options concise.

Step 8: Execute Choice

• Run QA: superharness qa --task .superharness/tasks/{task}. Pass or accept-risk transitions back to complete, creates an evidence-only commit, validates task evidence, then returns to Step 7. A fix decision: persist it, transition to implement, land the repair commit, transition to check, recheck the fix diff, run fresh non-E2E verification, complete with a new evidence chain, then automatically rerun QA without asking.
• Tester handoff: invoke superharness:to-tester {task}, then return to Step 7.
• Developer report: invoke superharness:to-coder {task}, then return to Step 7.
• Merge locally: checkout the base branch, pull, merge, verify tests on the merged result, delete the feature branch, then clean up the worktree (Step 9).
• Push and create PR: git push -u origin <branch>, then gh pr create with a summary, evidence summary (task item commits, final review, verification commands), and test plan. Clean up the worktree (Step 9).
• Keep as-is: report "Keeping branch . Worktree preserved at ." Do not clean up. The task stays completed — that is correct even though the branch persists.
• Discard: confirm first with the exact typed word discard (or 确认丢弃), listing the branch, commits, and worktree to delete. If confirmed: checkout the base branch, git branch -D <branch>, then in the base checkout run superharness task transition {task} discarded (a terminal status like completed), and clean up the worktree (Step 9).

Step 9: Cleanup Task Worktree

For Merge, Create PR, and Discard: git worktree remove <worktree-path>. For Keep as-is, QA, tester handoff, and developer report: keep the worktree — the user's delivery choice controls the single task checkout.

Red Flags

Never:

• Proceed with failing tests, or merge without verifying tests on the result
• Report completion without durable evidence: a valid task evidence chain plus task.json, verification.md, Git, QA, and trace.jsonl read back
• Present options while workflow evidence is uncommitted or the worktree is dirty
• Treat E2E cases as a completion prerequisite
• Delete work without typed confirmation, or force-push without explicit request
• Bind evidence to a HEAD whose post-review commits lack fix-diff rechecks