Skill Sync

---
name: dream-sync
description: >
  Load when the user asks to sync/reconcile the dreamcontext brain repo with a team (a shared
  `_dream_context/` git remote), or when `dreamcontext brain sync` (or the SessionStart snapshot)
  reports a team merge awaiting resolution. Triggers: "/dream-sync", "sync the brain", "reconcile
  with the team", "resolve the brain merge conflict", "already-awaiting-agent", "awaiting-agent",
  "pending team-merge handoff". This is the agent half of the semantic-merge contract: the CLI
  resolves every deterministic file (JSON changelog/releases/config/taxonomy, task status +
  changelog) automatically and only ever defers PROSE files (knowledge/features) where two people
  edited the same section — you read base/ours/theirs snapshots and write the actual semantic
  merge, then hand back to the CLI to commit + push.
user-invocable: true
alwaysApply: false
tags: [sync, brain-repo, git, merge, collaboration, dreamcontext]
---

# /dream-sync — the agent half of the brain-repo merge contract

You are the **semantic merge resolver**. The CLI (`dreamcontext brain sync`) already did
everything it safely can on its own: every JSON class (changelog, releases, config, taxonomy) and
every task markdown file were merged and committed automatically — set-unions and furthest-status
logic never lose data and never need judgment. The ONLY thing left for you is **prose that two
people edited in the same `##` section** of a knowledge file or feature doc — a case the CLI
correctly refuses to resolve on its own (see `references/merge-rules.md` — the "C1 discard
contract"), because a naive textual merge mangles Markdown and a "remote wins" default would
silently throw away one author's words.

**Read `references/merge-rules.md` before touching anything** — it is the single source of truth
for the deterministic rules, the CLI-vs-agent split, and the full pull-only → resume → resolve →
continue state machine you are stepping into.

## Step 1 — determine the handoff state

Run `dreamcontext brain status`. It reports two independent booleans:

- `mergeInProgress` (a real git `MERGE_HEAD` exists) — the **classic** path: `brain sync` (auto
  mode) hit an agent-class conflict directly and left the merge open.
- `pendingAgentMerge` (no `MERGE_HEAD`, but a report was deferred) — the **pull-only** path: a
  headless background pull (session-start) hit the same conflict, but pull-only NEVER leaves the
  tree mid-merge — it aborted back to a clean commit and recorded the defer for you to redo
  attended.

Branch on exactly these two signals (equivalently: a plain `dreamcontext brain sync` returning
`already-awaiting-agent` tells you one of the two is true, without telling you which):

| State | What to do |
|---|---|
| `mergeInProgress: true` | Go straight to **Step 2** (report already exists, real `MERGE_HEAD`). |
| `pendingAgentMerge: true`, `mergeInProgress: false` | Run `dreamcontext brain sync --resume` FIRST. If it returns `pushed` or `pulled`, the handoff is DONE — the remote moved on and nothing needed your judgment. If it returns `awaiting-agent`, a FRESH report + a real `MERGE_HEAD` now exist — go to **Step 2**. |
| Neither | Just run `dreamcontext brain sync` (normal on-demand sync) — nothing to resolve. |

**You never call `--resume` when a `MERGE_HEAD` is already there, and you never skip `--resume`
for a `pendingAgentMerge`-only state** — the CLI enforces this with `invalid-flag`, but don't rely
on that as your only guardrail; read the state first.

## Step 2 — read the report and resolve each deferred file

Read `_dream_context/state/.brain-merge/report.json`. For each entry in `deferred`:

1. Read the three snapshots it names: `basePath` (common ancestor), `oursPath` (this machine's
   version), `theirsPath` (the remote/teammate's version) — all under `state/.brain-merge/`.
2. Write the semantically-merged content directly into the REAL file at `path` (repo-relative,
   possibly under an `_dream_context/` prefix in in-tree mode — strip it to find the file on disk).
   Preserve both authors' intent: don't just pick one side. For a knowledge/feature doc, merge
   section-by-section — sections only one side touched keep that side's version; sections BOTH
   touched are the ones you're here for — read them and write prose that keeps both people's point,
   reconciling wording, not concatenating raw diffs.
3. Stage it — run `git add <path>` at the project root (the git root is the project folder, so
   `path` carries the `_dream_context/` prefix).

Do this for every entry in `deferred` before moving on — `--continue` commits everything staged in
one shot.

## Step 3 — hand back to the CLI

Run `dreamcontext brain sync --continue`. It re-scrubs (a secret can be reintroduced by a merge —
never skip this), commits, and pushes (retrying once on a non-fast-forward race). On success the
report and its snapshot files are gone, `pendingAgentMerge` flips back to `false`, and a normal
`brain sync` runs cleanly from here on. If it instead reports `blocked-scrub`, something you wrote
looks like a secret or a local path — fix it and re-run `--continue`.

## What you must NEVER do

- **Never call `--resume` or `--continue` unattended / speculatively** — they are the explicit
  ATTENDED gates for exactly this handoff. `sleep done`'s autoSync, the session-start background
  pull, and the dashboard all stop at `already-awaiting-agent` and print the instruction to run
  `/dream-sync` — they never drive these flags themselves.
- **Never write the CLI's discarded remote-wins output** for a deferred knowledge/feature file —
  if you see `report.json`'s `deferred` entry for a path, that means the CLI's own attempt was
  thrown away specifically because it would have clobbered one side; only your snapshot-based
  merge is authoritative for that file.
- **Never hand-edit `.brain-merge/report.json`** or its snapshots — they are inputs, not outputs.