brain-sync

---
name: brain-sync
description: "Bring this brain's repo up to date and commit its changes the same way every time: show where it stands, run the checks, commit with a scoped subject, pull with rebase, and push only when asked. After an update, commit the template change on its own and mark answered upstream suggestions. Use when doctor says the brain is behind or has unpushed work, after writing a skill, script or practice, or before long work. Does NOT write the skill, script or practice itself (brain-write-skill, brain-write-script, brain-write-practice), and does NOT touch nested project repos or template-owned files."
---

# brain-sync

Every change reaches the history the same way: checked, grouped by scope, reviewed, and pushed only
when the person says so. A history of scoped commits can be read, reverted and compared.

## Where this sits

<!-- where:begin — generated by _meta/brain routing sync; do not edit -->
**Runs after:** `brain-setup` · `brain-upstream` · `brain-write-mod` · `brain-write-practice` · `brain-write-script` · `brain-write-skill`

**Hand to next:** nothing — a person takes it from here.

**Reserved output:** writing `docs/UPSTREAM.md` needs this skill to have run.
<!-- where:end -->

**Call it directly when:** a skill, script, practice or log change is ready to commit, an `update`
has just run, or `doctor` reports unpushed or uncommitted work; nothing needs to run first.

## 1. Where it stands

`git status --short --branch`; with a remote, `git fetch`, then `git log --oneline @{u}..` (not
pushed) and `git log --oneline ..@{u}` (not pulled). Tell the person briefly what changed, by scope,
and how far ahead or behind it is. A template that is behind is an update, run by `brain-setup`.

## 2. Run the checks

```bash
_meta/brain lint                      # skills and the routing map
_meta/brain routing sync --check
_meta/brain practices lint
_meta/brain doctor --quick
<scripts.python> -m unittest discover -s ./scripts/tests -t ./scripts   # when scripts/ changed
```

`<scripts.python>` is `brain.json` `scripts.python`. A BROKEN or BLOCK line stops the commit. Fix it
through the skill that owns the file (skills and the map: `brain-write-skill`; practices:
`brain-write-practice`; scripts: `brain-write-script`; a template-owned file: `brain-upstream`); a
BLOCK about no file (the hook, `core.hooksPath`, a missing tool, a copy never set up) goes to
`brain-setup`. Then run the checks again. GAPs and doctor's uncommitted-work warning do not stop it.

## 3. Commit by scope

| Scope | Holds |
| --- | --- |
| `skill(<name>)` | one skill's folder, with its node in `docs/ROUTING.md` and its gate rule in `brain.json` |
| `script(<system>)` | one system's scripts and tests, with their `docs/CAPABILITIES.md` rows |
| `practice(<id>)` | one practice file and the regenerated `docs/practices/INDEX.md` |
| `docs(<area>)` | other `docs/` changes: `docs(retro)` for the two logs, `docs(upstream)`, `docs(<folder>)` |
| `meta(brain)` | `brain.json`, `README.md`, `.env.example`, `.claude/settings.json`, `CLAUDE.md` and `.gitignore` below the managed blocks; and the template update (section 4) |

For each group, in turn:

1. Stage it by path: `git add -- <paths>`. Never `git add -f`, never everything at once, never a
   path inside a nested project repo, and no git command inside one: it is not the brain. Forcing
   past the allowlist `.gitignore` is exactly how a project repo, an asset or a `.env` gets in.
2. Read `git diff --cached --stat`: only this group's files, nothing large, nothing you did not mean
   to stage. Unstage the rest with `git restore --staged -- <path>`.
3. Commit with `git commit -F -` and the subject `<scope>: <what changed>`, imperative and short,
   following any commit convention in the brain's `CLAUDE.md` (a trailer, a language).

The pre-commit guard runs on every commit; when it refuses, fix what it names. **Never
`--no-verify`**: the guard is the only check between a secret, a private name or a project repo and
a history that may be pushed. A refusal that looks wrong is a `privacy` setting for the person to
change, or an upstream suggestion; never a bypass.

A change to a template-owned file (`_meta/`, a `brain-*` skill, a managed block) outside an update
is a local edit: never commit it, or make one to get a check to pass; hand it to `brain-upstream`.
A restore to the installed version is the exception: once `doctor --quick` shows no manifest edit,
commit it alone as `meta(brain): restore <file>`.

**In the template** (`brain.json` `role` is `template` and `local/` exists), `_meta/` and the
`brain-*` skills are the template's own work, not local edits. Run the test suite as well
(`PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -t .`), commit under
`meta(<area>)`, `skill(<name>)`, `test(<area>)` or `docs(<area>)`, and skip section 4.

## 4. After an update

`update` writes but never commits. Commit what it changed on its own, so the history shows exactly
what the template brought:

1. Commit any other pending work first, in its own groups, including other `docs/UPSTREAM.md` edits.
2. For each id `update` reported as answered (`_meta/brain upstream list` shows them with the
   template's answer), set that entry's line to `- status: landed <version>` or
   `- status: declined: <reason>`, as the template's `CHANGELOG.md` says. The flips belong to the
   update's own commit: a separate one leaves a point where an answered suggestion reads `open`.
3. Stage the update's files (the template-owned paths, `_meta/MANIFEST.sha256`, `brain.json`, the
   managed blocks, `.claude/settings.json`) and `docs/UPSTREAM.md`; read the stat; commit
   `meta(brain): update template to <version>`, `<version>` being `brain.json` `template.version`.

## 5. Pull, then push only when asked

`git pull --rebase` when there is a remote (`--autostash` if the person left changes uncommitted).
If the rebase stops on a conflict, show it to the person and resolve it with them, or
`git rebase --abort` to go back. Run the checks again if the pull brought skills, map or practices.

Push only when the person asks for it in this conversation: `git push`. Never `--force`, and never
rewrite a commit that is already pushed. With no remote, say so, and offer `brain-setup`'s online
backup; whether to have one is the person's call.

## Done when

- The checks ran on what was committed, with no BROKEN or BLOCK.
- Each commit holds one scope, its subject starts with that scope, and its staged stat was read.
- A template update is its own `meta(brain): update template to <version>` commit, with every
  answered `docs/UPSTREAM.md` entry flipped in it.
- No nested repo path, no `.env` and no file over `max_file_kb` was staged; no `--no-verify`.
- In the template, the test suite passed before each commit.
- The branch is rebased on its remote, and pushed only if the person asked.