junction-handover

name	junction-handover
description	Maintain junction's cross-session memory and hand off cleanly between Claude Code sessions. Use at the END of an increment (to log progress), when CONTEXT is getting heavy (to decide continue-vs-new-session), or at the START of a new session (to resume). Keeps docs/STATE.md current so any future agent can pick up with full context.

Junction Handover — cross-session memory

docs/STATE.md is junction's living project memory: where we are, how we work, the recurring traps, the plan, and a session log. This skill keeps it accurate so a brand-new Claude Code session can resume with zero loss of context. Three moments to use it.

A. End of an increment — LOG IT (do this every time)

This is the final step of the per-increment loop, alongside the end-of-increment report. After an increment is merged:

1. Update docs/STATE.md:
   • Bump the freshness marker <!-- STATE-done-through: N --> to the increment you just finished. This is gate-enforced — pnpm verify runs docs:check, which FAILS if this marker lags the highest done increment in docs/methods/README.md. So you cannot mark an increment done + pass the gate without doing this. (Prose can't satisfy it — it's a machine-readable marker.)
   • §1 Snapshot — bump "last merged" PR, the increment count, and the immediate next.
   • §7 Session log — prepend a terse entry: YYYY-MM-DD — increment NN (name). + what shipped, any notable review fix, and "Next: NN+1." Keep it to a few lines. (docs:check also nudges that §7 mentions the latest increment.)
   • §3 Traps — if a NEW recurring trap bit this increment, add it (and to docs/futures/gotchas.md).
   • §4 Plan — if the route/slicing changed, reconcile with docs/methods/README.md.
2. Keep the registers current (already part of the loop): docs/futures/{gotchas,revisit-when,deprecations}.md.
3. Mark the increment done in docs/methods/README.md (this is what the marker is checked against).
4. Reflect — and harden the system, not just the memory. This is a required step, not optional polish: a retrospective is how the system gets harder to fool over time (the compounding is the whole point — see docs/behaviours/verify-the-artifact.md). Ask:
   • What recurred? Did a class of bug escape to manual QA / CI / the user more than once? (This session: "green but blind" 5+ times.) A recurring escape is a signal to close the gap in the cheap gate, not to "remember next time."
   • For each recurring escape, promote it into the layer that prevents recurrence: a gate (a pnpm verify / CI step — e.g. web:smoke, the shared leak-check), a skill (a repeatable QA loop — e.g. junction-web-verify), an agent rule (fold the lesson into a reviewer's prompt — e.g. anti-slop → junction-web-reviewer), a behaviour (a first-class decision principle), or at minimum a gotcha. Prefer gates > skills > docs (a gate can't be skipped; a doc can).
   • Did a builder report "done" on something that wasn't? If so, tighten the builder-brief "done" bar (docs/workflow.md) and the orchestrator's independent-verification discipline.
   • Did scope creep or go out-of-bounds? Note it; surface scope decisions to the user earlier next time.
   • Record the reflection's outcomes (what you promoted where) in the §7 entry — terse, e.g. "promoted X to a verify step + skill Y." If the user asks for a deeper reflection, write it up; otherwise the promoted artifacts ARE the reflection.
5. Commit these doc updates (with the increment, or as a small follow-up). The pre-commit/pre-push gate (docs:check inside pnpm verify) blocks the commit if STATE.md is stale or malformed.

Why a gate, not just this skill: instructions are advisory — an agent can skip them. The docs:check gate gives the memory teeth: structure + freshness are mechanically enforced on every commit/push/CI. (It can't judge entry quality — that stays your discipline via this checklist.)

Keep it terse — this is a running memory, not prose. The git log + the method files hold the detail; STATE.md holds the orientation.

B. Increment boundary — DECIDE: continue or new session

Before starting the next increment, judge context load:

• Default — continue here if context is light/moderate.
• Recommend a new session if context is heavy: a long session, several increments already done this session, or the harness has summarized context. Then:
  1. Finish/merge the current increment cleanly (don't hand off mid-increment).
  2. Run step A (update docs/STATE.md).
  3. Tell the user: "Context is getting large — I'd start increment NN in a fresh session. docs/STATE.md is the handoff; the new session should read it first."
  4. The user decides. If they continue, proceed; if they open a new session, that session uses §C.

The agent can't read its exact token count, but err toward recommending a fresh session at an increment boundary once the conversation is clearly long — increment boundaries are the clean cut points, and STATE.md makes the handoff lossless.

C. Start of a new session — RESUME

Follow docs/STATE.md §6 (Resume checklist):

1. Read CLAUDE.md + docs/STATE.md + docs/methods/README.md; skim docs/behaviours/ + docs/futures/gotchas.md.
2. git checkout main && git pull; gh pr list (confirm no surprise open PRs).
3. Pick the next increment from STATE.md §4 / the map and run the per-increment loop.

Where memory lives (don't duplicate)

• CLAUDE.md — stable rules / architecture / operating model. (Rarely changes.)
• docs/STATE.md — volatile current state + resume + session log. (Changes every increment.)
• docs/methods/README.md — the increment map / plan (status column).
• docs/methods/NN-*.md — per-increment specs.
• docs/futures/ — deferred decisions (revisit-when), known gotchas, deprecations.
• docs/behaviours/ — how we decide.

STATE.md is the index + pointer + must-know traps, not a copy of the others.