Session Handoff Protocol
Attribution: YourVisionYourCreation LLC, yourvisionyourcreation.com
Doctrine class: YVYC library, agentic category
Universal So-What
Sessions end. Context windows fill, get compacted, or close entirely,
and everything the agent held in working state evaporates with them.
The doctrine library governs how an agent behaves while a session is
alive. Nothing governs what survives when it dies. The result is a tax
the operator pays at the top of every session: re-stating the mission,
re-issuing settled decisions, watching the agent rediscover a path that
was ruled out three sessions ago.
The handoff capsule is the fix. State is written at the moment it is
cheapest to write, while it is still loaded, and read at the moment it
is most valuable, before the first output of the next session. The test
of a good handoff: the resumed session's first response reads like the
same operator's agent continuing the same mission, not a stranger doing
intake.
The Capsule
One artifact per project. One screen of text. Seven sections, every
line load-bearing. It lives in the repository as a plain file the
operator can read, diff, and version (for example CAPSULE.md at the
project root, or wherever the operator's doctrine room assigns it).
| Section |
Carries |
| Mission line |
One sentence. What this project is driving toward. Unchanged most sessions; when it changes, that change is the headline. |
| Decision ledger |
Decisions made, each with the reason it was made. The reason is what prevents re-litigation: a bare decision invites a fresh debate, a reasoned one closes it. |
| Open loops |
Work in flight, each with its exact state: what is done, what is not, and where the seam is. "Auth flow: token issue works, refresh untested" beats "working on auth." |
| Dead ends |
Approaches tried and invalidated, with the evidence that killed them. This section pays for the whole capsule: unrecorded dead ends get re-explored at full cost. |
| Convention deltas |
Standing rules established since the last capsule. This section is a staging area, not a home: deltas migrate into the operator's doctrine files (CLAUDE.md, class rules) and are then removed here. |
| State facts |
Environment facts that outlive the session and are not discoverable in seconds: which branch carries what, which service is stubbed, which credential the operator holds offline. |
| Next actions |
An ordered queue. The first item must be startable with zero clarifying questions; if it is not, the blocker is named beside it. |
Write Discipline
When the capsule is written:
- At the end of any substantive session, as the final act before the
turn closes.
- Before any context compaction, so the capsule is authored from full
context rather than from a summary of a summary.
- Immediately after any major decision, pivot, or invalidation, even
mid-session. A capsule that only updates at session end loses the
sessions that end unexpectedly.
How it is written:
- Overwrite, never append. The capsule is a ledger of current
state, not a log of history. Version control is the archive; the
capsule is the present tense.
- Ceiling, not floor. One screen. When the capsule outgrows a
screen, the excess is either doctrine (migrate it), history (delete
it, git holds it), or bloat (cut it).
- Anchored, not timestamped trust. The capsule states what it was
written against: a commit hash, a milestone, a named artifact
version. "Current as of commit a9cf891" is verifiable; "current as
of Tuesday" is not.
- No secrets. Ever. The capsule is a committed, readable file.
Credentials, tokens, and private personal detail never enter it.
State facts may say a credential exists and who holds it, never what
it is.
Load Discipline
First action of a resumed session: read the capsule. Second
action: verify it against reality before trusting it. Files change
between sessions. Branches merge. Other agents and other humans do
work. The trust order is fixed:
Current reality → capsule → model memory.
Verification is proportional, not exhaustive: check the anchor (does
the stated commit match, does the named branch exist, is the stubbed
service still stubbed), then proceed. When the capsule contradicts
reality, reality wins, the capsule is corrected on the spot, and the
discrepancy is surfaced to the operator in one line. A capsule that
fails verification is demoted to a hypothesis, never silently obeyed.
Loading is not optional when a capsule exists. "I remember this
project" is model memory claiming rank it does not hold.
What the Capsule Is Not
- Not a chat log or session summary. Narrative of what happened
is history; the capsule carries only what the next session needs to
act.
- Not hidden memory. It is an operator-visible, operator-editable
file with full provenance. For the defense doctrine on persistent
stores the operator cannot see, this skill defers entirely to
memory-poisoning-defense.
- Not a doctrine fork. Rules do not live here. Convention deltas
pass through on their way to the canon (
correction-conversion-protocol,
the operator's doctrine room) and are deleted once they land. A
capsule that accumulates rules has become a second canon, and two
canons diverge.
- Not an apology archive. Misses convert to rules and move on. The
capsule records the rule's destination, never the contrition.
Failure Modes
| Failure |
Correction |
| Capsule bloat. The file grows past a screen and stops being read. |
Enforce the ceiling at write time. Migrate doctrine out, delete history, cut the rest. |
| Stale authority. A capsule written five sessions ago is loaded and trusted over the current repository. |
Verify-on-load is mandatory. The anchor makes staleness detectable; reality always outranks the file. |
| Write skipped on a "small" session. The session that ruled out an approach in two turns leaves no record, and the approach returns. |
Any session that decided or invalidated anything updates the capsule. Size of session does not gate the write. |
| Load skipped on confidence. The agent proceeds on model memory because the project feels familiar. |
Model memory holds rank zero. A capsule that exists is read, every time. |
| Rules nesting in the capsule. Convention deltas stop migrating and the capsule forks the canon. |
Deltas are staged, migrated, and deleted. A delta present across two consecutive capsules is a migration failure to fix now. |
| Secrets leaking in. A token lands in a committed file. |
Hard ban, checked at write time. Reference the credential's existence and holder, never its value. |
Boundary (Read Before Applying)
| Skill |
Governs |
compaction-integrity-protocol |
State surviving compaction within a live session. |
correction-conversion-protocol |
Corrections becoming standing class rules. The capsule stages deltas for it, nothing more. |
doctrine-room-architecture |
The canon itself: rule lifecycle, decision governance across projects. |
memory-poisoning-defense |
Persistent stores the operator cannot inspect. The capsule avoids that class by design. |
session-handoff-protocol |
Cross-session mission state: what is written when context dies, and how it is loaded and verified when work resumes. |
Overlap is a defect. State lives here; rules live in the canon; hidden
memory is a different threat surface entirely.
Compliance Check (Run at Session Close and Session Open)
- Does a capsule exist, and was it loaded before the first output?
- Was the capsule verified against its anchor before being trusted?
- Does every decision in the ledger carry its reason?
- Is every dead end recorded with the evidence that killed it?
- Is the first next-action startable without a clarifying question?
- Have convention deltas migrated to the canon and been cleared?
- Is the capsule still one screen, and is its anchor current?
Adversarial Evaluator Gate
What would a hostile evaluator attack first?
The capsule becoming a stale authority. A confidently loaded wrong
state is worse than a cold start: the cold-start agent asks, the
poisoned agent acts. The defense is structural, not aspirational:
verify-on-load is a mandatory step with a concrete anchor to check,
and the trust order places reality above the file without exception.
The second attack: the capsule quietly becoming a second doctrine
system. Every rule that nests in the capsule instead of migrating is a
fork of the canon, and forks diverge silently until they conflict
loudly. The staging-area design, the two-capsule migration deadline,
and the one-screen ceiling exist to make that accumulation impossible
to sustain.
YourVisionYourCreation LLC, yourvisionyourcreation.com
Licensed under CC BY 4.0
1---2name: session-handoff-protocol3description: Eliminates the cold-start tax between sessions via a continuity capsule: mission line, decision ledger, open loops, dead ends, convention deltas, state facts, and next-actions queue. Trigger at the end of any substantive session, before context compaction, after major decisions, at the start of any session where a capsule exists, and whenever the operator re-explains settled ground. Cross-session state only; within-session compaction belongs to compaction-integrity-protocol.4license: CC BY 4.05---67# Session Handoff Protocol89**Attribution:** YourVisionYourCreation LLC, yourvisionyourcreation.com10**Doctrine class:** YVYC library, agentic category1112---1314## Universal So-What1516Sessions end. Context windows fill, get compacted, or close entirely,17and everything the agent held in working state evaporates with them.18The doctrine library governs how an agent behaves while a session is19alive. Nothing governs what survives when it dies. The result is a tax20the operator pays at the top of every session: re-stating the mission,21re-issuing settled decisions, watching the agent rediscover a path that22was ruled out three sessions ago.2324The handoff capsule is the fix. State is written at the moment it is25cheapest to write, while it is still loaded, and read at the moment it26is most valuable, before the first output of the next session. The test27of a good handoff: the resumed session's first response reads like the28same operator's agent continuing the same mission, not a stranger doing29intake.3031---3233## The Capsule3435One artifact per project. One screen of text. Seven sections, every36line load-bearing. It lives in the repository as a plain file the37operator can read, diff, and version (for example `CAPSULE.md` at the38project root, or wherever the operator's doctrine room assigns it).3940| Section | Carries |41|---|---|42| **Mission line** | One sentence. What this project is driving toward. Unchanged most sessions; when it changes, that change is the headline. |43| **Decision ledger** | Decisions made, each with the reason it was made. The reason is what prevents re-litigation: a bare decision invites a fresh debate, a reasoned one closes it. |44| **Open loops** | Work in flight, each with its exact state: what is done, what is not, and where the seam is. "Auth flow: token issue works, refresh untested" beats "working on auth." |45| **Dead ends** | Approaches tried and invalidated, with the evidence that killed them. This section pays for the whole capsule: unrecorded dead ends get re-explored at full cost. |46| **Convention deltas** | Standing rules established since the last capsule. This section is a staging area, not a home: deltas migrate into the operator's doctrine files (CLAUDE.md, class rules) and are then removed here. |47| **State facts** | Environment facts that outlive the session and are not discoverable in seconds: which branch carries what, which service is stubbed, which credential the operator holds offline. |48| **Next actions** | An ordered queue. The first item must be startable with zero clarifying questions; if it is not, the blocker is named beside it. |4950---5152## Write Discipline5354**When the capsule is written:**55561. At the end of any substantive session, as the final act before the57 turn closes.582. Before any context compaction, so the capsule is authored from full59 context rather than from a summary of a summary.603. Immediately after any major decision, pivot, or invalidation, even61 mid-session. A capsule that only updates at session end loses the62 sessions that end unexpectedly.6364**How it is written:**6566- **Overwrite, never append.** The capsule is a ledger of current67 state, not a log of history. Version control is the archive; the68 capsule is the present tense.69- **Ceiling, not floor.** One screen. When the capsule outgrows a70 screen, the excess is either doctrine (migrate it), history (delete71 it, git holds it), or bloat (cut it).72- **Anchored, not timestamped trust.** The capsule states what it was73 written against: a commit hash, a milestone, a named artifact74 version. "Current as of commit a9cf891" is verifiable; "current as75 of Tuesday" is not.76- **No secrets. Ever.** The capsule is a committed, readable file.77 Credentials, tokens, and private personal detail never enter it.78 State facts may say a credential exists and who holds it, never what79 it is.8081---8283## Load Discipline8485**First action of a resumed session:** read the capsule. **Second86action:** verify it against reality before trusting it. Files change87between sessions. Branches merge. Other agents and other humans do88work. The trust order is fixed:8990> **Current reality → capsule → model memory.**9192Verification is proportional, not exhaustive: check the anchor (does93the stated commit match, does the named branch exist, is the stubbed94service still stubbed), then proceed. When the capsule contradicts95reality, reality wins, the capsule is corrected on the spot, and the96discrepancy is surfaced to the operator in one line. A capsule that97fails verification is demoted to a hypothesis, never silently obeyed.9899Loading is not optional when a capsule exists. "I remember this100project" is model memory claiming rank it does not hold.101102---103104## What the Capsule Is Not1051061. **Not a chat log or session summary.** Narrative of what happened107 is history; the capsule carries only what the next session needs to108 act.1092. **Not hidden memory.** It is an operator-visible, operator-editable110 file with full provenance. For the defense doctrine on persistent111 stores the operator cannot see, this skill defers entirely to112 `memory-poisoning-defense`.1133. **Not a doctrine fork.** Rules do not live here. Convention deltas114 pass through on their way to the canon (`correction-conversion-protocol`,115 the operator's doctrine room) and are deleted once they land. A116 capsule that accumulates rules has become a second canon, and two117 canons diverge.1184. **Not an apology archive.** Misses convert to rules and move on. The119 capsule records the rule's destination, never the contrition.120121---122123## Failure Modes124125| Failure | Correction |126|---|---|127| **Capsule bloat.** The file grows past a screen and stops being read. | Enforce the ceiling at write time. Migrate doctrine out, delete history, cut the rest. |128| **Stale authority.** A capsule written five sessions ago is loaded and trusted over the current repository. | Verify-on-load is mandatory. The anchor makes staleness detectable; reality always outranks the file. |129| **Write skipped on a "small" session.** The session that ruled out an approach in two turns leaves no record, and the approach returns. | Any session that decided or invalidated anything updates the capsule. Size of session does not gate the write. |130| **Load skipped on confidence.** The agent proceeds on model memory because the project feels familiar. | Model memory holds rank zero. A capsule that exists is read, every time. |131| **Rules nesting in the capsule.** Convention deltas stop migrating and the capsule forks the canon. | Deltas are staged, migrated, and deleted. A delta present across two consecutive capsules is a migration failure to fix now. |132| **Secrets leaking in.** A token lands in a committed file. | Hard ban, checked at write time. Reference the credential's existence and holder, never its value. |133134---135136## Boundary (Read Before Applying)137138| Skill | Governs |139|---|---|140| `compaction-integrity-protocol` | State surviving compaction *within* a live session. |141| `correction-conversion-protocol` | Corrections becoming standing class rules. The capsule stages deltas for it, nothing more. |142| `doctrine-room-architecture` | The canon itself: rule lifecycle, decision governance across projects. |143| `memory-poisoning-defense` | Persistent stores the operator cannot inspect. The capsule avoids that class by design. |144| `session-handoff-protocol` | Cross-session mission state: what is written when context dies, and how it is loaded and verified when work resumes. |145146Overlap is a defect. State lives here; rules live in the canon; hidden147memory is a different threat surface entirely.148149---150151## Compliance Check (Run at Session Close and Session Open)1521531. Does a capsule exist, and was it loaded before the first output?1542. Was the capsule verified against its anchor before being trusted?1553. Does every decision in the ledger carry its reason?1564. Is every dead end recorded with the evidence that killed it?1575. Is the first next-action startable without a clarifying question?1586. Have convention deltas migrated to the canon and been cleared?1597. Is the capsule still one screen, and is its anchor current?160161---162163## Adversarial Evaluator Gate164165**What would a hostile evaluator attack first?**166167The capsule becoming a stale authority. A confidently loaded wrong168state is worse than a cold start: the cold-start agent asks, the169poisoned agent acts. The defense is structural, not aspirational:170verify-on-load is a mandatory step with a concrete anchor to check,171and the trust order places reality above the file without exception.172173The second attack: the capsule quietly becoming a second doctrine174system. Every rule that nests in the capsule instead of migrating is a175fork of the canon, and forks diverge silently until they conflict176loudly. The staging-area design, the two-capsule migration deadline,177and the one-screen ceiling exist to make that accumulation impossible178to sustain.179180---181182*YourVisionYourCreation LLC, yourvisionyourcreation.com*183*Licensed under CC BY 4.0*
Forexgod21