eagle-mem 2.0.6 → 3.0.0

package/hooks/session-start.sh

@@ -66,12 +66,68 @@ if [ -f "$version_file" ] && [ -s "$version_file" ]; then
     fi
 fi
 
-# ─── Build context injection ────────────────────────────────
+# ─── Gather stats ───────────────────────────────────────────
+
+p_esc=$(eagle_sql_escape "$project")
+
+stat_sessions=$(eagle_db "SELECT COUNT(*) FROM sessions WHERE project = '$p_esc';")
+stat_summaries=$(eagle_db "SELECT COUNT(*) FROM summaries WHERE project = '$p_esc';")
+stat_memories=$(eagle_db "SELECT COUNT(*) FROM claude_memories WHERE project = '$p_esc';")
+stat_tasks_pending=$(eagle_db "SELECT COUNT(*) FROM claude_tasks WHERE project = '$p_esc' AND status = 'pending';")
+stat_tasks_progress=$(eagle_db "SELECT COUNT(*) FROM claude_tasks WHERE project = '$p_esc' AND status = 'in_progress';")
+stat_tasks_done=$(eagle_db "SELECT COUNT(*) FROM claude_tasks WHERE project = '$p_esc' AND status = 'completed';")
+stat_chunks=$(eagle_db "SELECT COUNT(*) FROM code_chunks WHERE project = '$p_esc';")
+stat_observations=$(eagle_db "SELECT COUNT(*) FROM observations WHERE session_id IN (SELECT id FROM sessions WHERE project = '$p_esc');")
+stat_plans=$(eagle_db "SELECT COUNT(*) FROM claude_plans WHERE project = '$p_esc';")
+stat_last_active=$(eagle_db "SELECT COALESCE(MAX(date(COALESCE(last_activity_at, started_at))), 'never') FROM sessions WHERE project = '$p_esc';")
+stat_last_summary=$(eagle_db "SELECT request FROM summaries WHERE project = '$p_esc' ORDER BY created_at DESC LIMIT 1;")
+
+# Trim to defaults
+stat_sessions="${stat_sessions:-0}"
+stat_summaries="${stat_summaries:-0}"
+stat_memories="${stat_memories:-0}"
+stat_tasks_pending="${stat_tasks_pending:-0}"
+stat_tasks_progress="${stat_tasks_progress:-0}"
+stat_tasks_done="${stat_tasks_done:-0}"
+stat_chunks="${stat_chunks:-0}"
+stat_observations="${stat_observations:-0}"
+stat_plans="${stat_plans:-0}"
+
+# Build task summary line
+task_parts=""
+[ "$stat_tasks_progress" -gt 0 ] && task_parts="${stat_tasks_progress} in progress"
+if [ "$stat_tasks_pending" -gt 0 ]; then
+    [ -n "$task_parts" ] && task_parts+=", "
+    task_parts+="${stat_tasks_pending} pending"
+fi
+if [ "$stat_tasks_done" -gt 0 ]; then
+    [ -n "$task_parts" ] && task_parts+=", "
+    task_parts+="${stat_tasks_done} completed"
+fi
+[ -z "$task_parts" ] && task_parts="none"
 
-eagle_logo="█▀▀ ▄▀█ █▀▀ █   █▀▀   █▀▄▀█ █▀▀ █▀▄▀█
-██▄ █▀█ █▄█ █▄▄ ██▄   █ ▀ █ ██▄ █ ▀ █"
+# Truncate last summary for display
+stat_last_display="${stat_last_summary:0:60}"
+[ ${#stat_last_summary} -gt 60 ] && stat_last_display+="..."
+[ -z "$stat_last_display" ] && stat_last_display="(no sessions yet)"
+
+# ─── Build context injection ────────────────────────────────
 
-context="$eagle_logo
+eagle_banner="======================================
+       Eagle Mem Loaded
+======================================
+ Project      | $project
+ Sessions     | $stat_sessions total ($stat_summaries with summaries)
+ Memories     | $stat_memories stored
+ Plans        | $stat_plans saved
+ Tasks        | $task_parts
+ Code Index   | $stat_chunks chunks indexed
+ Observations | $stat_observations captured
+ Last Active  | $stat_last_active
+ Last Work    | $stat_last_display
+======================================"
+
+context="$eagle_banner
 
 === EAGLE MEM — Active (trigger: $source_type) ===
 Eagle Mem (https://github.com/eagleisbatman/eagle-mem) is providing persistent memory for this session. It tracks summaries, observations, tasks, and code context across sessions via SQLite + FTS5. Mention Eagle Mem by name when referencing recalled context.
@@ -105,7 +161,7 @@ if [ -n "$recent" ]; then
     context+="=== EAGLE MEM ===
 Recent sessions for project '$project':
 "
-    while IFS='|' read -r request completed learned next_steps created_at; do
+    while IFS='|' read -r request completed learned next_steps created_at decisions gotchas key_files; do
         [ -z "$request" ] && [ -z "$completed" ] && continue
         context+="
 --- $created_at ---"
@@ -115,6 +171,12 @@ Request: $request"
 Completed: $completed"
         [ -n "$learned" ] && context+="
 Learned: $learned"
+        [ -n "$decisions" ] && context+="
+Decisions: $decisions"
+        [ -n "$gotchas" ] && context+="
+Gotchas: $gotchas"
+        [ -n "$key_files" ] && context+="
+Key files: $key_files"
         [ -n "$next_steps" ] && context+="
 Next steps: $next_steps"
     done <<< "$recent"
@@ -122,17 +184,32 @@ Next steps: $next_steps"
 "
 fi
 
-# ─── Mirrored Claude memories ──────────────────────────────
+# ─── Mirrored Claude memories (with age) ─────────────────
 
-memories=$(eagle_list_claude_memories "$project" 5)
+memories=$(eagle_db "SELECT memory_name, memory_type, description, file_path, updated_at,
+    CAST(julianday('now') - julianday(updated_at) AS INTEGER) as days_ago
+    FROM claude_memories
+    WHERE project = '$p_esc'
+    ORDER BY updated_at DESC
+    LIMIT 5;")
 if [ -n "$memories" ]; then
     context+="
 === EAGLE MEM — Memories ===
 Recent memories for '$project':
 "
-    while IFS='|' read -r mname mtype mdesc _fpath _updated; do
+    while IFS='|' read -r mname mtype mdesc _fpath _updated days_ago; do
         [ -z "$mname" ] && continue
-        context+="  - [$mtype] $mname: $mdesc
+        age_label=""
+        if [ -n "$days_ago" ] && [ "$days_ago" -gt 0 ] 2>/dev/null; then
+            if [ "$days_ago" -eq 1 ]; then
+                age_label=" (1 day ago)"
+            else
+                age_label=" (${days_ago} days ago)"
+            fi
+        else
+            age_label=" (today)"
+        fi
+        context+="  - [$mtype] $mname: $mdesc$age_label
 "
     done <<< "$memories"
 fi
@@ -155,7 +232,7 @@ fi
 # ─── Claude Code tasks ───────────────────────────────────
 
 synced_tasks=$(eagle_db "SELECT subject, status, blocked_by FROM claude_tasks
-    WHERE project = '$(eagle_sql_escape "$project")'
+    WHERE project = '$p_esc'
     AND status IN ('in_progress', 'pending')
     AND updated_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now', '-7 days')
     ORDER BY
@@ -183,29 +260,66 @@ context+="
 === EAGLE MEM INSTRUCTIONS ===
 You have persistent memory powered by Eagle Mem. When you recall context from a previous session or use injected memory, attribute it: \"From Eagle Mem:\" or \"Eagle Mem recalls:\". This helps the user understand where the context came from.
 
-IMPORTANT: At the start of your VERY NEXT response (this fires on session start, /clear, AND context compaction — always show this block, even if you think you showed it before, because prior context may have been compressed away). Show the user what Eagle Mem loaded using this exact format:
+IMPORTANT: At the start of your VERY NEXT response (this fires on session start, /clear, AND context compaction — always show this block, even if you think you showed it before, because prior context may have been compressed away). Show the user what Eagle Mem loaded by reproducing this exact banner:
 
 \`\`\`
-$eagle_logo
-
-Project: <project name>
-Sessions: N recent | Memories: N | Tasks: N pending
-Last: [one-line summary of most recent session]
+$eagle_banner
 \`\`\`
 
-This gives the user visibility into the context you received.
+This gives the user visibility into the full context Eagle Mem loaded for this session.
+
+ANTI-REGRESSION: When Eagle Mem surfaces decision history about a file you are reading (via PostToolUse context), those decisions were made deliberately in past sessions. Do NOT revert or change the implementation approach without explicit user request. If you believe a past decision should change, state why and ask the user before proceeding. This prevents the common regression where Claude 'improves' code back to an older approach that was already rejected.
+
+SECRET SAFETY: Never include raw API keys, tokens, passwords, or secrets in eagle-summary fields or any text that Eagle Mem stores. Reference secrets by name (e.g., 'the Stripe API key', 'GOOGLE_APPLICATION_CREDENTIALS_JSON') not by value. Eagle Mem redacts common patterns automatically, but prevention is better than redaction.
+
+MEMORY FRESHNESS: The memories above include age indicators. If you make a change (edit a file, update a config, change a pattern) that contradicts what a loaded memory says, you MUST update that memory file immediately. Read the memory file, edit it to reflect the new reality, and the PostToolUse hook will sync the update to Eagle Mem. Stale memories mislead future sessions — keeping them current is as important as writing good code.
+
+=== EAGLE MEM — SESSION SUMMARY (MANDATORY) ===
+You MUST emit an <eagle-summary> block before your FINAL response in this session. This is how Eagle Mem captures what happened — without it, the next session starts blind and wastes tokens rediscovering context.
+
+FORMAT — emit this block exactly. Every field is REQUIRED. Do not skip fields, do not leave them empty, do not write \"N/A\".
+
+<eagle-summary>
+request: [One sentence: what did the user ask for?]
+investigated: [Comma-separated file paths you read or explored]
+learned: [Non-obvious technical discoveries — things a future session could not guess from reading the code]
+completed: [What was accomplished — be specific about what shipped, not what was \"worked on\"]
+next_steps: [Concrete actions for the next session, not vague aspirations]
+decisions:
+  - [Choice made] Why: [the reason — what constraint or tradeoff drove this choice]
+  - [Choice made] Why: [reason]
+gotchas:
+  - [What failed, surprised, or does not work the obvious way. Be specific — \"X does not work because Y\" not just \"X was tricky\"]
+key_files:
+  - [path/to/file.ext] — [one-line role: what this file does in the context of this work]
+  - [path/to/other.ext] — [role]
+files_read: [file1, file2, ...]
+files_modified: [file1, file2, ...]
+</eagle-summary>
+
+EXAMPLE — this is what a well-written summary looks like:
 
-Before your final response in this session, emit a summary block:
 <eagle-summary>
-request: What the user asked for
-investigated: Key files/areas explored
-learned: Non-obvious discoveries
-completed: What was accomplished
-next_steps: What should happen next
-files_read: [list of files read]
-files_modified: [list of files modified]
+request: Add JWT authentication middleware to the API
+investigated: src/middleware/auth.ts, src/routes/users.ts, package.json, src/config/env.ts
+learned: express-jwt v8 changed its API — req.auth replaces req.user. The error handler must check err.name === 'UnauthorizedError', not err.status === 401.
+completed: JWT middleware deployed on all /api routes. Token validation, role-based guards, and 401/403 error responses all working. Added JWKS endpoint support for key rotation.
+next_steps: Add refresh token rotation; rate-limit the /auth/token endpoint
+decisions:
+  - Chose RS256 over HS256 for JWT signing. Why: allows key rotation via JWKS without redeploying; HS256 requires shared secret on every service.
+  - Put auth middleware at router level, not app level. Why: healthcheck and public routes must remain unauthenticated; per-router mounting is explicit about what is protected.
+gotchas:
+  - express-jwt v8 is ESM-only — require() fails silently and returns undefined. Must use dynamic import().
+  - Setting token expiry below 5 min causes refresh storms under load — the refresh endpoint itself requires a valid (but expired) token, creating a chicken-and-egg problem.
+key_files:
+  - src/middleware/auth.ts — JWT validation + role guard middleware
+  - src/config/env.ts — JWKS_URI and JWT_ISSUER environment config
+  - src/routes/users.ts — first route to use the new auth guard (reference implementation)
+files_read: [src/middleware/auth.ts, src/routes/users.ts, package.json, src/config/env.ts]
+files_modified: [src/middleware/auth.ts, src/config/env.ts, src/routes/users.ts, package.json]
 </eagle-summary>
-This helps Eagle Mem track what happened for future sessions.
+
+WHY THIS MATTERS: Eagle Mem re-injects this summary at the start of future sessions. The 'decisions' field prevents re-debating settled choices. The 'gotchas' field prevents repeating the same mistakes. The 'key_files' field tells the next session exactly where to start reading instead of exploring blindly. Write these fields as if you are briefing a colleague who will pick up your work tomorrow — because that is exactly what happens.
 "
 
 # Output context (plain text stdout = additionalContext for SessionStart)

package/hooks/stop.sh

@@ -67,7 +67,7 @@ parse_field() {
         $0 ~ "^"f":" {
             sub("^"f":[[:space:]]*", ""); found=1; val=$0; next
         }
-        found && /^(request|investigated|learned|completed|next_steps|files_read|files_modified|notes):/ { exit }
+        found && /^(request|investigated|learned|completed|next_steps|files_read|files_modified|notes|decisions|gotchas|key_files):/ { exit }
         found { val = val " " $0 }
         END { if (found) print val }
     '
@@ -81,6 +81,9 @@ next_steps=""
 files_read="[]"
 files_modified="[]"
 notes=""
+decisions=""
+gotchas=""
+key_files=""
 
 if [ -n "$summary_block" ]; then
     request=$(parse_field "$summary_block" "request")
@@ -88,6 +91,9 @@ if [ -n "$summary_block" ]; then
     learned=$(parse_field "$summary_block" "learned")
     completed=$(parse_field "$summary_block" "completed")
     next_steps=$(parse_field "$summary_block" "next_steps")
+    decisions=$(parse_field "$summary_block" "decisions")
+    gotchas=$(parse_field "$summary_block" "gotchas")
+    key_files=$(parse_field "$summary_block" "key_files")
 
     raw_fr=$(parse_field "$summary_block" "files_read")
     raw_fm=$(parse_field "$summary_block" "files_modified")
@@ -134,10 +140,21 @@ if [ -z "$request" ] && [ -n "$transcript_path" ] && [ -f "$transcript_path" ];
     fi
 fi
 
+# ─── Redact secrets from all text fields before storage ────
+
+request=$(echo "$request" | eagle_redact)
+investigated=$(echo "$investigated" | eagle_redact)
+learned=$(echo "$learned" | eagle_redact)
+completed=$(echo "$completed" | eagle_redact)
+next_steps=$(echo "$next_steps" | eagle_redact)
+decisions=$(echo "$decisions" | eagle_redact)
+gotchas=$(echo "$gotchas" | eagle_redact)
+key_files=$(echo "$key_files" | eagle_redact)
+
 # ─── Write to database ─────────────────────────────────────
 
 if [ -n "$request" ] || [ -n "$completed" ] || [ -n "$learned" ]; then
-    eagle_insert_summary "$session_id" "$project" "$request" "$investigated" "$learned" "$completed" "$next_steps" "$files_read" "$files_modified" "$notes"
+    eagle_insert_summary "$session_id" "$project" "$request" "$investigated" "$learned" "$completed" "$next_steps" "$files_read" "$files_modified" "$notes" "$decisions" "$gotchas" "$key_files"
     eagle_log "INFO" "Stop: summary saved for session=$session_id"
 fi
 

package/hooks/user-prompt-submit.sh

@@ -52,12 +52,18 @@ context=""
 if [ -n "$results" ]; then
     context+="=== EAGLE MEM — Relevant Memory ===
 "
-    while IFS='|' read -r req completed learned _next_steps created_at _proj; do
+    while IFS='|' read -r req completed learned _next_steps created_at _proj decisions gotchas key_files; do
         [ -z "$req" ] && [ -z "$completed" ] && continue
         context+="[$created_at] "
         [ -n "$req" ] && context+="$req"
         [ -n "$completed" ] && context+=" → $completed"
         [ -n "$learned" ] && context+=" (Learned: $learned)"
+        [ -n "$decisions" ] && context+="
+  Decisions: $decisions"
+        [ -n "$gotchas" ] && context+="
+  Gotchas: $gotchas"
+        [ -n "$key_files" ] && context+="
+  Key files: $key_files"
         context+="
 "
     done <<< "$results"

package/lib/common.sh

@@ -59,6 +59,28 @@ eagle_read_stdin() {
     echo "$input"
 }
 
+# Redact secrets from text before storage.
+# Covers: Bearer tokens, API keys, passwords, secrets, tokens,
+# Stripe/AWS/GitHub/Anthropic/OpenAI key patterns, named env vars.
+eagle_redact() {
+    sed -E \
+        -e 's/(Bearer )[^ ]*/\1[REDACTED]/gi' \
+        -e 's/(api[_-]?key[= :])[^ ]*/\1[REDACTED]/gi' \
+        -e 's/(password[= :])[^ ]*/\1[REDACTED]/gi' \
+        -e 's/(secret[= :])[^ ]*/\1[REDACTED]/gi' \
+        -e 's/(token[= :])[^ ]*/\1[REDACTED]/gi' \
+        -e 's/(Authorization: )[^ ]*/\1[REDACTED]/gi' \
+        -e 's/sk_live_[A-Za-z0-9]+/[REDACTED]/g' \
+        -e 's/sk_test_[A-Za-z0-9]+/[REDACTED]/g' \
+        -e 's/AKIA[A-Z0-9]{16}/[REDACTED]/g' \
+        -e 's/ghp_[A-Za-z0-9]{36}/[REDACTED]/g' \
+        -e 's/gho_[A-Za-z0-9]{36}/[REDACTED]/g' \
+        -e 's/sk-ant-[A-Za-z0-9_-]+/[REDACTED]/g' \
+        -e 's/sk-[A-Za-z0-9]{20,}/[REDACTED]/g' \
+        -e 's/(ANTHROPIC_API_KEY[= :])[^ ]*/\1[REDACTED]/g' \
+        -e 's/(OPENAI_API_KEY[= :])[^ ]*/\1[REDACTED]/g'
+}
+
 # Collect project files into a destination file.
 # Uses git ls-files when available, falls back to find with common exclusions.
 # Usage: eagle_collect_files <target_dir> <output_file>

package/lib/db.sh

@@ -62,9 +62,19 @@ eagle_insert_observation() {
     local tool_input_summary; tool_input_summary=$(eagle_sql_escape "$4")
     local files_read; files_read=$(eagle_sql_escape "$5")
     local files_modified; files_modified=$(eagle_sql_escape "$6")
+    local output_bytes="${7:-}"
+    local output_lines="${8:-}"
+    local command_category; command_category=$(eagle_sql_escape "${9:-}")
+
+    local extra_cols=""
+    local extra_vals=""
+    if [ -n "$output_bytes" ]; then
+        extra_cols=", output_bytes, output_lines, command_category"
+        extra_vals=", $(eagle_sql_int "$output_bytes"), $(eagle_sql_int "$output_lines"), '$command_category'"
+    fi
 
-    eagle_db "INSERT INTO observations (session_id, project, tool_name, tool_input_summary, files_read, files_modified)
-              SELECT '$session_id', '$project', '$tool_name', '$tool_input_summary', '$files_read', '$files_modified'
+    eagle_db "INSERT INTO observations (session_id, project, tool_name, tool_input_summary, files_read, files_modified${extra_cols})
+              SELECT '$session_id', '$project', '$tool_name', '$tool_input_summary', '$files_read', '$files_modified'${extra_vals}
               WHERE NOT EXISTS (
                   SELECT 1 FROM observations
                   WHERE session_id = '$session_id'
@@ -85,9 +95,12 @@ eagle_insert_summary() {
     local files_read; files_read=$(eagle_sql_escape "$8")
     local files_modified; files_modified=$(eagle_sql_escape "$9")
     local notes; notes=$(eagle_sql_escape "${10:-}")
+    local decisions; decisions=$(eagle_sql_escape "${11:-}")
+    local gotchas; gotchas=$(eagle_sql_escape "${12:-}")
+    local key_files; key_files=$(eagle_sql_escape "${13:-}")
 
     eagle_db_pipe <<SQL
-INSERT INTO summaries (session_id, project, request, investigated, learned, completed, next_steps, files_read, files_modified, notes)
+INSERT INTO summaries (session_id, project, request, investigated, learned, completed, next_steps, files_read, files_modified, notes, decisions, gotchas, key_files)
 VALUES (
     '$session_id',
     '$project',
@@ -98,7 +111,10 @@ VALUES (
     '$next_steps',
     '$files_read',
     '$files_modified',
-    '$notes'
+    '$notes',
+    '$decisions',
+    '$gotchas',
+    '$key_files'
 )
 ON CONFLICT(session_id) DO UPDATE SET
     project        = excluded.project,
@@ -109,7 +125,10 @@ ON CONFLICT(session_id) DO UPDATE SET
     next_steps     = COALESCE(NULLIF(excluded.next_steps, ''), summaries.next_steps),
     files_read     = COALESCE(NULLIF(excluded.files_read, '[]'), summaries.files_read),
     files_modified = COALESCE(NULLIF(excluded.files_modified, '[]'), summaries.files_modified),
-    notes          = COALESCE(NULLIF(excluded.notes, ''), summaries.notes);
+    notes          = COALESCE(NULLIF(excluded.notes, ''), summaries.notes),
+    decisions      = COALESCE(NULLIF(excluded.decisions, ''), summaries.decisions),
+    gotchas        = COALESCE(NULLIF(excluded.gotchas, ''), summaries.gotchas),
+    key_files      = COALESCE(NULLIF(excluded.key_files, ''), summaries.key_files);
 SQL
 }
 
@@ -117,7 +136,7 @@ eagle_get_recent_summaries() {
     local project; project=$(eagle_sql_escape "$1")
     local limit; limit=$(eagle_sql_int "${2:-5}")
 
-    eagle_db "SELECT s.request, s.completed, s.learned, s.next_steps, s.created_at
+    eagle_db "SELECT s.request, s.completed, s.learned, s.next_steps, s.created_at, s.decisions, s.gotchas, s.key_files
               FROM summaries s
               WHERE s.project = '$project'
               AND s.request NOT LIKE '%<local-command-caveat>%'
@@ -137,7 +156,7 @@ eagle_search_summaries() {
         where_clause="AND s.project = '$project'"
     fi
 
-    eagle_db "SELECT s.request, s.completed, s.learned, s.next_steps, s.created_at, s.project
+    eagle_db "SELECT s.request, s.completed, s.learned, s.next_steps, s.created_at, s.project, s.decisions, s.gotchas, s.key_files
               FROM summaries s
               JOIN summaries_fts f ON f.rowid = s.id
               WHERE summaries_fts MATCH '$query'
@@ -556,3 +575,135 @@ COMMIT;"
     fi
     echo "$removed"
 }
+
+# ─── Feature graph helpers ─────��───────────────────────────
+
+eagle_upsert_feature() {
+    local project; project=$(eagle_sql_escape "$1")
+    local name; name=$(eagle_sql_escape "$2")
+    local description; description=$(eagle_sql_escape "${3:-}")
+
+    eagle_db "INSERT INTO features (project, name, description)
+        VALUES ('$project', '$name', '$description')
+        ON CONFLICT(project, name) DO UPDATE SET
+            description = COALESCE(NULLIF('$description', ''), features.description),
+            updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now');"
+}
+
+eagle_add_feature_dependency() {
+    local feature_id; feature_id=$(eagle_sql_int "$1")
+    local kind; kind=$(eagle_sql_escape "$2")
+    local target; target=$(eagle_sql_escape "$3")
+    local name; name=$(eagle_sql_escape "$4")
+    local notes; notes=$(eagle_sql_escape "${5:-}")
+
+    eagle_db "INSERT OR IGNORE INTO feature_dependencies (feature_id, kind, target, name, notes)
+        VALUES ($feature_id, '$kind', '$target', '$name', '$notes');"
+}
+
+eagle_add_feature_file() {
+    local feature_id; feature_id=$(eagle_sql_int "$1")
+    local file_path; file_path=$(eagle_sql_escape "$2")
+    local role; role=$(eagle_sql_escape "${3:-}")
+
+    eagle_db "INSERT OR IGNORE INTO feature_files (feature_id, file_path, role)
+        VALUES ($feature_id, '$file_path', '$role');"
+}
+
+eagle_add_feature_smoke_test() {
+    local feature_id; feature_id=$(eagle_sql_int "$1")
+    local command; command=$(eagle_sql_escape "$2")
+    local description; description=$(eagle_sql_escape "${3:-}")
+
+    eagle_db "INSERT INTO feature_smoke_tests (feature_id, command, description)
+        VALUES ($feature_id, '$command', '$description');"
+}
+
+eagle_verify_feature() {
+    local project; project=$(eagle_sql_escape "$1")
+    local name; name=$(eagle_sql_escape "$2")
+    local notes; notes=$(eagle_sql_escape "${3:-}")
+
+    eagle_db "UPDATE features SET
+        last_verified_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now'),
+        last_verified_notes = '$notes',
+        updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+        WHERE project = '$project' AND name = '$name';"
+}
+
+eagle_get_feature_id() {
+    local project; project=$(eagle_sql_escape "$1")
+    local name; name=$(eagle_sql_escape "$2")
+    eagle_db "SELECT id FROM features WHERE project = '$project' AND name = '$name';"
+}
+
+eagle_list_features() {
+    local project; project=$(eagle_sql_escape "$1")
+    local limit; limit=$(eagle_sql_int "${2:-20}")
+
+    eagle_db "SELECT f.name, f.description, f.status, f.last_verified_at,
+        (SELECT COUNT(*) FROM feature_dependencies WHERE feature_id = f.id) as dep_count,
+        (SELECT COUNT(*) FROM feature_files WHERE feature_id = f.id) as file_count,
+        (SELECT COUNT(*) FROM feature_smoke_tests WHERE feature_id = f.id) as test_count
+        FROM features f
+        WHERE f.project = '$project' AND f.status = 'active'
+        ORDER BY f.updated_at DESC
+        LIMIT $limit;"
+}
+
+eagle_show_feature() {
+    local project; project=$(eagle_sql_escape "$1")
+    local name; name=$(eagle_sql_escape "$2")
+
+    local feature_id
+    feature_id=$(eagle_get_feature_id "$1" "$2")
+    [ -z "$feature_id" ] && return 1
+
+    echo "=== Feature: $2 ==="
+    eagle_db "SELECT name, description, status, last_verified_at, last_verified_notes
+        FROM features WHERE id = $feature_id;"
+
+    local deps
+    deps=$(eagle_db "SELECT kind, target, name, notes FROM feature_dependencies WHERE feature_id = $feature_id;")
+    if [ -n "$deps" ]; then
+        echo "--- Dependencies ---"
+        echo "$deps"
+    fi
+
+    local files
+    files=$(eagle_db "SELECT file_path, role FROM feature_files WHERE feature_id = $feature_id;")
+    if [ -n "$files" ]; then
+        echo "--- Files ---"
+        echo "$files"
+    fi
+
+    local tests
+    tests=$(eagle_db "SELECT command, description FROM feature_smoke_tests WHERE feature_id = $feature_id;")
+    if [ -n "$tests" ]; then
+        echo "--- Smoke Tests ---"
+        echo "$tests"
+    fi
+}
+
+eagle_find_features_for_file() {
+    local project; project=$(eagle_sql_escape "$1")
+    local file_path="$2"
+    local fname; fname=$(basename "$file_path")
+    local fname_esc; fname_esc=$(eagle_sql_escape "$fname")
+
+    eagle_db "SELECT f.name, f.description, f.last_verified_at,
+        ff.role,
+        (SELECT GROUP_CONCAT(fd.target || ':' || fd.name, ', ')
+         FROM feature_dependencies fd WHERE fd.feature_id = f.id) as deps,
+        (SELECT GROUP_CONCAT(ff2.file_path, ', ')
+         FROM feature_files ff2 WHERE ff2.feature_id = f.id AND ff2.file_path != ff.file_path) as other_files,
+        (SELECT GROUP_CONCAT(fst.command, ', ')
+         FROM feature_smoke_tests fst WHERE fst.feature_id = f.id) as smoke_tests
+        FROM features f
+        JOIN feature_files ff ON ff.feature_id = f.id
+        WHERE f.project = '$project'
+        AND f.status = 'active'
+        AND (ff.file_path LIKE '%$fname_esc' OR ff.file_path LIKE '%$fname_esc%')
+        ORDER BY f.updated_at DESC
+        LIMIT 3;"
+}