Blocked Branch Preserve Tag Cleanup

---
name: blocked-branch-preserve-tag-cleanup
description: Safely clean stale local branches that cannot be merged by preserving them with local tags before deletion
version: 1.0.0
source: session-learned
---

# Blocked Branch Preserve-Tag Cleanup

Use when cleaning many repos and some stale local branches cannot be merged safely into the default branch.

## Trigger conditions
- `git merge` fails with `refusing to merge unrelated histories`
- branch has no matching remote branch
- branch has shared history but the diff is extremely large / artifact-heavy / conflict-heavy, making opportunistic cleanup riskier than preservation
- repo hygiene is the goal, not historical branch recovery work

## Safe disposition workflow
1. Inspect the blocked branch:
   - confirm default branch
   - check whether a matching remote branch exists
   - check whether histories are unrelated via failed merge or missing merge-base
   - estimate branch size with `git diff --shortstat <default>...<branch>` when histories are related
2. Classify the branch:
   - `mergeable` if small and clean
   - `preserve-only` if unrelated history, no remote, or very large/conflict-heavy
   - `active/worktree-backed` if the branch is attached to a live worktree; do not delete yet
3. For `preserve-only` branches, create a local recovery tag before deletion:
   - `git tag preserve/<branch>-$(date +%Y%m%d) <branch>`
4. Delete the local branch after tagging:
   - `git branch -D <branch>`
5. Do not push the preservation tag by default. Keep it local unless the user explicitly wants remote archival.

## Why this works
This gives you a reversible cleanup path: branch clutter is removed, but the exact tip commit remains recoverable through the tag.

## Practical heuristics
- Unrelated-history branches with no remote are usually stale/orphan branches; do not force `--allow-unrelated-histories` unless the user explicitly wants content salvage.
- If a branch diff is huge (for example thousands of files, generated assets, or vendored environments), prefer preserve-only cleanup over ad hoc conflict resolution.
- If a conflict is in legacy control-plane files (`.agent-os`, old instructions, generated environments), that is usually a sign the branch is not worth opportunistic merging during hygiene work.
- Worktree-backed branches must be handled after their worktrees are removed or confirmed inactive.

## Verification
After cleanup, verify:
- `git branch -vv` no longer lists the stale branch
- `git tag --list 'preserve/*'` contains the recovery tag
- default branch remains checked out and clean/up to date