durable-session-state

# Durable Session State

Long swarm-mode sessions outlive their context window. Compaction summarizes
history, and summaries lose exactly the things the swarm gates depend on:
which diff a reviewer approved, what evidence was recorded, which decisions
are settled. Without durable artifacts, a resumed session re-litigates settled
decisions or — worse — treats a stale approval as current. Persist state to
files as you go; treat the conversation as cache, not storage.

## Where artifacts live

- Generic swarm tasks: `.claude/session/tasks/<task-slug>/` in the project.
- Issue-tracer work: `.claude/issue-traces/<issue>/` (that skill's own schema
  — `08b-implementation-review.md`, `09-final-critic.md` — wins for its work).
- Never write task artifacts to the repo root, and never under `.swarm/` —
  that directory is the OpenCode plugin's runtime state, not Claude Code's.
- These artifacts are working state, not deliverables: do not commit them
  unless the user asks. Before committing, check `git status` and exclude
  them explicitly.

## What to persist

Keep it to four small files per task; update in place:

1. `plan.md` — task scope, success criteria, files in scope, what must not
   break. Update when scope changes; never fork a second plan file.
2. `decisions.md` — one line per settled decision with a one-line rationale
   ("chose X over Y because Z"). Settled means: do not reopen without new
   evidence or a user request.
3. `evidence.md` — validation commands run and their outcomes (pass/fail plus
   the load-bearing output lines, not full logs).
4. `gates.md` — the approval ledger. One entry per reviewer/critic verdict:

   ```
   ## <gate> — <APPROVE|NEEDS_REVISION|BLOCKED>
   when: <ISO timestamp or turn marker>
   head: <git rev-parse HEAD>
   diff: <git diff --stat summary>
   items: <blocking items, or none>
   ```

## When to write

- At phase boundaries (scope settled, plan built, implementation done, each
  gate verdict received).
- Before ending a turn while background subagents are running.
- Whenever you notice the conversation is long — write ahead of compaction,
  not after it.

## Resume protocol

On resuming (after compaction, a restart, or a handoff), before doing new
work:

1. Re-read the task's artifacts. They are authoritative over your memory of
   the conversation.
2. Do not re-litigate `decisions.md` entries or redo work `evidence.md`
   already proves, absent new evidence or a user request.
3. Check gate staleness: if `git rev-parse HEAD` or the working-tree diff no
   longer matches the latest APPROVE entry in `gates.md`, that approval is
   invalid — re-run the affected reviewer/critic gate on the current diff.
4. If artifacts and the summarized conversation disagree, trust the artifacts
   and say so.

## Relationship to swarm gates

The swarm-mode contract invalidates any approval issued before the latest
edit. The `gates.md` ledger is what makes that rule *checkable* instead of
vibes: record the HEAD and diff summary at approval time, compare on resume
and before final synthesis. If you cannot demonstrate approval-after-last-edit
from the ledger, the gate is not satisfied.