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