Spec: turn-annotation for out-of-band Memory worktree changes #324

Part of #114.

Problem Statement

As a Human editing Memory files on disk between turns, my changes are invisible to the long-lived Orchestrator Session: the turn input carries only inbox plus message, nothing snapshots the worktree at turn start, and reconciliation only sees Git HEAD. The bot keeps acting on silently stale files unless it happens to re-read.

Solution

A bounded, bottom-appended turn-annotation names the out-of-band worktree delta in the next turn message. It never touches the system prompt prefix, never wakes, never duplicates a tool result - the three bans from ADR-0060 stay intact.

User Stories

1. As a Human editing Memory files on disk between turns, I want the next turn to state what changed on disk, so that the bot acts on current files.
2. As a Human switching Memory branches, I want no extra annotation noise, so that the switch tool result stays single record.
3. As a Human editing PERSONA.md, I want the note to say the session keeps its frozen voice, so that I know which version the bot follows.
4. As an Orchestrator agent, I want changed files named precisely, so that my re-reads are targeted instead of defensive.
5. As a Human who changed nothing, I want zero annotation bytes, so that quiet turns stay quiet.

Implementation Decisions

• Trigger: turn-start worktree observation finds a delta with no covering tool result in history (silent human edits). Branch switches and the agent's own writes are excluded - their results already cover them.
• Content bounds (webhook shape): branch line plus path lists only - committed names plus worktree additions including untracked files, capped; never bodies. The agent reads details itself with ordinary git and file tools. PERSONA.md deltas carry the frozen-precedence half-sentence without detail.
• Seam: the existing turn boundary (observe at prepare, append at message assembly, reconcile unchanged). No new seams, no new services.
• Rejected: per-actor precedence platform rules (agent judgment, no Host guarantee); fixed USER.md/MEMORY.md dual files; Nudge/background distillation loops; the compaction contract (deferred to the persona-refresh track); stat and full-diff blocks in the annotation (the turn pays for what it names).

Testing Decisions

• Behavioral tests on the next-turn message: human edit -> named annotation; branch switch -> silence; PERSONA.md edit -> half-sentence.
• Prefix-invariance test: system prompt bytes unchanged by the annotation path (prior art: ADR-0060's mid-session edit assertion).
• Prior art: memory and bridge suites under packages/core/test.

Out of Scope

• Persona refresh at compaction (Spec: persona refresh at compaction boundary #326 track); live persona re-reads per turn (steering belongs in the prefix); preset creation UI (Creation presets: colleague vs roleplay PERSONA.md seeds #325 backlog); the prepare-signature change lands in the implementation slice, not this spec.

Further Notes

• Supersedes the per-actor-precedence recommendation in docs/research/2026-09-26-relationship-persona-organization.md (decision: no platform rule; file left as dated investigation).
• Terminology: turn-annotation is defined against ADR-0060's rejected notice/injection - bottom text only, never prefix, never wake.