Safe Worktree Cleanup

Overview

Use this skill to clean up issue worktrees and branches without risking main/master or the active integration branch.

This workflow is built for Codex command-policy environments where commands like git branch -d or git push origin --delete may be rejected.

Important:

• Git can retain stale worktree registrations after manual folder removal.
• The helper script handles this automatically by running git worktree prune as part of normal cleanup.

Use When

• A PR is merged and you need local/remote branch + worktree cleanup.
• An issue branch/worktree is intentionally abandoned and must be removed.
• Standard cleanup commands are being blocked by policy.

Branch Protection Baseline

Before cleanup, check whether the repo already enforces local branch-deletion safeguards (for example, protected branch hooks in core.hooksPath).

If safeguards are missing, offer to install lightweight local hooks before branch cleanup:

• pre-push to block remote deletion pushes for protected branches.
• reference-transaction to block local branch deletion for protected branches.

Reference templates and install notes:

• references/branch-protection-hooks.md

Required Inputs

• REPO_ROOT: repository path.
• INTEGRATION_BRANCH: usually master or main.
• ISSUE_NUMBER: numeric issue id.
• BRANCH: expected codex/issue-<issue-number>-<slug>.
• WORKTREE_PATH: expected issue worktree path.

Hard Safety Rules

• Never delete protected branches: main, master, develop, staging, production.
• Never delete the integration branch.
• Never delete the currently checked out branch.
• By default, only delete branches matching ^codex/issue-[0-9]+-.
• Refuse dangerous worktree paths (/, ., $HOME, or empty).
• Run destructive actions as separate commands, not one long chained command.

Helper CLI (Deterministic)

Use the bundled helper instead of emitting inline scripts:

/Users/robertsale/.codex/skills/safe-worktree/scripts/safe-worktree-cleanup \
  --repo-root "/path/to/repo" \
  --integration-branch "master" \
  --issue-number "123" \
  --branch "codex/issue-123-some-slug" \
  --worktree-path "../repo-wt-123" \
  --delete-remote true \
  --allow-unmerged-delete false

Run --help for usage:

/Users/robertsale/.codex/skills/safe-worktree/scripts/safe-worktree-cleanup --help

Deterministic Protections Implemented By Script

• Refuses protected branches: main, master, develop, staging, production.
• Refuses deleting integration branch or currently checked out branch.
• Refuses non-issue branch names by default (^codex/issue-[0-9]+-).
• Optionally enforces --issue-number branch match.
• Refuses dangerous worktree paths (/, ., $HOME, empty, repo root).
• Uses recoverable deletion fallback (trash) when git worktree remove cannot fully remove the directory.
• Runs git worktree prune by default (before and after worktree-path cleanup) to clear stale registrations automatically.
• Requires merged state unless --allow-unmerged-delete true.
• Uses policy-aware fallback deletes for local and remote refs.
• Fails non-zero if branch/worktree still exists after attempted cleanup.