/finish — Branch Completion Protocol

/finish — Branch Completion Protocol

The gap between "code works" and "branch is ready" is where quality lives. This protocol ensures branches are clean, tested, and reviewable.

Invocation

/finish patch [target-branch]    # Verify, clean, bump patch, ship
/finish minor [target-branch]    # Verify, clean, bump minor, ship
/finish major [target-branch]    # Verify, clean, bump major, ship

Default target: main.

Protocol

1. Verify Completeness

Run /pds:verify first. Do not proceed until it passes.

2. Rebase onto Target

Ensure your branch is current with the target:

git fetch origin
git rebase origin/main    # or target branch

Resolve any conflicts. Each conflict resolution should maintain both sides' intent — don't blindly accept one side.

3. Clean Commit History

Review your commits:

git log --oneline main..HEAD

If there are fixup commits or WIP entries, squash them non-interactively:

# Squash all branch commits into one clean commit
git reset --soft origin/main
git commit -m "feat(scope): descriptive message"

# Or use autosquash for commits prefixed with fixup!/squash!
git rebase --autosquash origin/main

Each commit should be atomic and meaningful. Use conventional commit format: <type>(<scope>): <subject>. Types: feat, fix, refactor, test, docs, chore, perf. Subject in imperative mood, max 72 chars. Body explains what and why, not how.

Do NOT use git rebase -i — interactive rebase requires terminal input and will hang in agent contexts.

4. Run Tests Post-Rebase

Tests must pass after rebase, not just before:

# Run full test suite again
npm test    # or equivalent

Rebasing can introduce subtle breakage — verify.

5. Permission Audit

Review .claude/settings.local.json for permission patterns that should be promoted to .claude/settings.json:

1. Read both files
2. Identify glob-style allow patterns in local (e.g., Bash(git *:*), Bash(gh *:*), tool names) that aren't already in project settings
3. Exclude one-off entries (specific file paths, session-specific rm commands, temp artifacts)
4. If promotable patterns exist, add them to .claude/settings.json permissions.allow and remove from settings.local.json
5. If no promotable patterns exist, skip — do not modify either file

This ensures permission improvements ship with the code rather than accumulating silently in local settings.

6. Extract Knowledge

If .claude/swarm/ exists in the current worktree, preserve ephemeral state as its own commit before shipping:

1. Archive artifacts to git. Copy all *.md files from .claude/swarm/ to docs/swarm-reports/<YYYY-MM-DD-HHmm>/:

   REPORT_DIR="docs/swarm-reports/$(date +%Y-%m-%d-%H%M)"
   mkdir -p "$REPORT_DIR"
   cp .claude/swarm/*.md "$REPORT_DIR/"
   git add "$REPORT_DIR"
   git commit -m "chore: archive swarm artifacts to docs/swarm-reports"
   

2. Distill to auto-memory. Review the archived artifacts and write 1-2 auto-memory entries (project or feedback type) capturing:
   • WHY key decisions were made and what alternatives were rejected
   • Surprising findings or constraints discovered during the swarm
   • Skip anything derivable from code, git history, or existing docs

Auto-memory writes happen outside git (under ~/.claude/projects/) and survive worktree removal automatically.

Extraction lives here — after the branch is clean and audited, before ship — so the archive commit is atomic and reviewable in the PR, never mixed into a verify/rebase/clean step. If .claude/swarm/ does not exist, skip to Step 7.

7. Ship

Bump, commit, push, and create/update PR.

Protected branch check. Before pushing, check if the target branch is protected:

1. Read CLAUDE.md for a Protected Branches section listing branch patterns (e.g., main, release/*)
2. If the current branch or push target matches a protected pattern, prompt the user for confirmation before pushing
3. If no Protected Branches section exists in CLAUDE.md, no branches are protected — push freely

7a. Commit Work

If uncommitted changes exist (staged or unstaged):

• Stage changes: git add relevant files (not -A — be deliberate)
• Commit with provided message, or derive from branch name and changes
• Use conventional commit format: <type>(<scope>): <subject>

If working tree is clean, skip to 7b.

7b. Detect Bump Type (if not specified)

If no bump type was passed, scan git log since the last version tag:

git log $(git describe --tags --abbrev=0 2>/dev/null)..HEAD --oneline 2>/dev/null || git log --oneline

Apply the highest-precedence rule found:

Commit prefix	Bump type
BREAKING CHANGE in body, or ! after type (e.g. feat!:)	major
feat:	minor
fix:, perf:, refactor:, etc.	patch

Default to patch if no conventional commits found.

7c. Bump Version

Follow /pds:bump protocol:

1. Detect version file (VERSION, package.json, etc.)
2. Calculate new version based on bump type
3. Update version file(s) + CHANGELOG.md
4. Commit: chore: bump version to X.Y.Z

7d. Push and PR

git push origin HEAD
gh pr create --fill    # Create if none exists
gh pr view             # Show existing PR

Work commit is separate from bump commit — clean git history.

7e. Resolve Tracking Issue

Experimental — off by default. Steps 7e and 7f only run when PDS_DIARY=1 (or PDS_DIARY=on) is set in the environment. Without the flag, skip straight to Cleanup — the diary pipeline will not fire and legacy branches will not be prompted for renames. Enable per-invocation with PDS_DIARY=1 /pds:finish ..., or export in your shell rc to keep it on.

Also fires automatically at session end. When PDS_DIARY=1 is set, a SessionEnd hook (hooks/scripts/diary-session-end.sh) posts the diary for you using the canonical transcript_path handed down by Claude Code. Manual invocation from /pds:finish remains supported for ship-time diaries — both paths end up editing the same canonical comment keyed off the <!-- pds:diary --> marker, so re-fires are idempotent.

case "${PDS_DIARY:-}" in
  1|on|true|yes) ;;
  *) echo "dev-diary disabled (set PDS_DIARY=1 to enable)"; exit 0 ;;
esac

Parse the issue number from the branch name. The canonical pattern is <type>/<issue>-<slug> (see /pds:worktree issue-tied creation):

BRANCH="$(git branch --show-current)"
ISSUE="$(echo "$BRANCH" | sed -nE 's|^[a-z]+/([0-9]+)-.*|\1|p')"

Legacy branches (no issue encoded). If $ISSUE is empty:

1. Prompt the user: "This branch doesn't encode a tracking issue. Issue number for the diary, or skip?"
2. If they supply a number, rename the branch in place:

   NEW_BRANCH="<type>/<N>-$(echo "$BRANCH" | sed -E 's|^[a-z]+/||' | tr '/ ' '--')"
   git branch -m "$NEW_BRANCH"
   git push origin -u "$NEW_BRANCH" :"$BRANCH" 2>/dev/null || git push origin -u "$NEW_BRANCH"
   BRANCH="$NEW_BRANCH"; ISSUE="<N>"
   

3. If they say skip, proceed to 7f with an empty $ISSUE; the diary step will be skipped with a note.

7f. Post Dev Diary

If $ISSUE is set, invoke the diary assembler:

BRANCH="$BRANCH" ISSUE="$ISSUE" MODE=post bash "$CLAUDE_PLUGIN_ROOT/scripts/assemble-diary.sh"

The script:

• Derives a Summary from commit subjects, a Timeline from commit timestamps, and "What went well / wrong" from instincts, auto-memory, commit signals (fixups/reverts), and ★ Insight blocks parsed out of the raw transcript.
• Wraps the full export-session.sh output inside a collapsed <details> block.
• Looks up an existing diary comment on the issue by a stable <!-- pds:diary --> marker. If found, edits in place; otherwise posts a new comment (single canonical comment per issue).
• On gh failure, writes the assembled document to $TMPDIR/pds-diary-<issue>-<ts>.md and surfaces the path. Never silently swallows.

If $ISSUE is empty (user chose skip), skip this step and report it plainly.

Cleanup

After the branch is merged:

• Remove the worktree: git worktree remove .worktrees/branch-name
• Delete the branch: git branch -d branch-name
• Close related issues
• Update task status via TaskUpdate if working as a team agent

When to Use

Situation	Skill
Formal ship: verify, rebase, clean, bump, push	/finish
Quick ship: bump, commit, push	/pds:checkpoint
Version bump only (no push)	/pds:bump
Verify before shipping	/pds:verify then /finish

After Shipping

After shipping, consider running /pds:pause — shipping is a natural break point. It saves session state so you can resume cleanly in the next session.

See Also

• /pds:bump — version bump details
• /pds:verify — completion self-check (step 1)
• /pds:pause — save session state before stepping away