feat(hooks): Replace SessionStart file-list loop with ranker (#78)

* feat(hooks): Replace SessionStart file-list loop with ranker

Replace the per-file list_decisions loop in on_session_start_decisions
with a single rank_related_decisions call that uses all five signals:
file paths, uncommitted diff (truncated 8192 bytes), recent commit SHAs,
recent assessment IDs (configurable lookback window), and quality score.

Add _get_uncommitted_diff and _get_recent_commit_shas helpers. Score
breakdown is included in Markdown via _format_decision_entry. No
fallback — ranker has internal padding via _MIN_CANDIDATE_THRESHOLD.

New config key: decisions.assessment_lookback_hours (default 48).

Refs GH-72
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(hooks): Normalize file paths before passing to ranker

Git-relative paths (e.g. src/app.py) must be normalized via
_normalize_path before passing to rank_related_decisions, which uses
exact/proximity matching against stored decision_files paths. Without
normalization, decisions linked with absolute or ./-prefixed paths
would not match.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs(test): Update stale docstring for ranker-based SessionStart

The docstring referenced the removed per-file list_decisions loop
and its 10-row cap. Updated to describe the current rank_related_decisions
behavior with include_contradicted=False.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: teslamint

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Relevance-based SessionStart reactivation** (#72) — SessionStart hook now uses `rank_related_decisions()` with full multi-signal ranking (file paths, uncommitted diff, recent commit SHAs, assessment IDs) instead of the per-file `list_decisions()` loop. Score breakdown is included in Markdown output. Assessment signal lookback is configurable via `decisions.assessment_lookback_hours` (default 48).
 - **Retrieval telemetry completeness** (#70) — PostToolUse and SessionStart hooks now record per-decision `retrieval_selections` rows alongside the existing `retrieval_events` row, threading `selection_id` into Markdown fallback files. `record_retrieval_event` and `record_retrieval_selection` in `core/telemetry.py` accept a `commit` parameter (default `True`) so hook callers can defer commits for atomicity.
 - **Extraction noise gate and confidence threshold** (#71) — `maybe_extract_decisions` now checks session quality before launching the extraction worker: sessions must have at least 1 checkpoint OR a configurable minimum number of turns with `files_touched` (`decisions.noise_gate_min_turns_with_files`, default 3). Additionally, `run_extraction` filters candidates below `decisions.candidate_min_confidence` (raised from 0.0 to 0.35) before persistence, preventing low-quality session-source candidates with no rationale or alternatives from entering the candidate pipeline.
 - **Contract-sync drift guards** — `tests/test_contract_sync.py` asserts `mcp/server.__all__` matches what `register_tools()` actually registers (driven by AST extraction of `server.py`'s module tuple, not a hardcoded copy), that every `ec_*` tool is present in the README `### Available Tools` section bidirectionally (catches stale rows as well as missing rows), that `decision_hooks` fallback filename constants are documented in README, and that the current `SCHEMA_VERSION` is cross-referenced in a CHANGELOG paragraph that also mentions "schema". Replaces `tests/test_mcp_registration.py`, whose hardcoded expected set had silently drifted (its registration loop omitted `tools.decision_candidates` and its expected set omitted the four candidate tools, so it passed via symmetric drift — the exact failure mode the v0.2.0 retrospective finding #2 named).

src/entirecontext/core/config.py

@@ -71,6 +71,7 @@
         "auto_extract": False,
         "show_related_on_start": False,
         "auto_promotion_contradicted_threshold": 2,
+        "assessment_lookback_hours": 48,
         "surface_on_tool_use": False,
         "surface_on_tool_use_turn_interval": 1,
         "surface_on_tool_use_limit": 3,

src/entirecontext/hooks/decision_hooks.py

@@ -42,6 +42,40 @@ def _post_tool_fallback_name(session_id: str) -> str:
     return f"{_POST_TOOL_FALLBACK_BASE}-{safe}.md"
 
 
+def _get_uncommitted_diff(repo_path: str) -> str | None:
+    """Return uncommitted diff text, truncated to 8192 bytes. Returns None on failure."""
+    try:
+        result = subprocess.run(
+            ["git", "diff", "HEAD"],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout[:8192]
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        pass
+    return None
+
+
+def _get_recent_commit_shas(repo_path: str, limit: int = 5) -> list[str]:
+    """Return recent commit SHAs. Returns empty list on failure."""
+    try:
+        result = subprocess.run(
+            ["git", "log", "--format=%H", f"-{limit}"],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return [s for s in result.stdout.strip().split("\n") if s]
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        pass
+    return []
+
+
 def _load_decisions_config(repo_path: str) -> dict:
     from ..core.config import load_config
 
@@ -117,6 +151,13 @@ def _format_decision_entry(d: dict, stale: bool = False) -> str:
         parts.append(f"  Files: {files}")
     if rationale_short:
         parts.append(f"  Rationale: {rationale_short}")
+    if d.get("score") is not None and d.get("score_breakdown"):
+        sb = d["score_breakdown"]
+        parts.append(
+            f"  Score: {d['score']:.1f}"
+            f" (file={sb.get('file_exact', 0)}+{sb.get('file_proximity', 0)},"
+            f" diff={sb.get('diff_relevance', 0)}, quality={sb.get('quality', 0)})"
+        )
     if d.get("selection_id"):
         parts.append(f"  Selection: {d['selection_id']}")
     return "\n".join(parts)
@@ -134,12 +175,7 @@ def on_session_start_decisions(data: dict[str, Any]) -> str | None:
         if not config.get("show_related_on_start", False):
             return None
 
-        from ..core.decisions import (
-            _apply_staleness_policy,
-            get_decision,
-            list_decisions,
-            resolve_successor_chain,
-        )
+        from ..core.decisions import _normalize_path, get_decision, list_decisions, rank_related_decisions
         from ..db import get_db
 
         conn = get_db(repo_path)
@@ -148,65 +184,44 @@ def on_session_start_decisions(data: dict[str, Any]) -> str | None:
             seen_ids: set[str] = set()
             display_limit = 5
 
-            # 1. Recently changed files → linked decisions.
-            # Use `list_decisions(file_path=f)` per changed file so path matching
-            # preserves the existing LIKE-contains semantics (handles `./src/app.py`
-            # vs `src/app.py` divergence between git output and stored decision_files).
-            # Staleness policy: contradicted rows are dropped by the policy filter,
-            # but superseded rows are intentionally kept so the loop below can walk
-            # their supersession chain and substitute the terminal successor.
+            # 1. Assemble signals and rank decisions via the full multi-signal ranker.
             changed_files = _get_recently_changed_files(repo_path)
-            file_related = []
-            if changed_files:
-                raw_seen: set[str] = set()
-                for f in changed_files:
-                    if len(seen_ids) >= display_limit:
-                        break
-
-                    # Push contradicted-exclusion down to SQL so the limit=10
-                    # row cap can't hide fresh/superseded candidates behind a
-                    # wall of contradicted rows (PR #55 Codex review).
-                    file_rows: list[dict] = []
-                    for d in list_decisions(conn, file_path=f, limit=10, include_contradicted=False):
-                        if d["id"] in raw_seen:
-                            continue
-                        raw_seen.add(d["id"])
-                        file_rows.append(d)
-
-                    if not file_rows:
-                        continue
+            diff_text = _get_uncommitted_diff(repo_path)
+            commit_shas = _get_recent_commit_shas(repo_path, limit=5)
 
-                    # SQL already dropped contradicted rows; the policy call
-                    # still enforces `include_superseded=True` so the chain
-                    # collapse branch below can substitute each one with its
-                    # terminal successor.
-                    kept, _stats = _apply_staleness_policy(
-                        file_rows,
-                        include_stale=True,
-                        include_superseded=True,
-                        include_contradicted=False,
-                    )
-                    for row in kept:
-                        if row["id"] in seen_ids:
-                            continue
-                        effective_id = row["id"]
-                        if row.get("staleness_status") == "superseded":
-                            if not row.get("superseded_by_id"):
-                                # No successor pointer — hide this orphaned record.
-                                continue
-                            terminal_id, terminal_status = resolve_successor_chain(conn, row["id"])
-                            if terminal_id == row["id"] or terminal_status in ("contradicted", "superseded"):
-                                # Unresolved chain or terminal is also filtered — skip.
-                                continue
-                            effective_id = terminal_id
-                            if effective_id in seen_ids:
-                                continue
-                        full = get_decision(conn, effective_id)
+            assessment_ids: list[str] = []
+            try:
+                from ..core.futures import list_assessments
+                from datetime import datetime, timedelta, timezone
+
+                lookback_hours = config.get("assessment_lookback_hours", 48)
+                since = (datetime.now(timezone.utc) - timedelta(hours=lookback_hours)).isoformat()
+                recent_assessments = list_assessments(conn, limit=20, since=since)
+                assessment_ids = [a["id"] for a in recent_assessments]
+            except Exception:
+                pass
+
+            normalized_files = [_normalize_path(f) for f in changed_files if _normalize_path(f)]
+
+            file_related: list[dict] = []
+            if normalized_files or diff_text or commit_shas or assessment_ids:
+                ranked = rank_related_decisions(
+                    conn,
+                    file_paths=normalized_files,
+                    diff_text=diff_text,
+                    commit_shas=commit_shas,
+                    assessment_ids=assessment_ids,
+                    limit=display_limit,
+                    include_contradicted=False,
+                )
+                for d in ranked:
+                    if d["id"] not in seen_ids:
+                        full = get_decision(conn, d["id"])
                         if full:
+                            full["score"] = d.get("score")
+                            full["score_breakdown"] = d.get("score_breakdown")
                             file_related.append(full)
-                            seen_ids.add(effective_id)
-                        if len(seen_ids) >= display_limit:
-                            break
+                            seen_ids.add(d["id"])
 
             # 2. Stale decisions — explicit status filter; separate from default policy.
             stale = list_decisions(conn, staleness_status="stale", limit=10)

tests/test_decision_hooks.py

@@ -213,7 +213,7 @@ def test_max_5_decisions(self, ec_repo, ec_db, monkeypatch):
         entries = [line for line in result.split("\n") if line.strip().startswith("- [")]
         assert len(entries) <= 5
 
-    def test_session_start_stops_querying_changed_files_after_display_cap(self, ec_repo, ec_db, monkeypatch):
+    def test_session_start_ranker_respects_display_limit(self, ec_repo, ec_db, monkeypatch):
         monkeypatch.setattr(
             "entirecontext.hooks.decision_hooks._load_decisions_config",
             lambda _: {"show_related_on_start": True},
@@ -226,37 +226,25 @@ def test_session_start_stops_querying_changed_files_after_display_cap(self, ec_r
 
         monkeypatch.setattr("entirecontext.hooks.decision_hooks._get_recently_changed_files", lambda _: changed_files)
 
-        from entirecontext.core.decisions import list_decisions as core_list_decisions
-
-        file_path_calls: list[str] = []
-
-        def spy_list_decisions(
-            conn,
-            staleness_status=None,
-            file_path=None,
-            limit=20,
-            include_contradicted=False,
-        ):
-            if file_path is not None:
-                file_path_calls.append(file_path)
-            return core_list_decisions(
-                conn,
-                staleness_status=staleness_status,
-                file_path=file_path,
-                limit=limit,
-                include_contradicted=include_contradicted,
-            )
+        from entirecontext.core.decisions import rank_related_decisions as core_ranker
+
+        ranker_calls: list[dict] = []
 
-        monkeypatch.setattr("entirecontext.core.decisions.list_decisions", spy_list_decisions)
+        def spy_ranker(conn, **kwargs):
+            ranker_calls.append(kwargs)
+            return core_ranker(conn, **kwargs)
+
+        monkeypatch.setattr("entirecontext.core.decisions.rank_related_decisions", spy_ranker)
 
         from entirecontext.hooks.decision_hooks import on_session_start_decisions
 
         result = on_session_start_decisions({"cwd": str(ec_repo), "session_id": "s1"})
 
         assert result is not None
-        assert file_path_calls == changed_files[:5]
+        assert len(ranker_calls) == 1
+        assert ranker_calls[0]["limit"] == 5
         entries = [line for line in result.split("\n") if line.strip().startswith("- [")]
-        assert len(entries) == 5
+        assert len(entries) <= 5
 
     def test_git_failure_returns_none(self, ec_repo, ec_db, monkeypatch):
         from unittest.mock import MagicMock
@@ -306,10 +294,10 @@ def test_session_start_excludes_contradicted_decisions(self, ec_repo, ec_db, mon
         assert "Contradicted choice" not in result
 
     def test_session_start_hot_file_with_many_contradicted_still_surfaces_fresh(self, ec_repo, ec_db, monkeypatch):
-        """PR #55 Codex review: when a hot file has more than list_decisions'
-        row cap of contradicted entries, a fresh decision just beyond that
-        cap must still surface — the filter has to push down into SQL so the
-        10-row cap can't hide valid guidance.
+        """When a hot file has many contradicted decisions, a fresh decision
+        must still surface — rank_related_decisions excludes contradicted
+        entries via include_contradicted=False so they cannot suppress valid
+        guidance.
         """
         from entirecontext.core.decisions import update_decision_staleness