Sync Branch

Core Question

How should this branch be safely brought up to date while preserving user work and making merge/rebase risk explicit?

When To Use

Use this skill when:

• the user asks to pull, fetch, sync, update, rebase onto, or merge from an upstream branch
• the branch is behind or diverged
• the user wants remote state refreshed
• the user asks why pull is blocked or risky

When Not To Use

Do not use this skill when:

• general branch creation or deletion
• conflict file resolution
• abort/reset/recovery
• force-push or remote deletion
• commit grouping

Route to:

• branch creation or push gates route to branch-workflow
• conflicts after sync route to resolve-conflicts
• abort or recovery routes to undo-recover
• dirty work that should be committed routes to atomic-commits or stash-shelve

Required Evidence

Before action, inspect or establish:

• current branch, upstream, and target branch
• status including staged, unstaged, and untracked paths
• ahead/behind/diverged evidence
• merge-base and recent log when branch relationship is ambiguous
• operation-in-progress markers
• project policy for merge versus rebase when available

No-evidence rule:

• Do not make strong claims without observed evidence.
• State assumptions when proceeding under incomplete evidence.
• Stop when missing evidence affects safety, correctness, user work, remote state, or irreversible action.

Operating Contract

You MAY:

• inspect relevant repository state and project files.
• generate a plan, report, or local artifact within the declared risk scope.
• route to another skill when the requested action is outside this skill's owner boundary.

You MUST:

• inspect before acting.
• keep the task within the declared owner boundary.
• classify state and risk before any meaningful action.
• preserve unrelated user work.
• verify outcomes proportional to risk.
• report evidence, assumptions, actions, verification, and residual risk.

You MUST NOT:

• invent project policy.
• expose secrets or sensitive values.
• mutate unrelated files or refs.
• perform destructive, remote, shared, history-rewriting, or irreversible actions without explicit action-specific confirmation.
• continue after unexpected destructive output.

State / Risk Table

Workflow

1. Identify the user goal and current owner boundary.
2. Inspect required evidence.
3. Classify repository/task state.
4. Classify risk using the declared scope.
5. Choose the minimal sufficient action or route.
6. Execute only allowed actions, if any.
7. Verify outcome or self-check the artifact.
8. Report result, evidence, verification, assumptions, and residual risk.

Decision Rules

• Treat git fetch as remote-read/local-ref refresh; report that remote-tracking refs may change.
• Do not run a blind pull when branch is dirty, diverged, or missing upstream.
• Prefer fast-forward when the branch is clean and behind only.
• Require explicit user choice for merge versus rebase when both are viable and policy is unknown.

Workflow Guardrails

Force Push / Shared History Rewrite

Trigger:

• A sync, pull, merge, or rebase changes local history and the user asks to update a remote/shared branch.

Default: <!-- guardrail:sync-force-push.route-out -->

• Stop sync execution and route remote rewrite planning to branch-workflow or destructive recovery to undo-recover; do not perform the push in this skill.

Must:

• Inspect git status --short --branch, git branch -vv, local-only commits, and remote-only commits before routing.
• State that local history rewrite does not imply remote rewrite.

Must not: <!-- guardrail:sync-force-push.no-force-push-in-sync -->

• Run git push --force-with-lease or git push --force from this skill.
• Treat a successful local rebase as permission to force-update a remote branch.

Requires explicit confirmation:

• Remote name, branch/ref, local SHA, remote SHA, intended force update, and recovery plan in the routed workflow.

Verification:

• Verify sync state locally before routing.
• The routed owner must verify the remote ref after any confirmed force update.

Tool Rules

• May run read-only state commands and fetch when remote refresh is explicitly requested.
• May run narrow fast-forward, merge, or rebase only after evidence and confirmation match risk.
• Must not force-push, reset hard, clean untracked files, or resolve conflicts here.

Verification

Minimum verification:

• Verify status after sync action.
• Verify ahead/behind state or resulting branch relationship.
• If conflicts occur, verify routing to resolve-conflicts and do not continue automatically.

Risk-based floor:

• R0-R1: evidence inspected and output self-checked.
• R2: inspect resulting diff or local state.
• R3: verify local state and report recovery limits.
• R4-R5: require explicit confirmation, preflight evidence, and post-action verification where this skill owns the action.

Output Contract

Final response must include:

## Result

- Decision, action, or artifact produced.

## Evidence

- Files, commands, diffs, refs, or assumptions used.

## Verification

- Checks performed and their result.

## Risks / Limitations

- Remaining uncertainty, blocked actions, or routed next steps.

Stop / Confirmation Rules

Stop when the repository state is dirty, conflicted, diverged, missing required evidence, or ambiguous in a way that could overwrite user work, invalidate the requested scope, or require a gated action.

Require explicit action-specific confirmation for:

• destructive local mutation.
• remote/shared mutation.
• history rewriting.
• security/secret/data impact.
• irreversible or hard-to-recover operation.

Broad approval such as "do whatever" is not enough for R4-R5 actions.

Lazy-load References

Load references/fetch-pull-safety.md when:

• the task needs the detailed guidance described by the file name.
• the state/risk table identifies an ambiguous or high-risk path.

Load references/merge-vs-rebase.md when:

• the task needs the detailed guidance described by the file name.
• the state/risk table identifies an ambiguous or high-risk path.

Load references/upstream.md when:

• the task needs the detailed guidance described by the file name.
• the state/risk table identifies an ambiguous or high-risk path.