handoff

# Handoff — Close the Session from Corrected Truth ## Why this exists The primer is the first thing a cold session reads, and the session that writes it is the one with the blind spots. So the primer is written once, at the close, after a retro has surfaced what the session did not claim — and the write is gated: `retro-before-primer` denies it until a retro note postdates the scope's last edit. The handoff is the operator's ceremony, never the agent's; the retro is the grooming step that precedes it. ## Prerequisites - `WIKI_SCOPE: <scope>` declared in the project instructions. If missing, suggest `/wiki`. - A retro note under `projects/<scope>/notes/retro-YYYY-MM-DD.md` whose `updated` is at or after the newest page under the scope's `plan/`, `spec/`, `adr/`, and `intent/` folders. Otherwise stop and run `/retro` first. - The scope's primer at `projects/<scope>/primer.md`. ## The protocol ### Step 1 — Gate check Read the newest retro note's `updated` and the newest `updated` under the four working folders. If the retro is older, stop: `/retro`, then back here. The pretool gate enforces this deterministically; checking first avoids a denied write mid-ceremony. ### Step 2 — Primer rewrite Write the primer first — the gate compares the retro note against the scope's newest page, and the sweep and reconcile below move story clocks past it. The primer's reader is an agent: `prime` inlines it into the next session's context. Write for that reader. Activate the `signal-dense` register (`/signal-dense`) before drafting, and read `projects/<scope>/glossary.md` first — every term the primer uses is a canonical handle from there, typed the way the glossary types it, never a synonym or a narrative paraphrase. Direct predicates, no hedging, no register shifts. Four sections, about 300 words, `updated` from the clock: - **Focus** — three lines: what the scope is doing now and why. - **Next** — the top three items, drawn from the Story Index and the draft intents ordered by `sightings`. A slice named where one is in progress. - **Open** — pointers to intents only. A question without an intent is filed as one first. - **Read order** — three links. The rule: nothing in the primer that a query or another surface derives. Invariants live in the project instructions; versions and release state in the changelog and tags; counts and active ADRs come from `prime`. Write it through the harness's file tool or with a literal vault path, so the gate and the resync both see the write. ### Step 3 — Status sweep Slices tick during a session, and a story whose slices and acceptance are all resolved archives at the last tick (`/tdd`). The sweep catches what that missed: list every story whose slices are all resolved — ticked, or declined with recorded rationale — and whose `status` is still `active` or `draft`. For each, name any outstanding verification debt from its Decisions or its intents. Propose the set. Flip `status: archived` **only on the operator's approval**, with `updated` from the clock (`date -u +%Y-%m-%dT%H:%M:%SZ`). The operator decides whether debt blocks closure. A scope that skips this buries live work under finished work. ### Step 4 — Story Index reconcile For each plan under the scope, the Story Index rows match story frontmatter: state, category, archived stories marked as such, and a row for every story promoted from an intent this session. The plan's `updated` moves only if a row changed. ### Step 5 — Confirm the sync `kmd config`: the `synced` line advanced past the primer write. If not, `kmd validate`, fix findings, `kmd sync`. ### Step 6 — The next line One line, last: `Next session starts with: story-<slug> slice N` — or the top intent when nothing is in progress. ## Output shape Visible response: the sweep proposal and its outcome, the Story Index changes, the primer's word count, the sync confirmation, and the next line. No separate report. ## Anti-patterns - **Handoff without a retro.** The gate blocks it; a handoff that works around the gate inherits the session's blind spots. - **Sweep without approval.** Archiving is the operator's call; the agent proposes. - **Primer as log.** Session narrative, restated invariants, version numbers, and work-item lists that the Story Index already holds are the rot the budget exists to prevent. - **Primer in prose register.** Synonyms, paraphrase, and hedges dilute the signal an agent reads; the canonical-dense register and the glossary's handles are the primer's language. - **Open questions without intents.** The primer points; it does not carry. - **Writes the resync cannot see.** A primer written through a shell variable path bypasses both the gate and the posttool sync.