# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.