session-end

name	session-end
description	End session and create all handoff documentation
disable-model-invocation	false
wrought	{"version":"1.0","tools":{"capabilities":["read_file","search_content","find_files","write_file","edit_file","run_command"]},"platforms":{"claude-code":{"allowed-tools":"Read, Grep, Glob, Write, Edit, Bash","disable-model-invocation":false}},"agent":{"role":"Session Manager","expertise":["handoff documentation","session summarization"],"non_goals":["implementation","investigation"]},"execution":{"default_mode":"react","stop_conditions":["Handoff document written","CLAUDE.md updated with handoff reference","User instructed to stop"]},"output":{"format":"markdown","template":"NEXT_SESSION_PROMPT_{YYYY-MM-DD_HHMM}.md","required_sections":["What Was Done","Current Status","Next Priorities"]},"pipeline":{"track":"standalone","standalone":true,"prerequisites":[],"produces":["NEXT_SESSION_PROMPT_*.md"]}}

Session is ending. Please complete all session end tasks:

1. Save active plan file (if exists):

   • Check ~/.claude/plans/ for recent plan files (modified today)
   • If found, copy to ~/docs/plans/PLAN_{datetime}_{original_name}.md
   • This preserves implementation plans between sessions

2. Create new handoff document:

   • Get current date/time: date '+%Y-%m-%d_%H%M'
   • Create file: NEXT_SESSION_PROMPT_{datetime}.md
   • Include updated "START HERE" section
   • Update status: what was completed this session
   • Update priorities: what's next
   • Include any new insights or decisions
   • Reference any active plan file (from step 1)

3. Create session summary:

   • Create file: SESSION_SUMMARY_{datetime}.md
   • Document what was accomplished
   • List issues encountered
   • Record decisions made
   • Include metrics and statistics
   • Reference plan file if applicable

4. Update CLAUDE.md (pointer only — NEVER stack narrative):

   • Replace the filename between <!-- SESSION_HANDOFF_START --> and <!-- SESSION_HANDOFF_END --> with the NEW handoff filename. No @ prefix — an @ import is transitively auto-loaded, which re-inflates every session and every subagent spawn with the whole handoff.
   • Update the **Last Updated** timestamp
   • Replace the single **Last Session** line with a one-line summary of THIS session
   • NEVER append or stack an additional **Last Session** / **S1NN** entry. The full narrative belongs in NEXT_SESSION_PROMPT_*.md; superseded handoffs are archived to docs/archive/sessions/ at step 5. Stacking them is what grew CLAUDE.md to 96 KB (S137); tests/test_context_budget.py now fails the build if it recurs.

5. Archive old handoff:

   • Move old NEXT_SESSION_PROMPT_*.md to docs/archive/sessions/
   • Keep only the NEW handoff in root directory 6a. Review finding disposition check (BEFORE tracker updates):
   • Scan ALL docs/findings/*_FINDINGS_TRACKER.md files (not just those related to this session's work)
   • Check for any finding where the Type column contains "Review Warning" AND the Status column is "Open" AND the row does NOT carry [round 2+ — non-blocking]
   • Do NOT gate on "Review Suggestion" — Suggestions accrue across sessions by design (rule 9). Count them, never block on them
   • Do NOT gate on a row carrying [round 2+ — non-blocking] — rule 9's in-session obligation applies to the first /forge-review of a session's substantive diff, and Step 8 of /forge-review stamps that marker onto every Warning it raises at round 2+. Count them, report them, never block on them. A Warning whose row LACKS the marker is treated as round 1 and does gate: the marker is the only record of round that survives to this step, so its absence must fail closed
   • If unresolved round-1 Review Warnings are found:

     UNRESOLVED REVIEW WARNINGS DETECTED:
     {tracker_name}: F{N} — {title} (Status: Open)
     
     These MUST be resolved before session end:
     - Warnings → /rca-bugfix or direct fix, or reject with rationale ("Resolved: Rejected — {reason}")
     
     Resolve these findings now, then re-run /session-end.
     

   • STOP — do NOT proceed with session-end documentation until every round-1 Review Warning is Resolved or explicitly rejected with rationale. This STOP belongs to the unresolved-Warning branch above and to nothing else: it does not run when that branch printed nothing, and a permitted [round 2+ — non-blocking] Warning neither satisfies it nor trips it. Without that stated extent the STOP becomes permanently unsatisfiable the first time a permitted Warning is left Open, and /session-end can never run again
   • If no unresolved round-1 Review Warnings found: report both queues, then proceed to Step 6:

     Suggestion queue: {N} open (non-blocking — see rule 9).
     Permitted round-2+ Warnings: {N} open (non-blocking — marked `[round 2+ — non-blocking]`).
     

     These lines are a report, never a gate: no persistence, no comparison against a prior session's count, no STOP (CST-016). Print them and continue to Step 6.

6. Update Findings Trackers (if applicable):

   • Each group of related findings has its own named tracker: docs/findings/{datetime}_{name}_FINDINGS_TRACKER.md
   • Check ALL docs/findings/*_FINDINGS_TRACKER.md files for trackers related to this session's work
   • For each tracker that had findings-related work done this session (fixes, investigations, designs, or verification of FN tasks):
     • Update the checkbox status of any resolved tasks (e.g., - [x] **F1.1**: ...)
     • Update the finding's Status field (Open → In Progress → Resolved → Verified)
     • Update the finding's Stage field to reflect the current pipeline position
     • Update Resolved in session / Verified in session fields with the session number
     • Add a row to the Changelog table with the date, session number, and what changed
     • Update the Last Updated timestamp at the top of the file

   Stage reconciliation — Check if artifacts exist that the tracker doesn't yet reflect:

   • Investigation report exists in docs/investigations/ matching finding → Stage should be ≥ Investigating
   • RCA exists in docs/RCAs/ matching finding → Stage should be ≥ RCA Complete
   • Design analysis exists in docs/design/ matching finding → Stage should be ≥ Designing
   • Blueprint exists in docs/blueprints/ matching finding → Stage should be ≥ Blueprint Ready
   • Plan exists in docs/plans/ matching finding → Stage should be ≥ Planned
   • Code changes committed for finding → Stage should be Resolved If a stage was missed (artifact exists but no lifecycle row), backfill the lifecycle row with approximate timestamp.

   GitHub Projects sync (NON-FATAL) — For each finding whose stage changed this session, read docs/reference/github_projects_sync_protocol.md and follow Protocol B to update the board. Key mappings:

   • Implementing → Lifecycle Stage = Implementing (9afc76db), Status = In Progress ()

IMPORTANT:

• Save plan file FIRST (step 1)
• Create new files NEXT (steps 2-3)
• THEN update CLAUDE.md to point to them (step 4)
• This ensures CLAUDE.md never points to non-existent files

After completing all tasks, provide a summary showing:

• New handoff filename
• New summary filename
• CLAUDE.md updated (show the new handoff pointer between the SESSION_HANDOFF markers)
• Old handoff archived location
• Findings Tracker(s) updated (if applicable — show which tracker(s), which tasks/findings changed)