eagle-mem 4.13.0 → 4.14.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to the **Eagle Mem** project are documented here.
 
 ---
 
+## v4.14.0 Governance Parity & Curator Provenance
+
+Two trust-surface features that close the remaining governance gaps from the v4.13.0 review.
+
+- **Release-gate parity at the git layer (`eagle-mem gate`).** The feature-verification gate was enforced only in `PreToolUse`, so a bare-shell `git push` or a Grok session (no hook lifecycle) bypassed governance entirely. New `eagle-mem gate`:
+  - `gate check` runs the same reconcile-and-block logic as the hook for the current repo (exit 1 when verifications are pending). It **fails open** (exit 0) when Eagle Mem is disabled, has no database, or the directory isn't a recognized project — a git hook must never wedge unrelated pushes.
+  - `gate install [--repo PATH] [--force]` installs an **opt-in, repo-local** `pre-push` hook that calls `gate check`, and **refuses to clobber** a pre-existing non-Eagle-Mem hook. `gate uninstall` removes only the managed hook.
+  - Bypass a single push with `git push --no-verify` or `EAGLE_MEM_DISABLE_HOOKS=1 git push`.
+  - Opt-in by design (Eagle Mem installs agent hooks globally but does not silently add git hooks to every repo). The cross-agent enforcement scope is documented in `docs/agent-compatibility/README.md`.
+- **Provenance + trust gate for curator-generated command rules.** Command rules steer `PreToolUse` output handling (`truncate` appends `| head -N`; `summary` adds a hint). They could be authored by the LLM curator with only format-level validation. Migration 045 adds `command_rules.source` (`manual` | `curator`); the curator tags its rules `curator`; and `eagle_get_command_rule` honors `token_guard.trust_learned_rules` (default **true**, preserving auto-learning). Set it `false` to apply only human-authored rules, so model output cannot silently shape command handling. (Guardrails already carried provenance; the actual command rewrite path is code-derived, not LLM-derived — so the gap was scoped to command rules.)
+- **Performance proposals evaluated, intentionally not implemented.** The deferred Phase 4 micro-optimizations were assessed and found net-negative: a PostToolUse zero-state short-circuit adds a query to the common populated case to save queries only in rare empty projects; UserPromptSubmit query consolidation entangles three differently-ranked FTS queries to save ~1 process spawn; a provider output cache has a near-zero hit rate because enrichment prompts embed unique per-session transcript excerpts. The meaningful token-economy win (the SessionStart injection ceiling) shipped in v4.13.0.
+
+New coverage: `tests/test_release_gate_prepush.sh`, `tests/test_command_rule_provenance.sh`.
+
+---
+
+## v4.13.1 Test-Suite & Packaging Hygiene
+
+Follow-up cleanup that clears the bounded items left after the v4.13.0 review. No runtime behavior change for normal sessions.
+
+- **`eagle-mem test` is now green from a published install.** Two suites failed when run from an installed package rather than a source checkout:
+  - *Compaction Survival Matrix* created its fixture repo inside `$ROOT_DIR`; from a published install that path is under `node_modules/`, which the code scanner excludes — so the fixture indexed 0 files and the post-compact "Relevant Code" recall never appeared. The fixture now lives in a neutral system temp dir and is indexed explicitly (no longer relying on a racy background auto-index).
+  - *Rust Migration Plan* guards `MIGRATION.md`, a maintainer roadmap intentionally not shipped in the npm package. It now **skips cleanly** when the doc is absent and runs strictly from a source checkout.
+  - The test runner learned an honest **"skipped"** state (a dev-only contract test with absent preconditions is neither a pass nor a failure).
+- **Antigravity Python hook test is now in the suite.** `tests/test_antigravity_hook.py` (mocked, stdlib-only) ran only by hand before; it's now a guarded python lane that skips cleanly if `python3` is unavailable.
+- **One source of truth for Claude hook registration.** `install.sh` and `update.sh` each held their own copy of the event→matcher→script mapping (the historical drift class). Extracted `eagle_register_claude_hooks` into `lib/hooks.sh`; both call it (installer verbose, updater quiet). Behavior preserved exactly.
+- **Dead-function sweep — analyzed, nothing removed.** A full cross-surface call-graph (`.sh`/`.py`/`.js`/skills/`bin`, 280 functions) found zero unreferenced functions and no computed-name dispatch; the "no shell caller" candidates are all reached via tests, skills, adapters, or the public CLI. Removing any would be regression risk with no benefit.
+
+---
+
 ## v4.13.0 Full-Spectrum Security & Reliability Hardening
 
 A six-lens fix-in-place review of the whole codebase (security, data integrity, reliability, token economy, code quality, architecture). 32 files hardened, 6 new regression suites, full smoke suite green. No behavioral surface for normal sessions changed — recall and capture are byte-for-byte the same; what changed is the failure, concurrency, and trust behavior underneath.

package/bin/eagle-mem

@@ -31,6 +31,7 @@ case "$command" in
     updates)    bash "$SCRIPTS_DIR/updates.sh" "$@" ;;
     statusline) "$SCRIPTS_DIR/statusline-em.sh" "$@" ;;
     guard)      bash "$SCRIPTS_DIR/guard.sh" "$@" ;;
+    gate)       bash "$SCRIPTS_DIR/gate.sh" "$@" ;;
     overview)   bash "$SCRIPTS_DIR/overview.sh" "$@" ;;
     graph)      bash "$SCRIPTS_DIR/memories.sh" graph "$@" ;;
     session|sessions)

package/db/045_command_rules_source.sql

@@ -0,0 +1,14 @@
+-- Migration 045: Command-rule provenance
+-- command_rules steer output handling (truncate / summary) in the PreToolUse
+-- hook. They can be authored by a human OR generated by the LLM curator from
+-- observed command patterns. Tag who authored each rule so model-derived rules
+-- are auditable and can be excluded from enforcement when desired:
+--   'manual'  — human-authored (default; trusted)
+--   'curator' — generated by the LLM curator (eagle-mem curate)
+-- Default 'manual' preserves every existing row and the current behavior. The
+-- getter (eagle_get_command_rule) honors `token_guard.trust_learned_rules`
+-- (default true); set it false to apply only 'manual' rules.
+
+ALTER TABLE command_rules ADD COLUMN source TEXT NOT NULL DEFAULT 'manual';
+
+CREATE INDEX IF NOT EXISTS idx_command_rules_source ON command_rules(source);

package/docs/agent-compatibility/README.md

@@ -36,3 +36,18 @@ The compatibility gate applies to these file groups:
 - `CLAUDE.md` when present
 
 The test `tests/test_agent_compatibility_docs_gate.sh` enforces that these docs and fixtures exist. When sensitive files are changed in an uncommitted worktree, the same test also requires a changed compatibility doc or agent-hook fixture in the same diff.
+
+## Release-Gate Enforcement Scope
+
+The feature-verification release gate (blocking `git push` / `npm publish` / `gh pr create` while changed files map to unverified features) is enforced inside `PreToolUse` for agents that have a hook lifecycle: **Claude Code** and **Codex** (and, via the plugin adapter, **OpenCode**). Two paths historically bypassed it:
+
+- **Grok** is skills-and-CLI only — it has no hook lifecycle, so nothing intercepts its tool calls.
+- A **bare-shell `git push`** (any terminal, any agent, or none) never reaches `PreToolUse`.
+
+`eagle-mem gate` closes this gap at the git layer so governance is not silently skippable:
+
+- `eagle-mem gate check` runs the same reconcile-and-block logic as the hook for the current repo, exiting non-zero when verifications are pending. It **fails open** (exit 0) when Eagle Mem is disabled (`EAGLE_MEM_DISABLE_HOOKS=1`), has no database, or the directory is not a recognized project — a git hook must never wedge unrelated pushes.
+- `eagle-mem gate install [--repo PATH] [--force]` installs an **opt-in, repo-local** `pre-push` hook that calls `gate check`. It refuses to clobber a pre-existing non-Eagle-Mem `pre-push` hook unless `--force` is given. `eagle-mem gate uninstall` removes only the Eagle-Mem-managed hook.
+- Bypass a single push with `git push --no-verify` (skips git hooks) or `EAGLE_MEM_DISABLE_HOOKS=1 git push`.
+
+This is opt-in by design: Eagle Mem installs agent hooks globally but does not silently add git hooks to every repository. Coverage proof: `tests/test_release_gate_prepush.sh` (blocks on pending, fails open, install/foreign-protection/uninstall).

package/lib/db-observations.sh

@@ -90,9 +90,26 @@ eagle_get_command_rule() {
     local project; project=$(eagle_sql_escape "$1")
     local base_cmd; base_cmd=$(eagle_sql_escape "$2")
     local full_cmd; full_cmd=$(eagle_sql_escape "${3:-$2}")
+
+    # Provenance gate: command_rules are human-authored ('manual') or generated
+    # by the LLM curator ('curator'). When token_guard.trust_learned_rules is
+    # false, only human-authored rules may steer command handling — model-derived
+    # rules are excluded so LLM output cannot silently shape execution. Default
+    # true preserves the auto-learning behavior. COALESCE guards rows written
+    # before migration 045 (treated as 'manual').
+    local trust
+    if declare -F eagle_config_get >/dev/null 2>&1; then
+        trust=$(eagle_config_get "token_guard" "trust_learned_rules" "true")
+    else
+        trust=$(eagle_config_get_light "token_guard" "trust_learned_rules" "true")
+    fi
+    local source_filter=""
+    [ "$trust" = "false" ] && source_filter="AND COALESCE(source, 'manual') = 'manual'"
+
     eagle_db "SELECT strategy, max_lines, reason
         FROM command_rules
         WHERE enabled = 1
+        $source_filter
         AND (project = '$project' OR project = '')
         AND ('$base_cmd' = pattern OR '$full_cmd' = pattern OR '$full_cmd' LIKE pattern || ' %')
         ORDER BY CASE WHEN project != '' THEN 0 ELSE 1 END,

package/lib/hooks.sh

@@ -100,3 +100,40 @@ eagle_patch_hook() {
     [ -n "$description" ] && eagle_ok "$description"
     return 0
 }
+
+# Register (idempotently) the full Claude Code hook set into a settings.json.
+# Single source of truth for the event→matcher→script mapping so install.sh and
+# update.sh can never drift (the historical bug class). Requires $EAGLE_MEM_DIR.
+#   $1 = settings.json path
+#   $2 = "verbose" to print a "✓ <Event> hook" line per registration (installer);
+#        omitted/anything else = quiet (updater prints its own summary line).
+eagle_register_claude_hooks() {
+    local settings="$1"
+    local V=""
+    [ "${2:-}" = "verbose" ] && V=1
+
+    # Clean old registrations before re-registering (handles matcher changes across versions).
+    eagle_clean_hook_entries "$settings" "Stop" "$EAGLE_MEM_DIR/hooks/stop.sh"
+    eagle_clean_hook_entries "$settings" "PostToolUse" "$EAGLE_MEM_DIR/hooks/post-tool-use.sh"
+    eagle_clean_hook_entries "$settings" "PreToolUse" "$EAGLE_MEM_DIR/hooks/pre-tool-use.sh"
+
+    # ${V:+label} expands to the label only in verbose mode; otherwise to "",
+    # which makes eagle_patch_hook silent (it only prints when given a description).
+    eagle_patch_hook "$settings" "SessionStart" "" "$EAGLE_MEM_DIR/hooks/session-start.sh" "${V:+SessionStart hook}"
+    eagle_patch_hook "$settings" "Stop" "" "bash \"$EAGLE_MEM_DIR/hooks/stop.sh\"" "${V:+Stop hook}"
+    eagle_patch_hook "$settings" "PostToolUse" "Read|Write|Edit|Bash|TaskUpdate" "$EAGLE_MEM_DIR/hooks/post-tool-use.sh" "${V:+PostToolUse hook}"
+    eagle_patch_hook "$settings" "TaskCreated" "" "$EAGLE_MEM_DIR/hooks/post-tool-use.sh" "${V:+TaskCreated hook}"
+    eagle_patch_hook "$settings" "TaskCompleted" "" "$EAGLE_MEM_DIR/hooks/post-tool-use.sh" "${V:+TaskCompleted hook}"
+    eagle_patch_hook "$settings" "SessionEnd" "" "$EAGLE_MEM_DIR/hooks/session-end.sh" "${V:+SessionEnd hook}"
+    eagle_patch_hook "$settings" "UserPromptSubmit" "" "$EAGLE_MEM_DIR/hooks/user-prompt-submit.sh" "${V:+UserPromptSubmit hook}"
+    eagle_patch_hook "$settings" "PreToolUse" "Bash|Read|Edit|Write" "$EAGLE_MEM_DIR/hooks/pre-tool-use.sh" "${V:+PreToolUse hook}"
+
+    # Allow agent-issued session capture to run without a permission prompt.
+    if eagle_patch_permission_allow "$settings" "Bash(eagle-mem session save:*)"; then
+        [ -n "$V" ] && eagle_ok "Capture permission ${DIM}(eagle-mem session save)${RESET}"
+    fi
+    # Explicit success: the trailing conditional above evaluates false in quiet
+    # mode (V empty), which would otherwise make this function return 1 and abort
+    # a `set -e` caller (update.sh) right after a fully successful registration.
+    return 0
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eagle-mem",
-  "version": "4.13.0",
+  "version": "4.14.0",
   "description": "Shared memory, release guardrails, RTK token protection, and worker lanes for Claude Code, Codex, OpenCode, Grok, and Google Antigravity",
   "bin": {
     "eagle-mem": "bin/eagle-mem"

package/scripts/curate.sh

@@ -316,12 +316,15 @@ If no rules needed, output: NONE"
                             ml_val="${max_lines:-NULL}"
                             [ "$ml_val" != "NULL" ] && ml_val=$(eagle_sql_int "$ml_val")
 
-                            eagle_db "INSERT INTO command_rules (project, pattern, strategy, max_lines, reason)
-                                VALUES ('$p_esc', '$pattern_esc', '$strategy', $ml_val, '$reason_esc')
+                            # Tag provenance: these rules are LLM-derived. They can be
+                            # excluded from enforcement via token_guard.trust_learned_rules=false.
+                            eagle_db "INSERT INTO command_rules (project, pattern, strategy, max_lines, reason, source)
+                                VALUES ('$p_esc', '$pattern_esc', '$strategy', $ml_val, '$reason_esc', 'curator')
                                 ON CONFLICT(project, pattern) DO UPDATE SET
                                     strategy = excluded.strategy,
                                     max_lines = excluded.max_lines,
                                     reason = excluded.reason,
+                                    source = 'curator',
                                     updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now');"
                             eagle_log "INFO" "Curator: added command rule: $pattern → $strategy"
                         fi

package/scripts/gate.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — Release gate (git-layer parity)
+#
+# The PreToolUse hook already blocks release-boundary commands for Claude and
+# Codex. But a bare-shell `git push`, or a Grok session (which has no hook
+# lifecycle), bypasses that gate entirely. This brings the SAME feature-
+# verification gate to the git layer via an opt-in `pre-push` hook, so
+# governance is not silently skippable regardless of which agent (or no agent)
+# runs the push.
+#
+#   eagle-mem gate check            run the gate for the current repo (exit 1 if blocked)
+#   eagle-mem gate install [--repo PATH] [--force]
+#                                   install a repo-local .git/hooks/pre-push that runs `gate check`
+#   eagle-mem gate uninstall [--repo PATH]
+#                                   remove the Eagle Mem pre-push hook (only if it's ours)
+#
+# Bypass a single push: `git push --no-verify` or `EAGLE_MEM_DISABLE_HOOKS=1 git push`.
+# ═══════════════════════════════════════════════════════════
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LIB_DIR="$SCRIPT_DIR/../lib"
+
+. "$LIB_DIR/common.sh"
+. "$LIB_DIR/db.sh"
+. "$SCRIPT_DIR/style.sh"
+
+HOOK_SENTINEL="# eagle-mem-managed-pre-push"
+
+gate_check() {
+    # Fail OPEN in any situation where blocking would be wrong: explicitly
+    # disabled, no database yet, or not inside a recognized project. A git hook
+    # must never wedge pushes just because Eagle Mem isn't set up here.
+    [ "${EAGLE_MEM_DISABLE_HOOKS:-}" = "1" ] && exit 0
+    [ -f "$EAGLE_MEM_DB" ] || exit 0
+
+    local cwd project
+    cwd="$(pwd)"
+    project=$(eagle_project_from_cwd "$cwd")
+    [ -z "$project" ] && exit 0
+
+    local release_changed_files
+    release_changed_files=$(eagle_changed_files_for_release "$cwd" 2>/dev/null || true)
+    eagle_reconcile_current_feature_verifications "$project" "$cwd" "git-prepush" "git-push" \
+        "Release boundary detected for current repository diff" "$release_changed_files" >/dev/null 2>&1 || true
+
+    local pending_rows pending_count
+    pending_rows=$(eagle_list_current_pending_feature_verifications "$project" "$cwd" "$release_changed_files" 8 2>/dev/null || true)
+    pending_count=$(printf '%s\n' "$pending_rows" | sed '/^[[:space:]]*$/d' | wc -l | tr -d ' ')
+    pending_count=${pending_count:-0}
+
+    if [ "$pending_count" -gt 0 ] 2>/dev/null; then
+        {
+            echo ""
+            echo "Eagle Mem blocked this push because ${pending_count} feature verification(s) are pending."
+            echo ""
+            echo "Resolve them, then push again:"
+            echo "  eagle-mem feature verify <name> --notes \"what passed\""
+            echo "  eagle-mem feature waive <id> --reason \"why this is safe\""
+            echo ""
+            echo "Pending checks:"
+            while IFS='|' read -r pid pname pfile preason _ptrigger _pcreated psmoke pfingerprint; do
+                [ -z "$pid" ] && continue
+                local line="  #${pid} ${pname}"
+                [ -n "$pfile" ] && line+=" (${pfile})"
+                [ -n "$preason" ] && line+=" — ${preason}"
+                [ -n "$psmoke" ] && line+=" | smoke: ${psmoke}"
+                [ -n "$pfingerprint" ] && line+=" | diff: ${pfingerprint}"
+                echo "$line"
+            done <<< "$pending_rows"
+            echo ""
+            echo "Bypass once: git push --no-verify   (or EAGLE_MEM_DISABLE_HOOKS=1 git push)"
+        } >&2
+        exit 1
+    fi
+    exit 0
+}
+
+# Resolve the .git/hooks dir for a repo (handles worktrees and submodules).
+gate_hooks_dir() {
+    local repo="$1"
+    ( cd "$repo" 2>/dev/null && git rev-parse --git-path hooks 2>/dev/null )
+}
+
+gate_install() {
+    local repo="" force=0
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --repo) repo="${2:-}"; shift 2 ;;
+            --force|-f) force=1; shift ;;
+            *) shift ;;
+        esac
+    done
+    repo="${repo:-$(pwd)}"
+
+    if ! ( cd "$repo" 2>/dev/null && git rev-parse --is-inside-work-tree >/dev/null 2>&1 ); then
+        eagle_err "Not a git repository: $repo"
+        exit 1
+    fi
+
+    local hooks_dir hook
+    hooks_dir="$(gate_hooks_dir "$repo")"
+    # git rev-parse --git-path returns a path relative to the repo; resolve it.
+    case "$hooks_dir" in
+        /*) ;;
+        *) hooks_dir="$repo/$hooks_dir" ;;
+    esac
+    mkdir -p "$hooks_dir"
+    hook="$hooks_dir/pre-push"
+
+    if [ -f "$hook" ] && ! grep -qF "$HOOK_SENTINEL" "$hook" 2>/dev/null && [ "$force" -ne 1 ]; then
+        eagle_err "A non-Eagle-Mem pre-push hook already exists: $hook"
+        eagle_info "Re-run with --force to replace it, or add this line to your hook manually:"
+        eagle_dim "  command -v eagle-mem >/dev/null 2>&1 && eagle-mem gate check"
+        exit 1
+    fi
+
+    cat > "$hook" <<EOF
+#!/usr/bin/env bash
+$HOOK_SENTINEL
+# Runs the Eagle Mem feature-verification gate before every push.
+# Fail-open if eagle-mem is unavailable so pushes never wedge on a missing tool.
+command -v eagle-mem >/dev/null 2>&1 || exit 0
+exec eagle-mem gate check
+EOF
+    chmod +x "$hook"
+    eagle_ok "Installed Eagle Mem pre-push gate: $hook"
+    eagle_dim "Bypass once with: git push --no-verify"
+}
+
+gate_uninstall() {
+    local repo="" ; repo="${1:-}"
+    [ "$repo" = "--repo" ] && { repo="${2:-}"; }
+    repo="${repo:-$(pwd)}"
+    local hooks_dir hook
+    hooks_dir="$(gate_hooks_dir "$repo")"
+    case "$hooks_dir" in /*) ;; *) hooks_dir="$repo/$hooks_dir" ;; esac
+    hook="$hooks_dir/pre-push"
+    if [ -f "$hook" ] && grep -qF "$HOOK_SENTINEL" "$hook" 2>/dev/null; then
+        rm -f "$hook"
+        eagle_ok "Removed Eagle Mem pre-push gate: $hook"
+    else
+        eagle_info "No Eagle Mem pre-push gate found for: $repo"
+    fi
+}
+
+subcommand="${1:-check}"
+shift 2>/dev/null || true
+case "$subcommand" in
+    check)      gate_check ;;
+    install)    gate_install "$@" ;;
+    uninstall)  gate_uninstall "$@" ;;
+    *)
+        eagle_err "Unknown gate command: $subcommand"
+        eagle_info "Usage: eagle-mem gate [check|install|uninstall]"
+        exit 1
+        ;;
+esac

package/scripts/install.sh

@@ -283,47 +283,9 @@ if [ "$claude_found" = true ]; then
             echo '{}' > "$SETTINGS"
         fi
 
-        eagle_patch_hook "$SETTINGS" "SessionStart" "" \
-            "$EAGLE_MEM_DIR/hooks/session-start.sh" \
-            "SessionStart hook"
-
-        # Clean old registrations before re-registering (handles matcher changes across versions)
-        eagle_clean_hook_entries "$SETTINGS" "Stop" "$EAGLE_MEM_DIR/hooks/stop.sh"
-        eagle_clean_hook_entries "$SETTINGS" "PostToolUse" "$EAGLE_MEM_DIR/hooks/post-tool-use.sh"
-        eagle_clean_hook_entries "$SETTINGS" "PreToolUse" "$EAGLE_MEM_DIR/hooks/pre-tool-use.sh"
-
-        eagle_patch_hook "$SETTINGS" "Stop" "" \
-            "bash \"$EAGLE_MEM_DIR/hooks/stop.sh\"" \
-            "Stop hook"
-
-        eagle_patch_hook "$SETTINGS" "PostToolUse" "Read|Write|Edit|Bash|TaskUpdate" \
-            "$EAGLE_MEM_DIR/hooks/post-tool-use.sh" \
-            "PostToolUse hook"
-
-        eagle_patch_hook "$SETTINGS" "TaskCreated" "" \
-            "$EAGLE_MEM_DIR/hooks/post-tool-use.sh" \
-            "TaskCreated hook"
-
-        eagle_patch_hook "$SETTINGS" "TaskCompleted" "" \
-            "$EAGLE_MEM_DIR/hooks/post-tool-use.sh" \
-            "TaskCompleted hook"
-
-        eagle_patch_hook "$SETTINGS" "SessionEnd" "" \
-            "$EAGLE_MEM_DIR/hooks/session-end.sh" \
-            "SessionEnd hook"
-
-        eagle_patch_hook "$SETTINGS" "UserPromptSubmit" "" \
-            "$EAGLE_MEM_DIR/hooks/user-prompt-submit.sh" \
-            "UserPromptSubmit hook"
-
-        eagle_patch_hook "$SETTINGS" "PreToolUse" "Bash|Read|Edit|Write" \
-            "$EAGLE_MEM_DIR/hooks/pre-tool-use.sh" \
-            "PreToolUse hook"
-
-        # Allow agent-issued session capture to run without a permission prompt
-        if eagle_patch_permission_allow "$SETTINGS" "Bash(eagle-mem session save:*)"; then
-            eagle_ok "Capture permission ${DIM}(eagle-mem session save)${RESET}"
-        fi
+        # Single source of truth for the Claude hook set (see lib/hooks.sh);
+        # verbose mode prints a line per registration.
+        eagle_register_claude_hooks "$SETTINGS" verbose
     fi
 else
     eagle_info "Claude hooks skipped ${DIM}(Claude Code not detected)${RESET}"

package/scripts/test.sh

@@ -16,13 +16,24 @@ eagle_banner
 eagle_header "Smoke Tests"
 
 errors=0
+skipped=0
 
 run_check() {
     local name="$1"
     local cmd="$2"
     echo -e "  ${BOLD}→${RESET} $name"
-    if eval "$cmd" >/dev/null 2>&1; then
+    local rc=0
+    eval "$cmd" >/dev/null 2>&1 || rc=$?
+    if [ "$rc" -eq 0 ]; then
         eagle_ok "$name"
+    elif [ "$rc" -eq 2 ]; then
+        # Exit code 2 = the check skipped itself because its preconditions are
+        # absent in this environment — e.g. a dev-only contract test running
+        # from a published install, where the maintainer doc it guards is not
+        # shipped in the npm package. A skip is neither a pass nor a failure, so
+        # it must not increment the error count or fail the suite.
+        eagle_info "skipped: $name (preconditions not present here)"
+        skipped=$((skipped + 1))
     else
         eagle_fail "$name"
         # Assignment form (not ((errors++))) so a failing check does not abort
@@ -80,10 +91,19 @@ run_check "Data Integrity Hardening (migrate idempotency, SQL escaping, summary
 run_check "Mod-Tracker Concurrency (lock TTL, no lost append, observation dedup race)" "bash \"$SCRIPTS_DIR/../tests/test_mod_tracker_concurrency.sh\""
 run_check "Reliability Retention (scan in-flight vs freshness, eagle_events prune)" "bash \"$SCRIPTS_DIR/../tests/test_reliability_retention.sh\""
 run_check "Test Runner No-Abort (failing check does not kill the suite under set -e)" "bash \"$SCRIPTS_DIR/../tests/test_test_runner_no_abort.sh\""
+# Python lane: the native Antigravity hook (mocked). Subshell-wrapped so a
+# missing python3 yields a clean skip (exit 2) instead of aborting the suite.
+run_check "Antigravity Hook (native Python SDK lifecycle, mocked)" "( command -v python3 >/dev/null 2>&1 || exit 2; python3 \"$SCRIPTS_DIR/../tests/test_antigravity_hook.py\" )"
+run_check "Release Gate Parity (eagle-mem gate: blocks pending, fails open, pre-push install)" "bash \"$SCRIPTS_DIR/../tests/test_release_gate_prepush.sh\""
+run_check "Command Rule Provenance (curator rules tagged + trust_learned_rules gate)" "bash \"$SCRIPTS_DIR/../tests/test_command_rule_provenance.sh\""
 
 echo ""
 if [ "$errors" -eq 0 ]; then
-    eagle_ok "All smoke tests passed"
+    if [ "$skipped" -gt 0 ]; then
+        eagle_ok "All smoke tests passed ($skipped skipped — preconditions not present here)"
+    else
+        eagle_ok "All smoke tests passed"
+    fi
     
     # Auto-verify the 7 core features in the database
     for feat in "compaction-survival" "feature-verification" "grok-cli-integration" "agent-orchestration" "Cross Agent Memory" "Installer And Updater" "Code Scan And Index"; do

package/scripts/update.sh

@@ -86,23 +86,9 @@ fi
 # ─── Re-register hooks (idempotent) ───────────────────────
 
 if [ "$claude_found" = true ] && [ -f "$SETTINGS" ] && command -v jq &>/dev/null; then
-    # Clean old registrations before re-registering (handles matcher changes across versions)
-    eagle_clean_hook_entries "$SETTINGS" "Stop" "$EAGLE_MEM_DIR/hooks/stop.sh"
-    eagle_clean_hook_entries "$SETTINGS" "PostToolUse" "$EAGLE_MEM_DIR/hooks/post-tool-use.sh"
-    eagle_clean_hook_entries "$SETTINGS" "PreToolUse" "$EAGLE_MEM_DIR/hooks/pre-tool-use.sh"
-
-    eagle_patch_hook "$SETTINGS" "SessionStart" "" "$EAGLE_MEM_DIR/hooks/session-start.sh"
-    eagle_patch_hook "$SETTINGS" "Stop" "" "bash \"$EAGLE_MEM_DIR/hooks/stop.sh\""
-    eagle_patch_hook "$SETTINGS" "PostToolUse" "Read|Write|Edit|Bash|TaskUpdate" "$EAGLE_MEM_DIR/hooks/post-tool-use.sh"
-    eagle_patch_hook "$SETTINGS" "TaskCreated" "" "$EAGLE_MEM_DIR/hooks/post-tool-use.sh"
-    eagle_patch_hook "$SETTINGS" "TaskCompleted" "" "$EAGLE_MEM_DIR/hooks/post-tool-use.sh"
-    eagle_patch_hook "$SETTINGS" "SessionEnd" "" "$EAGLE_MEM_DIR/hooks/session-end.sh"
-    eagle_patch_hook "$SETTINGS" "UserPromptSubmit" "" "$EAGLE_MEM_DIR/hooks/user-prompt-submit.sh"
-    eagle_patch_hook "$SETTINGS" "PreToolUse" "Bash|Read|Edit|Write" "$EAGLE_MEM_DIR/hooks/pre-tool-use.sh"
-
-    # Allow agent-issued session capture to run without a permission prompt
-    eagle_patch_permission_allow "$SETTINGS" "Bash(eagle-mem session save:*)"
-
+    # Single source of truth for the Claude hook set (see lib/hooks.sh); quiet
+    # mode — the updater prints one summary line instead of per-hook lines.
+    eagle_register_claude_hooks "$SETTINGS"
     eagle_ok "Hooks registered"
 fi
 

package/tests/test_command_rule_provenance.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Curator command-rule provenance — closes the curator -> guardrail -> PreToolUse
+# loop where LLM output became enforcement input with no provenance.
+# command_rules steer PreToolUse output handling (truncate/summary). Curator-
+# generated rules are now tagged source='curator'; setting
+# token_guard.trust_learned_rules=false excludes them so model output cannot
+# silently shape command handling. Human ('manual') rules are unaffected.
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+tmp_dir=$(mktemp -d "${TMPDIR:-/tmp}/eagle-rule-prov.XXXXXX")
+trap 'rm -rf "$tmp_dir"' EXIT
+
+export HOME="$tmp_dir/home"
+export EAGLE_MEM_DIR="$tmp_dir/eagle-mem"
+mkdir -p "$HOME" "$EAGLE_MEM_DIR"
+
+. "$ROOT_DIR/lib/common.sh"
+"$ROOT_DIR/db/migrate.sh" >/dev/null
+. "$ROOT_DIR/lib/db.sh"
+
+pass=0; fail=0
+ok()  { echo "  ok: $1"; pass=$((pass+1)); }
+bad() { echo "  FAIL: $1"; fail=$((fail+1)); }
+
+project="rule-prov"
+p=$(eagle_sql_escape "$project")
+eagle_db "INSERT INTO command_rules (project, pattern, strategy, max_lines, reason, source)
+          VALUES ('$p','curatorcmd','truncate',50,'noisy','curator');" >/dev/null
+eagle_db "INSERT INTO command_rules (project, pattern, strategy, max_lines, reason, source)
+          VALUES ('$p','manualcmd','truncate',50,'noisy','manual');" >/dev/null
+
+# 1. provenance is persisted
+[ "$(eagle_db "SELECT source FROM command_rules WHERE pattern='curatorcmd';")" = "curator" ] \
+    && ok "curator rule stored with source=curator" || bad "curator source not persisted"
+[ "$(eagle_db "SELECT source FROM command_rules WHERE pattern='manualcmd';")" = "manual" ] \
+    && ok "manual rule stored with source=manual" || bad "manual source not persisted"
+
+# 2. default (no config) trusts learned rules — curator rule applies
+[ -n "$(eagle_get_command_rule "$project" "curatorcmd" "curatorcmd")" ] \
+    && ok "default: curator rule applies (auto-learning preserved)" \
+    || bad "default: curator rule should apply"
+
+# 3. trust_learned_rules=false excludes curator rules, keeps manual rules
+printf '[token_guard]\ntrust_learned_rules = false\n' > "$EAGLE_MEM_DIR/config.toml"
+[ -z "$(eagle_get_command_rule "$project" "curatorcmd" "curatorcmd")" ] \
+    && ok "trust=false: curator rule excluded from enforcement" \
+    || bad "trust=false: curator rule should be excluded"
+[ -n "$(eagle_get_command_rule "$project" "manualcmd" "manualcmd")" ] \
+    && ok "trust=false: manual rule still applies" \
+    || bad "trust=false: manual rule should still apply"
+
+# 4. the curator code path tags new rules as 'curator'
+grep -q "VALUES ('\$p_esc', '\$pattern_esc', '\$strategy', \$ml_val, '\$reason_esc', 'curator')" "$ROOT_DIR/scripts/curate.sh" \
+    && ok "curate.sh writes command rules with source='curator'" \
+    || bad "curate.sh does not tag command rules as curator"
+
+echo ""
+echo "test_command_rule_provenance: $pass passed, $fail failed"
+[ "$fail" -eq 0 ] || exit 1

package/tests/test_compaction_survival_matrix.sh

@@ -7,7 +7,12 @@ set -euo pipefail
 ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 EAGLE_BIN="$ROOT_DIR/bin/eagle-mem"
 
-tmp_dir=$(mktemp -d "$ROOT_DIR/.tmp-compaction-survival.XXXXXX")
+# Use a neutral system temp dir, NOT one inside $ROOT_DIR. From a published
+# install $ROOT_DIR lives under node_modules/, and the code scanner excludes
+# node_modules — so a fixture repo created here would index 0 files and the
+# post-compact "Relevant Code" recall would never appear (the suite is run from
+# the installed package via `eagle-mem test`).
+tmp_dir=$(mktemp -d "${TMPDIR:-/tmp}/eagle-compaction-survival.XXXXXX")
 trap 'rm -rf "$tmp_dir"' EXIT
 
 export HOME="$tmp_dir/home"
@@ -190,6 +195,13 @@ assert_json "$compaction_json" '
     and .metrics.semantic_graph_nodes >= 5
 ' "compaction --json did not report durable survival metrics"
 
+# Index the fixture code deterministically so the post-compact recall can
+# surface "Relevant Code". This previously relied on a background auto-index
+# that only won the race from a warm source checkout, so the assertion failed
+# when the suite ran from a published install via `eagle-mem test`. The
+# `index` command is synchronous, so chunks exist by the time the hook runs.
+( cd "$repo" && "$EAGLE_BIN" index >/dev/null 2>&1 )
+
 eagle_upsert_session "$post_session" "$project" "$repo" "test-model" "test" "codex" >/dev/null
 hook_input=$(jq -nc \
     --arg sid "$post_session" \

package/tests/test_release_gate_prepush.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Release-gate parity at the git layer (`eagle-mem gate`). The PreToolUse hook
+# blocks release-boundary commands for Claude/Codex; this proves the SAME
+# feature-verification gate is enforceable for bare-shell / Grok pushes via an
+# opt-in pre-push hook, blocks when verifications are pending, fails OPEN where
+# blocking would be wrong, and never clobbers a foreign pre-push hook.
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+BIN="$ROOT_DIR/bin/eagle-mem"
+tmp_dir=$(mktemp -d "${TMPDIR:-/tmp}/eagle-gate-prepush.XXXXXX")
+trap 'rm -rf "$tmp_dir"' EXIT
+
+export HOME="$tmp_dir/home"
+export EAGLE_MEM_DIR="$tmp_dir/eagle-mem"
+mkdir -p "$HOME" "$EAGLE_MEM_DIR"
+
+. "$ROOT_DIR/lib/common.sh"
+"$ROOT_DIR/db/migrate.sh" >/dev/null
+. "$ROOT_DIR/lib/db.sh"
+
+pass=0; fail=0
+ok()  { echo "  ok: $1"; pass=$((pass+1)); }
+bad() { echo "  FAIL: $1"; fail=$((fail+1)); }
+
+# ── git repo fixture with a committed, feature-mapped file ──────────────────
+project="gate-prepush-test"
+export EAGLE_MEM_PROJECT="$project"
+repo="$HOME/proj"; mkdir -p "$repo/src"
+(
+  cd "$repo"
+  git init -q
+  git config user.email t@example.com
+  git config user.name tester
+  printf 'console.log("v1");\n' > src/app.js
+  git add -A && git commit -qm init
+)
+
+eagle_upsert_feature "$project" "app-entry" "app entrypoint"
+fid=$(eagle_get_feature_id "$project" "app-entry")
+eagle_add_feature_file "$fid" "src/app.js" "entrypoint" >/dev/null
+
+# ── 1. clean working tree → gate passes ────────────────────────────────────
+if ( cd "$repo" && "$BIN" gate check ) >/dev/null 2>&1; then
+    ok "clean working tree passes the gate (exit 0)"
+else
+    bad "clean working tree should pass the gate"
+fi
+
+# ── 2. uncommitted change to a feature file → gate blocks ──────────────────
+printf 'console.log("v2");\n' > "$repo/src/app.js"
+out=$( cd "$repo" && "$BIN" gate check 2>&1 ) && rc=0 || rc=$?
+[ "$rc" -eq 1 ] && ok "pending verification blocks the push (exit 1)" || bad "expected block exit 1, got $rc"
+case "$out" in *"blocked this push"*) ok "block message is shown" ;; *) bad "block message missing: $out" ;; esac
+
+# ── 3. EAGLE_MEM_DISABLE_HOOKS bypasses even with a pending verification ────
+if ( cd "$repo" && EAGLE_MEM_DISABLE_HOOKS=1 "$BIN" gate check ) >/dev/null 2>&1; then
+    ok "EAGLE_MEM_DISABLE_HOOKS=1 bypasses the gate"
+else
+    bad "EAGLE_MEM_DISABLE_HOOKS=1 should bypass the gate"
+fi
+
+# ── 4. verifying the feature unblocks the gate ─────────────────────────────
+( cd "$repo" && "$BIN" feature verify "app-entry" --notes "tested" ) >/dev/null 2>&1 || true
+if ( cd "$repo" && "$BIN" gate check ) >/dev/null 2>&1; then
+    ok "verified feature unblocks the gate (exit 0)"
+else
+    bad "verified feature should unblock the gate"
+fi
+
+# ── 5. fail-open outside a recognized project ──────────────────────────────
+other=$(mktemp -d "$tmp_dir/other.XXXXXX")
+if ( cd "$other" && env -u EAGLE_MEM_PROJECT "$BIN" gate check ) >/dev/null 2>&1; then
+    ok "fails open outside a recognized project (exit 0)"
+else
+    bad "should fail open outside a recognized project"
+fi
+
+# ── 6. install writes a managed, executable pre-push hook ──────────────────
+rm -f "$repo/.git/hooks/pre-push"
+( cd "$repo" && "$BIN" gate install ) >/dev/null 2>&1 || true
+if [ -x "$repo/.git/hooks/pre-push" ] && grep -q "eagle-mem-managed-pre-push" "$repo/.git/hooks/pre-push"; then
+    ok "gate install writes a managed, executable pre-push hook"
+else
+    bad "gate install should write a managed pre-push hook"
+fi
+
+# ── 7. install refuses to clobber a FOREIGN pre-push hook ──────────────────
+printf '#!/bin/sh\necho keepme\n' > "$repo/.git/hooks/pre-push"
+if ( cd "$repo" && "$BIN" gate install ) >/dev/null 2>&1; then
+    bad "gate install should refuse a foreign pre-push hook"
+else
+    ok "gate install refuses to clobber a foreign pre-push hook"
+fi
+grep -q "echo keepme" "$repo/.git/hooks/pre-push" && ok "foreign pre-push hook preserved" || bad "foreign pre-push hook was clobbered"
+
+# ── 8. uninstall leaves a foreign hook alone ───────────────────────────────
+( cd "$repo" && "$BIN" gate uninstall ) >/dev/null 2>&1 || true
+grep -q "echo keepme" "$repo/.git/hooks/pre-push" && ok "uninstall leaves a foreign hook untouched" || bad "uninstall removed a foreign hook"
+
+echo ""
+echo "test_release_gate_prepush: $pass passed, $fail failed"
+[ "$fail" -eq 0 ] || exit 1

package/tests/test_rust_migration_plan.sh

@@ -18,7 +18,14 @@ require_contains() {
     fi
 }
 
-[ -f "$PLAN" ] || fail "missing MIGRATION.md"
+# MIGRATION.md is a maintainer-only roadmap and is intentionally NOT shipped in
+# the npm package (`files` allowlist), so this contract test has nothing to
+# guard when the suite runs from a published install via `eagle-mem test`.
+# Skip cleanly (exit 2) in that case; run strictly from a source checkout.
+if [ ! -f "$PLAN" ]; then
+    echo "skip: MIGRATION.md not present (dev-only contract test)" >&2
+    exit 2
+fi
 
 require_contains "~/.eagle-mem/memory\\.db" "the existing user database path"
 require_contains "compatibility wrapper" "the Bash compatibility wrapper"