Repository navigation
v5.2.0 — The One Where Done Really Means Done
What this release is about
Your second brain had a habit of telling you something was done when it was not. This release is about the word done.
Your brain writes notes for you, tidies them, and updates itself. Each of those ends with a small report: saved, all clear, up to date. That report is the only thing you ever see, so it has to be the truth — and in five different places it was not.
None of them lost your work. A note it said it had saved was on your disk, exactly where you expected, just not backed up in the way your brain implied. A tidy report that said all clear was reading a note it could no longer understand and counting it as fine. An update you thought you had launched had not started, because the question was one line at the bottom of a long message. And when it told you it had found nothing, it did not say where it had looked.
They were not sloppiness — each one was a reasonable design that turned out to cover less ground than it claimed. This release makes each report say exactly as much as it knows, and no more. It also settles, once and in writing, when your brain may act on its own, when it should tell you what it is about to do, and when it genuinely has to ask you.
What you get
When your brain saves a note for you
- 💾 A note your brain writes is really backed up. When you ask it to tidy or file something, the note it writes is now versioned by the same gesture that wrote it, instead of waiting for a net that never saw it.
⚠️ And when it cannot, it tells you instead of ticking the box. It names the note, says it is on your disk but not backed up, and gives you the one command that says why.
When your brain tidies your notes (/lint)
- 📄 A note your brain can no longer read is now the first thing you are told about. Not buried in a tidying backlog: it comes first, and it says what it costs you — until you fix it, your searches answer from the version before the damage.
When you update your brain (/update-engine)
- 🔘 The question is a choice you click. It used to be one line of text at the bottom of a long message, easy to scroll straight past — and at least one person believed their update had run when it never had.
- 💻 Each of your computers gets the whole update. Some parts of your brain cannot travel through your backup repository, so a second machine used to end up with the new files and last week's wiring. It now notices and catches up on its own.
In ordinary conversations
- 🔍 "I found nothing" now says where it looked. Nothing in your notes or in Slack is a fact you can act on; a bare nothing reads, three days later, as nowhere. Your mail is now part of what it looks through before it says so.
- 🤝 It knows when to act and when to ask you. A settled rule, in writing: it does the undoable things quietly, tells you before the ones that would surprise you, and genuinely asks only where the answer is yours. Everything it writes is versioned, so almost nothing needs a permission slip.
What you have to do
Ask your brain to update its engine (/update-engine), click Run the update, then restart Claude once. Your notes, your keys, your constitution and the skills you tailored are left alone, as always.
Under the hood
The doctrine came first, deliberately, and it is ADR 0043. Group 3 of the tracker sweep held two very different things: a decision about how the brain speaks and when it may act, and a wide clean-up of every existing string. The decision ships here because this release emits new strings — writing them before the doctrine existed would have manufactured debt in the exact dimension the doctrine exists to clean. Three tiers (act silently · announce then act, with a veto · genuinely ask), gated on reversibility first, confidence second, with auto-commit named as what buys the autonomy: a brain that versions every write can afford to act, because acting is undoable. The tier belongs to the gesture, never to the skill. Prior art is named rather than reinvented — Sheridan & Verplank's levels of automation, SAE J3016, terraform plan → apply, undo-over-confirm and warning habituation, plainlanguage.gov / GOV.UK. The wide clean-up of existing strings is v5.4's subject, not this one's.
#77 — the writes the hook could not see. The auto-commit hook matches Write/Edit. /consolidate and /file-back route through scripts on purpose — that routing is what makes their notes conformant by construction — so the net had never seen them. Measured on a real brain: a consolidation pass refreshed five vault pages, printed ✓ Refreshed five times, and committed none. The two writer scripts now persist their own note by wrapping the hooks' own attemptCommit rather than spelling "commit the vault" a second time; two spellings of one gesture are two behaviours to keep in step. An unmerged tree is the one case where persistence steps aside, out loud: add . there would bury conflict markers inside your notes. The exit code stays 0 — the note is on disk, and a warning is not a failed write. The issue's secondary finding ("auto-push was on and nothing was pushed") is not a defect: auto-commit is commit-only by design and the push is debounced to the end of the turn.
#81 — a guard the harness steers around. The write guards match Write/Edit, and the harness actively steers towards Bash for file changes, so the path we recommend is the one nothing watches. Measured on a real vault: a malformed note landed two days after the guard shipped and answered searches from stale content for three weeks, its only trace one error line inside vault_stats. The direction was chosen before any code was written, and the obvious one was rejected: inspecting write-shaped Bash commands means reading shell, and a guard that half-reads shell is worse than none. The cheap pair catches the same defect after the bytes land, which is enough when the damage is unreadable rather than lost. A note that opens a frontmatter block and yields no keys is now its own finding, reported first, with no exemption, and it is the one frontmatter finding allowed past the session-start noise guardrail — on that guardrail's own criterion, a true regression that self-clears.
#96 — two kinds of promise, one of which git cannot keep. Files travel through git; machine-local wiring does not. .claude/settings.json, .mcp.json and rag/node_modules bake absolute paths or are build output, so they are gitignored by construction. The self-heal gate asked about skills and MCP servers only, so a release shipping a new hook or a new dependency converged on the machine that ran the update and nowhere else — silently, because a hook that was never wired runs never and therefore cannot report its own absence. It now asks four questions. For hooks the oracle is the reconciler itself, asked what it would add and told to write nothing, so anything reported has a remedy by construction; for dependencies it compares the names rag/package.json declares against what is on disk. The permission allowlist is deliberately not asked: an entry the engine never delivered and one you removed on purpose are the same absence, /permissions is a documented way back, and the reconciler has no allowlist remedy to run — a gate that reports a gap nothing can close is worse than one that stays quiet.
#98 — consent collected where nobody reads. The update quotes the release notes in full before asking, which means the better the notes, the further the only actionable sentence is pushed off screen. Both places the update asks — the go-ahead and the per-file three-way choice, plus its grouped variant — now use a clickable control, with the prose kept as the fallback where the host has no such tool. Three things deliberately did not change: consent is still required, an unanswered question still runs nothing, and "you are already on the latest release" still asks nothing at all.
#83 — an absence stated wider than the search behind it. "Exhaustive search in the vault and the chat tool" followed by "no trace" reads, three days later, as a general absence. It is the near-miss of #80, which shipped in v5.1.3 — same subject, different defect — and it is the one failure here whose consequence leaves the machine: a true, sourced statement was deleted from a message to an executive. The scope and the conclusion are now one sentence, and connected sources (mail above all) are part of what an absence check must cover. The retrieval ladder gained a rung for them, ahead of the open web. It ships as doctrine, carried by all six documents that hold this discipline in both languages, and pinned by a guard on each.
The update path was rehearsed twice on copies of real brains, before the tag rather than after it. A brain installed at v3.4.0 (508 engine files swapped, ten skills installed, nine automatic behaviours wired, one retired skill removed) and a brain one release behind holding 663 real notes (six skills refreshed, reindex incremental, nothing re-encoded). Both came out with the owner's own files byte-identical. The rehearsal only ever reads an original: the copy is taken without its history and every write goes to a temporary directory.
Mutation testing, scoped to what changed. Seven of eight targets at 100 %. The eighth is the entry worth reading: the self-heal wrapper scored 27 % on the first pass, because the gate is pure and was tested from every angle while the two functions that go and read the disk had no test at all — paths could be broken, both existence checks inverted and an or swapped for an and, with the file still green. It is the project's own convention word for word ("pure I/O" is not an exemption), and the second time that same seam has been the hole. Five tests later: 85.71 %, six named equivalents. Two other survivors died by asserting a separator rather than a name, and one was answered by a product change instead of a test — the banner printed a file extension that means something only to a developer. Full table in maintainers/mutation/RESULTS.md.
Closed by this release: #77, #81, #83, #96, #98, and #84 — which had no work left, only missing evidence that a real brain had received live sync, and the rehearsal above is that evidence.
Reviewed and knowingly left open, because a defect you reported deserves to be told it was seen: #72, #68, #82 and #66 are one subject seen from four angles and are v5.3's whole content. #79 is half done — its decision is ADR 0043, shipped here; the sweep of every existing string is v5.4. #78 splits into an engineering half that rides in v5.3 and a product question only the owner can answer. #62 is blocked on a design answer rather than on effort: a friction born inside a private vault would travel to a public repository, and nobody can size a de-identification design before it exists.