---
name: git-sync
description: Pull latest changes, surface new sync notes, install when needed, and run baseline verification without auto-reconciling template drift
---

# Git Sync

Pull the latest upstream changes for this project, detect any newly introduced template sync notes, install dependencies when the pull changed package baselines, and run the baseline verification flow.

**Usage:** `/git-sync`

Use this when:

- you just pulled a release-train update from the template repo
- the branch may include dependency or scaffold baseline changes
- you want the current sync-note guidance before making any manual reconciliation edits

This command is intentionally narrower than template reconciliation. It stops after pull, install, verification, and note surfacing. It never auto-overwrites project-owned files.

## Sync Notes Contract

Downstream release guidance lives in `.claude/sync-notes/`.

- Operative note files are named `YYYY-MM-DD-<slug>.md`
- `README.md` documents the contract and is ignored by note detection
- Notes are append-only release guidance; do not rewrite old note filenames after they ship
- Every operative note uses these exact headings:
  - `## Why this note exists`
  - `## Applies to`
  - `## Required actions`
  - `## Verification`
  - `## Not handled by /git-sync`

## Process

### Step 1: Check for Uncommitted Changes

```bash
git status --short
```

If the worktree is dirty, stop and tell the user to commit, stash, or discard changes first. Do not pull on top of local edits.

### Step 2: Snapshot Current Sync Notes

Capture the current operative note filenames before pulling:

```bash
git ls-files ".claude/sync-notes/*.md"
```

Ignore `README.md` when building the pre-pull note set.

### Step 3: Pull Latest Changes

```bash
git pull --rebase
```

If the pull conflicts, stop and report the conflict. Do not attempt auto-resolution.

### Step 4: Detect Whether Install Is Required

If the pull changed any dependency baseline files, run a fresh install:

```bash
git diff --name-only HEAD@{1} HEAD -- package.json pnpm-lock.yaml pnpm-workspace.yaml ui/package.json operations/package.json shared/package.json
```

If the diff is non-empty:

```bash
pnpm install
```

If none of those files changed, skip install and report that the dependency baseline was unchanged.

### Step 5: Run Baseline Verification

Run the standard project verification flow:

```bash
pnpm -C ui check-types
pnpm -C ui build
pnpm -C operations check
pnpm -C operations check-types
```

Stop on the first failure and report it clearly.

### Step 6: Surface Newly Introduced Sync Notes

Build the post-pull operative note set and compare it to the pre-pull set. Any newly added note filename is considered unread guidance for this pull.

When new notes exist:

- print each new note filename
- summarize the `## Required actions`, `## Verification`, and `## Not handled by /git-sync` sections
- tell the user exactly which manual follow-up remains

When no new notes exist, say so explicitly.

### Step 7: Stop Before Reconciliation

`/git-sync` ends after pull, optional install, verification, and note surfacing.

It does **not**:

- run registry/template reconciliation
- overwrite project-owned files
- resolve downstream migration conflicts
- treat a passing baseline verify as proof that manual follow-up is complete

If a sync note or the pulled diff requires project-specific changes, leave those as an explicit next step.

## Report

```text
Git Sync Complete
=================
Git:        pulled (<branch>)
Install:    ran | skipped (no dependency baseline changes)
Verify:     PASS | FAIL at <step>
Sync notes: none | 2026-04-22-example-change.md
Next step:  manual reconciliation required | none
```
