fix(search): keep higher-scoring rag hit when two share a topic (#23)

Spotted in code-review 2026-05-07. The merge loop overwrote
``acc[topic]`` unconditionally, so when two RAG hits resolved to the
same topic key (typical for the author-layout where concept.md and
reference.md sit in the same feature dir), the LATER hit silently
won — even when the earlier one had a higher score. Net effect:
precision loss whenever the corpus included multiple depths of the
same topic.

Compare scores before overwriting; keep the existing entry when its
``rag_score`` is at least as high as the incoming hit's normalized
score. The result is order-independent: high-then-low and low-then-
high both keep the high-scoring entry.

Two new tests cover both orderings.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: silversurfer562

sidecar/attune_gui/search.py

@@ -63,11 +63,22 @@ def merge(
     for hit in rag_hits:
         # citation.hits contains CitedSource objects: .template_path, .score, .excerpt
         topic = _rag_topic(hit.template_path)
+        normalized_score = hit.score / max_rag
+
+        existing = acc.get(topic)
+        if existing is not None and existing["rag_score"] >= normalized_score:
+            # Already seen this topic at an equal-or-better score; keep
+            # the earlier hit. Without this, the loop silently overwrote
+            # the higher-scoring entry whenever two RAG templates
+            # resolved to the same topic (precision loss flagged in
+            # code-review 2026-05-07).
+            continue
+
         acc[topic] = {
             "topic": topic,
             "path": hit.template_path,
             "excerpt": (hit.excerpt or "")[:200].strip(),
-            "rag_score": hit.score / max_rag,
+            "rag_score": normalized_score,
             "help_score": None,
         }
 

sidecar/tests/test_unified_search.py

@@ -232,3 +232,46 @@ def test_engine_failure_degrades_gracefully(client, monkeypatch):
     data = resp.json()
     assert len(data["results"]) == 1
     assert data["results"][0]["source"] == "rag"
+
+
+# ---------------------------------------------------------------------------
+# merge() dedup — duplicates resolving to the same topic must keep the best
+# ---------------------------------------------------------------------------
+
+
+def test_merge_keeps_higher_score_when_two_rag_hits_share_topic():
+    """Two RAG hits resolving to the same topic key must produce one
+    result whose score reflects the higher hit, not the later one.
+
+    Before the fix, the second iteration of the loop unconditionally
+    overwrote the first ``acc[topic]``, silently dropping the higher-
+    scoring hit when the order happened to be high-then-low.
+    """
+    # Same author-layout topic, different depths, both score above zero
+    # but the concept is rated higher than the reference.
+    rag_hits = [
+        _rag_hit("auth/concept.md", 5.0, "high-rank content"),
+        _rag_hit("auth/reference.md", 1.0, "low-rank content"),
+    ]
+    results = merge([], rag_hits, limit=10)
+    assert len(results) == 1
+    r = results[0]
+    assert r["topic"] == "auth"
+    # Top RAG hit normalizes to 1.0 (max=5.0), weighted by _RAG_WEIGHT=0.6
+    assert r["score"] == pytest.approx(0.6, abs=0.01)
+    # Path should be the higher-scoring hit's path
+    assert r["path"] == "auth/concept.md"
+
+
+def test_merge_keeps_higher_score_when_lower_comes_first():
+    """Order-independent: low-score-first should still keep the high-score hit."""
+    rag_hits = [
+        _rag_hit("auth/reference.md", 1.0, "low first"),
+        _rag_hit("auth/concept.md", 5.0, "high second"),
+    ]
+    results = merge([], rag_hits, limit=10)
+    assert len(results) == 1
+    r = results[0]
+    assert r["topic"] == "auth"
+    assert r["path"] == "auth/concept.md"
+    assert r["score"] == pytest.approx(0.6, abs=0.01)