Clean up merged worktrees and branches with one command

[taspinar]

What changed

• ./scripts/cleanup-worktree.sh <issue-number> finds the worktree of feature/<issue>-*; planning/<name> finds a planning worktree; a path keeps working, for any branch.
• It runs only from the primary checkout and asks GitHub whether the branch's pull request is merged, so it also works after a squash merge.
• It refuses an unmerged worktree, a branch with commits after its merged pull request head, and a worktree with uncommitted changes. Ignored review and triage files do not block it.
• After a merge it removes the worktree and the local branch, prunes worktree metadata, and fast-forwards main in a clean primary checkout of main (otherwise it fetches and says so).
• --merged removes every merged worktree and lists the kept ones with the reason; --discard removes an unmerged worktree after confirmation.
• A failed removal or branch deletion is reported as an error with a non-zero status.
• finish-feature.sh and finish-planning.sh mention the cleanup step; README, docs/development.md, docs/workflow.md, docs/example.md, and docs/project-map.md use the new form.

Issue / acceptance criteria

Closes #56

Risk

• Low
• Medium
• High

Verification evidence

• ./scripts/verify.sh passed, also without global or system Git configuration
• Tests added/updated where appropriate (tests/cleanup-worktree-test.sh with real worktrees and squash merges on a local remote, also passing under macOS system bash 3.2)
• Independent review completed when required
• Architecture/docs/ADR updated when required

Independent review: Codex (gpt-6-astra), read-only. CHANGES REQUIRED:

• M1 (a failed removal reported success, because the cleanup runs in a condition that disables errexit): fixed; every destructive step checks its status and failures exit non-zero. Tested with a locked worktree; a failing branch deletion is handled the same way but not separately tested.
• MIN1 (the primary-checkout rule was not enforced): fixed, with a test from a linked worktree.
• MIN2 (paths only worked for feature and planning branches): fixed, with a fix/ branch test.

Not re-reviewed after the fixes.

Agent involvement

Planner: —
Implementer: Claude (Opus 5.5)
Reviewer: Codex (gpt-6-astra)

Production impact

None.

🤖 Generated with Claude Code