eagle-mem 4.2.1 → 4.6.0

package/README.md

@@ -1,23 +1,22 @@
 ```
 ======================================
-Eagle Mem
+       Eagle Mem
 ======================================
 ```
 
 # Eagle Mem
 
-Persistent memory for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Every session starts with context from previous sessions — summaries, memories, tasks, and project overviews — injected automatically via hooks.
+## The Problem
 
-**Zero per-instance overhead.** No daemon, no vector DB, no MCP server. Just bash scripts, sqlite3, and jq.
+Claude Code starts every session with amnesia. It doesn't remember what you built yesterday, what decisions you made, what files matter, or what broke last time. Every `/compact` wipes context. Every new session is a cold start. You waste tokens re-explaining your project, re-reading files, and watching Claude repeat mistakes you already corrected.
 
-## Getting started
+The longer you work with Claude Code, the worse this gets. Projects accumulate history — decisions, gotchas, architectural patterns, feature dependencies — and none of it survives across sessions.
 
-```bash
-npm install -g eagle-mem
-eagle-mem install
-```
+## The Solution
 
-That's it. Open Claude Code in any project directory. Eagle Mem activates automatically:
+Eagle Mem gives Claude Code persistent memory. Every session starts with context from previous sessions — summaries, decisions, memories, tasks, project overviews, and relevant code — injected automatically via hooks. No commands to run, no prompts to write. It just works.
+
+**Zero per-instance overhead.** No daemon, no vector DB, no MCP server. Just bash scripts, sqlite3 (WAL mode, FTS5 full-text search), and jq.
 
 ```
 ======================================
@@ -32,66 +31,46 @@ That's it. Open Claude Code in any project directory. Eagle Mem activates automa
 ======================================
 ```
 
-Everything is automatic from here. Eagle Mem scans your codebase, indexes source files, captures session summaries, mirrors Claude's memories and tasks, learns which commands are noisy, and prunes stale data — all in the background via hooks.
-
-## Commands
-
-Six commands. Three for lifecycle, three for lookup and troubleshooting.
+## Getting Started
 
-| Command | What it does |
-|---------|-------------|
-| `eagle-mem install` | First-time setup: hooks, database, skills |
-| `eagle-mem update` | Re-deploy hooks and run migrations after `npm update` |
-| `eagle-mem uninstall` | Remove hooks and optionally delete data |
-| `eagle-mem search` | Single lookup command — see modes below |
-| `eagle-mem health` | Diagnose pipeline health and background automation |
-| `eagle-mem config` | View or change LLM provider settings |
+```bash
+npm install -g eagle-mem
+eagle-mem install
+```
 
-### Search modes
+That's it. Open Claude Code in any project directory. Eagle Mem activates automatically.
 
-| Mode | What it does |
-|------|-------------|
-| `eagle-mem search "query"` | FTS5 keyword search across session summaries |
-| `eagle-mem search --timeline` | Recent sessions in chronological order |
-| `eagle-mem search --overview` | View project overview |
-| `eagle-mem search --memories` | Mirrored Claude Code memories |
-| `eagle-mem search --tasks` | In-flight tasks (pending/in-progress) |
-| `eagle-mem search --files` | Most frequently modified files |
-| `eagle-mem search --stats` | Project statistics (counts) |
-| `eagle-mem search --session <id>` | Full observation trail for one session |
+Everything is automatic from here. Eagle Mem scans your codebase, indexes source files, captures session summaries, mirrors Claude's memories and tasks, learns which commands are noisy, and prunes stale data — all in the background via hooks.
 
-## Skills (inside Claude Code)
+### Prerequisites
 
-| Skill | What it does |
-|-------|-------------|
-| `/eagle-mem-search` | Search memory and past sessions — Claude interprets results in context |
-| `/eagle-mem-overview` | Build a rich project briefing from README, entry points, and git history |
-| `/eagle-mem-memories` | View and search mirrored Claude Code memories and plans |
-| `/eagle-mem-tasks` | TaskAware Compact Loop — break complex work into tasks that survive `/compact` |
+- `sqlite3` with FTS5 support (ships with macOS; the installer offers to install if missing)
+- `jq` (the installer offers to install if missing)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed (`~/.claude/` must exist)
 
-## How it works
+## How It Works
 
 Six hooks fire automatically at different points in Claude Code's lifecycle:
 
-| Hook | Fires when | What it does |
+| Hook | Fires When | What It Does |
 |------|-----------|--------------|
 | **SessionStart** | startup, resume, clear, compact | Injects overview, summaries, memories, tasks, core files, working set. Auto-provisions new projects (scan, index). |
-| **PreToolUse** | before Bash, Read, Edit, and Write calls | Rewrites noisy commands (learned rules), detects redundant reads, nudges co-edit partners |
-| **UserPromptSubmit** | user sends a message | FTS5 search for relevant past context |
-| **PostToolUse** | after tool calls | Records file touches, mirrors memory/plan/task writes, tracks modifications |
-| **Stop** | Claude's turn ends | Extracts `<eagle-summary>`, strips `<private>` tags |
+| **PreToolUse** | before Bash, Read, Edit, Write | Surfaces guardrails and decisions before edits. Rewrites noisy commands (learned rules). Detects redundant reads, nudges co-edit partners, detects stuck loops. |
+| **UserPromptSubmit** | user sends a message | FTS5 search across past sessions and indexed code for relevant context |
+| **PostToolUse** | after tool calls | Records file touches, mirrors memory/plan/task writes, surfaces decision history on reads |
+| **Stop** | Claude's turn ends | Extracts `<eagle-summary>` blocks for rich session summaries |
 | **SessionEnd** | session closes | Re-syncs tasks, marks session completed |
 
-### Background automation
+### Background Automation
 
 These run automatically via SessionStart — no commands needed:
 
 - **Auto-scan** — new project with no overview triggers a codebase scan
 - **Auto-index** — new or stale project triggers FTS5 source indexing
 - **Auto-prune** — observations over 10K rows trigger cleanup
-- **Auto-curate** — the self-learning curator analyzes observation data and generates command rules, co-edit patterns, and hot file detection (partially requires LLM provider)
+- **Auto-curate** — the self-learning curator analyzes observation data and generates command rules, co-edit patterns, hot file detection, and guardrails (partially requires LLM provider)
 
-### Token savings
+### Token Savings
 
 Eagle Mem actively reduces token consumption:
 
@@ -104,28 +83,94 @@ Eagle Mem actively reduces token consumption:
 - **Working set recovery** — on compact, SessionStart injects the files you were actively editing so you resume without re-reading everything
 - **Stuck loop detection** — if the same file is edited 5+ times in one session, PreToolUse nudges to reconsider the approach
 
-### Data
+### Anti-Regression
+
+Eagle Mem prevents Claude from repeating past mistakes:
+
+- **Decision surfacing** — when you edit a file that has past decisions recorded (from `<eagle-summary>` blocks), PreToolUse reminds Claude not to revert without asking
+- **Guardrails** — file-level rules (manual or curator-discovered) that fire before every Edit/Write
+- **Feature verification** — tracks features with smoke tests and dependencies; reminds you to verify on `git push`
+- **Gotcha surfacing** — past surprises and gotchas are surfaced when editing related files
+
+## Commands
+
+| Command | What It Does |
+|---------|-------------|
+| `eagle-mem install` | First-time setup: hooks, database, skills |
+| `eagle-mem update` | Re-deploy hooks and run migrations after `npm update` |
+| `eagle-mem uninstall` | Remove hooks and optionally delete data |
+| `eagle-mem search` | Search past sessions, memories, and code |
+| `eagle-mem health` | Diagnose pipeline health and background automation |
+| `eagle-mem config` | View or change LLM provider settings |
+| `eagle-mem guard` | Manage regression guardrails for files |
+| `eagle-mem overview` | Build or view project overview |
+| `eagle-mem memories` | View/sync Claude Code memories |
+| `eagle-mem tasks` | View mirrored tasks |
+| `eagle-mem curate` | Run curator (co-edits, hot files, guardrails) |
+| `eagle-mem feature` | Track and verify features |
+| `eagle-mem prune` | Clean old sessions and stale data |
+| `eagle-mem scan` | Scan codebase and generate overview |
+| `eagle-mem index` | Index source files for FTS5 code search |
+
+### Search Modes
+
+```bash
+eagle-mem search "auth bug"        # keyword search across summaries
+eagle-mem search --timeline        # recent sessions in chronological order
+eagle-mem search --overview        # project overview
+eagle-mem search --memories        # mirrored Claude Code memories
+eagle-mem search --tasks           # in-flight tasks (pending/in-progress)
+eagle-mem search --files           # most frequently modified files
+eagle-mem search --stats           # project statistics
+eagle-mem search --session <id>    # full observation trail for one session
+```
+
+## Skills (Inside Claude Code)
+
+| Skill | What It Does |
+|-------|-------------|
+| `/eagle-mem-search` | Search memory and past sessions — Claude interprets results in context |
+| `/eagle-mem-overview` | Build a rich project briefing from README, entry points, and git history |
+| `/eagle-mem-memories` | View and search mirrored Claude Code memories and plans |
+| `/eagle-mem-tasks` | TaskAware Compact Loop — break complex work into tasks that survive `/compact` |
+
+## Data
 
 Single SQLite database at `~/.eagle-mem/memory.db` (WAL mode, FTS5 full-text search):
 
-| Table | What it stores |
+| Table | What It Stores |
 |-------|---------------|
-| sessions | Active/completed sessions per project |
-| summaries | Per-session summaries (FTS5-indexed) |
-| observations | Per-tool-use file touch records |
-| overviews | One overview per project (auto-scan or manual) |
-| code_chunks | FTS5-indexed source file chunks |
-| command_rules | Curator-learned command output rules |
-| file_hints | Curator-learned file access patterns (co-edit pairs) |
-| claude_memories | Mirror of Claude Code auto-memories |
-| claude_plans | Mirror of Claude Code plans |
-| claude_tasks | Mirror of Claude Code tasks |
-
-## Prerequisites
+| `sessions` | Active/completed sessions per project |
+| `summaries` | Per-session summaries with decisions, gotchas, key files (FTS5-indexed) |
+| `observations` | Per-tool-use file touch records |
+| `overviews` | One overview per project (auto-scan or manual) |
+| `code_chunks` | FTS5-indexed source file chunks |
+| `command_rules` | Curator-learned command output rules |
+| `file_hints` | Curator-learned file access patterns (co-edit pairs, hot files) |
+| `guardrails` | File-level regression rules (manual or curator-discovered) |
+| `features` | Feature tracking with smoke tests and dependencies |
+| `eagle_meta` | Internal metadata (last scan, last curate, etc.) |
+| `claude_memories` | Mirror of Claude Code auto-memories |
+| `claude_plans` | Mirror of Claude Code plans |
+| `claude_tasks` | Mirror of Claude Code tasks |
 
-- `sqlite3` with FTS5 support (ships with macOS; the installer offers to install if missing)
-- `jq` (the installer offers to install if missing)
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed (`~/.claude/` must exist)
+### Project Identity
+
+Projects are identified by their HOME-relative path (e.g., `personal_projects/eagle-mem`). This ensures uniqueness even when multiple projects share the same directory name. Git repositories use the repo root; non-git directories use the working directory.
+
+### Namespace Migration
+
+When upgrading from older versions, `eagle-mem update` automatically migrates project data to the new namespace format. The migration preserves newer data when conflicts exist and cleans up stale entries.
+
+## LLM Provider (Optional)
+
+Some features (curator auto-enrichment, overview generation) can use an LLM for richer output. Configure with:
+
+```bash
+eagle-mem config
+```
+
+Supported providers: Ollama (auto-detected), Anthropic, OpenAI. Eagle Mem works fully without a provider — LLM features gracefully degrade to heuristic fallbacks.
 
 ## License
 

package/bin/eagle-mem

@@ -22,6 +22,15 @@ case "$command" in
     search)     bash "$SCRIPTS_DIR/search.sh" "$@" ;;
     health)     bash "$SCRIPTS_DIR/health.sh" "$@" ;;
     config)     bash "$SCRIPTS_DIR/config.sh" "$@" ;;
+    guard)      bash "$SCRIPTS_DIR/guard.sh" "$@" ;;
+    overview)   bash "$SCRIPTS_DIR/overview.sh" "$@" ;;
+    memories)   bash "$SCRIPTS_DIR/memories.sh" "$@" ;;
+    tasks)      bash "$SCRIPTS_DIR/tasks.sh" "$@" ;;
+    curate)     bash "$SCRIPTS_DIR/curate.sh" "$@" ;;
+    feature)    bash "$SCRIPTS_DIR/feature.sh" "$@" ;;
+    prune)      bash "$SCRIPTS_DIR/prune.sh" "$@" ;;
+    scan)       bash "$SCRIPTS_DIR/scan.sh" "$@" ;;
+    index)      bash "$SCRIPTS_DIR/index.sh" "$@" ;;
     help|--help|-h)
                 bash "$SCRIPTS_DIR/help.sh" ;;
     version|--version|-v|-V)

package/db/022_cleanup_fossils.sql

@@ -0,0 +1,12 @@
+-- Clear fossil placeholder data that the COALESCE upsert preserves forever.
+-- These rows block real data from being written on future Stop hook fires.
+PRAGMA trusted_schema=ON;
+
+UPDATE summaries SET completed = ''
+WHERE completed LIKE '%(auto-captured%';
+
+UPDATE summaries SET request = ''
+WHERE request LIKE '%<local-command-caveat>%';
+
+UPDATE summaries SET request = ''
+WHERE request LIKE '%<system-reminder>%';

package/db/023_guardrails.sql

@@ -0,0 +1,18 @@
+-- ═══════════════════════════════════════════════════════════
+-- Migration 023: Guardrails table
+-- Persistent per-project rules surfaced at Edit/Write time
+-- ═══════════════════════════════════════════════════════════
+
+CREATE TABLE IF NOT EXISTS guardrails (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    project      TEXT NOT NULL,
+    file_pattern TEXT NOT NULL DEFAULT '',
+    rule         TEXT NOT NULL,
+    source       TEXT NOT NULL DEFAULT 'manual',
+    active       INTEGER NOT NULL DEFAULT 1,
+    created_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    updated_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    UNIQUE(project, source, file_pattern, rule)
+);
+
+CREATE INDEX IF NOT EXISTS idx_guardrails_project ON guardrails(project, active);

package/hooks/post-tool-use.sh

@@ -20,7 +20,52 @@ session_id=$(echo "$input" | jq -r '.session_id // empty')
 cwd=$(echo "$input" | jq -r '.cwd // empty')
 tool_name=$(echo "$input" | jq -r '.tool_name // empty')
 
-if [ -z "$session_id" ] || [ -z "$tool_name" ]; then exit 0; fi
+hook_event=$(echo "$input" | jq -r '.hook_event_name // empty')
+
+if [ -z "$session_id" ]; then exit 0; fi
+
+# TaskCreated/TaskCompleted dedicated events — parse top-level fields and exit
+case "$hook_event" in
+    TaskCreated|TaskCompleted)
+        [ ! -f "$EAGLE_MEM_DB" ] && exit 0
+        project=$(eagle_project_from_cwd "$cwd")
+        [ -z "$project" ] && exit 0
+        eagle_upsert_session "$session_id" "$project" "$cwd" "" ""
+
+        task_id=$(echo "$input" | jq -r '.task_id // empty')
+        task_subject=$(echo "$input" | jq -r '.task_subject // empty')
+        task_desc=$(echo "$input" | jq -r '.task_description // empty')
+
+        if [ -n "$task_id" ] && [ -n "$task_subject" ]; then
+            local_status="pending"
+            [ "$hook_event" = "TaskCompleted" ] && local_status="completed"
+
+            # Synthetic file_path keyed on session+task — file_path is the UNIQUE column
+            synthetic_fp="event://${session_id}/${task_id}"
+
+            tid_sql=$(eagle_sql_escape "$task_id")
+            fp_sql=$(eagle_sql_escape "$synthetic_fp")
+            proj_sql=$(eagle_sql_escape "$project")
+            sid_sql=$(eagle_sql_escape "$session_id")
+            subj_sql=$(eagle_sql_escape "$task_subject")
+            desc_sql=$(eagle_sql_escape "$task_desc")
+            stat_sql=$(eagle_sql_escape "$local_status")
+
+            eagle_db_pipe <<SQL
+INSERT INTO claude_tasks (project, source_session_id, source_task_id, file_path, subject, description, status)
+VALUES ('$proj_sql', '$sid_sql', '$tid_sql', '$fp_sql', '$subj_sql', '$desc_sql', '$stat_sql')
+ON CONFLICT(file_path) DO UPDATE SET
+    subject     = excluded.subject,
+    description = excluded.description,
+    status      = excluded.status,
+    updated_at  = strftime('%Y-%m-%dT%H:%M:%fZ', 'now');
+SQL
+        fi
+        exit 0
+        ;;
+esac
+
+[ -z "$tool_name" ] && exit 0
 
 # Only track relevant tools
 case "$tool_name" in

package/hooks/pre-tool-use.sh

@@ -80,8 +80,9 @@ Bash)
                     done <<< "$changed_files"
 
                     if [ -n "$context" ]; then
-                        context="Eagle Mem: This push affects the following features. After deploy, verify each works and run 'eagle-mem feature verify <name>'.
-${context}"
+                        context="=== Eagle Mem ===
+This push affects the following features. After deploy, verify each works and run 'eagle-mem feature verify <name>'.
+${context}================"
                     fi
                 fi
             fi
@@ -91,7 +92,7 @@ ${context}"
     # ─── Command output filtering (learned rules) ─────────────
 
     base_cmd=$(echo "$cmd" | awk '{print $1}' | sed 's|.*/||')
-    rule=$(eagle_get_command_rule "$project" "$base_cmd")
+    rule=$(eagle_get_command_rule "$project" "$base_cmd" "$cmd")
 
     if [ -n "$rule" ]; then
         IFS='|' read -r strategy max_lines reason <<< "$rule"
@@ -105,7 +106,7 @@ ${context}"
                         *"| head"*|*"| tail"*|*"| wc"*|*"| grep"*|*">"*|*">>"*)
                             ;;
                         *)
-                            updated_input=$(jq -nc --arg cmd "${cmd} | head -${max_lines}" '{"command":$cmd}')
+                            updated_input=$(echo "$input" | jq --arg cmd "${cmd} | head -${max_lines}" '.tool_input + {"command":$cmd}')
                             context+="Eagle Mem: '${base_cmd}' output is typically long (${reason}). Piped through head -${max_lines}."
                             ;;
                     esac
@@ -121,6 +122,42 @@ ${context}"
 Edit|Write)
     fp=$(echo "$input" | jq -r '.tool_input.file_path // empty')
     if [ -n "$fp" ]; then
+        # ─── Guardrail + decision/gotcha surfacing ────────
+        fname=$(basename "$fp")
+        fname_stem="${fname%.*}"
+        case "$fp" in
+            "$HOME/.claude/"*) ;;
+            *)
+                # Guardrails use GLOB on full filename — no stem length minimum needed.
+                # FTS decision/gotcha lookups need a meaningful stem (>= 3 chars).
+                if [ ${#fname_stem} -ge 3 ]; then
+                    fts_query=$(eagle_fts_sanitize "$fname_stem")
+                    fts_query=${fts_query:-"$fname_stem"}
+                    edit_ctx=$(eagle_get_edit_context "$project" "$fname" "$fts_query" 2>/dev/null)
+                else
+                    # Short stem (e.g. db.sh) — only fetch guardrails, skip FTS queries
+                    edit_ctx=$(eagle_get_guardrails_for_file "$project" "$fname" 2>/dev/null)
+                    if [ -n "$edit_ctx" ]; then
+                        # Prefix with GR: to match batched output format; strip empty lines
+                        edit_ctx=$(echo "$edit_ctx" | grep -v '^$' | sed 's/^/GR:/')
+                    fi
+                fi
+                if [ -n "$edit_ctx" ]; then
+                    gr_block=""
+                    while IFS= read -r ctx_line; do
+                        case "$ctx_line" in
+                            GR:*)  gr_block+="  - ${ctx_line#GR:}"$'\n' ;;
+                            DEC:*) context+="=== Eagle Mem ==="$'\n'"Decisions for '${fname}': ${ctx_line#DEC:} — Do not revert without asking."$'\n'"================"$'\n' ;;
+                            GOT:*) context+="=== Eagle Mem ==="$'\n'"Gotchas for '${fname}': ${ctx_line#GOT:}"$'\n'"================"$'\n' ;;
+                        esac
+                    done <<< "$edit_ctx"
+                    if [ -n "$gr_block" ]; then
+                        context+="=== Eagle Mem ==="$'\n'"Guardrails for '${fname}':"$'\n'"${gr_block}================"$'\n'
+                    fi
+                fi
+                ;;
+        esac
+
         # ─── Stuck loop detection ─────────────────────────
         if [ -n "$session_id" ] && eagle_validate_session_id "$session_id"; then
             edit_tracker="$EAGLE_MEM_DIR/edit-tracker/${session_id}"

package/hooks/session-start.sh

@@ -322,9 +322,15 @@ Memory active for '$project'. Scan, index, prune, and self-learning run automati
 
 Before your final response, emit:
 <eagle-summary>
-request: [what user asked] | completed: [what shipped] | learned: [non-obvious discoveries]
-next_steps: [concrete actions] | decisions: [choice — why] | gotchas: [what surprised]
-key_files: [path — role] | files_read: [...] | files_modified: [...]
+request: [what user asked]
+completed: [what shipped]
+learned: [non-obvious discoveries]
+decisions: [choice — why]
+gotchas: [what surprised]
+next_steps: [concrete actions]
+key_files: [path — role]
+files_read: [path, ...]
+files_modified: [path, ...]
 </eagle-summary>
 "
 fi

package/hooks/stop.sh

@@ -42,7 +42,13 @@ eagle_upsert_session "$session_id" "$project" "$cwd" "" ""
 
 # ─── Primary: heuristic extraction from transcript ───────────
 
-request=$(jq -r 'select(.type == "user") | .message.content | if type == "string" then . elif type == "array" then [.[] | select(.type == "text") | .text] | join(" ") else "" end' "$transcript_path" 2>/dev/null | head -1 | cut -c1-500)
+request=$(jq -r 'select(.type == "user") | .message.content | if type == "string" then . elif type == "array" then [.[] | select(.type == "text") | .text] | join(" ") else "" end' "$transcript_path" 2>/dev/null \
+    | grep -v '<local-command-caveat>' \
+    | grep -v '<system-reminder>' \
+    | grep -v '<command-name>' \
+    | grep -v '<command-message>' \
+    | grep -v '^\[{' \
+    | head -1 | cut -c1-500)
 
 heuristic_reads=$(jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | select(.name == "Read") | .input.file_path // empty' "$transcript_path" 2>/dev/null | sort -u | head -20)
 heuristic_writes=$(jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | select(.name == "Write" or .name == "Edit") | .input.file_path // empty' "$transcript_path" 2>/dev/null | sort -u | head -20)
@@ -124,59 +130,157 @@ if [ -n "$summary_block" ]; then
     eagle_log "INFO" "Stop: eagle-summary block merged over heuristic data"
 fi
 
-# ─── LLM enrichment: fill in decisions/gotchas/key_files ─────
-# Check both local vars (from eagle-summary block) AND existing DB enrichment.
-# Skip LLM call if either source already has enrichment data.
-# Exception: under context pressure, force re-enrichment for richest summary.
+# ─── LLM enrichment: extract structured data when eagle-summary absent ──
+# Runs when: (a) no eagle-summary block, OR (b) heuristic data is thin
+# Skips when: eagle-summary already provided rich data, OR no text to analyze
 
 context_pressure=0
 if [ -f "$EAGLE_MEM_DIR/.context-pressure" ]; then
     context_pressure=1
 fi
 
-existing_enrichment=""
-if [ -z "$decisions" ] && [ -z "$gotchas" ] && [ -z "$key_files" ]; then
-    s_esc=$(eagle_sql_escape "$session_id")
-    existing_enrichment=$(eagle_db "SELECT decisions||gotchas||key_files FROM summaries WHERE session_id='$s_esc';")
+has_rich_data=0
+if [ -n "$decisions" ] || [ -n "$gotchas" ] || [ -n "$key_files" ]; then
+    has_rich_data=1
 fi
 
-if [ -z "$decisions" ] && [ -z "$gotchas" ] && [ -z "$key_files" ] && { [ -z "$existing_enrichment" ] || [ "$context_pressure" -eq 1 ]; }; then
+request_is_polluted=0
+if echo "$request" | grep -qE '<(local-command-caveat|system-reminder|command-name)>' 2>/dev/null; then
+    request_is_polluted=1
+fi
+
+needs_enrichment=0
+if [ "$has_rich_data" -eq 0 ]; then
+    needs_enrichment=1
+elif [ "$context_pressure" -eq 1 ]; then
+    needs_enrichment=1
+elif [ -z "$completed" ] && [ -z "$learned" ]; then
+    needs_enrichment=1
+elif [ "$request_is_polluted" -eq 1 ]; then
+    needs_enrichment=1
+fi
+
+if [ "$needs_enrichment" -eq 1 ]; then
     provider=$(eagle_config_get "provider" "type" "none" 2>/dev/null)
     if [ "$provider" != "none" ] && [ -n "$text_content" ]; then
-        excerpt=$(echo "$text_content" | tail -c 2000)
+        excerpt=$(echo "$text_content" | tail -c 3000)
+
+        enrich_prompt="Extract facts from this Claude Code session. Only include items with clear evidence in the session text. Do NOT invent or repeat example content.
+
+Respond with EXACTLY these sections (omit sections with no evidence):
 
-        enrich_prompt="Extract from this Claude Code session excerpt:
-1. DECISIONS: architectural or design choices made (with WHY). One per line.
-2. GOTCHAS: non-obvious pitfalls, bugs found, things that surprised. One per line.
-3. KEY_FILES: important files that were central to the work. One per line.
+REQUEST:
+One-line summary of what the user asked for. No system tags or XML.
 
-SESSION EXCERPT:
-$excerpt
+COMPLETED:
+What was actually accomplished. Be specific about changes made.
+
+LEARNED:
+Non-obvious discoveries or insights from the session.
 
-Output EXACTLY this format (omit sections with nothing to report):
 DECISIONS:
-- <decision> — why: <reason>
+Each as: <what was decided> — why: <reason>
+
 GOTCHAS:
-- <gotcha>
+Each as: <surprising finding or pitfall>
+
 KEY_FILES:
-- <filepath>"
+Each as: <filepath>
 
-        enrich_result=$(eagle_llm_call "$enrich_prompt" "Extract structured facts from development sessions. Be concise. Only include items with clear evidence." 512 2>/dev/null) || true
+SESSION TEXT:
+$excerpt"
 
-        if [ -n "$enrich_result" ]; then
+        enrich_system="You extract structured facts from development sessions. Output format for decisions: '- Did X — why: Y'. Output format for gotchas: '- Gotcha description'. Be concise. Only include items with clear evidence in the session text. Never fabricate content."
+        enrich_result=$(eagle_llm_call "$enrich_prompt" "$enrich_system" 768 2>/dev/null)
+        llm_rc=$?
+
+        if [ $llm_rc -ne 0 ] || [ -z "$enrich_result" ]; then
+            eagle_log "WARN" "Stop: LLM enrichment failed (rc=$llm_rc) for session=$session_id provider=$provider"
+        else
             extract_section() {
                 local result="$1" header="$2"
                 echo "$result" | awk -v h="$header:" '
                     $0 == h || $0 ~ "^"h { found=1; next }
                     found && /^[A-Z_]+:/ { exit }
-                    found && /^- / { sub(/^- /, ""); lines[++n] = $0 }
+                    found && /^[[:space:]]*$/ { next }
+                    found && /^- / { sub(/^- /, ""); lines[++n] = $0; next }
+                    found { lines[++n] = $0 }
                     END { for (i=1; i<=n; i++) { printf "%s", lines[i]; if (i<n) printf "; " } }
                 '
             }
-            decisions=$(extract_section "$enrich_result" "DECISIONS")
-            gotchas=$(extract_section "$enrich_result" "GOTCHAS")
-            key_files=$(extract_section "$enrich_result" "KEY_FILES")
-            [ -n "$decisions" ] || [ -n "$gotchas" ] || [ -n "$key_files" ] && eagle_log "INFO" "Stop: LLM enrichment extracted for session=$session_id"
+            _req=$(extract_section "$enrich_result" "REQUEST")
+            _comp=$(extract_section "$enrich_result" "COMPLETED")
+            _learn=$(extract_section "$enrich_result" "LEARNED")
+            _dec=$(extract_section "$enrich_result" "DECISIONS")
+            _got=$(extract_section "$enrich_result" "GOTCHAS")
+            _kf=$(extract_section "$enrich_result" "KEY_FILES")
+
+            [ -z "$request" ] || [ "$request_is_polluted" -eq 1 ] && [ -n "$_req" ] && request="$_req"
+            [ -z "$completed" ] && [ -n "$_comp" ] && completed="$_comp"
+            [ -z "$learned" ] && [ -n "$_learn" ] && learned="$_learn"
+            [ -z "$decisions" ] && [ -n "$_dec" ] && decisions="$_dec"
+            [ -z "$gotchas" ] && [ -n "$_got" ] && gotchas="$_got"
+            [ -z "$key_files" ] && [ -n "$_kf" ] && key_files="$_kf"
+
+            eagle_log "INFO" "Stop: LLM enrichment extracted for session=$session_id (req=${#_req} comp=${#_comp} dec=${#_dec})"
+        fi
+    else
+        eagle_log "INFO" "Stop: LLM enrichment skipped — provider=$provider text_len=${#text_content}"
+    fi
+else
+    eagle_log "INFO" "Stop: LLM enrichment skipped — rich data already present"
+fi
+
+# ─── Heuristic fallback: derive fields from tool activity when no LLM ──
+# Fills key_files and completed from files_modified when both are empty
+
+if [ -z "$key_files" ] && [ -n "$files_modified" ] && [ "$files_modified" != "[]" ]; then
+    key_files=$(echo "$files_modified" | jq -r '.[]?' 2>/dev/null | while read -r f; do basename "$f"; done | sort -u | head -10 | paste -sd ', ' -)
+fi
+
+if [ -z "$completed" ] && [ -n "$files_modified" ] && [ "$files_modified" != "[]" ]; then
+    mod_count=$(echo "$files_modified" | jq -r '.[]?' 2>/dev/null | wc -l | tr -d ' ')
+    mod_names=$(echo "$files_modified" | jq -r '.[]?' 2>/dev/null | while read -r f; do basename "$f"; done | sort -u | head -5 | paste -sd ', ' -)
+    if [ "${mod_count:-0}" -gt 0 ]; then
+        completed="Modified ${mod_count} files: ${mod_names}"
+    fi
+elif [ -z "$completed" ] && [ -n "$files_read" ] && [ "$files_read" != "[]" ]; then
+    read_count=$(echo "$files_read" | jq -r '.[]?' 2>/dev/null | wc -l | tr -d ' ')
+    read_names=$(echo "$files_read" | jq -r '.[]?' 2>/dev/null | while read -r f; do basename "$f"; done | sort -u | head -5 | paste -sd ', ' -)
+    if [ "${read_count:-0}" -gt 0 ]; then
+        completed="Reviewed ${read_count} files: ${read_names}"
+    fi
+fi
+
+if [ -z "$key_files" ] && [ -n "$files_read" ] && [ "$files_read" != "[]" ]; then
+    key_files=$(echo "$files_read" | jq -r '.[]?' 2>/dev/null | while read -r f; do basename "$f"; done | sort -u | head -10 | paste -sd ', ' -)
+fi
+
+# ─── Test reminder for guardrailed files ─────────────────
+
+if [ -n "$files_modified" ] && [ "$files_modified" != "[]" ]; then
+    # Short-circuit: skip per-file loop if project has no guardrails at all
+    has_gr=$(eagle_has_any_guardrails "$project" 2>/dev/null)
+    if [ -n "$has_gr" ]; then
+        guardrailed_files=""
+        while IFS= read -r mod_file; do
+            [ -z "$mod_file" ] && continue
+            mod_basename=$(basename "$mod_file")
+            gr_check=$(eagle_get_guardrails_for_file "$project" "$mod_basename" 2>/dev/null)
+            if [ -n "$gr_check" ]; then
+                guardrailed_files+="${mod_basename}, "
+            fi
+        done < <(echo "$files_modified" | jq -r '.[]?' 2>/dev/null)
+
+        if [ -n "$guardrailed_files" ]; then
+            guardrailed_files=${guardrailed_files%, }
+            test_reminder="Run affected tests for guardrailed files: ${guardrailed_files}"
+            if [ -n "$next_steps" ]; then
+                next_steps="${next_steps}; ${test_reminder}"
+            else
+                next_steps="$test_reminder"
+            fi
+            eagle_log "INFO" "Stop: added test reminder for guardrailed files: $guardrailed_files"
         fi
     fi
 fi