---
name: ao-selective-merge
description: "Update clean PR branches with feature branch changes while preserving ao-ops exclusions. Used after addressing code review feedback."
category: git
invokes: [ao-git, ao-interview]
invoked_by: [ao-branch-workflow]
state_files:
  read: [constitution.md, focus.json, log/selective-branch-*.log, log/created-files.log]
  write: [focus.json, log/selective-merge-*.log]
---

# Selective Merge — Update Clean Branch

Update the clean PR branch with changes made on the feature branch (where agent continues to work) while preserving all ao-ops file exclusions. This is the complement to `ao-selective-branch`.

> **Works with or without `aoc` CLI.** Uses standard git commands.

---

## Purpose

Update the clean PR branch with changes made on the feature branch while preserving all ao-ops file exclusions.

---

## CRITICAL: No Assumptions

> **NEVER assume. NEVER guess. ALWAYS ask.**

**Before updating ANY clean branch, confirm with user:**

| If unclear about... | ASK |
|---------------------|-----|
| Feature branch | "Which branch has your latest changes?" |
| Clean branch | "Which clean branch should I update?" |
| Exclusion log | "I found log at `{path}`. Is this correct?" |
| Merge conflicts | "There are conflicts in `{files}`. How should I resolve?" |

**NEVER:**
- Guess which branch to merge from/to
- Auto-resolve merge conflicts without asking
- Proceed if exclusion log is missing or unclear
- Assume the worktree path without verification

---

## When to Use

- After addressing code review feedback on the **feature** branch
- When clean branch needs new changes for re-review
- When selective-branch exclusion log exists

---

## Workflow Direction

```
Feature Branch (with agent files)  ────────────────────────────────►
    │                                    │
    ├── selective-branch                  ├── selective-merge
    │                                    │
    ▼                                    ▼
Clean Branch (no agent files)      ────────────────────────────────►
```

---

## Prerequisites

**Both files SHOULD exist before selective-merge can proceed:**

1. **`.agent/ops/log/created-files.log`** — File audit trail (from implementation)
2. **`.agent/ops/log/selective-branch-*.log`** — Exclusion log (from selective-branch)

**If audit trail missing**: Use git diff fallback
**If exclusion log missing**: STOP and inform user to run `selective-branch` first

---

## Arguments

| Argument | Description | Default |
|----------|-------------|---------|
| `source_branch` | Feature branch with resolved feedback | Current branch |
| `clean_branch` | Clean branch to update | `{source_branch}-clean` |

---

## Workflow

### 1. Validate Prerequisites (MANDATORY)

Check for required files. If missing, STOP and inform user.

### 2. Parse Exclusion Log

Extract from exclusion log:
- Base branch, Copy timestamp, RESTORE entries, REMOVE entries

Find NEW files created after selective-branch by comparing timestamps.

### 3. Switch to Clean Branch Worktree

```bash
cd ../feature-branch-clean
git checkout {clean_branch}
git pull origin {clean_branch} --rebase
```

### 4. Merge Feature Branch Changes

```bash
git merge {source_branch} --no-commit --no-ff
```

If conflicts occur, resolve manually then continue from step 5.

### 5. Re-apply Exclusions

For excluded directories: restore from base or remove from tracking.
For excluded files: `git rm --cached {file}`

### 6. Commit and Update Log

```bash
git add -A
git commit -m "chore: update clean branch for review cycle {N}"
```

Append to exclusion log with cycle number and new exclusions.

### 7. Verification

Confirm all feature files present and no ao-ops files leaked.

---

## Conflict Handling

| Scenario | Resolution |
|----------|------------|
| Same file modified in both branches | Normal git merge conflict resolution |
| Agent file appears in clean branch | Automatically removed by re-applying exclusions |
| New ao-created file | Logged and excluded via created-files.log sync |

---

## Cleanup

After PR merged: remove worktree and delete branch.

---

## Error Recovery

| Error | Cause | Solution |
|-------|-------|----------|
| "Missing: created-files.log" | Audit trail not created | Run `selective-branch` first |
| "No exclusion log found" | selective-branch not run | Run `selective-branch` first |
| "Worktree not found" | Worktree removed | Re-create with `git worktree add` |
| Merge conflicts | Divergent changes | Resolve manually, then continue |

---

## Related Skills

- `ao-selective-branch` — Creates initial clean branch
- `ao-git` — General git operations
- `ao-branch-workflow` — Orchestrates selective-* workflow
