brain_edit_root: alert and audit a governance-file rewrite, don't just slog it #97

New Issue

2026-08-18T18:39:52Z

mathias commented

2026-08-18 18:39:52 +00:00

Follow-up from #96 (brain#4), where both were named as deliberate deferrals rather than oversights.

brain_edit_root is the privileged door for CLAUDE.md — de-surfaced from tools/list and gated on the local static principal. When it succeeds it emits a slog.Warn and nothing else.

Why that is not enough

The whole reason the tool is separated is that a governance-file rewrite is durable and cross-session: the next agent to clone the brain loads that CLAUDE.md as instructions. brain-sync commits and pushes it within 15 minutes, unattended, authored brain-sync — so in the git history it is indistinguishable from routine note traffic.

A control that is gated but unobserved tells you a rewrite was allowed. It does not tell you one happened.

Scope

ntfy on every successful brain_edit_root — path, principal, before/after content hash. brain-sync already posts to ntfy on failure, so the wiring and topic exist.
Audit-sink record — the capture path has AuditEntry + AuditSink for exactly this class of event (principal, actor, timestamp, items, security events). A byte-level mutation primitive on a pushed tree deserves the same trail; today it has strictly less observability than a capture call that writes a note.
Consider whether ordinary brain_edit on knowledge//wiki/ also warrants an audit record, or whether the git history is sufficient there. Probably sufficient — the asymmetry is that governance files change agent behaviour.

Acceptance Criteria

caveman: me get told when someone rewrite rules other agents obey
A successful brain_edit_root produces an ntfy notification and an audit record; a refused one produces neither a notification nor a write
Red-first test on the audit record's contents (principal, path, both hashes)
No secret or file content in the notification body — path and hashes only

Refs

#96 (the tool), brain#4 (the issue it implements)
brain wiki/hyperguild/decisions/model-callable-write-tools-must-not-reach-instruction-files — why the privileged door exists at all
internal/capture — the existing AuditSink shape to reuse

Risk: LOW — additive observability, no behaviour change to the gate itself.

Follow-up from #96 (brain#4), where both were named as deliberate deferrals rather than oversights. `brain_edit_root` is the privileged door for `CLAUDE.md` — de-surfaced from `tools/list` and gated on the local static principal. When it succeeds it emits a `slog.Warn` and nothing else. ## Why that is not enough The whole reason the tool is separated is that a governance-file rewrite is **durable and cross-session**: the next agent to clone the brain loads that `CLAUDE.md` as instructions. `brain-sync` commits and pushes it within 15 minutes, unattended, authored `brain-sync` — so in the git history it is indistinguishable from routine note traffic. A control that is gated but unobserved tells you a rewrite was *allowed*. It does not tell you one *happened*. ## Scope - [ ] **ntfy on every successful `brain_edit_root`** — path, principal, before/after content hash. `brain-sync` already posts to ntfy on failure, so the wiring and topic exist. - [ ] **Audit-sink record** — the capture path has `AuditEntry` + `AuditSink` for exactly this class of event (principal, actor, timestamp, items, security events). A byte-level mutation primitive on a pushed tree deserves the same trail; today it has strictly less observability than a `capture` call that writes a note. - [ ] Consider whether ordinary `brain_edit` on `knowledge/`/`wiki/` also warrants an audit record, or whether the git history is sufficient there. Probably sufficient — the asymmetry is that governance files change agent behaviour. ## Acceptance Criteria - [ ] `caveman: me get told when someone rewrite rules other agents obey` - [ ] A successful `brain_edit_root` produces an ntfy notification and an audit record; a refused one produces neither a notification nor a write - [ ] Red-first test on the audit record's contents (principal, path, both hashes) - [ ] No secret or file content in the notification body — path and hashes only ## Refs - #96 (the tool), brain#4 (the issue it implements) - brain `wiki/hyperguild/decisions/model-callable-write-tools-must-not-reach-instruction-files` — why the privileged door exists at all - `internal/capture` — the existing `AuditSink` shape to reuse **Risk:** LOW — additive observability, no behaviour change to the gate itself.

mathias referenced this issue from a commit

2026-08-20 15:30:25 +00:00

feat(mcp): record and alert on a governance-file rewrite (#97)

mathias referenced a pull request that will close this issue

2026-08-20 15:30:51 +00:00

feat(mcp): record and alert on a governance-file rewrite (#97) #98

mathias closed this issue

2026-08-22 06:09:53 +00:00

mathias referenced this issue from a commit

2026-08-22 06:09:54 +00:00

feat(mcp): record and alert on a governance-file rewrite (#97) (#98)

mathias referenced this issue