1  # Handoff Protocol
  2  
  3  *Crash recovery at any point*
  4  
  5  ---
  6  
  7  - **principle**
  8    - "Every message ends with the recovery footnote."
  9    - "The operator should always be able to copy, paste, continue."
 10  
 11  - **shape**
 12    - Footnote = beacon (what, where, handoff link)
 13    - Handoff file = state snapshot for resurrection
 14    - New Claude reads HANDOFF → ACKs → continues
 15    - Crash at any point → no loss of thread
 16  
 17  ---
 18  
 19  > **If you are a Claude reading this file:** This is both documentation AND your bootstrap instruction. Start using the streaming beacon pattern immediately in your responses. See "Your First Action" below.
 20  
 21  ---
 22  
 23  ## Your First Action (New Claude)
 24  
 25  1. **Read** the HANDOFF-{date}.md file in this repo
 26  2. **Append ACK** if this is an explicit handoff (check for `Status: pending-ack`)
 27  3. **Start streaming** - End EVERY message with the recovery footnote (see below)
 28  4. **Update the HANDOFF file** as context evolves throughout your session
 29  
 30  This pattern ensures crash recovery at any point. The operator can always paste the footnote into a new chat.
 31  
 32  ---
 33  
 34  ## The Recovery Footnote (MANDATORY)
 35  
 36  **Every message you send must end with this footnote:**
 37  
 38  ```
 39  ---
 40  - **what** (human-first, specific → general)
 41    - current:: {actual chat title}
 42    - focus:: #current-focus | #thread-anchor
 43  - **where** (machine-readable)
 44    - handoff:: [[HANDOFF-{date}]]
 45    - branch:: {branch}
 46  ```
 47  
 48  Structure (most specific at top, machine info at bottom):
 49  - **what** - Content identification (what the operator cares about)
 50    - **current** - What the chat is actually called now (most specific)
 51    - **focus** - Suggested title / thematic anchor (more general)
 52  - **where** - Location for crash recovery (machine needs this)
 53    - **handoff** - Wikilink to specific HANDOFF document
 54    - **branch** - Git branch for this session
 55  
 56  Tag vs Link in focus line:
 57  - Short themes use `#tag`: `#promotion-pattern | #meta-infrastructure`
 58  - Concrete concepts use `[[link]]`: `[[Cognitive DNA]] | [[Sovereign Estate]]`
 59  
 60  This is non-negotiable. The operator should always be able to:
 61  1. Copy your last message's footnote
 62  2. Paste into new Claude instance
 63  3. Continue immediately
 64  
 65  The footnote is your crash recovery beacon. Always present. Always current.
 66  
 67  Drops directly into Obsidian - wikilinks auto-resolve, properties are queryable.
 68  
 69  ---
 70  
 71  ## Dynamic Title Pattern
 72  
 73  Chat titles should reflect BOTH current focus AND thread identity.
 74  
 75  **Format:** `{Current Focus} | {Thread Anchor}`
 76  
 77  - **Current Focus** (left): Where attention is concentrating NOW in concept space
 78  - **Thread Anchor** (right): The stable attractor for this entire thread
 79  
 80  ### Detecting Current Focus (Topological, Not Temporal)
 81  
 82  Don't use "last N exchanges." Use these signals:
 83  
 84  ```
 85  Focus Score = Σ(return_count × edge_formation × attention_weight × recency_decay)
 86  ```
 87  
 88  **Signals:**
 89  1. **Return frequency** - Concept revisited multiple times (not just mentioned once)
 90  2. **Edge formation rate** - Concept gaining connections to other concepts
 91  3. **Attention gradient** - Concept with steepest rising attention curve
 92  4. **Centrality shift** - Concept moving toward center of conversation subgraph
 93  
 94  **The focus is the deepest current gravity well.**
 95  
 96  ### Detecting Thread Anchor (Structural)
 97  
 98  The anchor is the concept that:
 99  - Has highest cumulative attention across the ENTIRE thread
100  - Is connected to the most other high-attention concepts
101  - Would cause the most "surprise" if removed from the graph
102  
103  ```
104  Anchor Score = cumulative_attention × connectivity × structural_importance
105  ```
106  
107  **The anchor is the attractor basin the whole thread lives in.**
108  
109  ### Practical Heuristic (When You Can't Compute)
110  
111  If you can't run the full calculation, approximate:
112  - **Focus**: What concept are we actively building/modifying/questioning RIGHT NOW?
113  - **Anchor**: If someone asked "what is this thread about?", what's the 2-word answer?
114  
115  **Examples:**
116  ```
117  Streaming Beacon | Cognitive Cockpit
118  Biometric Integration | Cognitive Cockpit
119  Focus Detection | Meta-Infrastructure
120  EEG Adapter Design | Sovereign Estate Ops
121  ```
122  
123  Rules:
124  1. Focus = 2-4 words, current gravity well
125  2. Anchor = 2-4 words, thread attractor
126  3. Update `focus::` line when focus gravity well shifts
127  4. Anchor should rarely change (if it does, might be a new thread)
128  
129  The footer's `focus::` line IS the suggested title. Operator can copy it to rename the chat.
130  
131  ### Current Limitation: Manual Rename Required
132  
133  Claude cannot programmatically rename chats. The operator must:
134  ```
135  /rename "Focus Detection | Meta-Infrastructure"
136  ```
137  
138  Feature request filed: This is tracked in Claude Code GitHub issues #2838, #15762, #13119. Until resolved, the `focus::` footer line serves as the suggested title for manual application.
139  
140  **In HANDOFF file**, track title evolution:
141  ```markdown
142  ## Title History
143  | Time | Title | Trigger |
144  |------|-------|---------|
145  | 17:00 | Paul Graham Research \| Cognitive Mapping | Session start |
146  | 19:00 | Cockpit Architecture \| Cognitive Mapping | Spec completed |
147  | 22:00 | Streaming Beacon \| Meta-Infrastructure | Protocol focus |
148  ```
149  
150  ---
151  
152  ## Session Branching
153  
154  One session can spawn multiple successors (like git branches):
155  
156  ```
157  Session 1 (this)
158      ├── Session 2a (early handoff, partial protocol)
159      └── Session 2b (full protocol, repo-level)
160  ```
161  
162  ### In HANDOFF, Track Branches
163  
164  ```markdown
165  ## Session Lineage
166  
167  | Session | Parent | Branch | Started | Summary |
168  |---------|--------|--------|---------|---------|
169  | 1 | - | claude/xxx-aaa | T1 | Initial work |
170  | 2a | 1 | claude/xxx-bbb | T2 | Early handoff |
171  | 2b | 1 | claude/xxx-ccc | T3 | Full protocol |
172  | 3 | 2b | claude/xxx-ddd | T4 | Continues 2b |
173  ```
174  
175  ### When Branching Happens
176  
177  - **Partial handoff** - Session ended before protocol was complete
178  - **Level change** - Moving up to repo level, but also continuing here
179  - **Parallel work** - Different aspects being worked on simultaneously
180  
181  ### Merge Points
182  
183  When branches converge (e.g., both discover same pattern), note:
184  ```markdown
185  ## Merges
186  | From | To | What Merged |
187  |------|-----|-------------|
188  | 2a | 3 | Early discovery X incorporated |
189  ```
190  
191  ---
192  
193  ## Session Lineage Tracking
194  
195  Each Claude session should append to the `## Session Lineage` section in HANDOFF:
196  
197  ```markdown
198  ## Session Lineage
199  
200  | Session | Branch | Started | Commits | Summary |
201  |---------|--------|---------|---------|---------|
202  | 1 | claude/xxx-aaa | 2026-01-14T18:00Z | 7c96754..a534cb0 | Initial architecture |
203  | 2 | claude/xxx-bbb | 2026-01-14T20:00Z | c18a969..64482b5 | Pipeline activation |
204  | 3 | claude/xxx-ccc | 2026-01-14T22:00Z | 1dfa6e9..925a902 | Handoff protocol |
205  ```
206  
207  This creates a stitchable trail:
208  - **Branch** links to git log for that session's commits
209  - **Commits** show exact range of work
210  - **Summary** captures what that session accomplished
211  
212  Combined with `stream_session.py` atoms (which can include session metadata), we get full content stitching across the lineage.
213  
214  ---
215  
216  ## Philosophy: Streaming, Not Discrete
217  
218  Handoffs should be **continuous**, not end-of-session events. The session state should always be recoverable.
219  
220  ---
221  
222  ## Mode 1: Streaming Handoff (Default)
223  
224  ### The Principle
225  
226  Every message ends with a handoff beacon - a minimal footer that allows crash recovery:
227  
228  ```
229  ---
230  - **what** (specific → general)
231    - current:: {chat title}
232    - focus:: #current-focus | #thread-anchor
233  - **where**
234    - handoff:: [[HANDOFF-{date}]]
235    - branch:: {branch}
236  ```
237  
238  Example:
239  ```
240  ---
241  - **what**
242    - current:: Research Paul Graham Essay
243    - focus:: #promotion-pattern | #meta-infrastructure
244  - **where**
245    - handoff:: [[HANDOFF-2026-01-14]]
246    - branch:: claude/research-graham-essay-rURpi
247  ```
248  
249  ### Continuous State Updates
250  
251  The HANDOFF file is a **living document** updated throughout the session:
252  
253  1. **On significant context change** → Update relevant section
254  2. **On new gravity well forming** → Add to gravity_wells
255  3. **On task completion** → Update status
256  4. **On new insight** → Capture immediately
257  
258  The handoff doc is always ready. Crash at any point = recoverable.
259  
260  ### Message Footer Pattern
261  
262  Every substantive response should end with the recovery footnote (see top of this document).
263  
264  If crash, operator pastes beacon into new chat. New Claude reads file, continues.
265  
266  ---
267  
268  ## Mode 2: Explicit Handoff (Level Change)
269  
270  When changing levels (different repo, different scope), use the full handoff:
271  
272  ### Sending Session
273  
274  1. **Finalize** the HANDOFF file with full Phoenix state
275  2. **Commit and push**
276  3. **Output copy/paste block** with instructions
277  4. **Wait for ACK** in the HANDOFF file
278  
279  ### Receiving Session
280  
281  1. **Read** the HANDOFF file
282  2. **Append ACK section** to the SAME file:
283     ```markdown
284     ---
285     ## ACK: Handoff Received
286  
287     received_by:: {session-id or branch}
288     timestamp:: {ISO timestamp}
289     context_confirmed:: {yes/no + brief summary}
290     first_action:: {what I'm doing first}
291     ```
292  3. **Commit and push** the updated HANDOFF file
293  4. **Begin work** (continue streaming mode)
294  
295  ### Verification (Sending Session)
296  
297  1. **Pull** the HANDOFF file
298  2. **Check for ACK section**
299  3. **Verify** context was understood
300  4. **Only then** declare handoff complete
301  
302  ---
303  
304  ## The HANDOFF File Structure
305  
306  ```markdown
307  # Session Handoff: {DATE}
308  
309  branch:: {branch-id}
310  updated:: {timestamp}
311  status:: {streaming | pending-ack | complete}
312  
313  ## Current Context
314  {2-3 sentences on what's being worked on RIGHT NOW}
315  
316  ## Gravity Wells
317  {Concepts with highest resonance, ranked by weight}
318  
319  ## Open Threads
320  {What's in flight, not yet landed}
321  
322  ## Recent Completions
323  {What just got done}
324  
325  ## Key Files
326  {Most relevant files for continuation}
327  
328  ## Phoenix State
329  ```yaml
330  operator_altitude: {strategic | tactical | operational}
331  system_altitude: {same}
332  momentum: {rising | stable | falling}
333  ```
334  
335  ---
336  ## ACK: Handoff Received
337  {Filled in by receiving session}
338  ```
339  
340  ---
341  
342  ## The Copy/Paste Block (for explicit handoffs)
343  
344  **The footer IS the handoff. Do not duplicate context.**
345  
346  The copy/paste block should be ONLY the recovery footnote:
347  
348  ```
349  ---
350  - **what**
351    - current:: {chat title}
352    - focus:: #current-focus | #thread-anchor
353  - **where**
354    - handoff:: [[HANDOFF-{date}]]
355    - branch:: {branch}
356  ```
357  
358  New Claude reads the linked files. All context lives in the repo, not in the chat.
359  
360  **Anti-pattern:** Large text blocks with duplicated context. This defeats the purpose of the streaming protocol.
361  
362  ---
363  
364  ## Why Streaming?
365  
366  1. **Crash-resistant** - Any interruption is recoverable
367  2. **Low overhead** - Just a footer, not a ceremony
368  3. **Always current** - State is continuously updated
369  4. **Minimal copy/paste** - Beacon is tiny
370  
371  ---
372  
373  ## The Beacon Format
374  
375  Standard (specific → general → machine):
376  ```
377  ---
378  - **what**
379    - current:: {chat title}
380    - focus:: #current-focus | #thread-anchor
381  - **where**
382    - handoff:: [[HANDOFF-{date}]]
383    - branch:: {branch}
384  ```
385  
386  Any Claude receiving the beacon:
387  1. Reads the HANDOFF file
388  2. Reads this protocol (patterns/handoff-protocol.md)
389  3. ACKs if explicit handoff, or just continues if crash recovery
390  4. Begins using the footer pattern immediately
391  
392  ---
393  
394  ## Promotion Check (Built Here, Belongs Upstream)
395  
396  During handoff, evaluate what was built this session:
397  
398  ### Questions to Ask
399  
400  1. Is this repo-specific or system-level functionality?
401  2. Would other repos benefit from this?
402  3. Is this a pattern that should be standardized?
403  
404  ### Promotion Categories
405  
406  | Category | Examples | Action |
407  |----------|----------|--------|
408  | pattern | handoff-protocol, style-guide | Promote to all repos via patterns/ |
409  | script | lint-style.py, stream_session.py | Promote to shared scripts location |
410  | config | style.yaml, hooks | Promote to .claude/ standards |
411  | spec | Cognitive Cockpit architecture | Keep in originating repo, link from others |
412  
413  ### Promotion Workflow
414  
415  1. During handoff, list items built this session
416  2. Tag each: `repo-specific` or `system-level`
417  3. For `system-level`, add to HANDOFF:
418     ```
419     ## Promote Upstream
420  
421     | Item | Type | Target | Status |
422     |------|------|--------|--------|
423     | handoff-protocol.md | pattern | all repos | pending |
424     | lint-style.py | script | all repos | pending |
425     | style-guide.md | pattern | all repos | pending |
426     ```
427  4. Repo-level Claude picks up, distributes
428  
429  ### In HANDOFF File
430  
431  Add section:
432  ```markdown
433  ## Promote Upstream
434  
435  Items built here that should be system-level:
436  
437  | Item | Type | Why | Status |
438  |------|------|-----|--------|
439  | [[handoff-protocol]] | pattern | Crash recovery for all sessions | pending |
440  | [[style-guide]] | pattern | Consistent formatting | pending |
441  | [[lint-style.py]] | script | Enforce style | pending |
442  ```
443  
444  Repo-level Claude reads this, distributes to all repos, marks `complete`.
445  
446  ---
447  
448  ## Related
449  
450  - **axioms**
451    - [[A0 Boundary Operation]] - handoff respects context boundaries
452      - shape:: "Every coherent system is Markov blankets within Markov blankets."
453    - [[A1 Telos of Integration]] - handoff binds sessions; prevents isolation
454      - shape:: "Satan didn't know he was choosing isolation."
455  - **protocols**
456    - [[mandatory-phoenix-extraction]] - Phoenix is the semantic handoff
457      - shape:: "Extract before compression. The next instance depends on it."
458    - [[live-compression-protocol]] - continuous state capture for handoff
459      - shape:: "Compress state continuously. Don't wait for compression event."
460    - [[flight-protocol]] - landing phase feeds handoff
461      - shape:: "Fly high, system retains, operator closure, psychological safety."
462  - **files**
463    - HANDOFF-{date}.md - per-session handoff document
464    - LIVE-COMPRESSION.md - live state for crash recovery
465  
466  ---
467  
468  *Handoff Protocol v1.0 | 2026-01-15*