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

brain_edit_root was gated but unobserved: on success it emitted a slog.Warn
and nothing else. That proves a rewrite was allowed, not that one happened —
and brain-sync commits it within 15 minutes authored `brain-sync`, so git
history cannot tell a CLAUDE.md rewrite apart from routine note traffic.

A successful brain_edit_root now emits an ntfy notification and an AuditEntry
through the same sink a capture already uses. notes.Result gains
PrevContentHash so both ends of the change are identifiable.

Path and hashes only in the notification body. Reserved at Internal, not
Confidential, because Confidential makes DegradingSink refuse to record while
loki is down rather than buffer. Observation is best-effort and never fails
the call; a failure to observe logs at ERROR.

Ordinary brain_edit on knowledge//wiki/ is deliberately not audited — git
history already carries the same before/after bytes with a diff.

Closes #97.

Co-authored-by: Mathias <mthbqv@gmail.com>

ingestion/internal/mcp/tools_notes.go

@@ -6,8 +6,11 @@ import (
 	"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"
 )
 
@@ -52,6 +55,20 @@ func noteToolDescriptors() []map[string]any {
 	}
 }
 
+// --- 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"`
 }
@@ -75,8 +92,17 @@ type brainEditArgs struct {
 }
 
 // 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) {
-	return s.editWithScope(args, notes.ScopeNotes)
+	_, out, err := s.editWithScope(args, notes.ScopeNotes)
+	return out, err
 }
 
 // brainEditRoot edits a governance file (CLAUDE.md). De-surfaced AND gated on
@@ -89,22 +115,72 @@ func (s *Server) brainEditRoot(ctx context.Context, args json.RawMessage) (json.
 		return nil, fmt.Errorf("brain_edit_root requires the local static principal; " +
 			"a governance file is not editable from a model-facing origin")
 	}
-	out, err := s.editWithScope(args, notes.ScopeRoot)
-	if err == nil {
-		// A durable instruction rewrite should be loud, not silent.
-		slog.Warn("brain_edit_root applied", "principal", info.principal, "result", string(out))
+	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
 }
 
-func (s *Server) editWithScope(args json.RawMessage, scope notes.Scope) (json.RawMessage, error) {
+// 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 nil, fmt.Errorf("parse args: %w", err)
+		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 nil, err
+		return notes.Result{}, nil, err
 	}
 
 	// Reindex only when the edit could have changed what the index reads.
@@ -121,7 +197,8 @@ func (s *Server) editWithScope(args json.RawMessage, scope notes.Scope) (json.Ra
 			res.ReindexError = ierr.Error()
 		}
 	}
-	return json.Marshal(res)
+	out, merr := json.Marshal(res)
+	return res, out, merr
 }
 
 // wingOf returns the wing for a wiki path, or "" for knowledge/ and root.