feat(pipeline): report when a re-ingest disagrees with the page on disk (#104)

The asymmetry that makes unattended ingest safe (#103) also discarded a
real signal. When a fresh extraction produced a different version of a
section already on disk, the on-disk version won and the model's version
went in the bin without a word — so "the source is unchanged" and "the
source changed its mind and we ignored it" were indistinguishable.

wiki.MergeReport now returns the headings where the incoming version
disagreed and lost, and the ingest run reports them as warnings, which
AppendLog already writes into log.md.

This is the simplified answer to contradiction flagging at ingest. The
issue proposed calling brain-gardener's Judge from the ingest path, which
needs either a shared Go module across two repos or an HTTP service that
does not exist — and puts an LLM call on the write path, where a timeout
must neither fail the ingest nor silently mark nothing as contested.

None of that is necessary to get the signal. The merge already computes
the disagreement; it was throwing it away. Surfacing it costs nothing,
needs no model, no cue-word matcher, no cross-repo dependency, and is
deterministic.

Deliberately textual disagreement, not semantic contradiction. Deciding
whether a disagreement is a genuine contradiction stays with the
Judge-gated enrich pass that already runs hourly and is approval-gated by
design (brain-gardener#175). Detection here, adjudication there.

Merge is kept as a thin wrapper over MergeReport so existing callers are
untouched.

Refs #104, #103, brain-gardener#175, brain#21.

.dispatch-allow

@@ -0,0 +1,2 @@
+# Presence of this file marks this repo as opt-in for headless dispatch.
+# See dispatch#3.

README.md

@@ -5,6 +5,11 @@ Instead of letting Claude Code do whatever it wants, hyperguild enforces structu
 workflows (TDD red/green/refactor), logs every session, and accumulates learnings
 into a searchable brain.
 
+**This repo is also where `brain-mcp` lives** — the MCP server at
+`brain-mcp.d-ma.be` that `brain_query`, `brain_write`, `brain_read`, `brain_edit`
+and `capture` are served from. It is not a separate deployable; see
+[Where brain-mcp lives](#where-brain-mcp-lives).
+
 ## Hypothesis
 
 > We believe routing skill tasks through local models, backed by brain context,
@@ -20,7 +25,7 @@ usage, the fast-model routing path should be reconsidered.
 
 **hyperguild = Claude Code + MCP.** This is a supervisor for Claude Code sessions specifically.
 For multi-agent orchestration (OpenCode + LiteLLM, executor/reviewer pipelines), see
-[agentsquad](http://gitea.d-ma.be/mathias/agentsquad) — a separate harness for a different
+[agentsquad](https://git.d-ma.be/mathias/agentsquad) — a separate harness for a different
 orchestration model. Skills (mathias/skills) are shared between both.
 
 ## How it works
@@ -44,6 +49,91 @@ brain/
 └── knowledge/      — legacy flat notes (migration pending: hyperguild#22)
 ```
 
+## Where brain-mcp lives
+
+`brain-mcp` is served from **`ingestion/internal/mcp`** in this repo, at
+**`brain-mcp.d-ma.be`**. It is a component *inside* the `ingestion` service, not
+a standalone deployable — one pod in the `supervisor` namespace serves the MCP
+endpoint, the REST API, and the claudewatcher together.
+
+| You are looking for | It is here |
+|---|---|
+| The MCP tool surface (`brain_query`, `brain_write`, `brain_read`, `brain_edit`, `capture`, …) | `ingestion/internal/mcp` |
+| The HTTP/REST API (`/query`, `/write`, `/ingest`) | `ingestion/internal/api` |
+| Session ingestion from Claude Code transcripts | `ingestion/internal/claudewatcher` |
+| The brain *content* (notes, wings, halls) | [`mathias/brain`](https://git.d-ma.be/mathias/brain) — a separate repo |
+| Deployment manifests | `config/supervisor` |
+
+### Why it is not its own repo
+
+Asked and decided in [#91](https://git.d-ma.be/mathias/hyperguild/issues/91)
+(part 2). `internal/mcp` imports 17 of ingestion's other internal packages and
+has exactly one importer — it is the MCP facade over the service's own
+internals, so "move it out" resolves to renaming `ingestion`, publishing 17
+packages as a shared library, or maintaining a shim. The discoverability problem
+that prompted the question is answered by naming it here instead.
+
+Full reasoning, including the reversal trigger: brain
+`wiki/hyperguild/decisions/brain-mcp-stays-in-ingestion-fix-discoverability-by-name`.
+
+## Ingest revises, it does not overwrite
+
+Re-ingesting a source **merges into the page already on disk** rather than
+replacing it. Previously the write was unconditional, so a second ingest of the
+same source discarded everything accumulated since — including hand-written
+sections.
+
+The merge is deliberately asymmetric in the existing page's favour:
+
+| On the page | In the fresh extraction | Result |
+|---|---|---|
+| a section | the same section | **the on-disk version wins** |
+| — | a new section | added |
+| a bullet list (`Sources`, `Key Claims`, …) | more bullets | unioned, no duplicates |
+| an append section (`Open Questions`, `Updates`, …) | more lines | only genuinely new lines appended |
+| frontmatter | frontmatter | **the on-disk frontmatter wins** |
+
+So an extraction can add to a note but never silently rewrite what a human put
+there, which is what makes it safe to run on every ingest rather than behind a
+review gate.
+
+Re-ingesting unchanged content is **byte-identical** — no diff, so brain-sync
+does not commit noise that hides real edits.
+
+Two fields are **generator-owned** and do get refreshed on a revise:
+`last_updated` and `source_hash`. Everything else on disk wins. The boundary is
+an explicit allowlist, so a field nobody has thought about stays human-owned.
+
+### Disagreement is reported, not resolved
+
+When the fresh extraction produces a *different version* of a section that
+already exists, the on-disk version still wins — but the run now says so:
+
+```
+wiki/sources/shape-up.md: source now disagrees on section "Summary" — on-disk version kept
+```
+
+That line lands in `log.md` with the rest of the run's warnings. Without it, "the
+source is unchanged" and "the source changed its mind and we ignored it" look
+identical from the outside.
+
+This is deliberately **textual** disagreement, not semantic contradiction: cheap,
+deterministic, no model on the write path. Deciding whether a disagreement is a
+genuine contradiction stays with the Judge-gated `brain-enrich` pass, which is
+approval-gated by design. Detection here, adjudication there.
+
+## Re-ingesting an unchanged source is skipped
+
+Ingest stores `source_hash` — sha256 of the ingested **body**, frontmatter
+excluded — on the source page. A later ingest of the same source compares it
+first and skips extraction entirely when it matches, reporting the skip rather
+than doing it silently.
+
+Body-only is deliberate: a re-crawl that stamps a new fetch date has not changed
+the source, and treating that as drift would re-extract the corpus every time a
+crawler ran. A missing or unreadable hash always means "extract" — a missed skip
+costs one extraction, a wrong skip loses an update.
+
 ## Phase 1 tools (available now)
 
 | Tool | What it does |
@@ -58,7 +148,7 @@ brain/
 | `tier` | Returns the current connectivity tier (1=cloud, 2=LAN, 3=offline) |
 
 > **Note:** `tdd_red/green/refactor` and `spec` were retired in Plan 7 (2026-05-12).
-> They are now SKILL.md files in [mathias/skills](http://gitea.d-ma.be/mathias/skills).
+> They are now SKILL.md files in [mathias/skills](https://git.d-ma.be/mathias/skills).
 
 ## Connect a project
 
@@ -147,7 +237,7 @@ The routing pod selects models per skill call based on historical pass rate:
 
 ## Open issues
 
-See [issues](http://gitea.d-ma.be/mathias/hyperguild/issues) — key open items:
+See [issues](https://git.d-ma.be/mathias/hyperguild/issues) — key open items:
 
 - **#25** — skills platform overhaul (audit first, then lazy loading + brain feedback loop)
 - **#24** — reduce context burn from skill listing

ingestion/cmd/server/main.go

@@ -144,6 +144,16 @@ func envInt(key string, fallback int) int {
 	return fallback
 }
 
+// buildNotifier returns the ntfy notifier, or a nil interface when
+// BRAIN_NTFY_URL is unset. A nil *interface* (not a typed-nil) is required so
+// DegradingSink/Reconcile and the governance observer skip it cleanly.
+func buildNotifier() audit.Notifier {
+	if n := audit.NewNtfyNotifier(os.Getenv("BRAIN_NTFY_URL"), os.Getenv("BRAIN_NTFY_TOKEN")); n != nil {
+		return n
+	}
+	return nil
+}
+
 // buildAuditSink selects the capture audit sink. When BRAIN_LOKI_URL is
 // set it builds the classification-aware DegradingSink (loki central +
 // durable file buffer + optional ntfy) and starts the reconcile loop;
@@ -161,12 +171,7 @@ func buildAuditSink(ctx context.Context, brainDir string, logger *slog.Logger) c
 		logger.Error("capture audit buffer init", "err", err)
 		os.Exit(1)
 	}
-	// Keep notifier as a nil interface (not a typed-nil) when unconfigured
-	// so DegradingSink/Reconcile skip it cleanly.
-	var notifier audit.Notifier
-	if n := audit.NewNtfyNotifier(os.Getenv("BRAIN_NTFY_URL"), os.Getenv("BRAIN_NTFY_TOKEN")); n != nil {
-		notifier = n
-	}
+	notifier := buildNotifier()
 	reconcileInterval := time.Duration(envInt("BRAIN_AUDIT_RECONCILE_INTERVAL", 60)) * time.Second
 	audit.StartReconcile(ctx, central, buffer, notifier, reconcileInterval)
 	logger.Info("capture audit: loki+buffer sink", "loki", lokiURL, "reconcile_s", int(reconcileInterval.Seconds()))
@@ -490,7 +495,13 @@ func main() {
 		// the existing /mcp OAuth connector. mcpSrv is already wrapped above;
 		// WithCapture mutates the same instance, so the tool appears live.
 		mcpSrv.WithCapture(captureSvc, jwtValidator, mcpToken, "local-cli", resolver)
-		logger.Info("capture enabled (REST + MCP tool)", "sovereign_principals", len(sovereign))
+		// hyperguild#97: a governance-file rewrite gets the same trail a
+		// capture already gets, plus an out-of-band alert. Wired here because
+		// brain_edit_root needs the capture plumbing anyway — that is what
+		// re-derives the static principal its gate checks.
+		mcpSrv.WithGovernanceObserver(auditSink, buildNotifier())
+		logger.Info("capture enabled (REST + MCP tool)", "sovereign_principals", len(sovereign),
+			"governance_observer", true)
 	} else {
 		logger.Info("capture endpoint disabled (BRAIN_GITEA_TOKEN unset)")
 	}

ingestion/internal/api/handler.go

@@ -12,6 +12,7 @@ import (
 	"time"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/claim"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/extract"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/search"
@@ -152,15 +153,24 @@ func writeHallNote(brainDir string, opts WriteNoteOptions) (string, error) {
 	if err != nil {
 		return "", err
 	}
-	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
-		return "", fmt.Errorf("create hall dir: %w", err)
-	}
-
 	existingFields, body := splitFrontmatter(opts.Content)
 	existingByKey := make(map[string]frontmatterField, len(existingFields))
 	for _, f := range existingFields {
 		existingByKey[f.key] = f
 	}
+
+	// Validate the claim-property envelope BEFORE creating the directory, so a
+	// rejected write leaves nothing behind — not even an empty hall dir
+	// (brain#21). Fail closed: a value outside the enum is worse than an absent
+	// one, because a lint skips what it cannot parse and the note then reads as
+	// classified while nothing acts on it.
+	if err := claim.ValidateEnvelope(scalarValues(existingFields)); err != nil {
+		return "", fmt.Errorf("claim envelope: %w", err)
+	}
+
+	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
+		return "", fmt.Errorf("create hall dir: %w", err)
+	}
 	emitted := make(map[string]bool, 6)
 
 	var fm strings.Builder
@@ -218,6 +228,25 @@ func writeHallNote(brainDir string, opts WriteNoteOptions) (string, error) {
 	return filepath.ToSlash(rel), nil
 }
 
+// scalarValues flattens frontmatter fields to key -> scalar value for
+// validation. Multi-line values (lists, nested blocks) yield the text after
+// the colon on the first line, which is empty for a list — correct here,
+// since every claim-property field is a scalar enum.
+func scalarValues(fields []frontmatterField) map[string]string {
+	out := make(map[string]string, len(fields))
+	for _, f := range fields {
+		if len(f.lines) == 0 {
+			continue
+		}
+		_, value, found := strings.Cut(f.lines[0], ":")
+		if !found {
+			continue
+		}
+		out[f.key] = strings.TrimSpace(value)
+	}
+	return out
+}
+
 // frontmatterField is one top-level YAML key from a frontmatter block,
 // along with its raw line and any indented continuation lines (e.g. a
 // bulleted list value spanning multiple lines).

ingestion/internal/api/handler_test.go

@@ -440,3 +440,60 @@ func TestIngestPath_Directory(t *testing.T) {
 	require.True(t, ok, "pages must be an array")
 	assert.NotEmpty(t, pagesSlice)
 }
+
+// --- brain#21: claim-property envelope on the write path -------------------
+
+func TestWriteNote_PreservesClaimEnvelopeVerbatim(t *testing.T) {
+	// writeHallNote already passes unknown keys through; this pins that
+	// behaviour for the envelope specifically, so a future refactor of the
+	// merge loop cannot silently drop it.
+	dir := t.TempDir()
+
+	rel, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content: "---\nhalf_life: durable\napplies: universal\nclaim_provenance: asserted\n---\n\nA durable claim.\n",
+		Wing:    "homelab",
+		Hall:    "decisions",
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.Contains(t, string(got), "half_life: durable")
+	assert.Contains(t, string(got), "applies: universal")
+	assert.Contains(t, string(got), "claim_provenance: asserted")
+}
+
+func TestWriteNote_RejectsInvalidClaimEnvelopeAndWritesNothing(t *testing.T) {
+	// Fail closed: a value outside the enum must not land. A lint skips what
+	// it cannot parse, so an unvalidated write produces a note that reads as
+	// classified while nothing acts on it.
+	dir := t.TempDir()
+
+	_, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content:  "---\nhalf_life: forever\nclaim_provenance: asserted\n---\n\nBody.\n",
+		Filename: "bad-envelope",
+		Wing:     "homelab",
+		Hall:     "facts",
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "half_life")
+
+	_, statErr := os.Stat(filepath.Join(dir, "wiki/homelab/facts/bad-envelope.md"))
+	assert.True(t, os.IsNotExist(statErr), "a rejected write must leave no file behind")
+}
+
+func TestWriteNote_RejectsClaimFieldWithoutProvenance(t *testing.T) {
+	dir := t.TempDir()
+
+	_, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content:  "---\napplies: homelab\n---\n\nBody.\n",
+		Filename: "no-provenance",
+		Wing:     "homelab",
+		Hall:     "facts",
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "claim_provenance")
+
+	_, statErr := os.Stat(filepath.Join(dir, "wiki/homelab/facts/no-provenance.md"))
+	assert.True(t, os.IsNotExist(statErr))
+}

ingestion/internal/claim/claim.go

@@ -0,0 +1,98 @@
+// Package claim validates the claim-property frontmatter that says when and
+// where a note's claim holds, and who decided that (brain#21).
+//
+// Two families were designed together and land separately. This is the
+// applicability envelope:
+//
+//	half_life:        volatile | seasonal | durable   — how fast it decays
+//	applies:          local | homelab | universal     — how widely it holds
+//	claim_provenance: asserted | inferred             — who set the above
+//
+// The strength family (confidence, contested) follows once the ingest-time
+// contradiction detector exists to populate it.
+//
+// Why the envelope is validated rather than merely accepted: a value outside
+// the enum is worse than an absent one. A lint skips what it cannot parse, so
+// the note reads as classified while nothing acts on it — the field becomes
+// decoration that suppresses the very review it was added to trigger.
+//
+// Why `applies` and not `scope`: `scope:` has been in use since brain#5 for
+// glossary terms (`homelab-core`, `project:<repo>`) — a disjoint value space
+// on the same key. The shipped schema keeps the name; this one takes another.
+package claim
+
+import (
+	"fmt"
+	"strings"
+)
+
+// Field names, exported so writers and lints agree on the spelling.
+const (
+	FieldHalfLife   = "half_life"
+	FieldApplies    = "applies"
+	FieldProvenance = "claim_provenance"
+)
+
+var (
+	halfLives   = []string{"volatile", "seasonal", "durable"}
+	appliesTo   = []string{"local", "homelab", "universal"}
+	provenances = []string{"asserted", "inferred"}
+)
+
+// ValidateEnvelope checks the envelope fields of one note's frontmatter.
+//
+// Absent fields are valid: the envelope is opt-in for new writes, and a
+// corpus-wide backfill is deliberately out of scope (brain#21) — inferring
+// 1113 notes' properties in bulk has the same failure mode as the extraction
+// pass that produced 28 wrong wikilinks out of 67.
+func ValidateEnvelope(fm map[string]string) error {
+	halfLife, hasHalfLife := present(fm, FieldHalfLife)
+	applies, hasApplies := present(fm, FieldApplies)
+	prov, hasProv := present(fm, FieldProvenance)
+
+	if hasHalfLife {
+		if err := oneOf(FieldHalfLife, halfLife, halfLives); err != nil {
+			return err
+		}
+	}
+	if hasApplies {
+		if err := oneOf(FieldApplies, applies, appliesTo); err != nil {
+			return err
+		}
+	}
+	if hasProv {
+		if err := oneOf(FieldProvenance, prov, provenances); err != nil {
+			return err
+		}
+	}
+
+	// The field and its provenance travel together or not at all. A value
+	// whose author is unknown cannot be trusted differently from one Mathias
+	// asserted, which is how an inferred guess hardens into accepted fact.
+	switch {
+	case (hasHalfLife || hasApplies) && !hasProv:
+		return fmt.Errorf("%s is required when %s or %s is set",
+			FieldProvenance, FieldHalfLife, FieldApplies)
+	case hasProv && !hasHalfLife && !hasApplies:
+		return fmt.Errorf("%s is set but neither %s nor %s is",
+			FieldProvenance, FieldHalfLife, FieldApplies)
+	}
+	return nil
+}
+
+// present reports a trimmed field value and whether it was set to anything
+// non-empty. A key written with an empty value is treated as absent rather
+// than as an error: that is a caller emitting a placeholder, not asserting.
+func present(fm map[string]string, key string) (string, bool) {
+	v := strings.TrimSpace(fm[key])
+	return v, v != ""
+}
+
+func oneOf(field, value string, allowed []string) error {
+	for _, a := range allowed {
+		if a == value {
+			return nil
+		}
+	}
+	return fmt.Errorf("%s: %q is not one of %s", field, value, strings.Join(allowed, ", "))
+}

ingestion/internal/claim/claim_test.go

@@ -0,0 +1,89 @@
+// Package claim_test covers the claim-property envelope (brain#21).
+package claim_test
+
+import (
+	"testing"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/claim"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestValidateEnvelope(t *testing.T) {
+	tests := []struct {
+		name    string
+		fm      map[string]string
+		wantErr string
+	}{
+		{
+			name: "absent is fine — the fields are opt-in on new writes",
+			fm:   map[string]string{"wing": "homelab", "hall": "facts"},
+		},
+		{
+			name: "complete envelope with provenance",
+			fm: map[string]string{
+				"half_life": "durable", "applies": "universal", "claim_provenance": "asserted",
+			},
+		},
+		{
+			name: "inferred provenance is equally valid — it just must be stated",
+			fm: map[string]string{
+				"half_life": "volatile", "applies": "local", "claim_provenance": "inferred",
+			},
+		},
+		{
+			// A value nobody can act on is worse than no value: a lint
+			// silently skips it, so the note looks classified and isn't.
+			name:    "unknown half_life value",
+			fm:      map[string]string{"half_life": "forever", "claim_provenance": "asserted"},
+			wantErr: `half_life: "forever" is not one of volatile, seasonal, durable`,
+		},
+		{
+			name:    "unknown applies value",
+			fm:      map[string]string{"applies": "galaxy", "claim_provenance": "asserted"},
+			wantErr: `applies: "galaxy" is not one of local, homelab, universal`,
+		},
+		{
+			// brain#21: a value a model inferred must never be
+			// indistinguishable from one Mathias asserted. Writing the field
+			// without saying who set it is exactly that laundering.
+			name:    "envelope field without provenance",
+			fm:      map[string]string{"half_life": "durable"},
+			wantErr: "claim_provenance is required when half_life or applies is set",
+		},
+		{
+			name:    "applies without provenance",
+			fm:      map[string]string{"applies": "homelab"},
+			wantErr: "claim_provenance is required when half_life or applies is set",
+		},
+		{
+			name:    "unknown provenance value",
+			fm:      map[string]string{"half_life": "durable", "claim_provenance": "probably"},
+			wantErr: `claim_provenance: "probably" is not one of asserted, inferred`,
+		},
+		{
+			// Provenance alone says who set fields that aren't there.
+			name:    "provenance without any envelope field",
+			fm:      map[string]string{"claim_provenance": "asserted"},
+			wantErr: "claim_provenance is set but neither half_life nor applies is",
+		},
+		{
+			// The glossary wing has used scope: homelab-core since #5. The
+			// envelope deliberately does NOT claim that key (brain#21).
+			name: "glossary scope is untouched",
+			fm:   map[string]string{"scope": "homelab-core", "term": "koala"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := claim.ValidateEnvelope(tt.fm)
+			if tt.wantErr == "" {
+				assert.NoError(t, err)
+				return
+			}
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), tt.wantErr)
+		})
+	}
+}

ingestion/internal/mcp/brain_update_test.go

@@ -165,7 +165,7 @@ func TestBrainUpdateReembedsNewContent(t *testing.T) {
 	ctx := context.Background()
 
 	callResult(t, toolCall(t, srv, "brain_write", map[string]any{
-		"content": "# Note\n\nthe OLD distinctive payload\n",
+		"content":  "# Note\n\nthe OLD distinctive payload\n",
 		"filename": "n", "wing": "a", "hall": "facts",
 	}))
 

ingestion/internal/mcp/handlers.go

@@ -14,6 +14,7 @@ import (
 	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/extract"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/graphsync"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/notes"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/search"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/session"
@@ -97,6 +98,8 @@ func (s *Server) tools() []map[string]any {
 				"slug":     str("optional target slug; defaults to filename minus date prefix"),
 			}),
 		},
+		noteToolDescriptors()[0],
+		noteToolDescriptors()[1],
 		{
 			"name":        "brain_tunnel",
 			"description": "Create an explicit bidirectional [[wikilink]] between two notes in different wings. Idempotent.",
@@ -320,6 +323,15 @@ func (s *Server) brainGet(ctx context.Context, args json.RawMessage) (json.RawMe
 	if target == "" {
 		return nil, fmt.Errorf("id or path is required")
 	}
+	// Containment: the store resolves any brain-relative path, and
+	// parseFrontmatter returns the WHOLE file as body when there is no
+	// frontmatter fence — so without this, brain_get reads verbatim session
+	// transcripts under archive/ and sessions/, which BM25 never indexes and
+	// which nobody therefore thinks of as reachable. Same allowlist as
+	// brain_read (brain#4).
+	if _, err := notes.Resolve(s.brainDir, target, notes.ScopeNotes); err != nil {
+		return nil, err
+	}
 	note, err := s.store.Get(ctx, target)
 	if err != nil {
 		return nil, err

ingestion/internal/mcp/server.go

@@ -49,6 +49,8 @@ type rpcError struct {
 // Server handles MCP JSON-RPC over HTTP for the ingestion service.
 type Server struct {
 	brainDir  string
+	govAudit  capture.AuditSink
+	govNotify govNotifier
 	pipeline  pipeline.Config
 	llm       pipeline.CompleteFunc
 	answerLLM pipeline.CompleteFunc // nil = brain_answer and brain_classify unavailable
@@ -275,6 +277,15 @@ func (s *Server) handleCall(ctx context.Context, name string, args json.RawMessa
 		return s.brainPromote(ctx, args)
 	case "capture":
 		return s.brainCapture(ctx, args)
+	case "brain_read":
+		return s.brainRead(ctx, args)
+	case "brain_edit":
+		return s.brainEdit(ctx, args)
+	case "brain_edit_root":
+		// Dispatches but is intentionally absent from tools/list — see
+		// tools_notes.go for why a governance-file editor must not be
+		// discoverable by a model.
+		return s.brainEditRoot(ctx, args)
 	case "brain_index":
 		return s.brainIndex(ctx, args)
 	case "brain_tunnel":

ingestion/internal/mcp/server_test.go

@@ -59,6 +59,7 @@ func TestServerToolsList(t *testing.T) {
 	assert.ElementsMatch(t, []string{
 		"brain_query", "brain_write", "brain_update", "brain_get",
 		"brain_pending", "brain_promote",
+		"brain_read", "brain_edit",
 		"brain_tunnel",
 		"brain_ingest_raw", "brain_ingest",
 		"brain_answer", "brain_classify", "brain_graph", "brain_context",
@@ -69,6 +70,13 @@ func TestServerToolsList(t *testing.T) {
 	// a caller verb is cognitive load with no decision behind it (ADR-0012
 	// rule 4, #78). The capability stays reachable — see the admin test below.
 	assert.NotContains(t, names, "brain_index")
+
+	// brain_edit_root is de-surfaced for a sharper reason than brain_index:
+	// brain content is ingested from the outside world and reaches a model's
+	// context, so a listed governance-file editor would be a durable
+	// prompt-injection path — one poisoned page rewriting the CLAUDE.md a
+	// .dispatch-allow agent later loads as instructions.
+	assert.NotContains(t, names, "brain_edit_root")
 }
 
 func TestBrainIndexStaysCallableForAdminUseAfterDeSurfacing(t *testing.T) {

ingestion/internal/mcp/tools_capture.go

@@ -31,7 +31,7 @@ func captureToolDescriptor() map[string]any {
 		"type": "object",
 		"properties": map[string]any{
 			"text": str("the insight body"), "wing": str("brain wing"),
-			"hall": str("brain hall (facts/decisions/failures/hypotheses/sources)"),
+			"hall":           str("brain hall (facts/decisions/failures/hypotheses/sources)"),
 			"supersede_slug": str("optional: slug of a prior note to revise in place instead of creating"),
 		},
 		"required": []string{"text", "wing", "hall"},
@@ -41,7 +41,7 @@ func captureToolDescriptor() map[string]any {
 		"properties": map[string]any{
 			"repo": str("gitea repo (owner is always mathias)"), "action": str("create|close|comment"),
 			"number": map[string]any{"type": "integer", "description": "issue number (close/comment)"},
-			"title": str("issue title (create)"), "body": str("issue/comment body"),
+			"title":  str("issue title (create)"), "body": str("issue/comment body"),
 		},
 		"required": []string{"repo", "action"},
 	}
@@ -51,14 +51,14 @@ func captureToolDescriptor() map[string]any {
 			"context": map[string]any{
 				"type": "object",
 				"properties": map[string]any{
-					"harness": str("descriptive harness label (telemetry only, never a gate input)"),
+					"harness":     str("descriptive harness label (telemetry only, never a gate input)"),
 					"session_ref": str("optional session reference"), "fidelity": str("live-capture|transcript-parse|agent-runlog"),
 					"actor": str("acting user/agent"), "classification": str("caller-declared sensitivity: public|internal|confidential"),
 				},
 			},
 			"insights": map[string]any{"type": "array", "items": insightItem},
 			"tickets":  map[string]any{"type": "array", "items": ticketItem},
-			"dry_run": map[string]any{"type": "boolean", "description": "validate + return the would-be receipt, write nothing"},
+			"dry_run":  map[string]any{"type": "boolean", "description": "validate + return the would-be receipt, write nothing"},
 		},
 	}
 	b, _ := json.Marshal(schema)

ingestion/internal/mcp/tools_notes.go

@@ -0,0 +1,222 @@
+package mcp
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"strings"
+	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/classification"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/notes"
+)
+
+// noteToolDescriptors are the model-facing halves of brain#4.
+//
+// brain_edit_root is deliberately absent: it dispatches but is not listed, the
+// same de-surfacing ADR-0012 rule 4 applies to brain_index (#78). Hiding the
+// verb matters here for a specific reason — brain content is ingested from the
+// outside world and reaches a model's context, so a listed governance-file
+// editor is a durable prompt-injection path: one poisoned page could rewrite
+// the CLAUDE.md that a .dispatch-allow agent later obeys. A human who knows
+// the tool exists can still call it; a model reading tools/list cannot
+// discover it.
+func noteToolDescriptors() []map[string]any {
+	str := func(d string) map[string]any { return map[string]any{"type": "string", "description": d} }
+	schema := func(required []string, props map[string]any) json.RawMessage {
+		b, _ := json.Marshal(map[string]any{"type": "object", "required": required, "properties": props})
+		return b
+	}
+	return []map[string]any{
+		{
+			"name": "brain_read",
+			"description": "Return a note's raw markdown verbatim — no synthesis, no excerpting. " +
+				"Use this to obtain the exact text before brain_edit; never build old_str from a " +
+				"brain_query excerpt, which is truncated and normalised and will not match.",
+			"inputSchema": schema([]string{"path"}, map[string]any{
+				"path": str("brain-relative path under knowledge/ or wiki/, e.g. wiki/homelab/facts/x.md"),
+			}),
+		},
+		{
+			"name": "brain_edit",
+			"description": "Replace exactly one occurrence of old_str with new_str in a note, leaving " +
+				"every other byte identical. Fails loudly if old_str is absent or matches more than " +
+				"once — extend old_str until it is unique. Does NOT stamp updated_at or supersedes " +
+				"(brain_update does); it is a byte-level patch, not a metadata operation.",
+			"inputSchema": schema([]string{"path", "old_str", "new_str"}, map[string]any{
+				"path":    str("brain-relative path under knowledge/ or wiki/"),
+				"old_str": str("exact text to replace; must occur exactly once"),
+				"new_str": str("replacement text; empty string deletes old_str"),
+			}),
+		},
+	}
+}
+
+// --- hyperguild#97: governance-rewrite observability -----------------------
+
+// govNotifier raises an out-of-band alert. Declared here rather than importing
+// internal/audit so the MCP package keeps depending on capture alone.
+type govNotifier interface {
+	Notify(ctx context.Context, msg string) error
+}
+
+// WithGovernanceObserver attaches the audit sink and notifier that observe a
+// successful brain_edit_root. Both are optional; either may be nil.
+func (s *Server) WithGovernanceObserver(sink capture.AuditSink, n govNotifier) {
+	s.govAudit, s.govNotify = sink, n
+}
+
+type brainReadArgs struct {
+	Path string `json:"path"`
+}
+
+func (s *Server) brainRead(_ context.Context, args json.RawMessage) (json.RawMessage, error) {
+	var a brainReadArgs
+	if err := json.Unmarshal(args, &a); err != nil {
+		return nil, fmt.Errorf("parse args: %w", err)
+	}
+	content, err := notes.Read(s.brainDir, a.Path)
+	if err != nil {
+		return nil, err
+	}
+	return json.Marshal(map[string]any{"path": a.Path, "content": string(content)})
+}
+
+type brainEditArgs struct {
+	Path   string `json:"path"`
+	OldStr string `json:"old_str"`
+	NewStr string `json:"new_str"`
+}
+
+// brainEdit is the model-facing editor: notes only.
+//
+// Deliberately NOT audited (#97). A note edit is already fully reconstructible
+// from git history, which carries the same before/after bytes plus a diff.
+// Governance files get the extra trail because they change what later agents
+// obey — the asymmetry is about instruction-carrying content, not about how
+// hard the change is to reconstruct. Auditing every note edit would also bury
+// the rare governance record under routine traffic, which is how an alert
+// stops being read.
+func (s *Server) brainEdit(_ context.Context, args json.RawMessage) (json.RawMessage, error) {
+	_, out, err := s.editWithScope(args, notes.ScopeNotes)
+	return out, err
+}
+
+// brainEditRoot edits a governance file (CLAUDE.md). De-surfaced AND gated on
+// the authenticated principal: only the static local-CLI token may call it, so
+// a claude.ai-origin session — the one that may have just read an untrusted
+// page — cannot rewrite the instructions later agents load.
+func (s *Server) brainEditRoot(ctx context.Context, args json.RawMessage) (json.RawMessage, error) {
+	info, ok := ctx.Value(principalKey).(principalInfo)
+	if !ok || !info.viaStatic {
+		return nil, fmt.Errorf("brain_edit_root requires the local static principal; " +
+			"a governance file is not editable from a model-facing origin")
+	}
+	res, out, err := s.editWithScope(args, notes.ScopeRoot)
+	if err != nil {
+		// A refusal is not a rewrite. Recording or alerting on one would cry
+		// wolf, and the gate already logs its own denials.
+		return out, err
+	}
+	// A durable instruction rewrite should be loud, not silent.
+	slog.Warn("brain_edit_root applied", "principal", info.principal, "result", string(out))
+	s.observeGovernanceEdit(ctx, info.principal, res)
+	return out, err
+}
+
+// observeGovernanceEdit records and alerts on a rewrite that already landed.
+//
+// Best-effort by construction: the bytes are written and brain-sync will commit
+// them within the quarter hour, so failing the call here would report a
+// non-rewrite to the caller while the rewrite sits on disk. A failure to
+// observe is therefore logged at ERROR — the one case where the trail itself is
+// what broke, and the only remaining signal.
+func (s *Server) observeGovernanceEdit(ctx context.Context, principal string, res notes.Result) {
+	// Path and hashes only. The notification leaves the cluster for a phone
+	// via a third-party topic; a hash identifies the rewrite, the bytes would
+	// leak whatever was written into an instruction file.
+	msg := fmt.Sprintf("brain_edit_root applied\npath=%s\nprincipal=%s\nbefore=%s\nafter=%s",
+		res.Path, principal, res.PrevContentHash, res.ContentHash)
+
+	if s.govNotify != nil {
+		if err := s.govNotify.Notify(ctx, msg); err != nil {
+			slog.Error("brain_edit_root notify failed", "path", res.Path, "err", err)
+		}
+	}
+	if s.govAudit == nil {
+		return
+	}
+	// Internal, not Confidential: a governance file is not client data, and
+	// Confidential would make DegradingSink REFUSE to record while loki is
+	// down rather than buffer — losing exactly the record that matters most.
+	outcome, err := s.govAudit.Reserve(ctx, classification.Internal)
+	if err != nil {
+		slog.Error("brain_edit_root audit reserve failed", "path", res.Path, "err", err)
+		return
+	}
+	entry := capture.AuditEntry{
+		Timestamp:               time.Now().UTC(),
+		Principal:               principal,
+		Actor:                   "brain_edit_root",
+		Harness:                 "mcp",
+		EffectiveClassification: classification.Internal.String(),
+		Items:                   []string{res.Path},
+		SecurityEvents: []string{fmt.Sprintf(
+			"governance file rewritten: %s before=%s after=%s",
+			res.Path, res.PrevContentHash, res.ContentHash)},
+	}
+	if err := s.govAudit.Record(ctx, entry, outcome); err != nil {
+		slog.Error("brain_edit_root audit record failed", "path", res.Path, "err", err)
+	}
+}
+
+func (s *Server) editWithScope(args json.RawMessage, scope notes.Scope) (notes.Result, json.RawMessage, error) {
+	var a brainEditArgs
+	if err := json.Unmarshal(args, &a); err != nil {
+		return notes.Result{}, nil, fmt.Errorf("parse args: %w", err)
+	}
+	res, err := notes.Edit(s.brainDir, a.Path, a.OldStr, a.NewStr, scope)
+	if err != nil {
+		return notes.Result{}, nil, err
+	}
+
+	// Reindex only when the edit could have changed what the index reads.
+	// BuildWingIndex consumes title/created_at from the frontmatter block;
+	// BM25 walks the filesystem live and embeddings are mtime-driven, so an
+	// unconditional rebuild would buy nothing and dirty a second file —
+	// _index.md being precisely the class brain-sync already needs a bespoke
+	// conflict resolver for.
+	if wing := wingOf(res.Path); wing != "" && touchesFrontmatter(a.OldStr, a.NewStr) {
+		if ierr := brain.BuildWingIndex(s.brainDir, wing); ierr != nil {
+			// Best-effort, matching every other index hook here: the write
+			// already landed and will be committed, so failing the call would
+			// make the caller retry an edit whose old_str no longer exists.
+			res.ReindexError = ierr.Error()
+		}
+	}
+	out, merr := json.Marshal(res)
+	return res, out, merr
+}
+
+// wingOf returns the wing for a wiki path, or "" for knowledge/ and root.
+func wingOf(rel string) string {
+	parts := strings.Split(rel, "/")
+	if len(parts) < 3 || parts[0] != "wiki" {
+		return ""
+	}
+	return parts[1]
+}
+
+// touchesFrontmatter reports whether either side of the edit mentions a field
+// the wing index reads.
+func touchesFrontmatter(oldStr, newStr string) bool {
+	for _, s := range []string{oldStr, newStr} {
+		if strings.Contains(s, "title:") || strings.Contains(s, "created_at:") || strings.Contains(s, "---") {
+			return true
+		}
+	}
+	return false
+}

ingestion/internal/mcp/tools_notes_test.go

@@ -0,0 +1,297 @@
+// ingestion/internal/mcp/tools_notes_test.go
+package mcp_test
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/audit"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainstore"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capturehttp"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/classification"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/mcp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// ---- brain#4: brain_read / brain_edit through the JSON-RPC surface --------
+
+func newBrainRepo(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, ".git"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki/homelab/facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "wiki/homelab/facts/n.md"),
+		[]byte("---\ntitle: 'n'\n---\n\nalpha\nbeta\n"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "CLAUDE.md"), []byte("# rules\n"), 0o644))
+	return dir
+}
+
+func call(t *testing.T, srv *mcp.Server, name string, args map[string]any) map[string]any {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodPost, "/mcp", body(t, map[string]any{
+		"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+		"params": map[string]any{"name": name, "arguments": args},
+	}))
+	rr := httptest.NewRecorder()
+	srv.ServeHTTP(rr, req)
+	var resp map[string]any
+	require.NoError(t, json.Unmarshal(rr.Body.Bytes(), &resp))
+	return resp
+}
+
+func TestBrainReadAndEdit_RoundTripThroughJSONRPC(t *testing.T) {
+	// The Go functions are tested in internal/notes; this pins the transport,
+	// because a tool that works in-process and is unreachable over JSON-RPC
+	// is indistinguishable from a working one in a unit test.
+	dir := newBrainRepo(t)
+	srv := mcp.NewServer(dir, nil, nil, nil)
+
+	resp := call(t, srv, "brain_read", map[string]any{"path": "wiki/homelab/facts/n.md"})
+	require.NotContains(t, resp, "error", "%v", resp["error"])
+
+	resp = call(t, srv, "brain_edit", map[string]any{
+		"path": "wiki/homelab/facts/n.md", "old_str": "beta", "new_str": "BETA",
+	})
+	require.NotContains(t, resp, "error", "%v", resp["error"])
+
+	got, err := os.ReadFile(filepath.Join(dir, "wiki/homelab/facts/n.md"))
+	require.NoError(t, err)
+	assert.Equal(t, "---\ntitle: 'n'\n---\n\nalpha\nBETA\n", string(got),
+		"only the matched bytes may change")
+}
+
+func TestBrainEdit_RefusesGovernanceFilesFromTheModelFacingTool(t *testing.T) {
+	dir := newBrainRepo(t)
+	srv := mcp.NewServer(dir, nil, nil, nil)
+
+	resp := call(t, srv, "brain_edit", map[string]any{
+		"path": "CLAUDE.md", "old_str": "# rules", "new_str": "# rewritten",
+	})
+	require.Contains(t, resp, "error", "brain_edit must not reach CLAUDE.md")
+
+	got, err := os.ReadFile(filepath.Join(dir, "CLAUDE.md"))
+	require.NoError(t, err)
+	assert.Equal(t, "# rules\n", string(got))
+}
+
+func TestBrainEditRoot_RefusedWithoutTheLocalStaticPrincipal(t *testing.T) {
+	// No principal in context is the model-facing case (and the default in
+	// this test server): the privileged door must stay shut.
+	dir := newBrainRepo(t)
+	srv := mcp.NewServer(dir, nil, nil, nil)
+
+	resp := call(t, srv, "brain_edit_root", map[string]any{
+		"path": "CLAUDE.md", "old_str": "# rules", "new_str": "# rewritten",
+	})
+	require.Contains(t, resp, "error")
+
+	got, err := os.ReadFile(filepath.Join(dir, "CLAUDE.md"))
+	require.NoError(t, err)
+	assert.Equal(t, "# rules\n", string(got), "governance file must be untouched")
+}
+
+func TestBrainGet_CannotReachSessionTranscripts(t *testing.T) {
+	// Pre-existing hole, not introduced here: api.ReadNote resolves any
+	// brain-relative path and parseFrontmatter returns the WHOLE file as body
+	// when there is no frontmatter fence. archive/ holds verbatim Claude
+	// session transcripts (up to 500 KB) that BM25 never indexes, so they are
+	// invisible to search and trivially readable by path — and CLAUDE.md
+	// documents the layout.
+	dir := newBrainRepo(t)
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "archive/claude-sessions/koala"), 0o755))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(dir, "archive/claude-sessions/koala/session-1.md"),
+		[]byte("verbatim transcript with tool output\n"), 0o644))
+
+	srv := mcp.NewServer(dir, nil, nil, nil)
+	resp := call(t, srv, "brain_get", map[string]any{"path": "archive/claude-sessions/koala/session-1.md"})
+
+	require.Contains(t, resp, "error", "brain_get must not read outside knowledge/ and wiki/")
+	assert.NotContains(t, string(mustJSON(t, resp)), "verbatim transcript")
+}
+
+func TestBrainGet_StillReadsNotes(t *testing.T) {
+	dir := newBrainRepo(t)
+	srv := mcp.NewServer(dir, nil, nil, nil)
+
+	resp := call(t, srv, "brain_get", map[string]any{"path": "wiki/homelab/facts/n.md"})
+	assert.NotContains(t, resp, "error", "%v", resp["error"])
+}
+
+func mustJSON(t *testing.T, v any) []byte {
+	t.Helper()
+	b, err := json.Marshal(v)
+	require.NoError(t, err)
+	return b
+}
+
+// ---- hyperguild#97: a governance rewrite must be observed, not just gated ----
+
+// govSink captures audit records. Governance edits are rare, so the whole
+// history is kept and asserted on rather than sampled.
+type govSink struct {
+	entries  []capture.AuditEntry
+	outcomes []capture.AuditOutcome
+	recErr   error
+}
+
+func (s *govSink) Reserve(context.Context, classification.Level) (capture.AuditOutcome, error) {
+	return capture.AuditCentral, nil
+}
+
+func (s *govSink) Record(_ context.Context, e capture.AuditEntry, o capture.AuditOutcome) error {
+	s.entries = append(s.entries, e)
+	s.outcomes = append(s.outcomes, o)
+	return s.recErr
+}
+
+type govNotifier struct {
+	msgs []string
+	err  error
+}
+
+func (n *govNotifier) Notify(_ context.Context, msg string) error {
+	n.msgs = append(n.msgs, msg)
+	return n.err
+}
+
+// govServer wires capture (which is what re-derives the static principal) plus
+// the #97 observer, and returns the brain dir so the test can read the file.
+func govServer(t *testing.T) (*mcp.Server, string, *govSink, *govNotifier) {
+	t.Helper()
+	dir := newBrainRepo(t)
+	cfg, err := classification.Load(dir)
+	require.NoError(t, err)
+	svc := capture.NewService(brainstore.New(dir), capFakeTracker{}, cfg, audit.NewSlogSink(nil))
+
+	srv := mcp.NewServer(dir, nil, nil, nil)
+	srv.WithCapture(svc, nil, capStaticTok, "local-cli", capturehttp.NewOriginResolver(nil))
+	sink, notifier := &govSink{}, &govNotifier{}
+	srv.WithGovernanceObserver(sink, notifier)
+	return srv, dir, sink, notifier
+}
+
+// authCall is call() with an Authorization header, so the static principal is
+// present and brain_edit_root's gate opens.
+func authCall(t *testing.T, srv *mcp.Server, authz, name string, args map[string]any) map[string]any {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodPost, "/mcp", body(t, map[string]any{
+		"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+		"params": map[string]any{"name": name, "arguments": args},
+	}))
+	if authz != "" {
+		req.Header.Set("Authorization", authz)
+	}
+	rr := httptest.NewRecorder()
+	srv.ServeHTTP(rr, req)
+	var resp map[string]any
+	require.NoError(t, json.Unmarshal(rr.Body.Bytes(), &resp))
+	return resp
+}
+
+func sha256hex(s string) string {
+	sum := sha256.Sum256([]byte(s))
+	return hex.EncodeToString(sum[:])
+}
+
+func TestBrainEditRoot_RecordsAnAuditEntryNamingPrincipalPathAndBothHashes(t *testing.T) {
+	// The gate proves a rewrite was ALLOWED. Only a record proves one HAPPENED
+	// — and brain-sync will commit it within 15 minutes authored `brain-sync`,
+	// so git history cannot tell it apart from routine note traffic.
+	srv, dir, sink, _ := govServer(t)
+
+	resp := authCall(t, srv, "Bearer "+capStaticTok, "brain_edit_root", map[string]any{
+		"path": "CLAUDE.md", "old_str": "# rules", "new_str": "# rewritten",
+	})
+	require.NotContains(t, resp, "error", "%v", resp["error"])
+
+	require.Len(t, sink.entries, 1, "exactly one audit record per governance rewrite")
+	e := sink.entries[0]
+	assert.Equal(t, "local-cli", e.Principal)
+	assert.Contains(t, e.Items, "CLAUDE.md", "the record must name what was rewritten")
+
+	joined := strings.Join(e.SecurityEvents, " ")
+	assert.Contains(t, joined, sha256hex("# rules\n"), "before-hash must be recorded")
+	assert.Contains(t, joined, sha256hex("# rewritten\n"), "after-hash must be recorded")
+	assert.NotZero(t, e.Timestamp)
+
+	got, err := os.ReadFile(filepath.Join(dir, "CLAUDE.md"))
+	require.NoError(t, err)
+	assert.Equal(t, "# rewritten\n", string(got))
+}
+
+func TestBrainEditRoot_NotifiesWithPathAndHashesButNeverContent(t *testing.T) {
+	srv, _, _, notifier := govServer(t)
+
+	resp := authCall(t, srv, "Bearer "+capStaticTok, "brain_edit_root", map[string]any{
+		"path": "CLAUDE.md", "old_str": "# rules", "new_str": "# rewritten",
+	})
+	require.NotContains(t, resp, "error", "%v", resp["error"])
+
+	require.Len(t, notifier.msgs, 1)
+	msg := notifier.msgs[0]
+	assert.Contains(t, msg, "CLAUDE.md")
+	assert.Contains(t, msg, "local-cli")
+	assert.Contains(t, msg, sha256hex("# rules\n"))
+	assert.Contains(t, msg, sha256hex("# rewritten\n"))
+
+	// The notification travels to a phone through a third-party topic. A hash
+	// identifies a rewrite; the bytes would leak whatever was written.
+	assert.NotContains(t, msg, "# rewritten", "no file content in the notification body")
+	assert.NotContains(t, msg, "# rules")
+}
+
+func TestBrainEditRoot_RefusedProducesNoRecordNoNotificationNoWrite(t *testing.T) {
+	srv, dir, sink, notifier := govServer(t)
+
+	// No Authorization header → no static principal → the gate stays shut.
+	resp := authCall(t, srv, "", "brain_edit_root", map[string]any{
+		"path": "CLAUDE.md", "old_str": "# rules", "new_str": "# rewritten",
+	})
+	require.Contains(t, resp, "error")
+
+	assert.Empty(t, sink.entries, "a refusal is not a rewrite — recording one would cry wolf")
+	assert.Empty(t, notifier.msgs)
+	got, err := os.ReadFile(filepath.Join(dir, "CLAUDE.md"))
+	require.NoError(t, err)
+	assert.Equal(t, "# rules\n", string(got))
+}
+
+func TestBrainEditRoot_FailedEditProducesNoRecordNoNotification(t *testing.T) {
+	// Authorised but no match: the door opened and nothing went through it.
+	srv, _, sink, notifier := govServer(t)
+
+	resp := authCall(t, srv, "Bearer "+capStaticTok, "brain_edit_root", map[string]any{
+		"path": "CLAUDE.md", "old_str": "absent-from-the-file", "new_str": "x",
+	})
+	require.Contains(t, resp, "error")
+
+	assert.Empty(t, sink.entries)
+	assert.Empty(t, notifier.msgs)
+}
+
+func TestBrainEdit_OnOrdinaryNotesIsNotAudited(t *testing.T) {
+	// The decided asymmetry (#97): note edits are covered by git history, which
+	// carries the same before/after bytes with a diff. Governance files get the
+	// extra trail because they change what later agents obey, not because they
+	// are harder to reconstruct.
+	srv, _, sink, notifier := govServer(t)
+
+	resp := authCall(t, srv, "Bearer "+capStaticTok, "brain_edit", map[string]any{
+		"path": "wiki/homelab/facts/n.md", "old_str": "beta", "new_str": "BETA",
+	})
+	require.NotContains(t, resp, "error", "%v", resp["error"])
+
+	assert.Empty(t, sink.entries, "note edits must not fill the governance audit trail")
+	assert.Empty(t, notifier.msgs)
+}

ingestion/internal/notes/edit.go

@@ -0,0 +1,282 @@
+package notes
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"syscall"
+	"unicode/utf8"
+)
+
+// maxNoteBytes caps what Read will hand back. Generous for knowledge/ and
+// wiki/ (the largest note today is far under it) and small enough that a
+// pathological file cannot flood a caller's context.
+const maxNoteBytes = 256 << 10
+
+// Errors callers distinguish.
+var (
+	ErrNoMatch    = errors.New("notes: old_str not found")
+	ErrAmbiguous  = errors.New("notes: old_str matches more than once")
+	ErrNotUTF8    = errors.New("notes: content is not valid UTF-8")
+	ErrGitBusy    = errors.New("notes: a git operation is in progress")
+	ErrTooLarge   = errors.New("notes: file exceeds the readable size limit")
+	ErrDegenerate = errors.New("notes: edit is degenerate")
+	ErrInConflict = errors.New("notes: file contains unresolved conflict markers")
+)
+
+// pathLocks serialises edits per file within this process. The flock below
+// covers the cross-process case (two pods share the hostPath during a rolling
+// update, and brain-fix/brain-enrich write the same tree).
+var pathLocks sync.Map // string -> *sync.Mutex
+
+// Result is what a successful edit reports.
+type Result struct {
+	Path string `json:"path"`
+	// PrevContentHash is the sha256 of the file as it was before this edit.
+	// Paired with ContentHash it identifies a rewrite in an audit trail or an
+	// alert without carrying any of the bytes (hyperguild#97).
+	PrevContentHash string `json:"prev_content_hash"`
+	ContentHash     string `json:"content_hash"`
+	BytesBefore     int    `json:"bytes_before"`
+	BytesAfter      int    `json:"bytes_after"`
+	ReindexError    string `json:"reindex_error,omitempty"`
+}
+
+// Read returns a note's bytes verbatim.
+//
+// No frontmatter parsing, no excerpting, no normalisation: the entire purpose
+// is to give a caller an exact basis for an edit. An excerpt from brain_query
+// would be truncated and normalised, and every old_str built from one would
+// miss.
+func Read(brainDir, path string) ([]byte, error) {
+	t, err := Resolve(brainDir, path, ScopeNotes)
+	if err != nil {
+		return nil, err
+	}
+	return readContained(t)
+}
+
+// ReadScoped is Read for a caller already holding the privileged scope.
+func ReadScoped(brainDir, path string, scope Scope) ([]byte, error) {
+	t, err := Resolve(brainDir, path, scope)
+	if err != nil {
+		return nil, err
+	}
+	return readContained(t)
+}
+
+func readContained(t Target) ([]byte, error) {
+	fi, err := os.Stat(t.Abs)
+	if err != nil {
+		return nil, fmt.Errorf("notes: stat %s: %w", t.Rel, err)
+	}
+	if fi.Size() > maxNoteBytes {
+		return nil, fmt.Errorf("%w: %s is %d bytes (limit %d)", ErrTooLarge, t.Rel, fi.Size(), maxNoteBytes)
+	}
+	b, err := os.ReadFile(t.Abs)
+	if err != nil {
+		return nil, fmt.Errorf("notes: read %s: %w", t.Rel, err)
+	}
+	// The MCP response marshals this into a JSON string, and encoding/json
+	// substitutes U+FFFD for invalid UTF-8 — silently returning different
+	// bytes than the file holds, which defeats "verbatim" entirely.
+	if !utf8.Valid(b) {
+		return nil, fmt.Errorf("%w: %s", ErrNotUTF8, t.Rel)
+	}
+	return b, nil
+}
+
+// Edit replaces exactly one occurrence of oldStr with newStr, in place.
+//
+// Fails loudly and writes nothing on: zero matches, more than one match
+// (counted with overlap), degenerate arguments, invalid UTF-8, a git operation
+// in flight, or unresolved conflict markers in the target.
+func Edit(brainDir, path, oldStr, newStr string, scope Scope) (Result, error) {
+	t, err := Resolve(brainDir, path, scope)
+	if err != nil {
+		return Result{}, err
+	}
+	if oldStr == "" {
+		return Result{}, fmt.Errorf("%w: old_str is empty", ErrDegenerate)
+	}
+	if oldStr == newStr {
+		return Result{}, fmt.Errorf("%w: old_str equals new_str", ErrDegenerate)
+	}
+	if !utf8.ValidString(newStr) {
+		return Result{}, fmt.Errorf("%w: new_str", ErrNotUTF8)
+	}
+	// brain#2 guard: refuse to write to a tree the sync does not commit from.
+	if err := assertSyncSource(brainDir); err != nil {
+		return Result{}, err
+	}
+	if err := assertGitIdle(brainDir); err != nil {
+		return Result{}, err
+	}
+
+	mu := lockFor(t.Abs)
+	mu.Lock()
+	defer mu.Unlock()
+
+	unlock, err := flockFile(t.Abs)
+	if err != nil {
+		return Result{}, err
+	}
+	defer unlock()
+
+	// Read INSIDE the lock: the match count must be evaluated against the
+	// bytes we are about to overwrite, or a concurrent edit is silently lost
+	// while both callers are told they succeeded.
+	before, err := readContained(t)
+	if err != nil {
+		return Result{}, err
+	}
+	if hasConflictMarkers(before) {
+		return Result{}, fmt.Errorf("%w: %s", ErrInConflict, t.Rel)
+	}
+
+	switch n := countOverlapping(string(before), oldStr); {
+	case n == 0:
+		return Result{}, fmt.Errorf("%w in %s (0 matches)%s", ErrNoMatch, t.Rel, crlfHint(string(before), oldStr))
+	case n > 1:
+		return Result{}, fmt.Errorf("%w in %s (%d matches) — extend old_str until it is unique",
+			ErrAmbiguous, t.Rel, n)
+	}
+
+	after := strings.Replace(string(before), oldStr, newStr, 1)
+	if err := writeAtomic(t.Abs, []byte(after)); err != nil {
+		return Result{}, err
+	}
+
+	sum := sha256.Sum256([]byte(after))
+	prev := sha256.Sum256(before)
+	return Result{
+		Path:            t.Rel,
+		PrevContentHash: hex.EncodeToString(prev[:]),
+		ContentHash:     hex.EncodeToString(sum[:]),
+		BytesBefore:     len(before),
+		BytesAfter:      len(after),
+	}, nil
+}
+
+// countOverlapping counts occurrences allowing overlap. bytes.Count does not:
+// "aa" occurs once in "aaa" by its reckoning, so a Count-based uniqueness
+// check accepts an ambiguous edit as unique.
+func countOverlapping(s, sub string) int {
+	var n, from int
+	for {
+		i := strings.Index(s[from:], sub)
+		if i < 0 {
+			return n
+		}
+		n++
+		from += i + 1
+	}
+}
+
+// crlfHint reports whether the caller's old_str would have matched if line
+// endings agreed. It never normalises — that would break byte-identity — but
+// an opaque "no match" is unfixable from the caller's side, and a stripped \r
+// is the likeliest cause.
+func crlfHint(content, oldStr string) string {
+	if strings.Contains(content, "\r\n") && !strings.Contains(oldStr, "\r\n") {
+		if strings.Contains(strings.ReplaceAll(content, "\r\n", "\n"), oldStr) {
+			return " — the file uses CRLF line endings and old_str does not; include the \\r"
+		}
+	}
+	return ""
+}
+
+func hasConflictMarkers(b []byte) bool {
+	s := string(b)
+	return strings.Contains(s, "\n<<<<<<< ") || strings.HasPrefix(s, "<<<<<<< ")
+}
+
+// assertGitIdle refuses while brain-sync (or brain-fix, or a human) has a git
+// operation in flight. An edit landing between `git merge` and its abort is
+// either hard-reset away or committed as a wrongly resolved conflict — and the
+// caller was told it succeeded.
+func assertGitIdle(brainDir string) error {
+	for _, marker := range []string{"MERGE_HEAD", "REBASE_HEAD", "CHERRY_PICK_HEAD", "index.lock"} {
+		if _, err := os.Stat(filepath.Join(brainDir, ".git", marker)); err == nil {
+			return fmt.Errorf("%w (.git/%s present) — retry after the sync settles", ErrGitBusy, marker)
+		}
+	}
+	return nil
+}
+
+func lockFor(abs string) *sync.Mutex {
+	v, _ := pathLocks.LoadOrStore(abs, &sync.Mutex{})
+	return v.(*sync.Mutex)
+}
+
+// flockFile takes an advisory lock covering other processes sharing the
+// hostPath — during a RollingUpdate two ingestion pods do.
+func flockFile(abs string) (func(), error) {
+	f, err := os.OpenFile(abs+".lock", os.O_CREATE|os.O_RDWR, 0o644)
+	if err != nil {
+		return nil, fmt.Errorf("notes: lock %s: %w", filepath.Base(abs), err)
+	}
+	if err := syscall.Flock(int(f.Fd()), syscall.LOCK_EX); err != nil {
+		_ = f.Close()
+		return nil, fmt.Errorf("notes: flock %s: %w", filepath.Base(abs), err)
+	}
+	return func() {
+		_ = syscall.Flock(int(f.Fd()), syscall.LOCK_UN)
+		_ = f.Close()
+		_ = os.Remove(abs + ".lock")
+	}, nil
+}
+
+// writeAtomic replaces the file via a same-directory temp + rename, then
+// fsyncs the directory so the rename survives a node crash.
+//
+// Same directory because a rename across the hostPath boundary fails with
+// EXDEV; the ".tmp" suffix because the tree's .gitignore already covers it, so
+// a leaked temp is not committed by `git add -A`.
+func writeAtomic(abs string, content []byte) error {
+	dir := filepath.Dir(abs)
+	tmp, err := os.CreateTemp(dir, filepath.Base(abs)+".*.tmp")
+	if err != nil {
+		return fmt.Errorf("notes: temp file: %w", err)
+	}
+	tmpName := tmp.Name()
+	defer func() { _ = os.Remove(tmpName) }() // no-op once renamed
+
+	if _, err := tmp.Write(content); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("notes: write temp: %w", err)
+	}
+	if err := tmp.Sync(); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("notes: sync temp: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("notes: close temp: %w", err)
+	}
+	// CreateTemp makes 0600; every other writer of this tree uses 0644 and
+	// other uids read it.
+	if err := os.Chmod(tmpName, 0o644); err != nil {
+		return fmt.Errorf("notes: chmod temp: %w", err)
+	}
+	if err := os.Rename(tmpName, abs); err != nil {
+		return fmt.Errorf("notes: rename: %w", err)
+	}
+	return fsyncDir(dir)
+}
+
+func fsyncDir(dir string) error {
+	d, err := os.Open(dir)
+	if err != nil {
+		return fmt.Errorf("notes: open dir: %w", err)
+	}
+	defer func() { _ = d.Close() }()
+	if err := d.Sync(); err != nil {
+		return fmt.Errorf("notes: fsync dir: %w", err)
+	}
+	return nil
+}

ingestion/internal/notes/edit_test.go

@@ -0,0 +1,256 @@
+package notes
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+)
+
+func seed(t *testing.T, dir, rel, content string) string {
+	t.Helper()
+	abs := filepath.Join(dir, rel)
+	if err := os.MkdirAll(filepath.Dir(abs), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(abs, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return abs
+}
+
+func read(t *testing.T, abs string) string {
+	t.Helper()
+	b, err := os.ReadFile(abs)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return string(b)
+}
+
+func TestRead_ReturnsVerbatimBytes(t *testing.T) {
+	dir := newBrain(t)
+	const body = "---\ntitle: 'x'\n---\n\nbody with  double  spaces\r\nand a CRLF line\nno trailing newline"
+	seed(t, dir, "knowledge/verbatim.md", body)
+
+	got, err := Read(dir, "knowledge/verbatim.md")
+	if err != nil {
+		t.Fatalf("Read: %v", err)
+	}
+	if string(got) != body {
+		t.Errorf("Read returned %q, want the file byte-for-byte", got)
+	}
+}
+
+func TestRead_RefusesNonUTF8RatherThanCorruptingIt(t *testing.T) {
+	// The response is marshalled into a JSON string, and encoding/json
+	// replaces invalid UTF-8 with U+FFFD. Returning it would mean every
+	// old_str the caller derives from that region can never match, and
+	// pasting it back would write the corruption to disk permanently.
+	dir := newBrain(t)
+	seed(t, dir, "knowledge/bad.md", "ok \xff\xfe broken\n")
+
+	if _, err := Read(dir, "knowledge/bad.md"); err == nil {
+		t.Fatal("Read accepted invalid UTF-8; it must refuse rather than silently substitute")
+	}
+}
+
+func TestEdit_ReplacesExactlyOnceAndLeavesEveryOtherByteAlone(t *testing.T) {
+	dir := newBrain(t)
+	const body = "---\ntitle: 'x'\n---\n\nalpha\nbeta\ngamma\n"
+	abs := seed(t, dir, "knowledge/n.md", body)
+
+	res, err := Edit(dir, "knowledge/n.md", "beta", "BETA", ScopeNotes)
+	if err != nil {
+		t.Fatalf("Edit: %v", err)
+	}
+	want := strings.Replace(body, "beta", "BETA", 1)
+	if got := read(t, abs); got != want {
+		t.Errorf("file = %q, want %q", got, want)
+	}
+	if res.ContentHash == "" {
+		t.Error("result should carry a content hash for read-after-write confirmation")
+	}
+}
+
+func TestEdit_RefusesAmbiguousAndAbsentMatchesWithoutWriting(t *testing.T) {
+	dir := newBrain(t)
+	const body = "alpha\nalpha\n"
+	abs := seed(t, dir, "knowledge/n.md", body)
+
+	cases := []struct{ name, old, want string }{
+		{"two matches", "alpha", "2"},
+		{"no match", "delta", "0"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := Edit(dir, "knowledge/n.md", tc.old, "x", ScopeNotes)
+			if err == nil {
+				t.Fatal("want a loud refusal")
+			}
+			if !strings.Contains(err.Error(), tc.want) {
+				t.Errorf("error must state the match count, got %v", err)
+			}
+			if got := read(t, abs); got != body {
+				t.Errorf("file changed on a refused edit: %q", got)
+			}
+		})
+	}
+}
+
+func TestEdit_CountsOverlappingMatches(t *testing.T) {
+	// bytes.Count counts NON-overlapping occurrences: "aa" in "aaa" is 1, so
+	// a Count-based uniqueness check calls an ambiguous edit unique.
+	dir := newBrain(t)
+	seed(t, dir, "knowledge/n.md", "aaa\n")
+
+	if _, err := Edit(dir, "knowledge/n.md", "aa", "b", ScopeNotes); err == nil {
+		t.Fatal("overlapping matches must be reported as ambiguous")
+	}
+}
+
+func TestEdit_RejectsDegenerateArguments(t *testing.T) {
+	dir := newBrain(t)
+	seed(t, dir, "knowledge/n.md", "alpha\n")
+
+	if _, err := Edit(dir, "knowledge/n.md", "", "x", ScopeNotes); err == nil {
+		t.Error("empty old_str must be rejected")
+	}
+	if _, err := Edit(dir, "knowledge/n.md", "alpha", "alpha", ScopeNotes); err == nil {
+		t.Error("a no-op edit must be rejected rather than burning a sync cycle")
+	}
+}
+
+func TestEdit_DeletionIsLegal(t *testing.T) {
+	dir := newBrain(t)
+	abs := seed(t, dir, "knowledge/n.md", "keep\ndrop\n")
+
+	if _, err := Edit(dir, "knowledge/n.md", "drop\n", "", ScopeNotes); err != nil {
+		t.Fatalf("Edit: %v", err)
+	}
+	if got := read(t, abs); got != "keep\n" {
+		t.Errorf("file = %q, want %q", got, "keep\n")
+	}
+}
+
+func TestEdit_ReportsWhenOnlyLineEndingsDiffer(t *testing.T) {
+	// The likeliest real failure: the caller's old_str lost its \r. Never
+	// normalise silently — that breaks byte-identity — but say so, because an
+	// opaque "no match" is unfixable from the caller's side.
+	dir := newBrain(t)
+	seed(t, dir, "knowledge/n.md", "alpha\r\nbeta\r\n")
+
+	_, err := Edit(dir, "knowledge/n.md", "alpha\nbeta", "x", ScopeNotes)
+	if err == nil {
+		t.Fatal("want a refusal")
+	}
+	if !strings.Contains(err.Error(), "line ending") {
+		t.Errorf("error should point at CRLF, got %v", err)
+	}
+}
+
+func TestEdit_RefusesWhileGitIsMidOperation(t *testing.T) {
+	// brain-sync runs `git merge -X ours origin/main`, and aborts on conflict
+	// with a hard reset. An edit landing inside that window is either erased
+	// or committed as a wrongly-resolved conflict, and the caller was told it
+	// succeeded.
+	dir := newBrain(t)
+	seed(t, dir, "knowledge/n.md", "alpha\n")
+
+	for _, marker := range []string{"MERGE_HEAD", "index.lock", "REBASE_HEAD"} {
+		t.Run(marker, func(t *testing.T) {
+			p := filepath.Join(dir, ".git", marker)
+			if err := os.WriteFile(p, []byte("x"), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			defer func() { _ = os.Remove(p) }()
+
+			if _, err := Edit(dir, "knowledge/n.md", "alpha", "beta", ScopeNotes); err == nil {
+				t.Errorf("edit accepted while %s exists", marker)
+			}
+		})
+	}
+}
+
+func TestEdit_RefusesAFileHoldingConflictMarkers(t *testing.T) {
+	dir := newBrain(t)
+	seed(t, dir, "knowledge/n.md", "<<<<<<< HEAD\nours\n=======\ntheirs\n>>>>>>> origin/main\n")
+
+	if _, err := Edit(dir, "knowledge/n.md", "ours", "x", ScopeNotes); err == nil {
+		t.Fatal("editing one side of an unresolved conflict must be refused")
+	}
+}
+
+func TestEdit_ConcurrentEditsBothApply(t *testing.T) {
+	// Read-modify-write with no lock loses one update AND reports success for
+	// both. old_str uniqueness does not protect against it: uniqueness is
+	// evaluated against the stale read.
+	dir := newBrain(t)
+	abs := seed(t, dir, "knowledge/n.md", "alpha\nbeta\n")
+
+	var wg sync.WaitGroup
+	errs := make([]error, 2)
+	for i, pair := range [][2]string{{"alpha", "ALPHA"}, {"beta", "BETA"}} {
+		wg.Add(1)
+		go func(i int, old, new string) {
+			defer wg.Done()
+			_, errs[i] = Edit(dir, "knowledge/n.md", old, new, ScopeNotes)
+		}(i, pair[0], pair[1])
+	}
+	wg.Wait()
+
+	for i, err := range errs {
+		if err != nil {
+			t.Fatalf("edit %d failed: %v", i, err)
+		}
+	}
+	if got := read(t, abs); got != "ALPHA\nBETA\n" {
+		t.Errorf("file = %q, want both edits applied", got)
+	}
+}
+
+func TestEdit_LeavesNoTemporaryFileBehind(t *testing.T) {
+	dir := newBrain(t)
+	seed(t, dir, "knowledge/n.md", "alpha\n")
+
+	if _, err := Edit(dir, "knowledge/n.md", "alpha", "beta", ScopeNotes); err != nil {
+		t.Fatal(err)
+	}
+	entries, err := os.ReadDir(filepath.Join(dir, "knowledge"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, e := range entries {
+		if e.Name() != "note.md" && e.Name() != "n.md" {
+			t.Errorf("stray file left in the tree: %q (git add -A would commit it)", e.Name())
+		}
+	}
+}
+
+func TestEdit_PreservesReadableMode(t *testing.T) {
+	// Other uids write this tree (brain-fix, brain-enrich). os.CreateTemp
+	// yields 0600 and rename preserves it, which would break them silently.
+	dir := newBrain(t)
+	abs := seed(t, dir, "knowledge/n.md", "alpha\n")
+
+	if _, err := Edit(dir, "knowledge/n.md", "alpha", "beta", ScopeNotes); err != nil {
+		t.Fatal(err)
+	}
+	fi, err := os.Stat(abs)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if fi.Mode().Perm() != 0o644 {
+		t.Errorf("mode = %v, want 0644", fi.Mode().Perm())
+	}
+}
+
+func TestEdit_RefusesNonUTF8Replacement(t *testing.T) {
+	dir := newBrain(t)
+	seed(t, dir, "knowledge/n.md", "alpha\n")
+
+	if _, err := Edit(dir, "knowledge/n.md", "alpha", "bad \xff", ScopeNotes); err == nil {
+		t.Fatal("new_str with invalid UTF-8 must be refused, not written")
+	}
+}

ingestion/internal/notes/path.go

@@ -0,0 +1,201 @@
+// Package notes provides containment-checked read and surgical edit of brain
+// notes on the live tree that brain-sync commits from.
+//
+// Everything here is defensive for one reason: brain content is ingested from
+// the outside world, that content reaches a model's context via brain_query /
+// brain_context, and these primitives are callable by that model. A path bug
+// is therefore not a path bug — it is an outside author choosing a file.
+package notes
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// Scope is which part of the tree a caller is allowed to touch.
+type Scope int
+
+const (
+	// ScopeNotes is the model-facing scope: markdown under knowledge/ and
+	// wiki/ only.
+	ScopeNotes Scope = iota
+	// ScopeRoot admits the named governance files and NOTHING else. It exists so
+	// there is an MCP path to CLAUDE.md at all — the absence of one is what
+	// pushed a session to edit via the gitea REST API on 2026-06-16, which
+	// never reached the live tree and wedged brain-sync for hours. It is NOT
+	// reachable from the model-facing toolset; see tools_notes.go.
+	ScopeRoot
+)
+
+// rootFiles is an exact-name allowlist, deliberately not a "root *.md" glob.
+//
+// Two reasons. log.md is gitignored, so an edit to it applies to the live tree
+// and never reaches gitea — the exact shape of brain#2, admitted by a glob. And
+// a glob auto-admits whatever governance file appears next (AGENTS.md, a
+// bootstrap doc) with nobody reviewing that decision.
+var rootFiles = map[string]bool{"CLAUDE.md": true}
+
+// noteDirs are the two trees that hold notes.
+var noteDirs = []string{"knowledge/", "wiki/"}
+
+// deniedPrefixes are refused in every scope, independent of the allowlist.
+//
+// A static backstop rather than a consequence of the allowlist being right:
+// .git/hooks/post-commit is executed by brain-sync inside a pod holding the
+// Gitea push credentials, and archive/ + sessions/ hold verbatim session
+// transcripts that BM25 never indexes and so nobody thinks of as reachable.
+var deniedPrefixes = []string{".git/", "archive/", "sessions/", "raw/", "training-data/", ".obsidian/"}
+
+// Errors are sentinels so callers can distinguish a refusal from an I/O fault.
+var (
+	ErrOutsideBrain  = errors.New("notes: path escapes the brain dir")
+	ErrNotAllowed    = errors.New("notes: path is not editable through this tool")
+	ErrNotSyncSource = errors.New("notes: brain dir is not the sync source")
+)
+
+// Target is a resolved, contained path.
+type Target struct {
+	Rel string // brain-relative, cleaned
+	Abs string // absolute, symlink-checked
+}
+
+// Resolve canonicalises path, then checks it against the scope's allowlist,
+// then re-checks containment after symlink evaluation.
+//
+// Order matters and is the point: a prefix test on the raw argument accepts
+// "knowledge/../.git/hooks/post-commit", because Clean only collapses it
+// afterwards.
+func Resolve(brainDir, path string, scope Scope) (Target, error) {
+	// Note: the sync-source assertion lives on the WRITE path (Edit), not
+	// here. brain#2 was an edit landing where the sync could not commit it; a
+	// read from such a tree is merely a read.
+
+	// 1. Canonicalise. Rooting at "/" makes Clean collapse every ".." that
+	//    would otherwise escape, and ToSlash normalises separators first.
+	clean := strings.TrimPrefix(filepath.Clean("/"+filepath.ToSlash(path)), "/")
+	if clean == "" || clean == "." {
+		return Target{}, fmt.Errorf("%w: empty path", ErrNotAllowed)
+	}
+
+	// 2. Static denials, before any allowlist reasoning.
+	for _, d := range deniedPrefixes {
+		if strings.HasPrefix(clean+"/", d) {
+			return Target{}, fmt.Errorf("%w: %q is not note content", ErrNotAllowed, clean)
+		}
+	}
+	if strings.HasPrefix(filepath.Base(clean), ".") {
+		return Target{}, fmt.Errorf("%w: dotfiles are not editable", ErrNotAllowed)
+	}
+
+	// 3. Scope allowlist.
+	if err := allow(clean, scope); err != nil {
+		return Target{}, err
+	}
+
+	// 4. Containment, lexically.
+	abs := filepath.Join(brainDir, filepath.FromSlash(clean))
+	if !within(brainDir, abs) {
+		return Target{}, fmt.Errorf("%w: %q", ErrOutsideBrain, path)
+	}
+
+	// 5. Containment again, after resolving symlinks. The tree is Syncthing
+	//    managed, so a link can appear without anyone adding one on purpose;
+	//    a symlinked note or directory would otherwise read and write outside
+	//    the brain entirely.
+	if err := assertNoSymlinkEscape(brainDir, abs); err != nil {
+		return Target{}, err
+	}
+
+	return Target{Rel: clean, Abs: abs}, nil
+}
+
+// allow enforces the scope's allowlist. The two scopes are DISJOINT, not
+// nested: the privileged root scope reaches governance files and nothing else,
+// so the tool that carries the higher privilege carries the smaller reach.
+func allow(clean string, scope Scope) error {
+	if scope == ScopeRoot {
+		if !rootFiles[clean] {
+			return fmt.Errorf("%w: %q is not a governance file", ErrNotAllowed, clean)
+		}
+		return nil
+	}
+	if !isNotePath(clean) {
+		return fmt.Errorf("%w: %q is outside knowledge/ and wiki/", ErrNotAllowed, clean)
+	}
+	return nil
+}
+
+func isNotePath(clean string) bool {
+	var inDir bool
+	for _, d := range noteDirs {
+		if strings.HasPrefix(clean, d) {
+			inDir = true
+			break
+		}
+	}
+	if !inDir || filepath.Ext(clean) != ".md" {
+		return false
+	}
+	// _index.md is generated per wing, and brain-sync's conflict resolver
+	// deliberately resolves it in origin's favour — an edit here is reverted
+	// by design, so accepting one would be a lie.
+	return filepath.Base(clean) != "_index.md"
+}
+
+func within(root, abs string) bool {
+	rel, err := filepath.Rel(root, abs)
+	if err != nil {
+		return false
+	}
+	return rel != ".." && !strings.HasPrefix(rel, ".."+string(filepath.Separator))
+}
+
+// assertNoSymlinkEscape resolves the deepest existing ancestor of abs and
+// requires it to still be inside brainDir. The file itself need not exist
+// (a create is legal); its directory chain must be real and contained.
+func assertNoSymlinkEscape(brainDir, abs string) error {
+	if fi, err := os.Lstat(abs); err == nil && fi.Mode()&os.ModeSymlink != 0 {
+		return fmt.Errorf("%w: %q is a symlink", ErrNotAllowed, abs)
+	}
+
+	realRoot, err := filepath.EvalSymlinks(brainDir)
+	if err != nil {
+		return fmt.Errorf("notes: resolve brain dir: %w", err)
+	}
+
+	dir := filepath.Dir(abs)
+	for {
+		resolved, err := filepath.EvalSymlinks(dir)
+		if err == nil {
+			if !within(realRoot, resolved) {
+				return fmt.Errorf("%w: %q resolves outside the brain dir", ErrOutsideBrain, dir)
+			}
+			return nil
+		}
+		if !os.IsNotExist(err) {
+			return fmt.Errorf("notes: resolve %q: %w", dir, err)
+		}
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			return fmt.Errorf("%w: no existing ancestor for %q", ErrOutsideBrain, abs)
+		}
+		dir = parent
+	}
+}
+
+// assertSyncSource refuses a brain dir that is not a git working tree.
+//
+// brain#2 was an edit landing on a directory the sync does not commit from.
+// That cannot be prevented by review — a wrong INGEST_BRAIN_DIR in a future
+// manifest reintroduces it while every unit test still passes — so it is
+// asserted at runtime, the same check brain-sync itself makes before running.
+func assertSyncSource(brainDir string) error {
+	if fi, err := os.Stat(filepath.Join(brainDir, ".git")); err != nil || !fi.IsDir() {
+		return fmt.Errorf("%w: %q has no .git, so an edit there would never be committed",
+			ErrNotSyncSource, brainDir)
+	}
+	return nil
+}

ingestion/internal/notes/path_test.go

@@ -0,0 +1,146 @@
+package notes
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// newBrain lays out a tree shaped like the live one: a git dir, note dirs,
+// and the non-note areas that must never be reachable.
+func newBrain(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	for _, d := range []string{
+		".git/hooks", "knowledge", "wiki/homelab/facts", "archive/claude-sessions/koala",
+		"sessions", "raw", ".obsidian",
+	} {
+		if err := os.MkdirAll(filepath.Join(dir, d), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	write := func(p, s string) {
+		t.Helper()
+		if err := os.WriteFile(filepath.Join(dir, p), []byte(s), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	write("CLAUDE.md", "# instructions\n")
+	write("log.md", "ignored scratch\n")
+	write("knowledge/note.md", "# note\n")
+	write("wiki/homelab/facts/f.md", "# fact\n")
+	write("wiki/homelab/_index.md", "# index\n")
+	write("archive/claude-sessions/koala/session-1.md", "verbatim transcript\n")
+	write("sessions/s.jsonl", "{}\n")
+	write(".git/hooks/post-commit", "#!/bin/sh\n")
+	return dir
+}
+
+func TestResolve_AcceptsNotePaths(t *testing.T) {
+	dir := newBrain(t)
+	for _, p := range []string{"knowledge/note.md", "wiki/homelab/facts/f.md"} {
+		got, err := Resolve(dir, p, ScopeNotes)
+		if err != nil {
+			t.Errorf("Resolve(%q): %v", p, err)
+			continue
+		}
+		if !strings.HasPrefix(got.Abs, dir) {
+			t.Errorf("Resolve(%q).Abs = %q, want inside %q", p, got.Abs, dir)
+		}
+	}
+}
+
+func TestResolve_RefusesEscapesAndNonNoteAreas(t *testing.T) {
+	dir := newBrain(t)
+
+	// Canonicalisation must happen BEFORE the allowlist check. A prefix test
+	// on the raw argument accepts every one of these: "knowledge/..%2f" style
+	// inputs collapse to .git, and .git/hooks/post-commit is executed by
+	// brain-sync inside a pod holding the Gitea push credentials.
+	refuse := []string{
+		"knowledge/../.git/hooks/post-commit",
+		"wiki/../.git/config",
+		"./knowledge/../.git/config",
+		"knowledge//../.git/config",
+		"../../etc/passwd",
+		"/etc/passwd",
+		".git/config",
+		"archive/claude-sessions/koala/session-1.md", // verbatim transcripts
+		"sessions/s.jsonl",
+		"raw/x.md",
+		".obsidian/workspace.json",
+		"log.md",                 // gitignored: an edit here would never sync (brain#2)
+		"wiki/homelab/_index.md", // generated; brain-sync resolves it in origin's favour
+		"knowledge/note.txt",     // not markdown
+		"CLAUDE.md",              // root file — not reachable in the notes scope
+	}
+	for _, p := range refuse {
+		if _, err := Resolve(dir, p, ScopeNotes); err == nil {
+			t.Errorf("Resolve(%q) = nil error, want refusal", p)
+		}
+	}
+}
+
+func TestResolve_RootScopeAdmitsOnlyNamedFiles(t *testing.T) {
+	dir := newBrain(t)
+
+	if _, err := Resolve(dir, "CLAUDE.md", ScopeRoot); err != nil {
+		t.Errorf("Resolve(CLAUDE.md, ScopeRoot): %v", err)
+	}
+	// log.md is the reason this is an exact-name list and not "root *.md":
+	// it is gitignored, so an edit would apply locally and never reach gitea.
+	for _, p := range []string{"log.md", "AGENTS.md", "knowledge/note.md", ".git/config"} {
+		if _, err := Resolve(dir, p, ScopeRoot); err == nil {
+			t.Errorf("Resolve(%q, ScopeRoot) = nil error, want refusal", p)
+		}
+	}
+}
+
+func TestResolve_RefusesSymlinkedTargets(t *testing.T) {
+	dir := newBrain(t)
+	outside := filepath.Join(t.TempDir(), "secret.md")
+	if err := os.WriteFile(outside, []byte("secret\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// The tree is Syncthing-managed, so a symlink can appear without anyone
+	// adding one deliberately. Containment must survive it.
+	if err := os.Symlink(outside, filepath.Join(dir, "knowledge/link.md")); err != nil {
+		t.Skipf("symlinks unavailable: %v", err)
+	}
+	if _, err := Resolve(dir, "knowledge/link.md", ScopeNotes); err == nil {
+		t.Error("Resolve followed a symlink out of the brain dir")
+	}
+
+	if err := os.Symlink(filepath.Dir(outside), filepath.Join(dir, "wiki/escape")); err != nil {
+		t.Skipf("symlinks unavailable: %v", err)
+	}
+	if _, err := Resolve(dir, "wiki/escape/secret.md", ScopeNotes); err == nil {
+		t.Error("Resolve followed a symlinked directory out of the brain dir")
+	}
+}
+
+func TestResolve_RefusesWhenTheTreeIsNotTheSyncSource(t *testing.T) {
+	// brain#2 was "wrote to a directory the sync does not commit from". No
+	// code review prevents that recurring — a wrong INGEST_BRAIN_DIR in a
+	// future manifest reintroduces it and every unit test still passes. So
+	// assert the property at runtime, the way brain-sync itself does.
+	dir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(dir, "knowledge"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "knowledge/note.md"), []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// Reads are fine anywhere; the guard belongs to writes.
+	if _, err := Resolve(dir, "knowledge/note.md", ScopeNotes); err != nil {
+		t.Fatalf("Resolve should not require .git for a read: %v", err)
+	}
+	_, err := Edit(dir, "knowledge/note.md", "x", "y", ScopeNotes)
+	if err == nil {
+		t.Fatal("Edit accepted a tree with no .git — the write would never be committed")
+	}
+	if !strings.Contains(err.Error(), "sync source") {
+		t.Errorf("error should name the cause, got %v", err)
+	}
+}

ingestion/internal/pipeline/build.go

@@ -76,6 +76,9 @@ func buildFrontmatter(rp RawPage, date string) string {
 		}
 		fmt.Fprintf(&sb, "date_ingested: %s\n", date)
 		fmt.Fprintf(&sb, "last_updated: %s\n", date)
+		if rp.SourceHash != "" {
+			fmt.Fprintf(&sb, "source_hash: %s\n", rp.SourceHash)
+		}
 		if rp.Source != "" {
 			fmt.Fprintf(&sb, "source: %s\n", yamlScalar(rp.Source))
 		}

ingestion/internal/pipeline/parse.go

@@ -20,9 +20,13 @@ type RawPage struct {
 	// ingested content's own frontmatter (see parseContentFrontmatter) — never
 	// set by the LLM. json:"-" keeps them immune to same-named keys the LLM
 	// might emit. Only meaningful for Type == "source".
-	Source    string `json:"-"`
-	Author    string `json:"-"`
-	Published string `json:"-"`
+	// SourceHash is sha256 of the ingested BODY (frontmatter excluded), stamped
+	// so the next ingest of the same source can tell "unchanged" from "edited"
+	// without re-running extraction (#105).
+	SourceHash string `json:"-"`
+	Source     string `json:"-"`
+	Author     string `json:"-"`
+	Published  string `json:"-"`
 }
 
 // ParseRawPages parses LLM output as a JSON array of RawPage objects.
@@ -112,6 +116,11 @@ type sourceMeta struct {
 	Source    string
 	Author    string
 	Published string
+	// BodyHash is sha256 of the content with any leading frontmatter removed.
+	// Body-only on purpose: a re-crawl that stamps a new fetch date has not
+	// changed the source, and treating that as drift would re-extract the
+	// whole corpus every time a crawler ran (#105).
+	BodyHash string
 }
 
 // parseContentFrontmatter extracts source/author/published from a leading
@@ -154,6 +163,7 @@ func applySourceMeta(pages []RawPage, meta sourceMeta) {
 		if pages[i].Type != "source" {
 			continue
 		}
+		pages[i].SourceHash = meta.BodyHash
 		pages[i].Source = meta.Source
 		pages[i].Author = meta.Author
 		pages[i].Published = meta.Published

ingestion/internal/pipeline/pipeline.go

@@ -3,6 +3,8 @@ package pipeline
 
 import (
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -26,6 +28,11 @@ type Config struct {
 type Result struct {
 	Pages    []string // relative paths written (or would-be written in dry-run)
 	Warnings []string
+	// Skipped reports that the source was byte-identical to the last ingest,
+	// so no extraction ran and nothing was written. Reported rather than
+	// silent: a run that does nothing must say so, or "the pipeline is fine"
+	// and "the pipeline stopped working" look the same (#105, #107).
+	Skipped bool
 }
 
 // Run ingests content and writes structured wiki pages to brainDir/wiki/.
@@ -43,6 +50,18 @@ func Run(ctx context.Context, cfg Config, brainDir, content, source string, dryR
 
 	sourceSlug := wiki.Slug(source)
 	date := time.Now().UTC().Format("2006-01-02")
+
+	// Drift check BEFORE any extraction: an unchanged source costs a full LLM
+	// pass over every chunk to produce a result that merges to nothing (#105).
+	// The merge is already idempotent (#103), so this is cost and signal, not
+	// correctness — which is why it is safe for it to be an early return.
+	bodyHash := hashBody(content)
+	if !dryRun && bodyHash != "" && bodyHash == storedSourceHash(brainDir, sourceSlug) {
+		return Result{Skipped: true, Warnings: []string{
+			fmt.Sprintf("source %q unchanged since last ingest (hash %s) — extraction skipped", source, bodyHash[:12]),
+		}}, nil
+	}
+
 	chunks := Chunk(content, cfg.ChunkSize)
 
 	var allRaw []RawPage
@@ -59,7 +78,9 @@ func Run(ctx context.Context, cfg Config, brainDir, content, source string, dryR
 		allWarnings = append(allWarnings, warnings...)
 	}
 
-	applySourceMeta(allRaw, parseContentFrontmatter(content))
+	meta := parseContentFrontmatter(content)
+	meta.BodyHash = bodyHash
+	applySourceMeta(allRaw, meta)
 
 	return buildAndWrite(allRaw, sourceSlug, date, brainDir, source, inventory, allWarnings, dryRun)
 }
@@ -96,7 +117,19 @@ func buildAndWrite(rawPages []RawPage, sourceSlug, date, brainDir, source string
 			if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
 				return Result{}, fmt.Errorf("mkdir for %s: %w", page.Path, err)
 			}
-			if err := os.WriteFile(dest, []byte(page.Content), 0o644); err != nil {
+			content, conflicts, err := reviseOrCreate(dest, page)
+			if err != nil {
+				return Result{}, err
+			}
+			for _, heading := range conflicts {
+				// Reported, not resolved. The on-disk version stands; whether
+				// the disagreement is a genuine contradiction is the
+				// Judge-gated enrich pass's call, not the write path's.
+				warnings = append(warnings, fmt.Sprintf(
+					"%s: source now disagrees on section %q — on-disk version kept",
+					page.Path, heading))
+			}
+			if err := os.WriteFile(dest, []byte(content), 0o644); err != nil {
 				return Result{}, fmt.Errorf("write %s: %w", page.Path, err)
 			}
 		}
@@ -115,6 +148,76 @@ func buildAndWrite(rawPages []RawPage, sourceSlug, date, brainDir, source string
 	return Result{Pages: written, Warnings: warnings}, nil
 }
 
+// hashBody returns sha256 of content with any leading frontmatter block
+// removed, or "" for empty content.
+//
+// Body-only on purpose: a re-crawl that stamps a new fetch date has not changed
+// the source, and treating that as drift would re-extract the corpus every time
+// a crawler ran (#105).
+func hashBody(content string) string {
+	body := content
+	if strings.HasPrefix(body, "---\n") {
+		if _, rest, found := strings.Cut(body[4:], "\n---"); found {
+			body = strings.TrimPrefix(rest, "\n")
+		}
+	}
+	if strings.TrimSpace(body) == "" {
+		return ""
+	}
+	sum := sha256.Sum256([]byte(body))
+	return hex.EncodeToString(sum[:])
+}
+
+// storedSourceHash reads source_hash from the source page a previous ingest
+// wrote, or "" when there is no such page or no such field.
+//
+// Absence always means "extract". That is the fail-safe direction: a missed
+// skip costs one extraction, while a wrong skip loses an update silently — and
+// silence is the failure mode this repo keeps paying for.
+func storedSourceHash(brainDir, sourceSlug string) string {
+	raw, err := os.ReadFile(filepath.Join(brainDir, "wiki", "sources", sourceSlug+".md"))
+	if err != nil {
+		return ""
+	}
+	for _, line := range strings.Split(string(raw), "\n") {
+		if key, value, found := strings.Cut(line, ":"); found && strings.TrimSpace(key) == "source_hash" {
+			return strings.TrimSpace(value)
+		}
+	}
+	return ""
+}
+
+// reviseOrCreate returns the bytes to write for one extracted page: merged into
+// whatever is already on disk, or the page as-is when the path is new.
+//
+// This is the compile half of compile-on-ingest. Before it, the write was an
+// unconditional os.WriteFile, so re-ingesting a source replaced its page
+// wholesale and discarded everything accumulated since — including human edits
+// (hyperguild#43: "re-ingest overwrites wholesale").
+//
+// The merge is deliberately asymmetric in the existing page's favour:
+// wiki.Merge keeps the on-disk frontmatter and the on-disk version of any
+// section both sides carry, adds sections only the extraction produced, and
+// unions bullet lists. So a freshly extracted page can add to a note but never
+// silently rewrite what a human put there — which is what makes it safe to run
+// this on every ingest rather than behind a review gate.
+//
+// Known limitation: because the on-disk frontmatter wins, `last_updated` keeps
+// its first-ingest date on a revised page. Left deliberately — the alternative
+// is this function editing frontmatter it does not own, and no lint reads that
+// field today.
+func reviseOrCreate(dest string, page wiki.Page) (string, []string, error) {
+	existing, err := os.ReadFile(dest)
+	switch {
+	case os.IsNotExist(err):
+		return page.Content, nil, nil
+	case err != nil:
+		return "", nil, fmt.Errorf("read existing %s: %w", page.Path, err)
+	}
+	merged, conflicts := wiki.MergeReport(wiki.Page{Path: page.Path, Content: string(existing)}, page)
+	return merged.Content, conflicts, nil
+}
+
 // mergeAll deduplicates pages by path, merging content from later occurrences.
 func mergeAll(pages []wiki.Page) []wiki.Page {
 	order := make([]string, 0, len(pages))

ingestion/internal/pipeline/pipeline_test.go

@@ -8,6 +8,7 @@ import (
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 
@@ -171,3 +172,156 @@ func mustJSON(v any) string {
 	}
 	return string(b)
 }
+
+// --- B1: compile-on-ingest — revise the existing page, never clobber it -----
+
+func TestRunRaw_MergesIntoAnExistingPageInsteadOfOverwritingIt(t *testing.T) {
+	// Before this, buildAndWrite did an unconditional os.WriteFile: re-ingesting
+	// a source replaced its page wholesale, discarding anything accumulated
+	// since — including human edits. hyperguild#43 recorded the symptom as
+	// "re-ingest overwrites wholesale".
+	dir := t.TempDir()
+	page := filepath.Join(dir, "wiki", "sources", "shape-up.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(page), 0o755))
+	require.NoError(t, os.WriteFile(page, []byte(`---
+title: 'Shape Up'
+---
+
+## Summary
+
+A book about shaping product work.
+
+## My Take
+
+Read this before the next planning cycle.
+`), 0o644))
+
+	_, err := RunRaw(dir, "shape-up", []RawPage{{
+		Title: "Shape Up", Type: "source", Subtype: "book", Domain: "product-strategy",
+		Content: "## Summary\n\nA book about shaping product work.\n\n## Key Claims\n\n- Appetite beats estimation.\n",
+	}}, false)
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(page)
+	require.NoError(t, err)
+	s := string(got)
+
+	assert.Contains(t, s, "## My Take", "a section the extraction never saw must survive the merge")
+	assert.Contains(t, s, "Read this before the next planning cycle.")
+	assert.Contains(t, s, "Appetite beats estimation.", "newly extracted material must still land")
+}
+
+func TestRunRaw_ReIngestingUnchangedContentIsByteIdentical(t *testing.T) {
+	// Compile-on-ingest runs on every ingest, so "nothing changed" must produce
+	// no diff at all. Otherwise every re-ingest dirties the tree, brain-sync
+	// commits it, and the git history fills with noise that hides real edits.
+	dir := t.TempDir()
+	raw := []RawPage{{
+		Title: "Shape Up", Type: "source", Subtype: "book", Domain: "product-strategy",
+		Content: "## Summary\n\nA book about shaping product work.\n\n## Open Questions\n\n- Does appetite scale?\n",
+	}}
+
+	_, err := RunRaw(dir, "shape-up", raw, false)
+	require.NoError(t, err)
+	first, err := os.ReadFile(filepath.Join(dir, "wiki", "sources", "shape-up.md"))
+	require.NoError(t, err)
+
+	_, err = RunRaw(dir, "shape-up", raw, false)
+	require.NoError(t, err)
+	second, err := os.ReadFile(filepath.Join(dir, "wiki", "sources", "shape-up.md"))
+	require.NoError(t, err)
+
+	assert.Equal(t, string(first), string(second),
+		"re-ingesting unchanged content must leave the page byte-identical")
+}
+
+// --- #105: source drift — an unchanged re-ingest must not re-extract --------
+
+func TestRun_SkipsExtractionWhenTheSourceIsUnchanged(t *testing.T) {
+	// #103 made a re-ingest harmless (byte-identical merge). It is still not
+	// free: the full LLM extraction runs over every chunk to produce a result
+	// that merges to nothing. This is the cost half.
+	dir := t.TempDir()
+	var calls int
+	cfg := Config{Complete: func(_ context.Context, _, _ string) (string, error) {
+		calls++
+		return `[{"title":"Shape Up","type":"source","subtype":"book","domain":"product","content":"## Summary\n\nA book.\n"}]`, nil
+	}}
+
+	content := "---\nsource: https://example.com/shape-up\n---\n\nThe body of the article.\n"
+
+	first, err := Run(context.Background(), cfg, dir, content, "shape-up", false)
+	require.NoError(t, err)
+	require.Equal(t, 1, calls, "first ingest must extract")
+	assert.False(t, first.Skipped)
+
+	second, err := Run(context.Background(), cfg, dir, content, "shape-up", false)
+	require.NoError(t, err)
+	assert.Equal(t, 1, calls, "unchanged content must not be extracted again")
+	assert.True(t, second.Skipped, "the skip must be reported, not silent")
+}
+
+func TestRun_ReExtractsWhenTheSourceBodyChanged(t *testing.T) {
+	dir := t.TempDir()
+	var calls int
+	cfg := Config{Complete: func(_ context.Context, _, _ string) (string, error) {
+		calls++
+		return `[{"title":"Shape Up","type":"source","subtype":"book","domain":"product","content":"## Summary\n\nA book.\n"}]`, nil
+	}}
+
+	_, err := Run(context.Background(), cfg, dir, "---\nsource: x\n---\n\nversion one\n", "shape-up", false)
+	require.NoError(t, err)
+	_, err = Run(context.Background(), cfg, dir, "---\nsource: x\n---\n\nversion two — the source was edited\n", "shape-up", false)
+	require.NoError(t, err)
+
+	assert.Equal(t, 2, calls, "changed content must be re-extracted")
+}
+
+func TestRun_FrontmatterOnlyChangeIsNotDrift(t *testing.T) {
+	// The hash covers the body, so re-fetching a page whose metadata moved
+	// (a re-crawl stamping a new date) is not treated as the source changing.
+	dir := t.TempDir()
+	var calls int
+	cfg := Config{Complete: func(_ context.Context, _, _ string) (string, error) {
+		calls++
+		return `[{"title":"Shape Up","type":"source","subtype":"book","domain":"product","content":"## Summary\n\nA book.\n"}]`, nil
+	}}
+
+	_, err := Run(context.Background(), cfg, dir, "---\nsource: x\nfetched: monday\n---\n\nsame body\n", "shape-up", false)
+	require.NoError(t, err)
+	_, err = Run(context.Background(), cfg, dir, "---\nsource: x\nfetched: tuesday\n---\n\nsame body\n", "shape-up", false)
+	require.NoError(t, err)
+
+	assert.Equal(t, 1, calls, "only the body counts as the source")
+}
+
+func TestRunRaw_ReportsWhenTheSourceDisagreesWithWhatIsOnDisk(t *testing.T) {
+	// The on-disk version still wins — that is what makes unattended ingest
+	// safe. But the run must say that the source now claims something else,
+	// or a changed source is indistinguishable from an unchanged one.
+	dir := t.TempDir()
+	page := filepath.Join(dir, "wiki", "sources", "shape-up.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(page), 0o755))
+	require.NoError(t, os.WriteFile(page, []byte(`---
+title: 'Shape Up'
+---
+
+## Summary
+
+Appetite is fixed, scope is variable.
+`), 0o644))
+
+	res, err := RunRaw(dir, "shape-up", []RawPage{{
+		Title: "Shape Up", Type: "source", Subtype: "book", Domain: "product",
+		Content: "## Summary\n\nAppetite is negotiable and scope is fixed.\n",
+	}}, false)
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(page)
+	require.NoError(t, err)
+	assert.Contains(t, string(got), "Appetite is fixed", "on-disk version wins")
+
+	joined := strings.Join(res.Warnings, " ")
+	assert.Contains(t, joined, "Summary", "the disagreeing section must be named")
+	assert.Contains(t, joined, "shape-up", "and the page it happened on")
+}

ingestion/internal/wiki/merge.go

@@ -32,10 +32,33 @@ type section struct {
 // Frontmatter is taken from a. Sections are merged by strategy:
 // bullet sections union unique lines, append sections concatenate,
 // all others keep a's version. Sections in b not present in a are appended.
+// Merge combines two pages, discarding any disagreement silently.
+// Prefer MergeReport where the caller can act on the disagreement.
 func Merge(a, b Page) Page {
-	fmA, secsA := parseSections(a.Content)
-	_, secsB := parseSections(b.Content)
+	page, _ := MergeReport(a, b)
+	return page
+}
 
+// MergeReport is Merge, plus the headings of sections where b carried a
+// different version of a section a already had — and lost.
+//
+// That loss is the property which makes ingest safe to run unattended (#103):
+// a regenerating writer can add to a note but never rewrite it. But the
+// discarded text is also a signal, and until now it went in the bin: the source
+// now says something different about a section we already hold. Nobody could
+// tell "the source is unchanged" from "the source changed its mind and we
+// ignored it".
+//
+// Deliberately NOT a semantic contradiction check. This reports textual
+// disagreement, which is cheap, deterministic, and needs no model on the write
+// path. Deciding whether a disagreement is a genuine contradiction stays with
+// the Judge-gated enrich pass that already exists (brain-gardener#175), which
+// is approval-gated by design — detection here, adjudication there.
+func MergeReport(a, b Page) (Page, []string) {
+	fmA, secsA := parseSections(a.Content)
+	fmB, secsB := parseSections(b.Content)
+
+	var conflicts []string
 	idx := make(map[string]int, len(secsA))
 	for i, s := range secsA {
 		idx[s.heading] = i
@@ -53,11 +76,65 @@ func Merge(a, b Page) Page {
 		case bulletSections[sB.heading]:
 			secsA[i].content = mergeBullets(sA.content, sB.content)
 		case appendSections[sB.heading]:
-			secsA[i].content = strings.TrimRight(sA.content, "\n") + "\n\n" + strings.TrimLeft(sB.content, "\n")
+			secsA[i].content = appendNew(sA.content, sB.content)
+		default:
+			// a wins — but say that b disagreed, rather than dropping it mute.
+			if strings.TrimSpace(sA.content) != strings.TrimSpace(sB.content) {
+				conflicts = append(conflicts, sB.heading)
+			}
 		}
 	}
 
-	return Page{Path: a.Path, Content: rebuildContent(fmA, secsA)}
+	return Page{Path: a.Path, Content: rebuildContent(refreshOwned(fmA, fmB), secsA)}, conflicts
+}
+
+// generatorOwned names the frontmatter fields the ingest pipeline may refresh
+// on a page it is revising. Everything else on disk wins.
+//
+// #103 made the on-disk frontmatter win wholesale, which is what stops a
+// regenerating writer from overwriting human-set metadata — a title someone
+// fixed, or the claim-property envelope (brain#21). The cost was that fields
+// the generator legitimately owns froze at their first-ingest values: when it
+// last ran, and what it last saw.
+//
+// An explicit allowlist rather than a carve-out: the ownership boundary is
+// nameable, and a field nobody has thought about stays human-owned by default,
+// which is the safe direction.
+var generatorOwned = map[string]bool{
+	"last_updated": true,
+	"source_hash":  true,
+}
+
+// refreshOwned returns a's frontmatter with the generator-owned fields taken
+// from b where b supplies them. Fields absent from b keep a's value, so a
+// generator that stops emitting a field cannot blank it.
+func refreshOwned(a, b string) string {
+	bVals := make(map[string]string)
+	for _, line := range strings.Split(b, "\n") {
+		key, value, found := strings.Cut(line, ":")
+		if !found || !generatorOwned[strings.TrimSpace(key)] {
+			continue
+		}
+		bVals[strings.TrimSpace(key)] = strings.TrimSpace(value)
+	}
+	if len(bVals) == 0 {
+		return a
+	}
+
+	out := make([]string, 0, len(strings.Split(a, "\n")))
+	for _, line := range strings.Split(a, "\n") {
+		key, _, found := strings.Cut(line, ":")
+		k := strings.TrimSpace(key)
+		if found && generatorOwned[k] {
+			if v, ok := bVals[k]; ok {
+				out = append(out, k+": "+v)
+				delete(bVals, k)
+				continue
+			}
+		}
+		out = append(out, line)
+	}
+	return strings.Join(out, "\n")
 }
 
 func parseSections(markdown string) (frontmatter string, sections []section) {
@@ -96,15 +173,64 @@ func parseSections(markdown string) (frontmatter string, sections []section) {
 	return
 }
 
+// rebuildContent serialises sections back into a page.
+//
+// Each section body is normalised to exactly one trailing newline and no
+// leading blank line. Without that, a section keeps whatever blank lines it was
+// parsed with and this function adds its own, so every merge pass grows the page
+// by a blank line — invisible in a diff viewer, fatal to byte-stability. Compile-on-ingest
+// merges on every run, so "merging changes nothing when nothing changed" has to
+// hold at the byte level, not just the content level.
 func rebuildContent(frontmatter string, sections []section) string {
 	var sb strings.Builder
 	sb.WriteString(frontmatter)
 	for _, sec := range sections {
-		fmt.Fprintf(&sb, "\n## %s\n\n%s", sec.heading, sec.content)
+		body := strings.Trim(sec.content, "\n")
+		fmt.Fprintf(&sb, "\n## %s\n\n%s\n", sec.heading, body)
 	}
 	return sb.String()
 }
 
+// appendNew concatenates the lines of b that a does not already carry.
+//
+// Append sections used to concatenate wholesale, which is correct exactly once.
+// Compile-on-ingest merges a freshly extracted page into the one already on
+// disk, so an unchanged source re-ingested would grow "Open Questions" and
+// "Updates" on every run until the page is unreadable — and the drift guard
+// that would otherwise catch it (hashing the source body) does not exist yet,
+// so idempotency has to hold here rather than upstream.
+//
+// Line-level rather than block-level: the common case is a re-ingest carrying
+// one genuinely new line alongside several it already has. A block-level
+// "skip if identical" would duplicate the old lines every time that happened.
+//
+// The cost is that a line repeated verbatim on purpose collapses to one. For
+// these sections — questions, updates, evolving notes — a repeat is noise
+// rather than signal, and the failure is conservative: the page stops growing
+// instead of growing wrongly.
+func appendNew(a, b string) string {
+	seen := make(map[string]bool)
+	for _, line := range strings.Split(a, "\n") {
+		if t := strings.TrimSpace(line); t != "" {
+			seen[t] = true
+		}
+	}
+
+	var add []string
+	for _, line := range strings.Split(b, "\n") {
+		t := strings.TrimSpace(line)
+		if t == "" || seen[t] {
+			continue
+		}
+		seen[t] = true
+		add = append(add, line)
+	}
+	if len(add) == 0 {
+		return a // nothing new — leave the section byte-identical
+	}
+	return strings.TrimRight(a, "\n") + "\n\n" + strings.Join(add, "\n") + "\n"
+}
+
 func mergeBullets(a, b string) string {
 	seen := make(map[string]bool)
 	var lines []string

ingestion/internal/wiki/merge_test.go

@@ -53,3 +53,146 @@ func TestMerge_KeepsFrontmatterFromA(t *testing.T) {
 	assert.Contains(t, got.Content, "title: A")
 	assert.NotContains(t, got.Content, "title: B")
 }
+
+// --- brain#21/B1: merging must be safe to run again -------------------------
+
+func TestMerge_AppendSectionDoesNotDuplicateContentAlreadyPresent(t *testing.T) {
+	// Compile-on-ingest merges a freshly extracted page into the one already
+	// on disk. Bullet sections union, so they are naturally idempotent — but
+	// append sections concatenate, so re-ingesting an unchanged source would
+	// grow "Open Questions" on every run until the page is unreadable.
+	page := Page{Path: "wiki/sources/x.md", Content: `---
+title: X
+---
+
+## Open Questions
+
+- Does this converge?
+`}
+
+	once := Merge(page, page)
+	twice := Merge(once, page)
+
+	assert.Equal(t, 1, strings.Count(once.Content, "Does this converge?"),
+		"merging a page with itself must not duplicate an append section")
+	assert.Equal(t, once.Content, twice.Content,
+		"merge must be idempotent — a third pass may not keep growing the page")
+}
+
+func TestMerge_AppendSectionStillAccumulatesGenuinelyNewContent(t *testing.T) {
+	// The dedup must not turn append sections into keep-a-only sections:
+	// new material is exactly what compile-on-ingest exists to add.
+	existing := Page{Path: "wiki/sources/x.md", Content: `---
+title: X
+---
+
+## Open Questions
+
+- Does this converge?
+`}
+	fresh := Page{Path: "wiki/sources/x.md", Content: `---
+title: X
+---
+
+## Open Questions
+
+- What happens under load?
+`}
+
+	got := Merge(existing, fresh).Content
+	assert.Contains(t, got, "Does this converge?", "existing question must survive")
+	assert.Contains(t, got, "What happens under load?", "new question must be added")
+}
+
+func TestMerge_GeneratorOwnedFrontmatterFieldsAreRefreshed(t *testing.T) {
+	// #103 made on-disk frontmatter win wholesale, which is what protects
+	// human-set fields from a regenerating writer. The cost was that fields the
+	// generator legitimately owns — when it last ran, what it last saw — froze
+	// at their first-ingest values. An explicit owned-set is the boundary:
+	// named fields the generator may refresh, everything else human-owned.
+	existing := Page{Path: "wiki/sources/x.md", Content: `---
+title: 'X'
+last_updated: 2026-01-01
+source_hash: aaaa
+half_life: durable
+claim_provenance: asserted
+---
+
+## Summary
+
+Original.
+`}
+	fresh := Page{Path: "wiki/sources/x.md", Content: `---
+title: 'Renamed by the model'
+last_updated: 2026-08-22
+source_hash: bbbb
+---
+
+## Summary
+
+Rewritten by the model.
+`}
+
+	got := Merge(existing, fresh).Content
+
+	assert.Contains(t, got, "last_updated: 2026-08-22", "generator owns last_updated")
+	assert.Contains(t, got, "source_hash: bbbb", "generator owns source_hash")
+	assert.Contains(t, got, "title: 'X'", "a human-set title must survive regeneration")
+	assert.Contains(t, got, "half_life: durable", "the claim envelope must survive regeneration")
+	assert.Contains(t, got, "claim_provenance: asserted")
+	assert.Contains(t, got, "Original.", "an existing section still wins over the model's rewrite")
+	assert.NotContains(t, got, "Renamed by the model")
+}
+
+func TestMerge_ReportsSectionsWhereTheFreshVersionWasDiscarded(t *testing.T) {
+	// The asymmetry that makes ingest safe (on-disk wins) also throws away a
+	// real signal: the source now says something different about a section we
+	// already have. Today that disagreement is silently discarded, so nobody
+	// can tell "the source is unchanged" from "the source changed its mind and
+	// we ignored it".
+	existing := Page{Path: "wiki/sources/x.md", Content: `---
+title: 'X'
+---
+
+## Summary
+
+Appetite is fixed, scope is variable.
+
+## Method
+
+Six-week cycles.
+`}
+	fresh := Page{Path: "wiki/sources/x.md", Content: `---
+title: 'X'
+---
+
+## Summary
+
+Appetite is negotiable and scope is fixed.
+
+## Method
+
+Six-week cycles.
+`}
+
+	got, conflicts := MergeReport(existing, fresh)
+
+	assert.Contains(t, got.Content, "Appetite is fixed", "on-disk version still wins")
+	assert.NotContains(t, got.Content, "negotiable")
+	assert.Equal(t, []string{"Summary"}, conflicts,
+		"only the section that actually disagreed is reported")
+}
+
+func TestMerge_ReportsNothingWhenTheFreshVersionAgrees(t *testing.T) {
+	page := Page{Path: "wiki/sources/x.md", Content: `---
+title: 'X'
+---
+
+## Summary
+
+Appetite is fixed, scope is variable.
+`}
+
+	_, conflicts := MergeReport(page, page)
+	assert.Empty(t, conflicts, "identical content is not a disagreement")
+}