v0.12.0 — Fewer round trips, for real

v0.11.0 made every figure exact, but a digest load still took 11 tool calls and a save 27. v0.12.0 brings them down to 2 and 8. It also fixes a flag-parsing bug that could write to the wrong graph.

v0.12.0 adds three composite helper commands, so a routine operation is a fixed sequence the helper runs in one process. A digest load is brain load. A save is brain save-begin, then one Read, then Claude's Edits, then brain save-finish. Claude still does the judgment; the helper does the bookkeeping, and now also writes the journal's ## Sessions bullet and the Index.md one-liner. It validates that text before writing it.

Measured (eval suite on the release commit: 11 of 11 cases passed, canary fully proven)

	v0.11.0	v0.12.0
Digest load, tool calls	11	2
Save, tool calls	27	8 (6 in two earlier runs)
Instruction files read on a routine load or save, beyond the skill's own SKILL.md	5–30 KB	none
Wrong-graph writes with --graph after the command	reproduced	none, proven by an eval case against a decoy config
Golden test cases	78	182, green on mawk, original-awk, gawk and macOS BWK awk, across Linux, macOS and Windows

The call targets (load ≤ 4, save ≤ 13) are now pass criteria in the eval suite, not just reported figures.

What's new

• --graph anywhere. The helper accepts --graph DIR before or after the command. A trailing flag used to be ignored: with a configured graph, the call ran against that graph and wrote the flag text into the journal. An empty --graph, or one given twice, is refused, and -- ends flag parsing. The graph path is resolved to a canonical absolute path, and CDPATH can't redirect it.
• brain load <page>. Info, the digest, today's journal mentions and the (digest) activity line, in one call. --mode full prints the section table and the byte budget of a full load.
• brain save-begin / brain save-finish.
  • save-begin records every baseline and prints what the Edits need: the digest, the newest Session Log entry, Current Plan, and the Index and ## Sessions anchors.
  • save-finish validates first: the texts, the digest caps, and a dry-run Map for every page in the save. A refusal writes nothing, so the same command can be rerun.
  • It then writes the Sessions bullet, the Index parenthetical and the Maps, and runs one check over every file the save touched.
  • The activity line is held back while a new error stands.
• The instruction diet, part 2. brain-load (5.0 KB) and brain-save (9.3 KB) carry everything a routine run needs, including the helper invocation. References are read only on their branches: a decision, a rotation, a page with no digest. brain check and brain lint print a one-line fix hint per rule.
• Smaller fixes.
  • read and tail accept a section written as its heading ('## Implementation').
  • File arguments in the C:/… form work on Windows.
  • A save-begin rerun after an Edit warns that those lines won't be checked.
  • The archive-page Remap instruction is removed.
  • BRAIN_VERSION is pinned to plugin.json by a golden case.

Requirements

Unchanged: a POSIX shell with awk. On Windows, install Git for Windows (Git Bash).

Upgrading

No migration. Existing pages, digests and journals work as they are. Saves made while v0.11.0 baselines are still live are unaffected. The first v0.12.0 save writes the ## Sessions bullet and refreshes the page's Index.md parenthetical itself.

Design: docs/superpowers/specs/2026-09-25-v0.12.0-design.md · PR #6