agents(workspace): auto-detect and clean up merged feature worktrees in workspace-sync

Problem

Currently, workspace-sync.sh only automates terminal-state cleanup for PR evaluation worktrees named pr-<number>. Local feature worktrees (e.g. <issue>-<slug> like 1254-pr-test-plan) are processed exclusively in Phase 4 ("Feature Branch Drift Awareness").

When a feature branch's Pull Request is merged into upstream main:

1. workspace-sync.sh only calculates ahead/behind commit counts via git rev-list --left-right --count.
2. Because the branch is already incorporated into main, all of its commits are ancestors of main, leaving ahead = 0 and behind >= 1 (accounting for the upstream merge commit).
3. The script misdiagnoses the completed feature branch as an active branch falling behind trunk, recommending a rebase:

   [BEHIND] ./1254-pr-test-plan (1254-pr-test-plan): 1 commit(s) behind main (0 ahead)
            👉 Run: git -C "./1254-pr-test-plan" rebase main when ready to incorporate upstream changes.
   

4. As a result, merged feature worktrees linger as zombie checkouts requiring manual lookup and deletion.

Proposed Solution

Enhance workspace-sync.sh to automatically detect when a feature branch worktree has been merged upstream and safely retire it alongside pr-<number> worktrees.

1. Merged State Detection

Incorporate two complementary detection mechanisms:

• GitHub PR Search via gh CLI:
  Query GitHub to detect whether an upstream PR from this branch was merged (supporting fork-to-upstream workflows and squash-merged PRs where commit SHAs differ):

  gh pr list --search "head:${branch_name}" --state merged --json number,state,title
  

• Git Ancestry:
  For standard merge or fast-forward commits where commit SHAs are preserved:

  git merge-base --is-ancestor "refs/heads/${branch_name}" "refs/heads/main"
  

  If ahead == 0 and it is an ancestor of main, the branch has no remaining unique commits.

2. Safety Invariants

• Cleanliness Verification: Never remove a dirty worktree (git status --porcelain). If untracked or uncommitted files exist, skip and emit a warning to protect work in progress.
• Active Directory Guard: If workspace-sync.sh is executed from inside the target worktree ($dir == $PWD), skip removal and prompt the developer to switch directories first.

3. Automated Retirement & Dry-Run Support

• For clean, confirmed-merged feature worktrees:
  • Remove worktree: git worktree remove "$dir"
  • Delete local branch: git branch -d "$branch_name" (or git branch -D if verified merged via gh on a squash-merge).
  • (Optional) Notify or prune the corresponding tracking branch on origin.
• Support --dry-run:

  ==> ./1254-pr-test-plan (1254-pr-test-plan)
      $ [dry-run] git worktree remove "./1254-pr-test-plan" && git branch -D "1254-pr-test-plan"
      [DRY RUN] Would remove worktree and branch for MERGED PR #1255 ("feat(skills): evaluate PRs for participant or experimenter UX changes...")
  

Related Context

• #1238 (Automated garbage collection of merged/closed pr-<number> evaluation worktrees)
• #1247 (Maintainer PR evaluation protocol and worktree lifecycle)

Start by reading workspace-sync.sh, especially Phase 4 ("Feature Branch Drift Awareness") and the existing pr- cleanup path. Exercise the script with a merged feature worktree, including dirty and current-directory cases, and trace the gh PR search and git ancestry checks. Done means clean confirmed-merged worktrees are retired safely, protected cases are skipped with warnings, and --dry-run reports the intended actions.