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

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.

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

_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

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.