Session Handoff + Durable Maintenance, Double-Audited

Session handoffFreshClaudeverified 2026-06-21sha 2c975663fe15

Born in: the post where it earned its place →

The generic “write me a handoff” produces a plausible summary; this version forces the agent to actually persist state and pass a fail-closed validation gate first, then audit the artifact twice against a cold-start reproducibility test and validate every claim against disk/git before it is allowed to say GO.

ROLE: You are the outgoing engineer running an end-of-session HANDOFF + durable MAINTENANCE pass. A fresh session with zero memory of this one must be able to take over cleanly. You do the work first, then prove it. A tidy summary of work you did not actually do is a failure.

SCOPE CAP (do not exceed without asking):
- Touch only files under {{repo_root}} plus the handoff doc {{handoff_doc}}.
- Allowed git surface: {{allowed_branches}} (current branch and its open PR). Do NOT touch other branches, do NOT delete branches, do NOT force-push, do NOT rewrite history.
- If completing this honestly needs more than {{max_actions}} mutating actions (writes, commits, pushes), STOP and report what remains.
- If a step is genuinely ambiguous, STOP and ask one specific question instead of guessing.

PHASE 1 - INVENTORY (read-only, no mutations yet):
1. List session-only state that exists nowhere on disk: decisions made, why, dead ends, in-flight edits, env/setup steps done by hand.
2. Run read-only git state: `git status`, `git log --oneline {{main_branch}}..HEAD`, `git diff --stat`. Capture exact output.
3. Open and read the current {{handoff_doc}} and any tracking files ({{task_file}}, changelog, plan/spec docs) so you know what already exists.
4. Self-critical line: state the ONE thing most likely to be missing or stale right now.

PHASE 2 - DURABLE MAINTENANCE (mutations; obey the scope cap):
For EACH action below, follow this loop: pre-flight check -> act -> verify-after -> on red, revert and report (never leave a half-done mutation).
1. Persist session-only state to disk: write decisions, rationale, and remaining tasks into {{handoff_doc}} / {{task_file}}. Pre-flight: confirm the target file exists and you read it. Verify: re-read the file and confirm your text is present.
2. Sync only the docs directly referenced in {{handoff_doc}} or {{task_file}} that drifted from reality. Pre-flight: diff each claim against the live source/command; edit only where they disagree. Do NOT touch unrelated docs. If more than 3 files need syncing, STOP and list them under HONEST GAPS instead of editing them all.
3. Git hygiene within scope: stage ONLY the files you changed in Phase 2, and list them before staging. Do NOT stage pre-existing dirty or untracked files unless the Phase 1 inventory proves they are part of this handoff and you name each one. Pre-flight: `git diff` every file you are about to stage and confirm it is intended. Do NOT commit secrets, large artifacts, or unrelated churn.
4. If a commit is warranted, commit on the current branch with a clear message. Verify: `git show --stat HEAD` matches what you intended; `git status` is clean of surprises.
5. Run the project's validation gate ({{verify_cmd}}). This is the fail-closed line: if it does not pass, do NOT report the handoff as ready. If your Phase 2 edits caused the failure, revert only those edits; if the failure was already there before you started, leave it untouched and report it as a pre-existing gap. Capture the real command output, not a paraphrase. Re-run {{verify_cmd}} after your final handoff edit; if it is red then, the verdict is NO-GO.

PHASE 3 - DOUBLE AUDIT OF THE HANDOFF (do not assume Phase 2 finished the job):
Audit the handoff doc twice, from a cold-start reader's point of view. Do not trust your own "done" - re-derive it.
Pass A - completeness: could a fresh session reproduce the current state from {{handoff_doc}} ALONE, with no access to this conversation? List every gap.
Pass B - commonly-missed checklist (check each explicitly, mark present/absent/NA):
- {{task_file}} updated with real remaining tasks (not aspirational)
- spec/plan docs not stale vs the code
- any reviewer/CI/telemetry output captured or linked
- environment/setup steps a human did by hand are written down
- branch/PR state described (what is merged, what is open, what is blocked)
- secrets/credentials NOT pasted into any tracked file
- exact next command the fresh session should run
For every claim in the handoff, validate it against disk/git/command output before you let it stand. Delete or correct anything you cannot verify.

OUTPUT (evidence, not vibes - paths, commands, and real output only):
1. WHAT I DID: bullet list, each with the file path touched and/or the command run.
2. PROOF: paste the real output of {{verify_cmd}}, the final `git status`, and `git log --oneline {{main_branch}}..HEAD`.
3. AUDIT RESULT: the Pass B checklist with present/absent/NA per item, and what you fixed.
4. GO / NO-GO: one line. GO only if {{verify_cmd}} passed AND the cold-start reproducibility check passed. Otherwise NO-GO with the exact blocking reason.
5. FRESH-SESSION TAKEOVER: the precise first command and first file the next session should open.
6. HONEST GAPS: anything you could not verify, ran out of scope for, or are unsure about. If there are none, say so plainly - do not pad.

Fill in: repo_root handoff_doc task_file main_branch allowed_branches max_actions verify_cmd

Shared as is, for reference. Read it and decide what it will do before you run it; using it is your responsibility, under the terms.