pal-e-docs
Project not found.

Review: Bug: stale agent worktrees accumulating across repos (re-review)

review-637-2026-03-28-v2 Doc

review approved
Project

Verdict: APPROVED

Re-review of board item #637. Previous review (review-637-2026-03-28) returned NEEDS_REFINEMENT with 5 BODY fixes. All 5 have been applied to the Forgejo issue body. No remaining issues.

Refinement Verification

# Recommendation Status
1 <code>[BODY]</code> Fix repo placement to claude-custom Applied. Repo section now reads: "Fix target: <code>forgejo_admin/claude-custom</code> (<code>hooks/cleanup-worktrees.sh</code>). pal-e-platform is the worst-affected repo but contains no fixable code."
2 <code>[BODY]</code> Fix worktree count from 31 to ~70 Applied. Body now shows detailed table with 64 + 2 + 1 + 1 = 68 stale dirs, ~1.8GB. Title still says "31" (cosmetic, not blocking).
3 <code>[BODY]</code> Add root cause to What Broke Applied. Root cause paragraph now explains <code>cleanup-worktrees.sh</code> only iterates <code>git worktree list --porcelain</code>, orphaned directories invisible, needs filesystem scan.
4 <code>[BODY]</code> Fix AC1 to generic wording Applied. AC1 now reads: "All stale worktree directories cleaned up across all repos."
5 <code>[BODY]</code> Replace "Claude Code's built-in worktree management" with forgejo-helper.sh Applied. File targets now list <code>hooks/cleanup-worktrees.sh</code> and <code>hooks/forgejo-helper.sh</code> (<code>remove_worktree_for_branch</code> function).

Template Completeness

Checked against template-issue-bug:
  • [x] Type -- Bug
  • [x] Lineage -- board, story, arch, discovery session documented
  • [x] Repo -- correctly identifies forgejo_admin/claude-custom as fix target
  • [x] What Broke -- detailed symptom table + root cause explanation
  • [x] Repro Steps -- 3 concrete steps with expected output
  • [x] Expected Behavior -- references cleanup hooks by name
  • [x] Environment -- archbox, worktree paths, related merged PRs
  • [x] File Targets -- 2 verified targets in claude-custom (bonus section)
  • [x] Acceptance Criteria -- 3 testable criteria
  • [x] Constraints -- 3 safety constraints (bonus section)
  • [x] Checklist -- 4 implementation steps (bonus section)
  • [x] Related -- 3 claude-custom PRs cited

Traceability

  • [x] story:superuser-deploy -- present on board item
  • [x] arch:worktree -- present on board item
  • [x] Forgejo issue -- forgejo_admin/pal-e-platform#243, open

File Targets

  • [x] hooks/cleanup-worktrees.sh -- verified at ~/claude-custom/hooks/cleanup-worktrees.sh. Line 48 uses git worktree list --porcelain as sole scan mechanism. Confirmed root cause.
  • [x] hooks/forgejo-helper.sh -- verified at ~/claude-custom/hooks/forgejo-helper.sh. Function remove_worktree_for_branch at line 280, also uses git worktree list --porcelain (line 307). May need orphan-aware cleanup.

Repo Placement

Correctly identified. Issue filed on pal-e-platform (worst-affected repo), fix targets claude-custom (where the hooks live). Body explicitly states this. PR must target claude-custom.

Dependencies

  • [x] claude-custom#194 (post-merge worktree cleanup) -- merged, satisfied
  • [x] claude-custom#195 (cleanup-worktrees.sh repo list) -- merged, satisfied
  • [x] claude-custom#184 (worktree isolation enforcement) -- merged, satisfied
No unresolved dependencies. Board item #637 is the only worktree-related item on board-pal-e-platform.

Acceptance Criteria

  • AC1: "All stale worktree directories cleaned up across all repos" -- testable via ls + du before/after.
  • AC2: "Root cause fixed (orphaned dirs detected and removed)" -- testable by creating an orphaned dir and running the script.
  • AC3: "Fix applied so future agent worktrees are cleaned up on merge or session end" -- testable via merge + session start cycle.
All 3 ACs are verifiable by an agent. No missing criteria.

Blast Radius

Same-pattern scan (git worktree list --porcelain) found in 4 files across claude-custom hooks. The fix to cleanup-worktrees.sh is the primary target. forgejo-helper.sh is secondary (post-merge cleanup of specific branches, not bulk scan). No downstream consumers affected. ~1.8GB disk recovery expected.

Decomposition

  • 2 file targets in 1 repo (claude-custom)
  • 3 acceptance criteria -- within limit
  • Estimated agent time: under 5 minutes
No decomposition needed.

Recommendation

No action needed. All 5 refinement items from the previous review have been applied correctly. Ticket is ready for dispatch.