Handoff

Style: Mode-B-lite. Produces the active-continuity artifact docs/tmp/handoff.md (FR-23 Tier 2) for the NEXT AI coding agent — not a human PM report. Operator-triggered (invocation: manual) for restart mode; Mode: run-ledger is the sole sanctioned autonomous write (long-run continuity, announced in chat).

Purpose

Capture the exact current state of a coding session into docs/tmp/handoff.md so a brand-new AI session continues without the previous chat. Long sessions degrade and compaction is lossy; a structured handoff preserves goal, repo state, decisions, in-flight files, failed attempts, constraints, and the single next action. This is the active restart state; formal role-relay prompts (implement/deploy/architect) are separate dated files under docs/tmp/handoff/ produced by implementation-planning / release-deploy-reporting.

Two modes (header Mode: line; absent in a legacy file → treat as restart): restart — operator-triggered snapshot for the next session; run-ledger — a long autonomous run's continuity note, written without operator trigger and announced in chat (one line), so context death mid-run loses nothing. A fresh session reading Mode: run-ledger resumes from records (read the ledger + cited artifacts first, resume from the last durable fact — task-delegation successor contract); a run-ledger is a continuity note, not a role-relay draft (it does not breach "AI Developer acknowledges; doesn't draft").

When to invoke

• Operator says "prepare a handoff" / "hand this off" / "continue in a new chat" / runs /handoff (→ Mode: restart).
• Operator replies rotate to a rotation offer (FR-17; role-discipline § Forward Momentum) → Mode: restart.
• Session is getting long / context degrading, or about to stop a complex implementation, migration, or debugging session.
• Meaningful code/test/schema/config/decision changes were made and must survive into the next session.
• A long autonomous run needs continuity across possible context death (→ Mode: run-ledger, no operator trigger needed; announce the write in chat — one line).

Do not invoke when

• No meaningful change happened this session (nothing to continue from) — say so; do not write a hollow file.
• Operator wants a human-facing status update / standup / PR description — this file is for an AI agent.
• The artifact needed is a formal role relay (docs/tmp/handoff/<date>-<slug>-{implement,deploy}.md) — that's implementation-planning / release-deploy-reporting.
• Operator wants release/deploy reporting — use release-deploy-reporting.

Required inputs

Procedure

1. Classify per FR-23 (documentation-budget): a handoff is Tier 2 — warranted only when the next session needs exact continuation state. If nothing meaningful changed, stop.
2. Inspect repo state: branch, short HEAD, git status --short, git diff --stat; review small diffs.
3. Detect real build/test/lint commands from manifests. Do not invent.
4. Reconstruct session facts: role + authority, goal + non-goals, done/partial/not-started, locked decisions, constraints, what failed and why, open questions, the single next concrete action.
5. Mode + archive (paper trail). Stamp Mode: restart (operator-triggered) or Mode: run-ledger (autonomous continuity — announce the write in chat, one line). Archive the predecessor to docs/tmp/handoff/archive/<YYYY-MM-DD-HHMM>-handoff.md (timestamp from its Updated: header when parseable, else file mtime/now) ONLY on restart supersede or mode transition (restart↔run-ledger, /handoff over a live ledger, or a different ticket's file). Run-ledger updates supersede IN PLACE (FR-18; git history is the audit trail) — never one archive file per ledger update. Archive files are dated history — agents never load them; the operator may prune the archive anytime (nothing references it).
6. Create docs/tmp/ if absent. Produce docs/tmp/handoff.md against templates/handoff.md — same section order, every section filled with content / Unknown / None, and current Updated: <YYYY-MM-DD HH:MMZ> + Mode: lines in the header. Do NOT append resumption notes above old content (FR-18); the superseded restart predecessor lives in the archive. Write primitive (FR-18): supersede replaces stale semantics, not the file. A run-ledger update where most sections are unchanged is a targeted Edit of the stale regions + the Updated:/HEAD: header — not a regeneration. A full Write is for a restart snapshot, a mode transition, a different ticket, or when most sections changed. "Fresh" means no stale semantics survive, never retype the file.
7. Quality bar: factual only; pointers to canonical spec/decisions/tasks instead of reprinting them (FR-23); exactly one concrete executable Next Step; preserve repo terminology; product/user decisions separate from implementation detail; before reusing any copied procedural block, check whether a capability shipped since it was written supersedes the procedure.
8. Report a short Mode A summary in chat (Goal, Current state, Active files, Next step, Validation). Do not paste the full file unless asked.

Resuming from a handoff (reader contract)

Named reader: the NEXT session, via workflows/session-initiation.md steps 5/5a (which reads docs/tmp/handoff.md automatically at session start).

1. Read the header: Mode:, Updated:, Branch:, HEAD:.
2. Trust gate. Diff recorded Branch:/HEAD: vs live git branch --show-current / git rev-parse --short HEAD. Match → Active Files in Flight and Next Step are current; resume there. Mismatch → the repo moved after the write: re-derive in-flight state from git status --short + git log <recorded-HEAD>..HEAD --oneline; treat the file table as historical; Key Decisions Made / Failed Attempts stay valid (they don't decay with HEAD).
3. Mode: run-ledger → resume from records: read the ledger's cited artifacts BEFORE acting; resume from the last durable fact (task-delegation successor contract).
4. Never append a resumption note to the file (FR-18) — the next write supersedes in place (targeted Edit when most sections are unchanged; full Write on a structure/mode/ticket change).

Run-ledger write cadence

Supersede the ledger at durable milestones, not per tool call: after each commit, gate verdict, locked decision, completed T-task/slice, or concluded failed attempt — and BEFORE any operation that could kill context (deploy, migration, long bounded run). Each write = one-line chat announcement. Between milestones the ledger may lag; git history covers the gap. One archive file per update is a violation (in-place supersede — see Procedure step 5).

Output artifacts

Failure cases

Escalation path

• Repo state ambiguous (detached HEAD, mid-rebase, dirty submodules) → record under Environment / Branch / Repo State and ask the operator to confirm before the next session continues.
• Session made deploy/production-affecting changes → also route through release-deploy-reporting; the active handoff is not a deploy record.
• Decisions still unsettled → list under Known Issues / Open Questions, not Key Decisions Made.

Anti-patterns

• Do not write a human-PM / marketing-style document — the reader is an AI agent.
• Do not guess; write Unknown.
• Do not hide failed attempts or dead-end debugging paths.
• Do not emit a vague Next Step.
• Do not include chain-of-thought or unrelated chat history.
• Do not use docs/tmp/handoff.md for a formal implement/deploy relay (those are dated files under docs/tmp/handoff/).
• Do not auto-invoke restart mode (invocation: manual) — the operator triggers it. Mode: run-ledger is the sole sanctioned autonomous write and MUST be announced in chat when written.
• Do not archive on every run-ledger update (in-place supersede; archive fires on restart supersede / mode transition only).

Clean-room note

Original Fusebase Flow content. The session-continuity-doc concept is common to long-running agent workflows; no third-party code, prompts, or skill files are copied. See docs/source-map.md.