pan-sync-main git:20260725.68ec740A

Immutable. This exact content is served forever at /api/v1/blob/faf87f05f3542d1f.

---
name: pan-sync-main
description: "pan sync-main <id> — merge latest main into the feature branch for an active workspace"
triggers:
  - sync with main
  - sync main into workspace
  - pull in hotfix
  - merge main into branch
  - pan sync-main
  - get latest changes from main
allowed-tools:
  - Bash
  - Read
---

# Sync with Main

Merges the latest `main` branch into a workspace's feature branch. Uses `git merge` (not rebase) to avoid rewriting history, and delegates conflict resolution to the merge-agent specialist.

## Usage

```bash
# CLI command
pan sync-main PAN-XXX

# Or via the dashboard API
curl -X POST http://localhost:3011/api/issues/PAN-XXX/sync-main
```

## What It Does

1. Checks for uncommitted changes (blocks if any — must commit, explicitly discard, or surface to the operator first; agents never `git stash`)
2. Resolves the workspace's required git repos; monorepos produce one repo root
3. Cleans up stale git locks in each repo
4. Fetches and merges each repo's configured target branch sequentially in config order
5. Stops at the first failed or conflicted repo and marks later repos skipped
6. If clean: reports aggregate commit/file totals plus one result per repo
7. If conflicts remain: aborts that repo's merge and reports its conflict files

## Outcomes

| Result | Meaning |
|--------|---------|
| Already up to date | Main has no new commits since last sync |
| Success (N commits) | Clean merge or agent-resolved conflicts |
| Uncommitted changes | Commit or discard workspace changes first |
| Conflict (unresolvable) | The failing repo's merge is aborted and its conflict files are reported |
| Per-repo / skipped | Polyrepo output shows each repo's result; repos after the first failure are skipped |

## Design Decisions

- **Merge, not rebase** — Rebase rewrites SHAs and requires force-push. Merge commits serve as audit markers.
- **No tests/builds** — Feature branch is WIP. Running tests after sync would fail on pre-existing issues.
- **No push to remote** — This is a local workspace operation only.
- **Sequential polyrepo sync** — Required repos sync in config order. The first failure stops iteration; earlier merges remain, later repos are skipped, and output reports every repo's result.

## Examples

```bash
# Sync PAN-123 workspace with latest main
pan sync-main PAN-123

# Output on success:
# ✓ Synced 3 commit(s) from main
#   Commits merged: 3
#   Changed files (5):
#     src/lib/auth.ts
#     src/lib/config.ts
#     ...

# Output when already current:
# ✓ PAN-123 is already up to date with main

# Output on uncommitted changes (blocks):
# ✗ Sync failed: Workspace has uncommitted changes. Commit or discard them before syncing with main.
```

## Dashboard

The "Sync with Main" button appears in the workspace detail panel:
- In the **Git Status** section as a small "Sync" button next to the branch name (disabled if uncommitted changes)
- In the **Actions** section as a full "Sync with Main" button

## Related Commands

- `pan approve <id>` — Review and merge to main
- `pan review request <id>` — Trigger review pipeline
- `pan tell <id> "<message>"` — Send message to agent