Deterministic Session Summary Compiler Runbook

Deterministic Session Summary Compiler Runbook

MC: #101065
Status: partial implementation, pending independent validation and final closure.

Purpose

Session-end checkpoints must be generated from machine evidence, not John-authored narrative. The compiler creates a checkpoint from git, Mission Control, evidence ledger, cost tracker, claim schemas, and transcript timestamps. John may only add one constrained notes paragraph.

Runtime pieces

• Generator: /Users/makinja/system/tools/session-summary-generator.js
• Stop hook wrapper: /Users/makinja/system/hooks/session-summary-stop-hook.sh
• Claude Stop hook registration: /Users/makinja/.claude/settings.json
• Generated checkpoints: /Users/makinja/.claude/session-checkpoints/
• Hook error log: /Users/makinja/.cache/alai/session-summary-errors.log
• Seeded simulation test: /Users/makinja/system/tests/session-summary-generator-simulation.js

Generator inputs

By default the generator reads:

• transcript timestamps from hook transcript_path, or --session-start <ISO>
• git commits since session start and until session end from valid repos under ~/system, ~/projects, ~/business, ~/clients-external, and ~/personal
• Mission Control SQLite DB: ~/system/databases/mission-control.db
• evidence ledger: ~/system/state/evidence-ledger.jsonl
• cost tracker: node ~/system/tools/cost-tracker.js summary session <session_id> with today-summary fallback only when session summary is unavailable
• claim schemas: /tmp/claim-schema-*.json modified inside the session window

Test overrides are available for deterministic fixtures:

• SESSION_SUMMARY_GIT_ROOTS
• SESSION_SUMMARY_MC_DB
• SESSION_SUMMARY_EVIDENCE_LEDGER
• SESSION_SUMMARY_COST_TRACKER
• SESSION_SUMMARY_CHECKPOINT_DIR
• SESSION_SUMMARY_CLAIM_SCHEMA_DIR

Manual commands

Syntax checks:

node --check /Users/makinja/system/tools/session-summary-generator.js
bash -n /Users/makinja/system/hooks/session-summary-stop-hook.sh
node --check /Users/makinja/system/tests/session-summary-generator-simulation.js

Manual dry-run:

node /Users/makinja/system/tools/session-summary-generator.js \
  --session-start 2026-05-23T13:45:00Z \
  --session-id manual-smoke-101065 \
  --auto-write \
  --output /tmp/alai/session-summary-generator-smoke-101065.md

Seeded simulation:

node /Users/makinja/system/tests/session-summary-generator-simulation.js

Expected seeded simulation evidence:

• output: /tmp/alai/session-summary-generator-seeded-simulation.md
• includes seeded git commit, MC #424242, seeded evidence path, seeded cost output
• excludes pre-session marker PRESESSION_SHOULD_NOT_APPEAR
• rejects bare John note Verified everything
• rejects John notes longer than 200 words

Stop hook behavior

session-summary-stop-hook.sh reads hook JSON on stdin, invokes the generator with --auto-write, logs errors, and always exits 0. Session closing must not be blocked by checkpoint generation failure.

If checkpoint generation fails, inspect:

tail -50 /Users/makinja/.cache/alai/session-summary-errors.log

John Notes rule

John Notes are optional and constrained by the generator:

• one paragraph maximum
• 200 words maximum
• completion/verification language requires an evidence reference such as an MC id, evidence path, sha256, or commit hash

The generated machine sections above ## John Notes are not to be hand-edited.

Closure requirements

Do not mark MC #101065 done until:

1. independent Proveo validation passes or accepted caveats are documented;
2. Stop hook registration is confirmed live;
3. seeded simulation output is retained as evidence;
4. BookStack/runbook publication is confirmed;
5. any remaining liveness-validator integration decision is recorded.