Session Start

Session Start

Dominant Variable

Does the handoff document what to do next, or what was done? If it lists completed work, the handoff was written incorrectly. If Priority 1 cannot be identified immediately, deepen your inspection of Phase 1.

Trigger

• /session-start
• "start session"
• "continue from where"
• "where did we get"
• (Korean language triggers handled in YAML frontmatter above)

Discard If

• memory/session-handoff-LATEST.md missing (first session) → skip the handoff Phase only; the remaining Phases still run (Invariant 2)
• User requests "start fresh" / "ignore context" → skip
• Project-unrelated standalone question → skip

Phase 0.5 runs even on discard: configuration errors must be detected in first session and standalone questions too.

---

Key Assumptions

1. memory/session-handoff-LATEST.md exists — if broken: fallback to "new session" mode. Do not synthesize handoff.
2. tasks/lessons.md exists — if broken: skip lesson review Phase.
3. settings.json parseable — if broken: skip health-check Phase only; proceed normally with rest.
4. scripts/harness_observability.py runs under the available Python interpreter — if broken: Phase 2.2/2.4 fall back to their own tool_failure handling (see those sections) rather than blocking session start.

Phase 0.5: Environment Health Check

Warnings only — no blocking. Use Read tool only (no modifications).

Check 1 — Model ID (read ~/.claude/settings.json):

• Confirm "model" field value → warn if outside this list:

  ["opus", "sonnet", "haiku", "fable",
   "claude-sonnet-5", "claude-opus-4-8", "claude-opus-4-7", "claude-sonnet-4-6",
   "claude-haiku-4-5", "claude-opus-4-5", "claude-sonnet-4-5", "claude-fable-5"]
  # Context suffixes like [1m]/[200k] are stripped before comparison (e.g., claude-fable-5[1m] → claude-fable-5)

• Message: ⚠️ settings.json model ID invalid: "{value}" — please update
• If file missing: skip silently

Check 2 — Accumulated Allow Entries (read ~/.claude/settings.local.json):

• Count permissions.allow array items
• If count > 5 → ⚠️ settings.local.json allow: N entries
• If file missing: skip silently

Note — session-scoped authorization does not carry over: one-time approvals for risky actions, temporarily-enabled high-risk feature flags, and other session-scoped permissions granted in a previous session are not restored automatically in a new session. If the handoff notes something as "approved" or "enabled," treat that as historical context only — ask the user to re-confirm before relying on it this session.

Output rule: Both clean → no output (omit environment-alerts line in Phase 5). If warnings present, display in Phase 5 **Environment alerts:** line.

---

Phase 1: Load Handoff

Read memory/session-handoff-LATEST.md (auto-injected above).

Step 0 — state-snapshot fast path: if the file has a <!-- state-snapshot v1 --> YAML block (fields: ts/ctx/next/diff/blocked) right after the frontmatter, parse that first — this is exactly the compact block session-checkpoint's Phase 2.3 (Memento CoT Compression) produces for this consumption; the two phases are a paired contract, not independent features.

• next → Priority 1 / Priority 2
• blocked → Outstanding/active blockers
• ctx → one-line session context, used only to decide which prose sections below still need a full read
• diff → one-line summary of the most recent changes (surfaced in Phase 5 as "Recent changes")

Only selectively read the prose sections below for items that need more detail than the compact block gives. If the block is absent (older-style handoff), fall back to the full prose extraction below as before.

Extract:

• Priority 1 — most urgent task for this session
• Outstanding decisions — questions awaiting user input
• Remaining issues — unresolved bugs or blockers
• Context notes — failed approaches from previous session (prevent repetition), critical causal links

If file empty or missing: output [No handoff — starting fresh], skip this Phase only, and continue with the remaining Phases (Invariant 2).

---

Phase 2: Review Lessons

Read tasks/lessons.md.

2.0 Load Graduated Gates (always-on — highest priority)

Extract the ## Graduated Gates (Graduated Gates) table section. Output it regardless of conf filter — these are verified gates (conf≥0.7 AND obs≥3), so always-on exposure is intentional (Loop B self-correction enforcement layer). In Phase 5 **Graduated gates:** line, compress each gate as trigger → check on one line.

Nature (user-specified, 2026-06-04): Gates are "expose → consult → decide" tools. Pause before the triggering action, check, and consult if unclear. Not automatic execution; not auto-generated. Their role is to surface decisions left to the user and conversation.

Skip section if missing.

2.1 Scan Related Lessons

Scan correction rules relevant to today's planned work:

• Code changes expected → check that domain's correction rules
• Commit/push planned → check commit-related rules
• Debugging planned → check debugging anti-patterns

v2 metadata line usage (> conf · seen · obs, from 2026-04-28~):

• conf ≥ 0.7 (verified/core) → one-line summary from body (priority exposure/signal)
• conf 0.5 (normal/Opus-triggered) → title only on one line
• conf < 0.5 (experimental/unresolved) → header title only or skip (noise control)
• seen within 30 days + obs ≥ 3 = active pattern — priority exposure
• v2 metadata absent = legacy lesson, treat normally (backward compat)

Flag one line per matching rule. Skip silently if file missing.

2.2 Model Difference Analysis Reminder (semi-automatic — deterministic check)

Trigger for converting accumulated model-tagged behavior observations into rules. Periodic reminder to digest model tag backlog into patterns → rules.

Deterministic commands (run in order — each is a single command, no manual scanning):

1. grep -c "model:" tasks/lessons.md → lessons_tagged (0 if file missing)
2. python "scripts/harness_observability.py" model-tag-count → parse count=N from stdout → jsonl_tagged (the script returns count=0 on its own when ~/.claude/.harness/interventions/ is missing or empty — no separate existence check needed). Replaces a per-file grep -c '"model"' sum with one deterministic script call.
3. grep "^last-analysis:" ~/.claude/memory/model-diff-ledger.md → baseline_date (if the header or file is absent, fall back to the earliest seen:/date: value found in the two counts above)
4. Count seen:/date: values dated after baseline_date across the same two sources → new_tags

Fixed stdout format: model_tags: total=N new=M days_elapsed=D (N = lessons_tagged + jsonl_tagged; D = today − baseline_date; if baseline_date cannot be established, days_elapsed=N/A)

If step 2's script invocation itself fails to run (interpreter missing, script not found): treat as tool_failure — fall back to jsonl_tagged=0 with a one-line ⚠️ harness_observability.py unavailable — model-tag count may undercount note, do not block the rest of this phase or session start.

Remind condition (both must be true):

• days_elapsed ≥ 14 AND new_tags ≥ 5
• → In Phase 5 **Model analysis:** line, output: 💡 Model-difference analysis recommended (new=M / days_elapsed=D) — call "model analysis" to aggregate + promotion candidates
• If unmet (elapsed too short OR tag count too low) → no output (prevent premature analysis, avoid noise)

Skip entirely if both source files/directories are missing. If total=0, Phase 2.2 produces no output (no model tags recorded yet — normal).

---

2.3 Context Rot Prevention

When loading handoff + lessons, apply a sliding window to prevent stale context from crowding out recent work:

• Recent 5 sessions: load full handoff content
• Older entries: 1-line summary only (title + date + outcome)
• context-log.md: entries older than 90 days with ref:0 → skip (no one referenced them)

Age source — record timestamp, never file mtime: context-log.md is append-only (never overwritten — see Dev Conventions), so the file's filesystem mtime only reflects the most recent append and cannot stand in for any individual entry's own date. Always read age from that entry's own [DATE] tag (the [DATE][TYPE][ttl:Nd][ref:0] prefix on its ## header, per memory-format.md convention) — never from stat/Get-ChildItem on the file itself.

Deterministic commands:

1. grep -c "^## " memory/context-log.md → total_entries (0 if file missing)
2. grep -c "\[ref:0\]" memory/context-log.md → ref0_entries (skip candidates; grep alone cannot test the 90-day age cutoff, so confirm age only on entries actually surfaced, not the whole file — read each surfaced entry's own [DATE] tag for that check, not the file's mtime)
3. skipped = ref0_entries that also pass the 90-day age check (age computed from each entry's [DATE] tag, not file mtime)

Fixed stdout format: context_rot: total=N skipped=M rate=X% (X = M/N × 100, 1 decimal; rate=N/A if total_entries=0)

This prevents the "memory keeps growing but quality keeps dropping" pattern where old context dilutes recent priorities.

2.4 Autoimmunity Rate

The rate at which harness gates (verification/pre-push/goal-lock) incorrectly block normal behavior — a false positive: the gate fired but the blocked action was actually fine. Excessive false positives are a signal that the harness itself is a net negative (the harness paradox).

Rejection ≠ false positive. The interventions log only records that a gate declined/blocked something (type == "rejection"); it does not record why. A correct block (the gate did its job) and a genuine false positive (the gate wrongly flagged legitimate behavior) both produce the same rejection event. Counting every rejection as autoimmunity conflates "user declined because the recommendation didn't fit" (e.g., priority mismatch, unrelated to the gate being wrong) with "user declined because the gate was actually mistaken." Only the latter — an explicit false-positive label — belongs in the numerator; a plain rejection alone does not.

Deterministic command:

1. python "scripts/harness_observability.py" rejection-rate --period 30d → parse rejections=N total=M rate=X% from stdout (the script itself scans ~/.claude/.harness/interventions/*.jsonl, returns total=0 when the directory is missing/empty, and already computes rate=N/A on a zero denominator). Replaces a find + two summed grep -c passes with one deterministic script call.

No current intervention producer writes an explicit false-positive label (e.g. a false_positive: true field, distinct from type == "rejection") — so this command's rejection=N is a rejection-rate proxy, not a verified false-positive rate. Do not synthesize a label from context/l0_clause text ex post; report the number honestly as a proxy until a producer starts recording the distinction. If a future record does carry such a label, restrict the numerator to labeled records only and drop the proxy caveat.

Fixed contract (same stdout parsing as before — labeling is a reporting-layer distinction, not a new script output field): autoimmunity: rejection=N total=M rate=X% (proxy)

If the script invocation itself fails to run (interpreter missing, script not found): treat as tool_failure — skip this phase's output silently, do not block session start.

Output conditions:

• interventions directory missing or total=0 → no output
• rate ≤ 5% → no output (normal range)
• rate > 5% → Phase 5 **Immune rate:** line: ⚠️ Autoimmunity rate X% (rejection N/total M, proxy — not a confirmed false-positive rate) — review gate over-intervention
• rate > 15% → 🚨 Autoimmunity rate X% (proxy) — recommend gate reduction or redesign

---