feat(continuity): wire §6.3 shared-docs staleness notice

MarkdownChanges was deleted as dead code, but the underlying spec
requirement wasn't abandoned — rebuilt it independently. Adds
continuity.ConventionsHash for AGENTS.md/CLAUDE.md/VOCAB.md, tracks a
per-session snapshot on herdr.Session, and adds
Coordinator.checkConventions (run every Monitor tick) which compares
each active session's snapshot against its project's base repo and
pushes an in-pane notice via a new herdr.ConventionsNotifier
capability when they drift.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W1rkJ2hBMybnJctPbcy4tT

internal/orchestrator/orchestrator.go

@@ -382,6 +382,7 @@ func (c *Coordinator) Monitor(ctx context.Context, hard float64, interval time.D
 		case <-t.C:
 			c.refreshSessionHealth(ctx)
 			c.cleanupCompleted(ctx)
+			c.checkConventions(ctx)
 			expired, err := c.expire(ctx)
 			c.setMonitorHealth(err, len(expired))
 			if err != nil {
@@ -420,6 +421,61 @@ func (c *Coordinator) cleanupCompleted(ctx context.Context) {
 	}
 }
 
+// checkConventions is §6.3: "on update, the orchestra injects a notice to
+// agents whose current task is adjacent" — adjacency here is "same project's
+// base repo," and staleness is tracked by comparing each session's own
+// last-known continuity.ConventionsHash against the base repo's current one,
+// never by trusting the agent to notice on its own.
+func (c *Coordinator) checkConventions(ctx context.Context) {
+	spec, ok := c.Worktrees.(WorktreeSpec)
+	if !ok {
+		return
+	}
+	c.loadSessions()
+	c.mu.Lock()
+	sessions := make(map[string]herdr.Session, len(c.sessions))
+	for id, s := range c.sessions {
+		sessions[id] = s
+	}
+	c.mu.Unlock()
+	changed := false
+	for taskID, session := range sessions {
+		t, ok := c.Store.Task(taskID)
+		if !ok || t.State != domain.StateLeased {
+			continue
+		}
+		repo, _, valid := spec.Spec(t)
+		if !valid {
+			continue
+		}
+		hash, err := continuity.ConventionsHash(repo)
+		if err != nil || hash == session.ConventionsHash {
+			continue
+		}
+		a, err := c.adapterFor(taskID, session)
+		if err != nil {
+			continue
+		}
+		notifier, ok := a.(herdr.ConventionsNotifier)
+		if !ok {
+			continue
+		}
+		if err := notifier.NotifyConventionsChanged(ctx, session); err != nil {
+			continue
+		}
+		session.ConventionsHash = hash
+		c.mu.Lock()
+		c.sessions[taskID] = session
+		c.mu.Unlock()
+		changed = true
+	}
+	if changed {
+		c.mu.Lock()
+		_ = c.saveSessionsLocked()
+		c.mu.Unlock()
+	}
+}
+
 func (c *Coordinator) expire(ctx context.Context) ([]domain.Event, error) {
 	// pane.exited is the low-latency path; lease expiry below remains the
 	// authoritative backstop when herdr misses an exit notification.
@@ -610,6 +666,11 @@ func (c *Coordinator) Start(ctx context.Context, e domain.Event) error {
 	}
 	s.HerdrID = p.HarnessID
 	s.TaskFileSHA = taskFileSHA
+	// Best-effort, same caveat as taskFileSHA above: only meaningful for a
+	// worktree this process can read locally. Snapshots the shared-docs
+	// state this session starts trusting; checkConventions notices drift
+	// from here, not from whatever the agent's own cached view is (§6.3).
+	s.ConventionsHash, _ = continuity.ConventionsHash(w)
 	c.mu.Lock()
 	if c.sessions == nil {
 		c.sessions = map[string]herdr.Session{}

internal/orchestrator/rotation_test.go

@@ -476,3 +476,76 @@ func TestRotationRequestsHandoffBeforeReleasing(t *testing.T) {
 		t.Fatal("rotate never called Release once the handoff file appeared")
 	}
 }
+
+type specWorktrees struct{ wtPath, repoPath string }
+
+func (w specWorktrees) Create(context.Context, domain.Task) (string, error) { return w.wtPath, nil }
+func (w specWorktrees) Spec(domain.Task) (string, string, bool)             { return w.repoPath, "", true }
+
+type conventionsAdapter struct {
+	fakeAdapter
+	notifications int
+}
+
+func (a *conventionsAdapter) NotifyConventionsChanged(context.Context, herdr.Session) error {
+	a.notifications++
+	return nil
+}
+
+// TestConventionsDriftNotifiesActiveSession guards §6.3's wiring: "on
+// update, the orchestra injects a notice to agents whose current task is
+// adjacent" — never left to the agent's own cached view. A session must not
+// be notified while the base repo's shared docs match what it started with,
+// and must be notified once they diverge.
+func TestConventionsDriftNotifiesActiveSession(t *testing.T) {
+	repo := t.TempDir()
+	worktree := t.TempDir()
+	if err := os.WriteFile(repo+"/AGENTS.md", []byte("v1"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(worktree+"/AGENTS.md", []byte("v1"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	s, err := store.Open(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := s.Append(domain.Event{ID: domain.NewID(), Type: "TaskCreated", TaskID: "t1", Surface: string(authz.System), Payload: mustJSON(map[string]any{
+		"source": "jsonl", "external_id": "1", "project": "p",
+	})}); err != nil {
+		t.Fatal(err)
+	}
+	task := s.Tasks()[0]
+	a := &conventionsAdapter{fakeAdapter: fakeAdapter{occupancy: 0}}
+	c := &orchestrator.Coordinator{Store: s, Worktrees: specWorktrees{wtPath: worktree, repoPath: repo}, Adapters: adapters{a}, StatePath: t.TempDir() + "/sessions.json"}
+
+	leaseEvt, err := s.Lease(task.ID, "h1", time.Minute)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := c.Start(context.Background(), leaseEvt); err != nil {
+		t.Fatal(err)
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go c.Monitor(ctx, .8, time.Millisecond)
+
+	time.Sleep(50 * time.Millisecond)
+	if a.notifications != 0 {
+		t.Fatalf("notified with no actual drift: notifications=%d", a.notifications)
+	}
+
+	if err := os.WriteFile(repo+"/AGENTS.md", []byte("v2"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	deadline := time.Now().Add(time.Second)
+	for time.Now().Before(deadline) && a.notifications == 0 {
+		time.Sleep(time.Millisecond)
+	}
+	if a.notifications == 0 {
+		t.Fatal("session was never notified of the conventions-doc update")
+	}
+}