Chapter 7: Session Continuity¶

The Handoff Artefact: What the Repository Cannot Tell You¶

1. Memory Is Not a Control¶

The task was a migration. It ran for an hour, ended on a clean gate, and was picked up the next morning in a different tool. The second session read the changed files, decided the approach was wrong, and reversed two of the three edits. Nothing had failed. The session that did the undoing simply did not know what the earlier one had rejected — and so it weighed the same options again, and this time chose one of them.

The three structures assume such work can be resumed. Session continuity is the discipline of making the handoff between sessions explicit, verifiable and repository-owned, so the next session resumes the work instead of reconstructing it.

Chapter 2 introduced the execution log, which records what a session did. Chapter 5 introduced context routing, which decides what a session reads. This chapter is the bridge between them: the artefact that tells the next session what was decided, so it neither re-reads what it does not need nor re-decides what was already settled.

An agent that resumes without such an artefact does not resume. It reconstructs, from whatever context it can retrieve, and the reconstruction is a story about work it did not do.

💰 Cost Check: a lost session costs the review twice — once to reconstruct what was done, once to catch what the reconstruction invented. The artefact costs a minute at each stop. The arithmetic is not close, and the expensive version is invisible until a change lands from a fiction.

🎯 What You'll Learn¶

Why tool-private memory cannot carry a task across tools, days or a crash
The seven fields a handoff needs, and what each one is for
Why the repository is the authority for what changed, and the file is the authority for what was decided

What an Interruption Costs¶

Interruption	What is lost without an artefact
a second tool	the task, the decisions, the files already changed
a night	the next step, and why it was next
a crash	the gate status: what was verified, and what was assumed
a handoff to a recipient who cannot see the file	all of it, unless the artefact is attached to the task

The cost is not the elapsed time. It is that the resumed work has no memory of what it decided, so it decides again — differently.

flowchart LR
  S["session 1<br/>task · decisions · files"] --> A["session artefact<br/>the handoff contract"]
  A --> R["session 2 — any tool<br/>resumes from the file"]
  A -.->|"no artefact"| G["reconstruction<br/>a story about work it did not do"]

What this shows: the artefact is what makes resumption possible; without it, the next session guesses.

✅ What to Check¶

Stop a task mid-way today. Could a different tool resume it from what is in the repository? If not, the gap is the artefact.
Name one decision made in the current session that is not written down. That is what an interruption deletes.

2. The Artefact Is a Contract¶

A Rule, Not a Mechanism¶

Two things can hold a task together across sessions, and they are not the same kind of thing.

The session lifecycle — resume, replay, identity, crash recovery — is a mechanism. Somebody built it, it belongs to a tool, and it stops at that tool's boundary. Adopt it; never rebuild it.

The artefact is a rule: a file in the repository, written by the session, reviewable in a diff, portable to any tool that can read. It is yours to define, and yours to enforce. §4 returns to the split at the point it matters — a crash — but the artefact is on the rule side from the first line it contains.

The Seven Fields¶

A session artefact is a small file with seven fields. Every field exists because a resumer needs it; a field added without a need is a field someone else maintains.

Field	The question it answers	Why it exists
task	what is being done, in one sentence	a resumer who cannot state the task reads everything to find out
status	not started · in progress · blocked · done	the first question of a resume is whether to continue at all
files-read	what was consulted	the next session does not re-read five files to learn what is already known
files-modified	what was changed	the resume starts from the truth, not from a claim about it
decisions	what was decided, and what was rejected	without it the next session re-litigates — the most expensive omission
next-step	the one action to take next	a resume that has to choose its own next step is a restart
gate-status	what has been verified, and what is assumed	a resumed session that trusts an unverified claim is a green nobody measured

The Field That Pays for the Artefact¶

decisions is the field that earns the file. The other six tell the next session where it is; this one tells it what not to undo. The scenario at the top of the chapter is not a hypothetical: a session that does not know a decision was made will make it again, and a coin flipped twice is not a state.

The half that matters is rejected. what and why record the choice; rejected records the options already weighed and why they lost. A resumer who has that neither re-opens a settled question nor quietly picks up the option that was turned down — which is exactly what the second session in the story did.

The schema, as a shape:

# .session/<task>.yaml — the handoff, gitignored
task: <one sentence>
status: in-progress | blocked | done
files_read: [<paths>]
files_modified: [<paths>]
decisions:
  - what: <the decision>
    why: <the reason>
    rejected: <what was not chosen, and why>
next_step: <one action>
gate: { ran: <checks>, passed: <bool>, at: <timestamp> }

What never goes in it. No secrets, no transcripts, no persona data. The artefact is read by whoever resumes, which may be a different tool with a different trust boundary.

✅ What to Check¶

Does your artefact have a decisions field with a rejected option? Without it, the next session re-litigates.
Does the file contain anything you would not paste into a ticket?

3. The Part the Repository Cannot Tell You¶

A session file looks like state you could simply re-derive, and for most fields you can. Split it by where each field comes from:

Field	Where it comes from
task	the branch name and the commit message, usually
status	the working tree and the gate, partly
files-read	nothing, unless an execution log is kept
files-modified	`git status`, exactly
decisions	nothing — a diff shows what was chosen, never what was rejected
next-step	nothing — it is a judgement about what remains
gate-status	the gate's own output for the checks it ran; the assumptions, nothing

That table is the reason the file exists. The derivable fields are the cheap ones; the fields a resumer needs are the ones nothing derives. git diff will tell the next session what changed. Nothing in the repository records that the retry loop was rejected because the audit log joins on the request id — and a rejected option leaves no trace to derive from, which is why the only way to recover it is to re-decide — the failure the chapter opened with.

So the file is not a cache of state that git already holds. It is the part of the session that would otherwise be lost, written once and checked against the repository afterwards. That is why it is gitignored and still not the authority: it is cheap to carry, cheap to ignore, and the fields that can be checked against the repository are checked.

Where the file travels. Gitignored means not pushed, not machine-bound: the file sits in the working tree and can be copied like any other. Its default life is one machine, because that is where the second tool and the crash are. When it has to cross a boundary — any recipient who cannot see the file: a colleague, a review, another machine, a fresh agent — the file is attached to the task or the pull request, and the durable part moves to the record that is committed: the decision is written in the change's description, and the gate result in the execution log. What must never happen is a resumer being asked to continue from a file they cannot see.

The reconciliation rule, stated once: before resuming, compare files_modified with the working tree. A file changed but not listed was changed after the artefact was written — reconcile before continuing, and when the two disagree, the repository is what happened.

✅ What to Check¶

Does anything reconcile the artefact with git status before resuming? If not, the artefact is a memoir.
Take a stale artefact and find the delta. What did it miss?

4. Cross-Tool, Mid-Task, and Crash¶

Cross-tool handoff is the test: start a task in one tool, stop deliberately, resume in another. If the resume needs the first tool, the continuity was private memory wearing a name.

A deliberate mid-task stop is the cheapest form of the drill: stop at a natural boundary, write the artefact, resume. Do it on a real task, not a rehearsal — the rehearsal always succeeds because the person writing it remembers.

A crash is where the split from §2 shows. Crash recovery — session lifecycle, resume, identity — is a mechanism: adopt it. Continuity is a rule — the artefact — and it must survive the mechanism's failure.

The Handoff, in Order¶

A handoff is a procedure, not a snapshot. Five steps, and the first two decide whether the other three are worth anything.

Write the artefact before you stop — at a natural boundary, not after the crash. A file written afterwards is a reconstruction, which is the failure this chapter opened with.
Record a decision while the option is still rejected. The moment an option loses, write what, why and rejected. Ten minutes later you will remember the choice and have lost the reasoning; a day later you will not remember either.
Reconcile before you hand over, not after: compare files_modified with git status, and fix the artefact rather than the tree.
Promote what must travel. Inside one machine, the file is enough. Across a boundary, attach it to the task and move the durable part — the decision, the gate result — into the committed record.
Resume in a different tool, and only do the next step. If the resume needs the first tool for anything, step 4 was skipped.

Two habits keep this cheap. One artefact per task, overwritten in place — it is state, not a log, and a directory of timestamped files is a directory nobody reads. Keep it to one screen: if the artefact no longer fits, the task is two tasks.

Mechanism and View¶

Mechanism: session lifecycle, resume, identity. Adopt it; never rebuild it.
View: a timeline or replay panel. Adopt it; never let it become the only place the state exists.

✅ What to Check¶

Run the handoff drill once. Record where it failed — that is the field your artefact is missing.
If the tool offers a replay view, can you still resume when it is empty?

5. Build the Handoff¶

Artefacts¶

Artefact	What it is for	Where it lives
session artefact	the handoff contract, seven fields	`.session/<task>.yaml`, gitignored
resume checklist	what to read before continuing	the Playbook
reconciliation check	artefact compared to the working tree	the resume step, or a script
handoff drill record	one real cross-tool resume, with its failure	the evidence pack

The resume checklist, as a shape — four steps, in order:

# Resume a task
1. Read the artefact: task, status, decisions, next-step.
2. Reconcile: compare files_modified with `git status`; investigate the delta.
3. Check the gate: what passed, what is assumed, what must re-run.
4. Do the next step — one, not the whole plan.

Decisions¶

Choice	Default	What changes if you choose otherwise
where the state lives	a file in the repository, gitignored	tool memory, which stops at the tool boundary
authority on conflict	git	a resumer that trusts a memoir
what to record	decisions, including the rejected option	a resumption that re-litigates
the drill	on a real task, once	a rehearsal that proves nothing

✅ Checks¶

A task started in one tool resumes in another from the artefact alone.
The artefact and git status agree, or the delta is explained.
No secret, transcript or persona data is in the file.

Sequence¶

Write the artefact at the first natural stop. Checkpoint: all seven fields filled, including a rejected option.
Write the resume checklist. Checkpoint: it begins with the artefact and the reconciliation, not with code.
Run the drill across two tools. Checkpoint: the second tool resumes without the first.
Add the reconciliation to the resume step. Checkpoint: a stale artefact is caught before work resumes.

Done When¶

A different tool can resume a real task from the artefact alone.
The artefact never disagrees with the working tree silently.
The drill record names what failed the first time.

6. 🔑 Chapter Summary¶

Continuity is a file, not a memory.

Tool-private memory cannot carry continuity — an interruption deletes it, and reconstruction is a story.
The artefact is a contract with seven fields, and decisions is the one that earns the file — what, why, and the option that was rejected.
Gitignored, not a cache — the file carries what the repository cannot, and the fields the repository can supply are reconciled before resume.
Cross-tool handoff is the test; a mid-task stop on real work is the cheapest way to run it.
Crash recovery is a mechanism, continuity is a rule — adopt the first, own the second.