eagle-mem 3.0.2 → 3.1.0

package/bin/eagle-mem

@@ -30,6 +30,7 @@ case "$command" in
     config)     bash "$SCRIPTS_DIR/config.sh" "$@" ;;
     curate)     bash "$SCRIPTS_DIR/curate.sh" "$@" ;;
     feature)    bash "$SCRIPTS_DIR/feature.sh" "$@" ;;
+    health)     bash "$SCRIPTS_DIR/health.sh" "$@" ;;
     help|--help|-h)
                 bash "$SCRIPTS_DIR/help.sh" ;;
     version|--version|-v|-V)

package/db/016_eagle_meta.sql

@@ -0,0 +1,8 @@
+-- Eagle meta key-value store for system state (curator timestamps, etc.)
+CREATE TABLE IF NOT EXISTS eagle_meta (
+    key TEXT NOT NULL,
+    project TEXT,
+    value TEXT NOT NULL,
+    updated_at TEXT DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    UNIQUE(key, project)
+);

package/hooks/post-tool-use.sh

@@ -31,6 +31,7 @@ esac
 [ ! -f "$EAGLE_MEM_DB" ] && exit 0
 
 project=$(eagle_project_from_cwd "$cwd")
+[ -z "$project" ] && exit 0
 
 # Ensure session row exists before inserting observations (FK constraint).
 # PostToolUse can race SessionStart — the session row might not exist yet.

package/hooks/pre-tool-use.sh

@@ -27,6 +27,7 @@ cmd=$(echo "$input" | jq -r '.tool_input.command // empty')
 session_id=$(echo "$input" | jq -r '.session_id // empty')
 cwd=$(echo "$input" | jq -r '.cwd // empty')
 project=$(eagle_project_from_cwd "$cwd")
+[ -z "$project" ] && exit 0
 
 context=""
 

package/hooks/session-end.sh

@@ -2,15 +2,17 @@
 # ═══════════════════════════════════════════════════════════
 # Eagle Mem — SessionEnd hook
 # Fires when the Claude Code session ends
-# Marks the session as completed
+# Marks the session as completed + triggers auto-curate
 # ═══════════════════════════════════════════════════════════
 set +e
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 LIB_DIR="$SCRIPT_DIR/../lib"
+SCRIPTS_DIR="$SCRIPT_DIR/../scripts"
 
 . "$LIB_DIR/common.sh"
 . "$LIB_DIR/db.sh"
+. "$LIB_DIR/provider.sh"
 
 input=$(eagle_read_stdin)
 [ -z "$input" ] && exit 0
@@ -21,6 +23,7 @@ session_id=$(echo "$input" | jq -r '.session_id // empty')
 
 cwd=$(echo "$input" | jq -r '.cwd // empty')
 project=$(eagle_project_from_cwd "$cwd")
+[ -z "$project" ] && exit 0
 
 # Final sweep: re-capture all task files to catch status changes
 # Claude Code may update task status without triggering PostToolUse
@@ -41,4 +44,23 @@ eagle_log "INFO" "SessionEnd: session=$session_id marked completed"
 # Prune observations older than 90 days (keeps DB size bounded)
 eagle_prune_observations 90 "$project"
 
+# ─── Auto-curate trigger ─────────────────────────────────
+curator_schedule=$(eagle_config_get "curator" "schedule" "manual")
+if [ "$curator_schedule" = "auto" ]; then
+    provider=$(eagle_config_get "provider" "type" "none")
+    if [ "$provider" != "none" ]; then
+        min_sessions=$(eagle_config_get "curator" "min_sessions" "5")
+        min_sessions=$(eagle_sql_int "$min_sessions")
+
+        last_curated=$(eagle_meta_get "last_curated_at" "$project")
+        since="${last_curated:-1970-01-01T00:00:00Z}"
+
+        sessions_since=$(eagle_count_sessions_since "$project" "$since")
+        if [ "${sessions_since:-0}" -ge "$min_sessions" ]; then
+            eagle_log "INFO" "SessionEnd: auto-curate triggered (${sessions_since} sessions since last curate)"
+            nohup bash "$SCRIPTS_DIR/curate.sh" -p "$project" >> "$EAGLE_MEM_LOG" 2>&1 &
+        fi
+    fi
+fi
+
 exit 0

package/hooks/session-start.sh

@@ -26,6 +26,9 @@ model=$(echo "$input" | jq -r '.model // empty')
 
 project=$(eagle_project_from_cwd "$cwd")
 
+# Skip ephemeral directories (tmp, Downloads, etc.) — no tracking
+[ -z "$project" ] && exit 0
+
 eagle_log "INFO" "SessionStart: session=$session_id project=$project source=$source_type"
 
 eagle_upsert_session "$session_id" "$project" "$cwd" "$model" "$source_type"
@@ -134,6 +137,15 @@ if [ -n "$update_notice" ]; then
 "
 fi
 
+# Nudge if last session lacked enrichment
+last_enriched=$(eagle_last_session_enriched "$project")
+if [ "${last_enriched:-1}" = "0" ] && [ "$stat_with_summaries" -gt 0 ]; then
+    context+="=== EAGLE MEM — Enrichment Reminder ===
+The previous session's summary did NOT include decisions, gotchas, or key_files. These fields power Eagle Mem's self-learning (feature discovery, anti-regression, command intelligence). Please emit an <eagle-summary> block at the end of this session with these fields populated.
+
+"
+fi
+
 # Project overview
 overview=$(eagle_get_overview "$project")
 if [ -n "$overview" ]; then

package/hooks/stop.sh

@@ -12,6 +12,7 @@ LIB_DIR="$SCRIPT_DIR/../lib"
 
 . "$LIB_DIR/common.sh"
 . "$LIB_DIR/db.sh"
+. "$LIB_DIR/provider.sh"
 
 eagle_ensure_db
 
@@ -29,6 +30,7 @@ agent_type=$(echo "$input" | jq -r '.agent_type // empty')
 [ -n "$agent_type" ] && [ "$agent_type" != "main" ] && exit 0
 
 project=$(eagle_project_from_cwd "$cwd")
+[ -z "$project" ] && exit 0
 
 eagle_log "INFO" "Stop: session=$session_id project=$project transcript=$transcript_path"
 
@@ -111,21 +113,25 @@ if [ -n "$summary_block" ]; then
     eagle_log "INFO" "Stop: parsed eagle-summary block"
 fi
 
-# ─── Heuristic fallback: extract from tool calls ───────────
+# ─── Guard: skip fallback work if summary already exists ──
+# Stop fires every assistant turn. Without this, the heuristic and LLM
+# enrichment blocks fire on turn 2+ — wasting tokens and producing
+# empty inserts that get rejected.
 
-if [ -z "$request" ] && [ -n "$transcript_path" ] && [ -f "$transcript_path" ]; then
-    # Skip heuristic if we already have a summary for this session.
-    # Stop fires every turn -- without this guard, each turn creates a duplicate row.
+existing_count=0
+if [ -z "$summary_block" ] && [ -n "$transcript_path" ] && [ -f "$transcript_path" ]; then
     existing_count=$(eagle_count_session_summaries "$session_id")
-    if [ "${existing_count:-0}" -gt 0 ]; then
-        eagle_log "INFO" "Stop: skipping heuristic — summary already exists for session=$session_id (count=$existing_count)"
-    else
+fi
+
+if [ -z "$summary_block" ] && [ "${existing_count:-0}" -eq 0 ]; then
+
+    # ─── Heuristic fallback: extract from tool calls ───────────
+
+    if [ -z "$request" ] && [ -n "$transcript_path" ] && [ -f "$transcript_path" ]; then
         eagle_log "INFO" "Stop: no eagle-summary found, using heuristic fallback"
 
-        # Extract first user prompt as "request"
         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)
 
-        # Extract files from Read/Write/Edit tool calls
         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)
 
@@ -138,6 +144,52 @@ if [ -z "$request" ] && [ -n "$transcript_path" ] && [ -f "$transcript_path" ];
 
         completed="(auto-captured from tool usage)"
     fi
+
+    # ─── LLM enrichment: extract decisions/gotchas/key_files ──
+
+    if [ -z "$decisions" ] && [ -z "$gotchas" ] && [ -z "$key_files" ]; 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)
+
+            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.
+
+SESSION EXCERPT:
+$excerpt
+
+Output EXACTLY this format (omit sections with nothing to report):
+DECISIONS:
+- <decision> — why: <reason>
+GOTCHAS:
+- <gotcha>
+KEY_FILES:
+- <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
+
+            if [ -n "$enrich_result" ]; then
+                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 }
+                        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"
+            fi
+        fi
+    fi
+
+elif [ -z "$summary_block" ] && [ "${existing_count:-0}" -gt 0 ]; then
+    eagle_log "INFO" "Stop: skipping fallback — summary already exists for session=$session_id (count=$existing_count)"
 fi
 
 # ─── Redact secrets from all text fields before storage ────

package/lib/common.sh

@@ -25,6 +25,18 @@ eagle_log() {
 
 eagle_project_from_cwd() {
     local cwd="${1:-$(pwd)}"
+    local resolved="$cwd"
+
+    # Resolve /private/tmp → /tmp on macOS
+    case "$resolved" in /private/tmp*) resolved="/tmp${resolved#/private/tmp}" ;; esac
+
+    # Skip ephemeral directories — return empty so hooks early-exit
+    case "$resolved" in
+        /tmp|/tmp/*|/var/tmp|/var/tmp/*) echo ""; return ;;
+        "$HOME/Downloads"|"$HOME/Downloads/"*) echo ""; return ;;
+        "$HOME/Desktop"|"$HOME/Desktop/"*) echo ""; return ;;
+    esac
+
     local git_root
     git_root=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null)
     if [ -n "$git_root" ]; then

package/lib/db-sessions.sh

@@ -66,3 +66,34 @@ eagle_count_session_summaries() {
     local sid; sid=$(eagle_sql_escape "$1")
     eagle_db "SELECT COUNT(*) FROM summaries WHERE session_id = '$sid';"
 }
+
+eagle_meta_get() {
+    local key; key=$(eagle_sql_escape "$1")
+    local project="${2:-}"
+    if [ -n "$project" ]; then
+        local p_esc; p_esc=$(eagle_sql_escape "$project")
+        eagle_db "SELECT value FROM eagle_meta WHERE key = '$key' AND project = '$p_esc' LIMIT 1;"
+    else
+        eagle_db "SELECT value FROM eagle_meta WHERE key = '$key' AND project IS NULL LIMIT 1;"
+    fi
+}
+
+eagle_meta_set() {
+    local key; key=$(eagle_sql_escape "$1")
+    local value; value=$(eagle_sql_escape "$2")
+    local project="${3:-}"
+    if [ -n "$project" ]; then
+        local p_esc; p_esc=$(eagle_sql_escape "$project")
+        eagle_db "INSERT INTO eagle_meta (key, project, value) VALUES ('$key', '$p_esc', '$value')
+                  ON CONFLICT(key, project) DO UPDATE SET value = excluded.value, updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now');"
+    else
+        eagle_db "INSERT INTO eagle_meta (key, project, value) VALUES ('$key', NULL, '$value')
+                  ON CONFLICT(key, project) DO UPDATE SET value = excluded.value, updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now');"
+    fi
+}
+
+eagle_count_sessions_since() {
+    local project; project=$(eagle_sql_escape "$1")
+    local since; since=$(eagle_sql_escape "$2")
+    eagle_db "SELECT COUNT(*) FROM sessions WHERE project = '$project' AND started_at > '$since';"
+}

package/lib/db-summaries.sh

@@ -130,6 +130,17 @@ eagle_search_decisions_for_file() {
         LIMIT 1;"
 }
 
+eagle_last_session_enriched() {
+    local project; project=$(eagle_sql_escape "$1")
+    eagle_db "SELECT CASE
+        WHEN (decisions IS NOT NULL AND decisions != '')
+          OR (gotchas IS NOT NULL AND gotchas != '')
+          OR (key_files IS NOT NULL AND key_files != '')
+        THEN 1 ELSE 0 END
+        FROM summaries WHERE project = '$project'
+        ORDER BY created_at DESC LIMIT 1;"
+}
+
 eagle_search_stale_memories() {
     local project; project=$(eagle_sql_escape "$1")
     local fts_query; fts_query=$(eagle_sql_escape "$2")

package/lib/provider.sh

@@ -151,8 +151,9 @@ model = "claude-haiku-4-5-20251001"
 model = "gpt-4o-mini"
 
 [curator]
-# How often the curator runs: "manual", "daily", "weekly"
+# "auto" = triggers at session end after min_sessions; "manual" = CLI only
 schedule = "manual"
+min_sessions = 5
 
 [redaction]
 # Additional secret patterns (regex) beyond built-in defaults

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eagle-mem",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "Persistent memory for Claude Code — SQLite + FTS5, no daemon, no bloat",
   "bin": {
     "eagle-mem": "bin/eagle-mem"

package/scripts/curate.sh

@@ -361,5 +361,6 @@ echo ""
 if [ "$DRY_RUN" -eq 1 ]; then
     eagle_footer "Dry run complete. Run without --dry-run to apply changes."
 else
+    eagle_meta_set "last_curated_at" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$project"
     eagle_footer "Curation complete for '$project'."
 fi

package/scripts/health.sh

@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — Health Check
+# Diagnoses how well the self-learning pipeline is working
+# ═══════════════════════════════════════════════════════════
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LIB_DIR="$SCRIPT_DIR/../lib"
+
+. "$LIB_DIR/common.sh"
+. "$SCRIPT_DIR/style.sh"
+. "$LIB_DIR/db.sh"
+. "$LIB_DIR/provider.sh"
+
+eagle_header "Health Check"
+
+project=""
+JSON_OUT=0
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        -p|--project) project="$2"; shift 2 ;;
+        -j|--json) JSON_OUT=1; shift ;;
+        *) shift ;;
+    esac
+done
+
+if [ -z "$project" ]; then
+    project=$(eagle_project_from_cwd "$(pwd)")
+fi
+
+if [ -z "$project" ]; then
+    eagle_err "Cannot determine project (ephemeral directory). Use -p <project>."
+    exit 1
+fi
+
+p_esc=$(eagle_sql_escape "$project")
+
+eagle_info "Project: ${BOLD}$project${RESET}"
+echo ""
+
+score=0
+max_score=0
+issues=()
+
+# ─── 1. Summary enrichment rate ──────────────────────────
+
+max_score=$((max_score + 30))
+
+total_summaries=$(eagle_db "SELECT COUNT(*) FROM summaries WHERE project = '$p_esc';")
+enriched_summaries=$(eagle_db "SELECT COUNT(*) FROM summaries WHERE project = '$p_esc' AND (decisions IS NOT NULL AND decisions != '' OR gotchas IS NOT NULL AND gotchas != '' OR key_files IS NOT NULL AND key_files != '');")
+
+if [ "${total_summaries:-0}" -eq 0 ]; then
+    enrich_pct=0
+else
+    enrich_pct=$((enriched_summaries * 100 / total_summaries))
+fi
+
+if [ "$enrich_pct" -ge 50 ]; then
+    eagle_ok "Enriched summaries: ${enriched_summaries}/${total_summaries} (${enrich_pct}%)"
+    score=$((score + 30))
+elif [ "$enrich_pct" -ge 20 ]; then
+    eagle_warn "Enriched summaries: ${enriched_summaries}/${total_summaries} (${enrich_pct}%) — aim for 50%+"
+    score=$((score + 15))
+    issues+=("Low enrichment rate (${enrich_pct}%). Eagle-summary blocks aren't being emitted reliably.")
+elif [ "${total_summaries:-0}" -gt 0 ]; then
+    eagle_fail "Enriched summaries: ${enriched_summaries}/${total_summaries} (${enrich_pct}%) — self-learning not working"
+    issues+=("Critical: ${enrich_pct}% enrichment. Decisions/gotchas/key_files are not being captured.")
+else
+    eagle_dim "  No summaries yet"
+fi
+
+# ─── 2. Feature discovery ────────────────────────────────
+
+max_score=$((max_score + 20))
+
+feature_count=$(eagle_db "SELECT COUNT(*) FROM features WHERE project = '$p_esc' AND status = 'active';")
+feature_file_count=$(eagle_db "SELECT COUNT(*) FROM feature_files ff JOIN features f ON ff.feature_id = f.id WHERE f.project = '$p_esc' AND f.status = 'active';")
+
+if [ "${feature_count:-0}" -ge 3 ]; then
+    eagle_ok "Features tracked: ${feature_count} (${feature_file_count} files mapped)"
+    score=$((score + 20))
+elif [ "${feature_count:-0}" -ge 1 ]; then
+    eagle_warn "Features tracked: ${feature_count} — curator needs more sessions"
+    score=$((score + 10))
+    issues+=("Only ${feature_count} features discovered. Run curator more often.")
+else
+    eagle_fail "Features tracked: 0 — feature graph is empty"
+    issues+=("No features discovered. Run: eagle-mem curate")
+fi
+
+# ─── 3. Command intelligence ─────────────────────────────
+
+max_score=$((max_score + 15))
+
+rule_count=$(eagle_db "SELECT COUNT(*) FROM command_rules WHERE (project = '$p_esc' OR project IS NULL) AND enabled = 1;")
+obs_with_metrics=$(eagle_db "SELECT COUNT(*) FROM observations WHERE project = '$p_esc' AND tool_name = 'Bash' AND output_bytes IS NOT NULL AND output_bytes > 0;")
+
+if [ "${rule_count:-0}" -ge 2 ]; then
+    eagle_ok "Command rules: ${rule_count} active (${obs_with_metrics} observations with metrics)"
+    score=$((score + 15))
+elif [ "${rule_count:-0}" -ge 1 ]; then
+    eagle_warn "Command rules: ${rule_count} — learning in progress"
+    score=$((score + 8))
+elif [ "${obs_with_metrics:-0}" -gt 20 ]; then
+    eagle_fail "Command rules: 0 (but ${obs_with_metrics} observations available — run curator)"
+    issues+=("Command metrics collected but no rules generated yet.")
+else
+    eagle_dim "  Command metrics: ${obs_with_metrics} observations (need more data)"
+    score=$((score + 5))
+fi
+
+# ─── 4. Provider configured ──────────────────────────────
+
+max_score=$((max_score + 15))
+
+provider=$(eagle_config_get "provider" "type" "none")
+if [ "$provider" != "none" ]; then
+    model=$(eagle_config_get "$provider" "model" "default")
+    eagle_ok "LLM provider: ${provider} (${model})"
+    score=$((score + 15))
+else
+    eagle_fail "No LLM provider — curator and enrichment extraction disabled"
+    issues+=("Configure a provider: eagle-mem config init")
+fi
+
+# ─── 5. Project data quality ─────────────────────────────
+
+max_score=$((max_score + 10))
+
+tmp_sessions=$(eagle_db "SELECT COUNT(*) FROM sessions WHERE project IN ('tmp', 'private', '');")
+total_sessions=$(eagle_db "SELECT COUNT(*) FROM sessions;")
+
+if [ "${total_sessions:-0}" -eq 0 ]; then
+    noise_pct=0
+else
+    noise_pct=$((tmp_sessions * 100 / total_sessions))
+fi
+
+if [ "$noise_pct" -le 5 ]; then
+    eagle_ok "Data quality: ${tmp_sessions} ephemeral sessions (${noise_pct}% noise)"
+    score=$((score + 10))
+elif [ "$noise_pct" -le 20 ]; then
+    eagle_warn "Data quality: ${tmp_sessions} ephemeral sessions (${noise_pct}% noise)"
+    score=$((score + 5))
+    issues+=("${noise_pct}% of sessions from ephemeral dirs. Skiplist should prevent new ones.")
+else
+    eagle_fail "Data quality: ${noise_pct}% noise — ${tmp_sessions}/${total_sessions} sessions from ephemeral dirs"
+    issues+=("Heavy ephemeral pollution. Update Eagle Mem to get skiplist protection.")
+fi
+
+# ─── 6. Curator activity ─────────────────────────────────
+
+max_score=$((max_score + 10))
+
+curator_schedule=$(eagle_config_get "curator" "schedule" "manual")
+last_curated=$(eagle_db "SELECT value FROM eagle_meta WHERE key = 'last_curated_at' AND (project = '$p_esc' OR project IS NULL) ORDER BY CASE WHEN project IS NOT NULL THEN 0 ELSE 1 END LIMIT 1;" 2>/dev/null || echo "")
+
+if [ -n "$last_curated" ]; then
+    eagle_ok "Curator: last run ${last_curated} (schedule: ${curator_schedule})"
+    score=$((score + 10))
+elif [ "$curator_schedule" = "auto" ]; then
+    eagle_warn "Curator: auto-scheduled but hasn't run yet"
+    score=$((score + 5))
+    issues+=("Auto-curate is configured but hasn't run. It triggers at session end.")
+else
+    eagle_fail "Curator: never run (schedule: ${curator_schedule})"
+    issues+=("Curator has never run. Try: eagle-mem curate --dry-run")
+fi
+
+# ─── Score ────────────────────────────────────────────────
+
+echo ""
+echo -e "  ${DIM}─────────────────────────────────────${RESET}"
+
+pct=$((score * 100 / max_score))
+if [ "$pct" -ge 80 ]; then
+    color="$GREEN"
+    grade="Healthy"
+elif [ "$pct" -ge 50 ]; then
+    color="$YELLOW"
+    grade="Needs attention"
+else
+    color="$RED"
+    grade="Unhealthy"
+fi
+
+echo -e "  ${BOLD}Score: ${color}${score}/${max_score} (${pct}%)${RESET}  ${color}${grade}${RESET}"
+
+if [ ${#issues[@]} -gt 0 ]; then
+    echo ""
+    echo -e "  ${BOLD}Issues:${RESET}"
+    for issue in "${issues[@]}"; do
+        echo -e "    ${YELLOW}!${RESET} $issue"
+    done
+fi
+
+eagle_footer "Health check complete."
+
+if [ "$JSON_OUT" -eq 1 ]; then
+    jq -nc \
+        --arg project "$project" \
+        --argjson score "$score" \
+        --argjson max_score "$max_score" \
+        --argjson pct "$pct" \
+        --arg grade "$grade" \
+        --argjson total_summaries "${total_summaries:-0}" \
+        --argjson enriched_summaries "${enriched_summaries:-0}" \
+        --argjson features "${feature_count:-0}" \
+        --argjson command_rules "${rule_count:-0}" \
+        --arg provider "$provider" \
+        --argjson noise_pct "$noise_pct" \
+        '{project:$project, score:$score, max:$max_score, pct:$pct, grade:$grade,
+          enrichment:{total:$total_summaries, enriched:$enriched_summaries},
+          features:$features, command_rules:$command_rules,
+          provider:$provider, noise_pct:$noise_pct}'
+fi

package/scripts/help.sh

@@ -27,6 +27,7 @@ echo -e "    ${CYAN}prune${RESET}       Remove old observations and orphaned chu
 echo -e "    ${CYAN}config${RESET}      View or change LLM provider settings"
 echo -e "    ${CYAN}curate${RESET}      Run the self-learning curator (LLM-powered analysis)"
 echo -e "    ${CYAN}feature${RESET}     Manage feature graph (list/show/verify/add)"
+echo -e "    ${CYAN}health${RESET}      Diagnose self-learning pipeline health"
 echo -e "    ${CYAN}install${RESET}     First-time setup: hooks, database, skills"
 echo -e "    ${CYAN}update${RESET}      Re-deploy hooks and run migrations"
 echo -e "    ${CYAN}uninstall${RESET}   Remove hooks and optionally delete data"