/session-end — Handoff for the next session

Save context before finishing. Receipt first, then three phases: handoff → reflect → docs-reflect.

Memory commands: node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" <command> — the memory dir is resolved from cwd; … dir prints it.

Write the handoff after the last commit of the session (or re-check "What's next" against git log before saving) — a handoff written before the final commit misses it.

Phase 0: Receipt

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" receipt

What the session already left — memory files it wrote, decisions and DOC the watcher logged, commits, the workstreams it moved and whether their cards kept up. Show it first: much of the session is already saved, and the phases below only add what is missing. For a workstream whose card is not updated or missing, offer the card change before the handoff (card <ws> --material, write-card after the user's yes). If the user wants a quick finish, the receipt plus the card offers are enough.

Phase 1: Handoff

1a: Update MEMORY.md

Check what is current:

• Profile — no changes?
• Rules — new agreements?
• Reference — new links?

1b: Routing analysis (preview)

Classify session activity by workstream — preview, not yet written (AP-24).

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" session-activity > /tmp/activity.json
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" session-changes > /tmp/changes.json

# Combine items + file paths + commit subjects into one array for classify
jq -s '[.[0].items[], .[1].commits[], .[1].files[]]' /tmp/activity.json /tmp/changes.json > /tmp/items.json
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" classify --items=/tmp/items.json

Show user a compact routing table:

Routing analysis:
  lifecycle       → 7 items
  infrastructure  → 3 items
  research        → 1 item
  _unassigned     → 2 items

(preview — handoffs per workstream will be written in step 1d)

1c: Propose handoff

MUST show the proposed handoff content to the user and wait for confirmation before writing.

First read the handoff it replaces:

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" handoff

The new one is a snapshot, not a log: "What was done" and "Where we stopped" describe this session only. But carry over the old "What's next" items this session didn't do or drop, and the old "Session decisions" that still hold — otherwise they are lost. Drop the ones the session finished or overturned, and say which in the proposal.

Prepare workstreams/handoff.md content:

---
name: Session handoff
description: Context for starting the next session
type: project
---

## Last session: YYYY-MM-DD

### What was done
- <list>

### Where we stopped
- <current state>

### What's next
1. <task> → recommendation: <model>
2. <task> → recommendation: <model>

### Uncommitted changes
- <git status summary, or "clean tree">

### Session decisions
- <new agreements, if any>

1d: Confirm and write

Show handoff to user. Wait for "ok" / "save" before writing.

On confirm, write in two layers:

1. Per-workstream handoffs — for each non-empty bucket from routing (excl. _unassigned):

   # Compose per-workstream slice (relevant What-was-done / What's-next / decisions).
   # Save to /tmp/<ws>-handoff.md, then:
   node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" write-handoff --workstream=<ws> --content=/tmp/<ws>-handoff.md

2. Global handoff — workstreams/handoff.md (overall summary + cross-refs):

   ### Per-workstream handoffs
   - lifecycle  → workstreams/lifecycle/handoff.md
   - research   → workstreams/research/handoff.md

   Save to /tmp/handoff.md, then:

   node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" write-handoff --global --content=/tmp/handoff.md

   Not the Write tool: write-handoff stamps the date and branch, so the next session start can tell an old or other-branch handoff from a fresh one.

If all items land in _unassigned, skip per-workstream writes and save only the global handoff.

Phase 2: Reflect

Session analysis — run /reflect:

1. Check backlog.md — what's closed, what's new
2. Find workarounds, repetitions, gaps, insights
3. Show to user, wait for confirmation
4. Write to backlog + memory

Phase 3: Docs-reflect

Check DOC: labels from the session:

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" docs

If DOC: labels found — run /docs-reflect:

1. Collect and group DOC: labels
2. Generalize, determine target files
3. Show to user, wait for confirmation
4. Write to .claude/rules/ or docs/

If no DOC: labels — skip, report: "No documentation findings this session."

Phase 4: Report

Session complete:
  ✓ Handoff saved to workstreams/handoff.md
  ✓ Reflect: N items → backlog.md
  ✓ Docs: N rules → .claude/rules/ (or: no DOC: notes)
  
On next start — /session-start will pick up the context.

Rules

• Handoff = concise, 20-30 lines maximum
• Workstream cards (workstreams/<name>.md) are kept current during work. If the session moved a workstream and its card lags, offer the update — write only with the user's yes (write-card)
• Model recommendation — based on the type of the next task
• If there's nothing to save — say so, don't create an empty handoff
• Phases 2 and 3 can be skipped if the user requests a quick finish
• Each phase requires user confirmation before writing