feat(worktree): add lifecycle management with automatic garbage collection

docs/worktree-lifecycle.md

@@ -0,0 +1,179 @@
+# Worktree Lifecycle Management
+
+Superpowers automatically manages the lifecycle of git worktrees, ensuring they're cleaned up when no longer needed.
+
+## How It Works
+
+### 1. Registration
+
+When `using-git-worktrees` creates a worktree, it registers it in `~/.config/superpowers/worktree-registry.json`:
+
+```json
+{
+  "id": "wt_1234567890_feature_auth",
+  "path": "/tmp/worktrees/feature-auth",
+  "branch": "feature/auth-system",
+  "project_root": "/Users/jason/myapp",
+  "created_at": "2026-03-10T10:00:00Z",
+  "status": "active"
+}
+```
+
+### 2. Status Tracking
+
+Worktrees progress through these states:
+
+- **active** - Currently in development
+- **pr_opened** - Pull request has been opened
+- **merged** - Branch has been merged to main
+- **abandoned** - Branch was deleted without merging
+- **cleanup_pending** - Scheduled for garbage collection
+
+### 3. Automatic Detection
+
+The garbage collection daemon (or manual detection) checks:
+
+- Does the branch still exist?
+- Is there an open PR for this branch?
+- Has the PR been merged?
+
+### 4. Safe Cleanup
+
+Cleanup only happens when:
+
+1. Status is `cleanup_pending`
+2. Worktree has no uncommitted changes
+3. Delay period has passed (default: 1 hour for merged, immediate for abandoned)
+
+## Installation
+
+### Enable GC Daemon (Recommended)
+
+```bash
+# macOS: Create a proper LaunchAgent plist
+cat > ~/Library/LaunchAgents/com.superpowers.worktree-gc.plist << 'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.superpowers.worktree-gc</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/bin/bash</string>
+        <string>-c</string>
+        <string>$HOME/.config/superpowers/lib/worktree-gc-daemon</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <false/>
+</dict>
+</plist>
+EOF
+launchctl load ~/Library/LaunchAgents/com.superpowers.worktree-gc.plist
+
+# Linux: Append to existing crontab (preserves existing entries)
+(crontab -l 2>/dev/null; echo "@reboot $HOME/.config/superpowers/lib/worktree-gc-daemon") | crontab -
+```
+
+### Log Rotation (Optional)
+
+To prevent log file growth, add this to `/etc/logrotate.d/superpowers-worktree-gc`:
+
+```
+$HOME/.config/superpowers/worktree-gc.log {
+    weekly
+    rotate 4
+    compress
+    missingok
+    notifempty
+}
+```
+
+### Install Git Hooks
+
+For automatic cleanup after merge:
+
+```bash
+# In your repository
+cp ~/.config/superpowers/lib/hooks/post-merge .git/hooks/
+chmod +x .git/hooks/post-merge
+```
+
+## Manual Commands
+
+```bash
+# List worktrees for current project
+~/.config/superpowers/lib/worktree-manager list
+
+# Check for status changes
+~/.config/superpowers/lib/worktree-manager detect
+
+# Run garbage collection manually
+~/.config/superpowers/lib/worktree-manager gc
+
+# Force cleanup of specific worktree
+~/.config/superpowers/lib/worktree-manager unregister <id>
+```
+
+## Configuration
+
+Edit `~/.config/superpowers/worktree-registry.json`:
+
+```json
+{
+  "metadata": {
+    "gc_policy": {
+      "enabled": true,
+      "interval_hours": 1,
+      "cleanup_delay_hours": 24,
+      "max_age_days": 30
+    }
+  }
+}
+```
+
+- **enabled**: Turn GC on/off
+- **interval_hours**: How often to check for cleanup
+- **cleanup_delay_hours**: Grace period after merge
+- **max_age_days**: Auto-cleanup worktrees older than this
+
+## Safety Guarantees
+
+1. **Never deletes worktrees with uncommitted changes**
+2. **Never deletes active worktrees**
+3. **Always provides grace period for merged branches**
+4. **Logs all cleanup actions** to `~/.config/superpowers/worktree-gc.log`
+
+## Integration with Finishing Branch
+
+When you use the `finishing-a-development-branch` skill:
+
+1. If merging locally, post-merge hook triggers cleanup
+2. If creating PR, worktree status updates to `pr_opened`
+3. When PR is merged, GitHub webhook (future) or GC daemon detects and schedules cleanup
+
+## Troubleshooting
+
+### Worktree not cleaned up
+
+```bash
+# Check status
+~/.config/superpowers/lib/worktree-manager find <branch>
+
+# Manually mark for cleanup
+~/.config/superpowers/lib/worktree-manager update <id> cleanup_pending
+
+# Run GC
+~/.config/superpowers/lib/worktree-manager gc
+```
+
+### Accidentally cleaned up
+
+Check logs:
+```bash
+cat ~/.config/superpowers/worktree-gc.log
+```
+
+The registry maintains history of all worktrees created.

lib/hooks/post-merge

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Git post-merge hook for automatic worktree cleanup
+# Install: Copy to .git/hooks/post-merge and make executable
+
+SUPERPOWERS_LIB="${HOME}/.config/superpowers/lib"
+WORKTREE_MANAGER="${SUPERPOWERS_LIB}/worktree-manager"
+
+# Only run if superpowers is installed
+if [ ! -x "$WORKTREE_MANAGER" ]; then
+    exit 0
+fi
+
+# Get the branch that was merged (from reflog)
+# Post-merge hook fires after merge, so we parse the reflog to find source branch
+MERGED_BRANCH=$(git reflog -1 --format='%gs' | sed -n 's/.*merge \([^:]*\).*/\1/p')
+
+# Fallback: if we can't determine merged branch, exit silently
+if [ -z "$MERGED_BRANCH" ]; then
+    exit 0
+fi
+
+# Find matching worktrees
++# Get first matching worktree (there could be multiple across projects)
++WORKTREE_INFO=$("$WORKTREE_MANAGER" find "$MERGED_BRANCH" 2>/dev/null | jq -s '.[0]' || true)
++
++if [ -n "$WORKTREE_INFO" ]; then
+    exit 0
+fi
+
+# Find matching worktrees
++WORKTREE_INFO=$("$WORKTREE_MANAGER" find "$MERGED_BRANCH" 2>/dev/null | jq -s '.[0]' || true)
++
++if [ -n "$WORKTREE_INFO" ]; then
+    WORKTREE_ID=$(echo "$WORKTREE_INFO" | jq -r '.id')
+    WORKTREE_PATH=$(echo "$WORKTREE_INFO" | jq -r '.path')
+
+    echo "🎉 Branch '$MERGED_BRANCH' merged!"
+
+    # Update status to merged (daemon will handle cleanup)
+    "$WORKTREE_MANAGER" update "$WORKTREE_ID" "merged"
+
+    echo "✅ Worktree marked as merged. GC daemon will clean up: $WORKTREE_PATH"
+fi
+
+exit 0

lib/worktree-gc-daemon

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Worktree Garbage Collection Daemon
+# Runs periodically to clean up abandoned worktrees
+
+set -euo pipefail
+
+SUPERPOWERS_LIB="${HOME}/.config/superpowers/lib"
+WORKTREE_MANAGER="${SUPERPOWERS_LIB}/worktree-manager"
+DAEMON_PID_FILE="/tmp/superpowers-worktree-gc.pid"
+DAEMON_LOCK_FILE="/tmp/superpowers-worktree-gc.lock"
+LOG_FILE="${HOME}/.config/superpowers/worktree-gc.log"
+
+# Ensure log directory exists
+mkdir -p "$(dirname "$LOG_FILE")"
+
+# Handle shutdown signals
+RUNNING=1
+shutdown() {
+    log "Daemon shutting down"
+    RUNNING=0
+}
+trap 'shutdown' SIGTERM SIGINT
+
+# Atomic lock acquisition using flock
+exec 200>"$DAEMON_LOCK_FILE"
+if ! flock -n 200; then
+    echo "Daemon already running (lock held)" >&2
+    exit 0
+fi
+
+# Cleanup on exit
+trap 'flock -u 200; rm -f "$DAEMON_PID_FILE"' EXIT
+
+# Write PID while holding lock
+echo $$ > "$DAEMON_PID_FILE"
+
+log() {
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" >> "$LOG_FILE"
+}
+
+log "Worktree GC daemon started (PID: $$)"
+
+# Main loop
+while [ "$RUNNING" = "1" ]; do
+    # Detect status changes
+    if [ -x "$WORKTREE_MANAGER" ]; then
+        "$WORKTREE_MANAGER" detect >> "$LOG_FILE" 2>&1 || true
+
+        # Run garbage collection
+        "$WORKTREE_MANAGER" gc >> "$LOG_FILE" 2>&1 || true
+    fi
+
+    # Sleep for 1 hour (in short intervals to allow graceful shutdown)
+    for i in $(seq 1 360); do
+        if [ "$RUNNING" = "0" ]; then
+            break
+        fi
+        sleep 10
+    done
+done