create-ccc-tutor 0.1.0

package/template/.harness/scripts/format-edit.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Post-edit format hook — runs the project's formatter on the file just edited.
+#
+# Called from .claude/settings.json + .codex/hooks.json on Edit|Write tool use.
+# Picks the formatter by file extension; silently skips unknown extensions.
+
+set -euo pipefail
+
+# Ensure brew-installed tools (jq, etc.) are on PATH even in non-interactive
+# shells where ~/.zprofile isn't loaded. macOS Apple Silicon path comes first.
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+# Edited file path is passed as $1 or via $CLAUDE_FILE_PATHS / stdin JSON
+FILE="${1:-}"
+if [ -z "$FILE" ]; then
+  # Try to extract from Claude Code's tool input JSON on stdin
+  if [ -t 0 ]; then
+    exit 0  # no stdin, no arg → nothing to format
+  fi
+  FILE=$(jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+fi
+
+if [ -z "$FILE" ] || [ ! -f "$FILE" ]; then
+  exit 0
+fi
+
+# ─────────────────────────────────────────────────────────────────────
+# CUSTOMIZE: per-extension formatter
+# ─────────────────────────────────────────────────────────────────────
+# Add / remove cases as your stack requires.
+# Failures here are silent (|| true) — formatter issues should not block edits.
+# ─────────────────────────────────────────────────────────────────────
+
+case "$FILE" in
+  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs|*.json|*.jsonc|*.md|*.mdx|*.html|*.css|*.scss|*.yaml|*.yml)
+    if command -v prettier >/dev/null 2>&1; then
+      prettier --write "$FILE" >/dev/null 2>&1 || true
+    elif command -v npx >/dev/null 2>&1; then
+      npx --no-install prettier --write "$FILE" >/dev/null 2>&1 || true
+    fi
+    ;;
+
+  *.py)
+    if command -v black >/dev/null 2>&1; then
+      black "$FILE" >/dev/null 2>&1 || true
+    elif command -v ruff >/dev/null 2>&1; then
+      ruff format "$FILE" >/dev/null 2>&1 || true
+    fi
+    ;;
+
+  *.go)
+    if command -v gofmt >/dev/null 2>&1; then
+      gofmt -w "$FILE" >/dev/null 2>&1 || true
+    fi
+    ;;
+
+  *.rs)
+    if command -v rustfmt >/dev/null 2>&1; then
+      rustfmt "$FILE" >/dev/null 2>&1 || true
+    fi
+    ;;
+
+  *.swift)
+    if command -v swift-format >/dev/null 2>&1; then
+      swift-format -i "$FILE" >/dev/null 2>&1 || true
+    fi
+    ;;
+
+  *.kt|*.kts)
+    if command -v ktlint >/dev/null 2>&1; then
+      ktlint -F "$FILE" >/dev/null 2>&1 || true
+    fi
+    ;;
+
+  *)
+    # No formatter configured for this extension. Silent.
+    ;;
+esac
+
+exit 0

package/template/.harness/scripts/lint-bans.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# Pre-commit lint bans — scans staged changes for project-specific anti-patterns.
+#
+# This script enforces FORBIDDEN patterns, not the inverse anti-flag rules.
+# Anti-flag rules in AGENTS.md say "X is correct, Y is BANNED — don't suggest Y."
+# This script greps for Y in the diff and blocks if found.
+#
+# Constitution § 1 — anti-flag rules are part of the harness's signal-quality
+# guarantee. Mechanical enforcement prevents banned patterns from leaking in.
+
+set -euo pipefail
+
+# Ensure brew-installed tools (jq, etc.) are on PATH even in non-interactive
+# shells where ~/.zprofile isn't loaded. macOS Apple Silicon path comes first.
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+# Filter: only fire on `git commit` invocations. The PreToolUse hook contract
+# passes the tool call payload via stdin; we parse it and silently exit if
+# the Bash command isn't a git commit.
+#
+# (We do this filtering here instead of relying on settings.json's `if`
+# clause because that clause was found NOT to be honored consistently —
+# see harness-testing-2026-05-25.md § P0.Z.)
+
+# Read stdin (Claude Code passes JSON with tool_input.command for Bash hooks)
+HOOK_INPUT="$(cat 2>/dev/null || true)"
+if [ -n "$HOOK_INPUT" ]; then
+  # Try to extract the Bash command. If jq is available, use it. Otherwise
+  # fall back to grep (best-effort).
+  if command -v jq >/dev/null 2>&1; then
+    BASH_CMD="$(printf '%s' "$HOOK_INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || echo "")"
+  else
+    # Best-effort fallback: extract "command":"..." substring via grep
+    BASH_CMD="$(printf '%s' "$HOOK_INPUT" | grep -oE '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*"command"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/' || echo "")"
+  fi
+  # Silent exit unless this is a git commit invocation
+  case "$BASH_CMD" in
+    git\ commit*|*\ git\ commit*)
+      # proceed
+      ;;
+    *)
+      exit 0
+      ;;
+  esac
+fi
+
+# === Original hook logic continues below ===
+
+# ─────────────────────────────────────────────────────────────────────
+# CUSTOMIZE: list of banned patterns (one regex per entry)
+# ─────────────────────────────────────────────────────────────────────
+# Each pattern is matched line-by-line on staged diff additions (lines starting
+# with `+`). Edit this list to mirror AGENTS.md § "Anti-flag rules" inverses.
+#
+# Examples (delete what doesn't apply, add what does):
+#
+# React Native projects:
+#   PATTERNS+=('TouchableOpacity|TouchableHighlight|TouchableNativeFeedback')
+#   PATTERNS+=('from .react-native. import .*KeyboardAvoidingView')
+#   PATTERNS+=('StyleSheet\.create')
+#   PATTERNS+=('forwardRef\(')
+#
+# Postgres/Supabase projects:
+#   PATTERNS+=('\.select\(.\*.\)')
+#   PATTERNS+=("import.*from\s+['\"]@supabase/auth-helpers")  # if deprecated
+#
+# Python projects:
+#   PATTERNS+=('print\(')   # if logging-only is the rule
+#
+# Generic:
+#   PATTERNS+=('console\.log\(')  # if console.log banned outside dev
+#   PATTERNS+=('debugger;')
+#   PATTERNS+=('@ts-ignore')      # if @ts-expect-error is preferred
+# ─────────────────────────────────────────────────────────────────────
+
+PATTERNS=()
+
+# ─────────────────────────────────────────────────────────────────────
+# Run
+# ─────────────────────────────────────────────────────────────────────
+if [ ${#PATTERNS[@]} -eq 0 ]; then
+  # No patterns configured — skip silently. /init may pre-fill these based on stack.
+  exit 0
+fi
+
+# Get added lines from staged diff
+ADDED_LINES=$(git diff --cached --unified=0 --no-color | grep -E '^\+[^+]' || true)
+
+if [ -z "$ADDED_LINES" ]; then
+  exit 0
+fi
+
+FOUND=0
+for pattern in "${PATTERNS[@]}"; do
+  matches=$(echo "$ADDED_LINES" | grep -E "$pattern" || true)
+  if [ -n "$matches" ]; then
+    echo "❌ Banned pattern found: $pattern"
+    echo "$matches" | sed 's/^/    /'
+    echo ""
+    FOUND=1
+  fi
+done
+
+if [ "$FOUND" -eq 1 ]; then
+  echo "Commit blocked. See AGENTS.md § Anti-flag rules for context."
+  echo "If this is a deliberate exception, edit .harness/scripts/lint-bans.sh"
+  echo "and document the change in your commit body."
+fi
+
+exit "$FOUND"

package/template/.harness/scripts/memory-archive.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# memory-archive.sh — Tier 2 → Tier 3 migration (v2 context architecture).
+#
+# Scans .harness/memory/sessions/recall/*.jsonl. Entries with `ts` older than
+# CCC_ARCHIVE_AGE_DAYS (default 30) are moved to
+# .harness/memory/sessions/archive/<YYYY-MM>.jsonl (by entry's original month).
+#
+# CONTRACT (Claude Code hook spec):
+#   stdin:  JSON (drained, not parsed)
+#   stdout: hookSpecificOutput JSON (silent if nothing archived)
+#   exit 0: always
+#
+# IDEMPOTENT: safe to run on every SessionStart. Skips silently if nothing
+# qualifies for archival.
+#
+# Also assigns `id` to any entries lacking one (back-fill for v1 → v2
+# migration). ID format: <KIND_PREFIX>-<YYYYMMDDNNN> where NNN is a 3-digit
+# sequence number within the day.
+#
+# bash 3.2 compatible.
+
+set -eu
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+RECALL_DIR="$PROJECT_DIR/.harness/memory/sessions/recall"
+ARCHIVE_DIR="$PROJECT_DIR/.harness/memory/sessions/archive"
+AGE_DAYS="${CCC_ARCHIVE_AGE_DAYS:-30}"
+
+# Drain stdin
+cat >/dev/null 2>&1 || true
+
+# Required dirs
+[ -d "$RECALL_DIR" ] || exit 0
+mkdir -p "$ARCHIVE_DIR" 2>/dev/null || true
+
+# jq required
+if ! command -v jq >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Compute cutoff timestamp (UTC ISO 8601)
+CUTOFF=""
+if date -u -v-${AGE_DAYS}d +%Y-%m-%dT%H:%M:%SZ >/dev/null 2>&1; then
+  CUTOFF=$(date -u -v-${AGE_DAYS}d +%Y-%m-%dT%H:%M:%SZ)
+else
+  CUTOFF=$(date -u -d "${AGE_DAYS} days ago" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "")
+fi
+[ -n "$CUTOFF" ] || exit 0
+
+ARCHIVED_COUNT=0
+RETAINED_COUNT=0
+
+# Process each recall file
+for RECALL_FILE in "$RECALL_DIR"/*.jsonl; do
+  [ -f "$RECALL_FILE" ] || continue
+  [ -s "$RECALL_FILE" ] || continue
+
+  TMP_RETAIN=$(mktemp /tmp/memory-archive.retain.XXXXXX)
+  trap 'rm -f "$TMP_RETAIN" 2>/dev/null || true' EXIT
+
+  # Read each line, classify retain vs archive
+  while IFS= read -r line || [ -n "$line" ]; do
+    [ -z "$line" ] && continue
+    if ! echo "$line" | jq empty >/dev/null 2>&1; then
+      # malformed: retain so user can fix
+      echo "$line" >> "$TMP_RETAIN"
+      RETAINED_COUNT=$((RETAINED_COUNT + 1))
+      continue
+    fi
+
+    entry_ts=$(echo "$line" | jq -r '.ts // ""')
+
+    # Back-fill id if missing
+    has_id=$(echo "$line" | jq -r 'has("id")')
+    if [ "$has_id" = "false" ]; then
+      kind=$(echo "$line" | jq -r '.kind // "observation"')
+      case "$kind" in
+        session-snapshot) prefix="SS" ;;
+        decision)         prefix="DEC" ;;
+        failure)          prefix="FAIL" ;;
+        *)                prefix="OBS" ;;
+      esac
+      # Date part from ts (YYYYMMDD) + a content-hash-derived suffix
+      date_part=$(echo "$entry_ts" | cut -c1-10 | tr -d '-')
+      [ -z "$date_part" ] && date_part="00000000"
+      hash_suffix=$(echo "$line" | shasum 2>/dev/null | cut -c1-3 || echo "001")
+      new_id="${prefix}-${date_part}${hash_suffix}"
+      line=$(echo "$line" | jq -c --arg id "$new_id" '.id = $id')
+    fi
+
+    # Compare ts to cutoff (ISO 8601 UTC string-compare works)
+    if [ -n "$entry_ts" ] && [ "$entry_ts" \< "$CUTOFF" ]; then
+      # Archive — destination by year-month of entry
+      year_month=$(echo "$entry_ts" | cut -c1-7)
+      [ -z "$year_month" ] && year_month="undated"
+      ARCHIVE_FILE="$ARCHIVE_DIR/${year_month}.jsonl"
+      echo "$line" >> "$ARCHIVE_FILE"
+      ARCHIVED_COUNT=$((ARCHIVED_COUNT + 1))
+    else
+      echo "$line" >> "$TMP_RETAIN"
+      RETAINED_COUNT=$((RETAINED_COUNT + 1))
+    fi
+  done < "$RECALL_FILE"
+
+  # Replace recall file with retained content (atomic)
+  if [ -s "$TMP_RETAIN" ]; then
+    mv "$TMP_RETAIN" "$RECALL_FILE"
+  else
+    : > "$RECALL_FILE"
+    rm -f "$TMP_RETAIN" 2>/dev/null || true
+  fi
+done
+
+# If anything was archived, emit additionalContext so the AI knows
+if [ "$ARCHIVED_COUNT" -gt 0 ]; then
+  jq -n \
+    --arg n "$ARCHIVED_COUNT" \
+    --arg r "$RETAINED_COUNT" \
+    --arg age "$AGE_DAYS" \
+    '{
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: ("📦 Memory layer maintenance: archived " + $n + " entries older than " + $age + " days. " + $r + " entries remain in recall. Use /recall --deep <query> to search archived entries.")
+      }
+    }'
+fi
+
+exit 0

package/template/.harness/scripts/memory-recall.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# memory-recall.sh — SessionStart hook for CCC-MAGI v2 (manifest mode).
+#
+# v2 CHANGE: instead of injecting full entry bodies (~2-3KB), inject ONLY a
+# manifest of one-line index entries (~80 tokens each) for the AI to scan. If
+# the AI decides a body is relevant per CLAUDE.md § Memory Calling Rules, it
+# fetches the body explicitly via the /recall <id> skill.
+#
+# This cuts SessionStart token cost by ~70% on average and prevents "context
+# distraction" (Drew Breunig) from eager injection.
+#
+# SCANS:
+#   .harness/memory/sessions/recall/observations.jsonl
+#   .harness/memory/sessions/recall/snapshots.jsonl
+# IGNORES (Tier 3):
+#   .harness/memory/sessions/archive/  (use /recall --deep instead)
+#
+# OUTPUT FORMAT (one line per entry):
+#   [<id>] feature=<f> kind=<k> date=<YYYY-MM-DD> focus="<≤80 chars>"
+#
+# RANKING:
+#   - Snapshots always sort BEFORE observations (higher signal density).
+#   - Within each, feature-match (+5) and recency (+1 if <7d) score apply.
+#   - Cap: top 12 entries OR ~1000 tokens of manifest, whichever first.
+#
+# bash 3.2 compatible.
+
+set -eu
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+RECALL_DIR="$PROJECT_DIR/.harness/memory/sessions/recall"
+OBS_FILE="$RECALL_DIR/observations.jsonl"
+SNAP_FILE="$RECALL_DIR/snapshots.jsonl"
+
+# Drain stdin
+cat >/dev/null 2>&1 || true
+
+# Bail if neither file exists with content
+if [ ! -s "$OBS_FILE" ] && [ ! -s "$SNAP_FILE" ]; then
+  exit 0
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Derive current feature from git branch
+BRANCH=""
+if command -v git >/dev/null 2>&1; then
+  BRANCH=$(cd "$PROJECT_DIR" 2>/dev/null && git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+fi
+
+FEATURE=""
+if [ -n "$BRANCH" ]; then
+  case "$BRANCH" in
+    feat/*|fix/*)
+      rest="${BRANCH#*/}"
+      case "$rest" in
+        *-*) FEATURE="${rest%%-*}" ;;
+        *)   FEATURE="$rest" ;;
+      esac
+      ;;
+    */*)
+      FEATURE="${BRANCH%%/*}"
+      ;;
+  esac
+fi
+
+# 7-day cutoff
+CUTOFF=""
+if date -u -v-7d +%Y-%m-%dT%H:%M:%SZ >/dev/null 2>&1; then
+  CUTOFF=$(date -u -v-7d +%Y-%m-%dT%H:%M:%SZ)
+else
+  CUTOFF=$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "")
+fi
+
+# Score one file's entries. Args: <file> <source_kind:snap|obs>
+# Output to stdout: "<score>\t<ts>\t<id>\t<kind>\t<feature>\t<focus_or_summary>"
+score_file() {
+  local file="$1"
+  local source_kind="$2"
+  [ -s "$file" ] || return 0
+  while IFS= read -r line || [ -n "$line" ]; do
+    [ -z "$line" ] && continue
+    if ! echo "$line" | jq empty >/dev/null 2>&1; then
+      continue
+    fi
+
+    local entry_id entry_ts entry_feature entry_kind entry_focus
+    entry_id=$(echo "$line" | jq -r '.id // ""')
+    entry_ts=$(echo "$line" | jq -r '.ts // ""')
+    entry_feature=$(echo "$line" | jq -r '.feature // ""')
+    entry_kind=$(echo "$line" | jq -r '.kind // "observation"')
+    # focus comes from .focus (snapshot) or .summary (observation)
+    entry_focus=$(echo "$line" | jq -r '.focus // .summary // ""')
+    # Truncate focus to 80 chars
+    if [ "${#entry_focus}" -gt 80 ]; then
+      entry_focus="${entry_focus:0:77}..."
+    fi
+    # Strip tabs and newlines from focus (output field separator safety)
+    entry_focus=$(printf '%s' "$entry_focus" | tr '\t\n' '  ')
+
+    [ -n "$entry_id" ] || continue  # skip entries without id (v1 entries get id'd by memory-archive.sh)
+
+    local score=0
+    # Snapshot kind bonus
+    if [ "$source_kind" = "snap" ]; then
+      score=$((score + 10))
+    fi
+    # Feature match
+    if [ -n "$FEATURE" ] && [ "$entry_feature" = "$FEATURE" ]; then
+      score=$((score + 5))
+    fi
+    # Recency
+    if [ -n "$CUTOFF" ] && [ -n "$entry_ts" ]; then
+      if [ "$entry_ts" \> "$CUTOFF" ] || [ "$entry_ts" = "$CUTOFF" ]; then
+        score=$((score + 1))
+      fi
+    fi
+
+    printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$score" "$entry_ts" "$entry_id" "$entry_kind" "${entry_feature:-general}" "$entry_focus"
+  done < "$file"
+}
+
+SCORED=$(mktemp /tmp/memory-recall.XXXXXX)
+trap 'rm -f "$SCORED" "$SCORED.sorted" 2>/dev/null || true' EXIT
+
+# Score snapshots and observations
+score_file "$SNAP_FILE" "snap" >> "$SCORED"
+score_file "$OBS_FILE" "obs" >> "$SCORED"
+
+if [ ! -s "$SCORED" ]; then
+  exit 0
+fi
+
+# Sort by score DESC, then ts DESC
+sort -t "$(printf '\t')" -k1,1nr -k2,2r "$SCORED" > "$SCORED.sorted"
+
+# Build manifest. Cap: 12 entries OR ~1000 tokens (~4000 chars)
+MAX_ENTRIES=12
+MAX_CHARS=4000
+
+HEADER="## Recent project memory — index (v2)
+
+Below is the **manifest** of recent recall-tier entries. Each line is one entry's index, NOT its body. The full body is fetched on demand via the \`/recall <id>\` skill.
+
+**When to fetch a body (per CLAUDE.md § Memory Calling Rules)**:
+- User explicitly references prior context (\"上次 / 之前 / before / previously / we decided\")
+- Current task's feature exactly matches an entry's feature
+- An entry's focus indicates a prior decision relevant to your upcoming action
+
+**Hard caps**: ≤ 3 body fetches per session. Do NOT fetch \"for completeness\".
+
+For older entries (>30d), use \`/recall --deep <query>\` (archive tier, ≤ 1 per session).
+
+---
+
+"
+
+BODY=""
+count=0
+total_chars=${#HEADER}
+
+while IFS= read -r entry_line || [ -n "$entry_line" ]; do
+  [ "$count" -ge "$MAX_ENTRIES" ] && break
+
+  # Parse: score \t ts \t id \t kind \t feature \t focus
+  entry_id=$(printf '%s' "$entry_line" | cut -f3)
+  entry_kind=$(printf '%s' "$entry_line" | cut -f4)
+  entry_feature=$(printf '%s' "$entry_line" | cut -f5)
+  entry_focus=$(printf '%s' "$entry_line" | cut -f6-)
+  entry_date=$(printf '%s' "$entry_line" | cut -f2 | cut -c1-10)
+
+  manifest_line="[$entry_id] feature=$entry_feature kind=$entry_kind date=$entry_date focus=\"$entry_focus\""$'\n'
+
+  new_chars=$((total_chars + ${#manifest_line}))
+  if [ "$new_chars" -gt "$MAX_CHARS" ] && [ "$count" -gt 0 ]; then
+    break
+  fi
+
+  BODY="$BODY$manifest_line"
+  total_chars=$new_chars
+  count=$((count + 1))
+done < "$SCORED.sorted"
+
+if [ "$count" -eq 0 ]; then
+  exit 0
+fi
+
+FULL="$HEADER$BODY"
+printf '%s' "$FULL" | jq -Rs '{
+  hookSpecificOutput: {
+    hookEventName: "SessionStart",
+    additionalContext: .
+  }
+}'

package/template/.harness/scripts/memory-snapshot.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# memory-snapshot.sh — PreCompaction hook (v2: deterministic harvest).
+#
+# v1 (DEPRECATED): asked Claude to write 3 summary entries before compaction.
+#   Problem: fights Sonnet 4.5+ native compaction; LLM-cost on the critical path.
+#
+# v2 (ACTIVE): deterministically harvests structured state already on disk
+#   into a single session-snapshot entry. No LLM call. Sources:
+#     1. .harness/state/scratchpad.md          (current objective + next step)
+#     2. .harness/state/workflow-checkpoints/  (current feature's stage + files done)
+#     3. .harness/memory/conventions.md        (project conventions, sampled)
+#     4. git status --short                    (files in flight)
+#
+# Result is written to .harness/memory/sessions/recall/snapshots.jsonl as a
+# session-snapshot entry. Survives compaction because it's on disk, not in
+# chat. /handoff (user-invoked) writes richer snapshots; this is the
+# fallback for un-supervised auto-compaction.
+#
+# CONTRACT:
+#   stdin:  JSON (drained)
+#   stdout: hookSpecificOutput JSON with a brief notification
+#   exit 0: always
+#
+# bash 3.2 compatible.
+
+set -eu
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+SCRATCHPAD="$PROJECT_DIR/.harness/state/scratchpad.md"
+CHECKPOINT_DIR="$PROJECT_DIR/.harness/state/workflow-checkpoints"
+SNAP_FILE="$PROJECT_DIR/.harness/memory/sessions/recall/snapshots.jsonl"
+
+# Drain stdin
+cat >/dev/null 2>&1 || true
+
+mkdir -p "$(dirname "$SNAP_FILE")" 2>/dev/null || true
+
+if ! command -v jq >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Determine current feature from git branch
+BRANCH=""
+FEATURE=""
+if command -v git >/dev/null 2>&1; then
+  BRANCH=$(cd "$PROJECT_DIR" 2>/dev/null && git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+  if [ -n "$BRANCH" ]; then
+    case "$BRANCH" in
+      feat/*|fix/*)
+        rest="${BRANCH#*/}"
+        case "$rest" in
+          *-*) FEATURE="${rest%%-*}" ;;
+          *)   FEATURE="$rest" ;;
+        esac
+        ;;
+      */*) FEATURE="${BRANCH%%/*}" ;;
+    esac
+  fi
+fi
+
+# Read scratchpad fields (best effort)
+FOCUS=""
+NEXT_INTENT=""
+if [ -f "$SCRATCHPAD" ]; then
+  FOCUS=$(awk '/^## Current objective/{flag=1; next} /^## /{flag=0} flag' "$SCRATCHPAD" 2>/dev/null | sed '/^$/d' | head -1 | head -c 200)
+  NEXT_INTENT=$(awk '/^## Next step/{flag=1; next} /^## /{flag=0} flag' "$SCRATCHPAD" 2>/dev/null | sed '/^$/d' | head -1 | head -c 200)
+fi
+[ -z "$FOCUS" ] && FOCUS="Auto-snapshot at compaction (no scratchpad)"
+[ -z "$NEXT_INTENT" ] && NEXT_INTENT="(unset)"
+
+# Read latest checkpoint for the feature (if any)
+CHECKPOINT_FILES_DONE="[]"
+CHECKPOINT_STAGE="null"
+if [ -n "$FEATURE" ] && [ -f "$CHECKPOINT_DIR/${FEATURE}.json" ]; then
+  CHECKPOINT_STAGE=$(jq -r '.current_stage // "null"' "$CHECKPOINT_DIR/${FEATURE}.json" 2>/dev/null || echo "null")
+  CHECKPOINT_FILES_DONE=$(jq -c '.stage_in_progress.files_done_list // []' "$CHECKPOINT_DIR/${FEATURE}.json" 2>/dev/null || echo "[]")
+fi
+
+# Files in flight from git status
+FILES_TOUCHED="[]"
+if command -v git >/dev/null 2>&1; then
+  FILES_TOUCHED=$(cd "$PROJECT_DIR" 2>/dev/null && git status --short 2>/dev/null | head -10 | awk '{print $NF}' | jq -R . | jq -sc '.' || echo "[]")
+fi
+
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+DATE_PART=$(echo "$TS" | cut -c1-10 | tr -d '-')
+RAND_SUFFIX=$(printf '%03d' $((RANDOM % 1000)))
+SS_ID="SS-${DATE_PART}${RAND_SUFFIX}"
+
+# Build snapshot entry (auto kind)
+ENTRY=$(jq -c -n \
+  --arg id "$SS_ID" \
+  --arg ts "$TS" \
+  --arg feature "$FEATURE" \
+  --arg focus "$FOCUS" \
+  --arg next_intent "$NEXT_INTENT" \
+  --argjson checkpoint_stage "$CHECKPOINT_STAGE" \
+  --argjson files_done "$CHECKPOINT_FILES_DONE" \
+  --argjson files_touched "$FILES_TOUCHED" \
+  '{
+    id: $id,
+    ts: $ts,
+    kind: "session-snapshot",
+    feature: (if $feature=="" then null else $feature end),
+    focus: $focus,
+    decisions: [],
+    open_problems: [],
+    next_intent: $next_intent,
+    files_touched: $files_touched,
+    checkpoint_stage: $checkpoint_stage,
+    checkpoint_files_done: $files_done,
+    source: "auto-precompaction"
+  }')
+
+echo "$ENTRY" >> "$SNAP_FILE"
+
+# Notify Claude (this is just observational; the snapshot is already saved)
+jq -n --arg id "$SS_ID" '{
+  hookSpecificOutput: {
+    hookEventName: "PreCompaction",
+    additionalContext: ("📸 Auto-snapshot saved (id=" + $id + ") to sessions/recall/snapshots.jsonl. The next session will see this in its recall manifest. For a richer snapshot, use /handoff before compaction next time.")
+  }
+}'