handover

The Lossless Handoff Protocol

A content contract for agent-to-agent context handoff and task delegation. Portable across repos. Handover (this repo) is the enforcement layer; this file is the spec it enforces. This specifies the format of the handover document; the single agent-to-agent artifact Handover is built around. (Handover also ships a separable behavioral gate; that is a distinct concern and is not specified here.)


0. The one invariant everything serves

A handoff is lossless iff a cold agent, given only the artifact plus repo access, and nothing from chat history, can reach the same decisions the sender would. It is seamless iff the receiver’s first action is unambiguous.

Every rule below exists to protect that sentence. When a rule seems expensive, ask: does skipping it force the receiver to re-derive a decision or a dead end? If yes, keep it.


1. Three interaction shapes, do not conflate them

Shape When Artifact Lifetime
Delegation Parent hands a bounded task to a child subagent that returns a result Task envelope (§5) Ephemeral
Handoff A session hands a whole workstream to a cold successor Handoff doc (§3–§4) Durable
Broadcast Shared canonical facts many agents read Single source of truth with supersession discipline (H6) Durable

Most loss comes from using a delegation envelope where a handoff doc was needed (successor starves) or a handoff doc where an envelope was needed (child drowns in irrelevant context and returns the wrong shape).


2. The two load-bearing ideas

2a. Every assertion is a claim, not a fact

A handoff records what the sender believed was true at a moment. Belief drifts from reality (code moves, PRs merge). Therefore every state claim MUST carry either (a) a one-line command to verify it, or (b) an explicit [belief, unverified] tag. The receiver trusts nothing that carries neither. This is the single highest-leverage rule; it converts a stale doc from a landmine into a checklist.

2b. Negative knowledge is the irreducible core

Positive state (what exists) is re-derivable by reading code. Negative knowledge is not; you cannot read the codebase to learn what was tried and abandoned, what was deliberately left unbuilt, or what was reverted and must not return. So preserve it in priority order, and if forced to cut length, cut positive state before negative knowledge:

  1. Tried-and-failed (what + why it failed) → prevents retry loops (the failure loop).
  2. Deliberately out-of-scope / not built → prevents scope creep.
  3. Built-then-reverted, do-not-re-add (+ the reason) → prevents undo/redo thrash.
  4. Decisions + rationale → prevents re-litigation.

3. The handoff document contract, required sections (all MUST be present)

  1. Orientation; one paragraph: what this is, self-contained.
  2. Identity block, repo, branch, latest commit SHA, open PR (URL), worktree?, ticket ids, each with its verify command.
  3. Current state as verifiable claims, a table; every row carries a verify command or [belief] tag (2a).
  4. Canonical sources, ranked, with the tie-break rule (“when docs disagree, higher wins; code is truth; X is stale where noted”).
  5. What changed since the last canonical doc was written; the deltas / do-not-rebuild list.
  6. Negative knowledge; the four categories of §2b.
  7. Next action, exactly one first step marked as the first step, then the ordered rest.
  8. Open questions / blocked-on-user.
  9. Whole-artifact verification; the compile/test command that proves the state still holds.

4. Hard rules (MUST / MUST NOT; each is testable, so each is lint-able / gate-checkable)


5. The delegation envelope (subagent case), required fields

A subagent starts cold and re-derives nothing you already know. The envelope MUST carry:

Keep it minimal on purpose: a delegation drowns on too much context, a handoff starves on too little. Opposite failure modes.


6. How this marries the gate (built)

This protocol is the content contract; the Handover gate is the deterministic backstop. It is built:

That turns the load-bearing MUSTs (H2 claims-carry-checks via the header, H5 one first action, H7 freshness SHA, H8 no silent Done) from aspiration into a checked gate; the same way the mutation gate turns “don’t force-push” into a refusal.

6b. The two layers handover-lint reports

The tool separates shape from truth, because they have different trust values and only one of them can be judged from the text alone.

STRUCTURE; the deterministic 0–100 rubric (always on)

Pure text analysis. Same input, same score. It proves a doc is built to be checkable, never that a claim is true. Weighted toward what §2b says matters:

Two optional header fields are recognized and validated if present: protocol_version (which protocol contract the doc targets) and author (who a receiver can go ask). Their absence is an advisory, not a failure.

VERIFICATION, repo-aware truth checks (opt-in)

Structure can’t know if true_at_sha is real or if status: done is earned. These checks can, but only inside the doc’s own repo, so they’re opt-in:

Execution contract (for verify_cmd and claim commands): commands run through the user’s shell, in the current working directory (run the lint from the repo root), with a 120s timeout for verify_cmd and 30s per claim. The only signal read is the exit code, write every check like a test, exiting non-zero when the claim is violated (test -f, grep -q, npm test), because a command that exits 0 regardless (git log, a bare ls) passes vacuously.

Verdict folds into one word: verified / stale-or-unproven / failed / unverified-no-repo / invalid-header. A fabricated SHA, future date, or failed verify_cmd exits non-zero; drift/unproven-done exits non-zero under --strict. All repo probes run without a shell, so a hostile doc’s header can never execute; the only document text that reaches a shell is verify_cmd (under --verify) and opted-in claim rows (under --claims).


6a. The universal handout: structured header + prose body (validated 2026-07-09)

A prototype validator run against real handoff docs showed prose-only rules have a ~30% false-positive rate: a doc that asserts “don’t rely on chat history” trips the same regex as one that violates it, and a doc that quotes banned phrases as examples flags itself. Conclusion: prose alone is not machine-checkable enough to gate on.

So the universal handout is a hybrid, and this is the template every durable handoff should follow:

---                          # structured header, tooling validates this STRICTLY (0 false positives)
protocol_version: 1          # which protocol contract this doc targets (optional, validated)
handoff: <workstream>
author: <who wrote this>     # a name a receiver can go ask (optional)
iso_date: 2026-07-09
true_at_sha: <commit SHA the claims below were true at>
shape: handoff | delegation | broadcast
supersedes: <path-or-null>
first_action: <the one unambiguous next step>
verify_cmd: <command that proves the state still holds>
status: in_progress | done   # 'done' only allowed if verify_cmd passes
---

<prose body follows the §3 section contract, linted LOOSELY: skip fenced code
blocks and blockquotes, and be negation-aware, so example/quote text isn't flagged>

The header carries exactly the facts that must never be lost or ambiguous (freshness SHA, the one first action, supersession, the verify command). Tooling checks their presence and shape deterministically. The prose stays human. This is the deliverable to standardize on.

7. The 10-second test for any handoff before you ship it

Delete the chat. Hand a stranger only this file and a terminal. Can they take the correct next action, avoid every dead end you already hit, and never rebuild something you deliberately removed? If any answer is no, the missing piece belongs in §2b, §4, or §6.