Handoff

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).
• 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

Input	Where it lives	If missing
Repo state	git status --short, git branch --show-current, git rev-parse --short HEAD, git diff --stat	Stop; confirm the working dir is the intended repo
Output structure	templates/handoff.md (the 16 canonical sections)	Use that template's section order; do not improvise
Session facts	the current conversation (goal, role, decisions, failures, next step)	Write Unknown; never guess
Build/test commands	package.json, Makefile, pyproject.toml, repo docs	Detect before inventing; else Unknown

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

Artifact	Path	Mode
Active session handoff	docs/tmp/handoff.md	Mode B (16 sections from templates/handoff.md, Updated: + Mode: header)
Archived predecessor	docs/tmp/handoff/archive/<YYYY-MM-DD-HHMM>-handoff.md	dated history — never loaded (restart supersede / mode transition only)
Handoff summary	chat	Mode A

Failure cases

Failure mode	Detection	Response
Nothing meaningful to hand off	git status clean, no in-flight decisions	Tell operator no handoff is warranted; do not write a hollow file
Facts unknown	A section can't be filled from session/repo	Write Unknown; never invent results/decisions
Vague next step	Next Step reads "continue" / "fix issues"	Rewrite as one named file/function/command + expected result
Stale existing handoff	docs/tmp/handoff.md describes a different/old task	Archive it, then supersede with current state — a different ticket is a full Write (FR-18 write primitive); do not merge contradictory histories
Regenerated an unchanged file to "supersede" it	whole-file Write whose diff touches a few regions	Use a targeted Edit; FR-18 replaces stale semantics, not the file
Reprinting canonical docs	Handoff restates the full spec/decisions/tasks	Replace with pointers (FR-23) + current state

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.