Sw Sync

---
name: sw-sync
description: >-
  Syncs the local repository by fetching all remotes, updating the base branch,
  and removing stale local branches that are not protected by live sessions or
  helper worktrees.
argument-hint: ""
allowed-tools:
  - Read
  - Bash
  - Glob
  - AskUserQuestion
---

# Specwright Sync

## Goal

Keep the local repository current without deleting branches that are still
claimed by a live Specwright session or a subordinate helper worktree.

## Inputs

- `{projectArtifactsRoot}/config.json`
- `{worktreeStateRoot}/session.json`
- `{repoStateRoot}/work/*/workflow.json`
- `git worktree list --porcelain`

## Outputs

- Remotes fetched and pruned
- Base branch fast-forwarded when safe
- Candidate stale branches previewed, then deleted only after confirmation
- Summary report: branches fetched, removed, skipped, protected, and any stale
  active works detected

## Advisory Reporting

- After fetch/prune completes, `sw-sync` may report stale active works against
  their recorded targets and latest known freshness state.
- This report is advisory only and does not take ownership of
  reconcile-or-ship decisions away from the lifecycle skills.
- `sw-sync` never rebases, merges, retargets, or clears a freshness block on
  behalf of `sw-build`, `sw-verify`, or `sw-ship`.

## Constraints

**Fetch (HIGH freedom):**
- Run `git fetch --all --prune`.

**State-aware protection set (LOW freedom):**
- Build a branch protection set from:
  - the currently checked out branch
  - the configured base branch and perennial branches
  - branches recorded by live `session.json` files across `git worktree list`
  - branches recorded in attached work `workflow.json.branch`
  - helper branch patterns `worktree-*` and `specwright-wt-*`
- Treat subordinate helper worktrees discovered via `git worktree list --porcelain`
  as protected branch owners even when they are not user-facing sessions.
- Never delete a branch that appears in that protection set.

**Stale branch detection (HIGH freedom):**
- Primary signal: `git branch -vv` entries with `[gone]`
- Supplementary signal: `git branch --merged` against the configured base branch
- Do not promote a branch to deletion solely because it is merged if a live
  session still references it.
- Do not delete a branch when a live session or subordinate helper still claims it.
- Classify confirmed stale branches into:
  - `safe-delete` for branches that should still use `git branch -d`
  - `force-delete-candidate` for `[gone]` branches only when they are not protected,
    not invalid, and not claimed by a live session or subordinate helper worktree

**Safety checks (LOW freedom):**
- Validate each candidate branch with `git check-ref-format --branch` before
  passing it to shell commands.
- Reject names that start with `-`, contain shell metacharacters or control
  whitespace, or fail ref-format validation.
- Pass branch names to Git as quoted positional arguments after `--`.
- If `config.git.cleanupBranch` is false, skip deletion entirely and say so.
- If worktree enumeration fails, skip deletion and warn rather than guessing.

**Confirmation (LOW freedom):**
- Show the candidate branch list with deletion reasons.
- Use AskUserQuestion for confirm-all, select-subset, or abort.
- In non-interactive context, skip deletion and report candidates only per
  `protocols/headless.md`.
- Keep `git branch -d` as the default delete path.
- Use `git branch -D` only for a `force-delete-candidate`.
- A `force-delete-candidate` requires an explicit second confirmation before
  running `git branch -D`.
- Never use `git branch -D` for merged-only, protected, invalid, or
  live-session-owned branches.

**Base branch sync (MEDIUM freedom):**
- Checkout the configured base branch and pull with `--ff-only`.
- Return to the original branch afterward.
- If the working tree is dirty, warn and skip the checkout/pull path.
- If `--ff-only` reports divergence, warn and continue without creating a merge
  commit.

**No state mutation (LOW freedom):**
- `sw-sync` never writes Specwright state.
- It is not a core workflow stage and never claims top-level work ownership.
- Reading session and workflow files to protect branches is allowed.

## Protocol References

- `protocols/git.md` -- branch lifecycle and cleanup rules
- `protocols/git-freshness.md` -- freshness result shape and status semantics for advisory reporting
- `protocols/context.md` -- logical roots and session loading
- `protocols/state.md` -- per-work workflow fields used for protection
- `protocols/headless.md` -- non-interactive behavior

## Failure Modes

| Condition | Action |
|---|---|
| no remotes configured | stop with a remote-setup error |
| `git fetch` fails | surface the error and skip deletion |
| no stale branch candidates | report that nothing is deletable |
| worktree/session inspection fails | skip deletion and warn |
| current session's attached work is building or verifying | abort and tell the user to finish or reset that work first |
| base branch cannot fast-forward | warn and continue without merging or resetting |