Session Close

Finalise from VERIFIED state, write each piece of state to its one home, hand off slim. The next session should inherit verified files and a one-page delta — not a conversation summary that may carry unverified claims.

CONFIGURATION (adapt to your project)

Two lanes of canonical files. Name yours:

Assistant-writable (you draft; the user saves):

• ROADMAP.md — the plan: sequence, status, gates, pending decisions
• TASKS.md — actionable items only
• HANDOVER — this session's delta (written fresh each close)
• (optional) convention/process guides the project keeps

Externally-owned (a second environment owns them; you can only request edits) — e.g. an agent's instruction file, a ledger of shipped work, anything living on another system's disk. If your project has none, skip Step 4 entirely.

Operating principle

One home per content type: the plan lives in the roadmap, actions in the task list, durable decisions in the project's decision home, per-work detail in its own artifacts. The handover holds ONLY the session delta plus pointers. If the handover is growing, content is sitting in the wrong home.

Step 1 — Reconcile (the safeguard)

List what changed this session that affects canonical state. Tag each item VERIFIED (confirmed against the most authoritative source available — disk, ledger, a real run) or CLAIM (asserted in conversation only). Never promote a CLAIM — a status flip, a hash, a "done", a metric the next session will act on — into a canonical file or the handover as fact. Either verify it now, or carry it explicitly tagged "UNVERIFIED — confirm before acting."

Step 2 — Update the assistant-writable files

• Roadmap — flip statuses, update gates, note the change in its log. (If a roadmap-rendering skill is installed, defer the render to it.)
• Tasks — move finished items to Done, add new ones, keep Active small.
• Guides — only if a convention actually changed this session.

End this step by telling the user exactly WHAT to save WHERE. A draft in chat is not a saved file — unsaved canonical files are how projects silently lose state.

Step 3 — Route this session's decisions to their homes

Decisions are made in conversation; they must not stay there. Route by state:

• Pending (raised, not decided) → a gate in the roadmap + a decide-action in the task list. This becomes the next session's "decisions waiting on you" view.
• Made / durable → the project's decision home (a decisions section or an externally-owned contract file — see Step 4), WITH its rationale in plain language, so it isn't re-litigated later.
• Parked (deliberately deferred) → an annotation with an explicit revisit-trigger ("revisit when X").

Step 4 — Externally-owned files (only if any changed this session)

If a durable decision or shipped work belongs in an externally-owned file:

1. Draft a precise edit request for the owning environment — exact insertions or exact FIND/REPLACE text, never "update as you see fit." Paraphrase is how locked decisions drift.
2. Tell the user in plain terms what the request will change and what to check in the reply, before they run it.
3. The chat is now "pending close" — not closed — until the revised file comes back and is verified.
4. Verify the return: read the revised file back through whichever channel your setup makes reliable, confirm each edit landed exactly as specified and nothing else changed. Note what your channel can and cannot confirm (content vs byte-identity) and rely on the owning environment's reported hash for the rest.

If nothing externally-owned changed: skip — assistant-writable close only.

Step 5 — Write the slim handover (~1 page)

## Handover — <date> · <session focus>

### For you (plain language)
[2-3 sentences: what this session accomplished, what now waits on the user.]

### Done this session
[Completed work only, VERIFIED only. One line each.]

### Mid-flight right now
[What is literally in progress this moment. Status, not instructions.
Tag anything UNVERIFIED.]

### Traps from this session
[Failed approaches + why; things the next session will be tempted to repeat.
Durable lessons were routed to their home in Step 3; these are the remainder.]

### Carry-forward context (still true; no canonical home yet)
[Facts the next session needs that no canonical file holds yet. Keep compact;
migrate when a home exists. Omit if empty.]

### Canonical state — read these, don't trust this doc
[List the project's canonical files.]

### For the next session
Load session-open. Read the canonical files before acting. Treat everything in
this handover as context to verify, not fact to trust. Then wait for instructions.

Rules

• Verify before writing; never launder a CLAIM into a canonical file or the handover.
• One home per content type; the handover points, it never restates.
• Externally-owned files change only via precise edit requests, verified on return.
• Keep the handover ~1 page; growth means content belongs in a canonical file.
• Forward-only: append to logs and ledgers; don't rewrite history.