#194 - Post-merge worktree cleanup — auto-delete on PR merge - ldraney/claude-custom

forgejo_admin commented

2026-03-28 04:38:59 +00:00

Contributor

Type

Feature

Lineage

Standalone — scoped during worktree lifecycle enforcement brainstorm (2026-03-28).
Spec: pal-e-platform/docs/superpowers/specs/2026-03-28-worktree-lifecycle-enforcement-design.md
Plan: pal-e-platform/docs/superpowers/plans/2026-03-28-worktree-lifecycle-enforcement.md — Task 2

Repo

forgejo_admin/claude-custom

User Story

As a session operator,
I want merged worktrees to be automatically deleted when a PR merges,
So that stale worktrees don't accumulate on disk.

Context

After PR merge, agent sessions are over but worktrees persist in .claude/worktrees/. Current cleanup is age-based (>7 days via SessionStart hook). The merge event is the natural cleanup trigger. 700MB incident on 2026-03-13 from accumulated stale worktrees. Both post-merge hooks already fast-forward local main — extending them with worktree cleanup is the minimal change.

File Targets

Files the agent should modify:

hooks/post-merge-rebase.sh — add worktree cleanup after existing fast-forward (gh path: gh pr view for branch name)
hooks/post-mcp-merge-rebase.sh — add worktree cleanup after existing fast-forward (MCP path: Forgejo API for branch name)

Files the agent should NOT touch:

hooks/cleanup-worktrees.sh — separate safety net hook, handled by different ticket
settings.json — no new registrations needed

Acceptance Criteria

gh path: extracts PR number from command, uses gh pr view to get head branch name
MCP path: extracts owner/repo/pull_number from tool_input, uses Forgejo API to get head branch
Walks git worktree list --porcelain, finds worktree on merged branch
Removes matching worktree via git worktree remove --force
Deletes local branch ref via git branch -D
Logs: [post-merge-cleanup] Removed worktree for branch <name> at <path>
Best-effort: silent exit if no matching worktree found
Existing fast-forward logic unchanged

Test Expectations

Manual: pipe mock gh merge JSON, verify no errors (cleanup is best-effort)
Manual: pipe mock MCP merge JSON, verify no errors
Manual: verify existing fast-forward still works after changes
Run command: echo '{"tool_input":{"command":"gh pr merge 207 --admin --squash"},"tool_response":{"exitCode":"0"},"cwd":"/home/ldraney/pal-e-platform"}' | bash hooks/post-merge-rebase.sh

Constraints

MCP path needs Forgejo token from $HOME/secrets/pal-e-services/forgejo.env — verify env var name before using
Cleanup logic goes AFTER existing fast-forward, BEFORE final exit 0
Must handle porcelain output with and without trailing blank line
Follow existing hook patterns in both files

Checklist

PR opened
Tests pass
No unrelated changes

project-pal-e-agency — agent infrastructure project
worktree-workflow — SOP this enforces

### Type Feature ### Lineage Standalone — scoped during worktree lifecycle enforcement brainstorm (2026-03-28). Spec: `pal-e-platform/docs/superpowers/specs/2026-03-28-worktree-lifecycle-enforcement-design.md` Plan: `pal-e-platform/docs/superpowers/plans/2026-03-28-worktree-lifecycle-enforcement.md` — Task 2 ### Repo `forgejo_admin/claude-custom` ### User Story As a session operator, I want merged worktrees to be automatically deleted when a PR merges, So that stale worktrees don't accumulate on disk. ### Context After PR merge, agent sessions are over but worktrees persist in `.claude/worktrees/`. Current cleanup is age-based (>7 days via SessionStart hook). The merge event is the natural cleanup trigger. 700MB incident on 2026-03-13 from accumulated stale worktrees. Both post-merge hooks already fast-forward local main — extending them with worktree cleanup is the minimal change. ### File Targets Files the agent should modify: - `hooks/post-merge-rebase.sh` — add worktree cleanup after existing fast-forward (gh path: `gh pr view` for branch name) - `hooks/post-mcp-merge-rebase.sh` — add worktree cleanup after existing fast-forward (MCP path: Forgejo API for branch name) Files the agent should NOT touch: - `hooks/cleanup-worktrees.sh` — separate safety net hook, handled by different ticket - `settings.json` — no new registrations needed ### Acceptance Criteria - [ ] gh path: extracts PR number from command, uses `gh pr view` to get head branch name - [ ] MCP path: extracts owner/repo/pull_number from tool_input, uses Forgejo API to get head branch - [ ] Walks `git worktree list --porcelain`, finds worktree on merged branch - [ ] Removes matching worktree via `git worktree remove --force` - [ ] Deletes local branch ref via `git branch -D` - [ ] Logs: `[post-merge-cleanup] Removed worktree for branch <name> at <path>` - [ ] Best-effort: silent exit if no matching worktree found - [ ] Existing fast-forward logic unchanged ### Test Expectations - [ ] Manual: pipe mock gh merge JSON, verify no errors (cleanup is best-effort) - [ ] Manual: pipe mock MCP merge JSON, verify no errors - [ ] Manual: verify existing fast-forward still works after changes - Run command: `echo '{"tool_input":{"command":"gh pr merge 207 --admin --squash"},"tool_response":{"exitCode":"0"},"cwd":"/home/ldraney/pal-e-platform"}' | bash hooks/post-merge-rebase.sh` ### Constraints - MCP path needs Forgejo token from `$HOME/secrets/pal-e-services/forgejo.env` — verify env var name before using - Cleanup logic goes AFTER existing fast-forward, BEFORE final `exit 0` - Must handle porcelain output with and without trailing blank line - Follow existing hook patterns in both files ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `project-pal-e-agency` — agent infrastructure project - `worktree-workflow` — SOP this enforces

forgejo_admin commented

2026-03-28 04:48:32 +00:00

Author

Contributor

Scope Review: READY

Review note: review-508-2026-03-27
Scope is solid — all template sections present, both file targets verified (post-merge-rebase.sh line 66, post-mcp-merge-rebase.sh line 62), traceability triangle complete, no blocking dependencies among 4 related worktree tickets, and blast radius is low (leaf hooks, cleanup-worktrees.sh correctly excluded). 8 AC are tightly coupled (same pattern in two files), fits single agent pass.

## Scope Review: READY Review note: `review-508-2026-03-27` Scope is solid — all template sections present, both file targets verified (post-merge-rebase.sh line 66, post-mcp-merge-rebase.sh line 62), traceability triangle complete, no blocking dependencies among 4 related worktree tickets, and blast radius is low (leaf hooks, cleanup-worktrees.sh correctly excluded). 8 AC are tightly coupled (same pattern in two files), fits single agent pass.