fix(scorecard): rec-path scorecard == marketplace (KI-FULLFACTS) — restores recommendation cards

ROOT CAUSE of empty CitedPolicyCards: brain_tools._scorecard_signal fed
build_scorecard the 7-key eligibility subset (_load_policy_facts), which is
below build_scorecard's data-completeness floor → every recommended policy
returned grade "—" / overall 0 → the Bug #71 >=70 fitness gate dropped 100%
of them → recommendation citations always empty → no cards. The marketplace
(/api/policies/all) scored the SAME policies correctly (HDFC ERGO Optima
Restore = A/78) because it feeds the FULL curated layer
(main._load_curated_facts, KI-219/251 canonical precedence).

Fix: _scorecard_signal now reuses main._load_curated_facts (lazy import —
main is loaded at request time; dodges the cycle) + the same
40-data/reviews/<slug>.json insurer reviews + profile that the marketplace
passes to build_scorecard. A policy's recommendation grade is now identical
to its marketplace grade by construction. The 7-key _load_policy_facts is
unchanged — it remains the correct input for the eligibility/dedup gate,
NOT for grading. Cached (curated layer + reviews) to stay off the hot path.

tests/test_scorecard_parity.py: NEW regression guard — rec-path grade letter
MUST equal marketplace grade letter for a representative policy spread
(incl. Optima Restore = strong A/B and rec-fit-floor-clearing). The two
paths can no longer silently diverge.

Verified: full pytest gate green (rc=0, 0 failures). Local E2E
(/tmp/local-verify.py) now PASSES first time — name captured turn 0 →
fact-find → retrieve_policies → grounded recommendation → structured
citation populated (CitedPolicyCards render). Not pushed
(deploy-altogether-later). KNOWN NEXT (#24): retrieval/ranking surfaces
C/D/F policies while A/87 maternity family floaters exist unretrieved —
separate retrieval-quality issue, not scorecard.

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

backend/brain_tools.py

@@ -203,19 +203,75 @@ def _load_policy_facts(policy_id: str) -> dict:
     return out
 
 
+_curated_all_cache: dict = {}  # single-slot cache for the full curated layer
+_reviews_cache: dict = {}
+
+
+def _curated_facts_all() -> dict:
+    """The FULL curated-facts layer, EXACTLY as the marketplace uses it.
+
+    KI-FULLFACTS (2026-05-17) — root cause of empty recommendation cards:
+    `_scorecard_signal` used to feed build_scorecard the 7-key eligibility
+    subset (`_load_policy_facts`), which is BELOW build_scorecard's
+    data-completeness floor → every recommended policy returned grade "—"
+    / overall 0 → the Bug #71 ≥70 gate dropped 100% of them → no cards.
+    Meanwhile /api/policies/all scored the SAME policies correctly
+    (HDFC Ergo Optima Restore = A/78) because it feeds the FULL curated
+    dict from main._load_curated_facts (KI-219/251 canonical precedence).
+    We now reuse that EXACT function (lazy import — main is loaded at
+    request time; dodges the import cycle) so a policy's recommendation
+    grade is identical to its marketplace grade by construction. The
+    7-key `_load_policy_facts` stays as-is — it is the correct input for
+    the eligibility/dedup gate, NOT for grading."""
+    if "d" not in _curated_all_cache:
+        from backend.main import _load_curated_facts  # lazy: avoids cycle
+        _curated_all_cache["d"] = _load_curated_facts()
+    return _curated_all_cache["d"]
+
+
+def _insurer_reviews(slug: str) -> Optional[dict]:
+    """Same reviews source the marketplace passes to build_scorecard
+    (40-data/reviews/<slug>.json) — drives the claim-experience sub-score.
+    Without it the rec-path grade would drift below the marketplace's."""
+    if not slug:
+        return None
+    if slug in _reviews_cache:
+        return _reviews_cache[slug]
+    ir = None
+    try:
+        rp = settings.DATA_DIR / "reviews" / f"{slug}.json"
+        if rp.exists():
+            ir = _json.loads(rp.read_text())
+    except Exception:  # noqa: BLE001 — reviews optional
+        ir = None
+    _reviews_cache[slug] = ir
+    return ir
+
+
 def _scorecard_signal(policy_id: str, profile=None) -> dict:
-    """Best-effort {_grade, _overall_score} from backend.scorecard. The
-    scorecard module's scoring math is being repaired concurrently — we
-    call it READ-ONLY and degrade silently (the ranking still works off
-    co-pay + SI headroom + cosine without it)."""
+    """Best-effort {_grade, _overall_score} from backend.scorecard, using
+    the IDENTICAL inputs as the marketplace (/api/policies/all) so a
+    policy's recommendation grade == its marketplace grade by construction
+    (parity is asserted by tests/test_scorecard_parity.py). READ-ONLY;
+    degrades silently to {} on any failure (ranking still works off
+    co-pay + SI headroom + cosine)."""
     try:
-        facts = _load_policy_facts(policy_id)
-        if not facts:
-            # Need the full curated dict for a real grade; fall back to a
-            # minimal dict so build_scorecard at least sees co-pay/SI.
-            facts = {}
+        cur = _curated_facts_all()
+        data = None
+        for stem in _candidate_stems(policy_id):
+            if stem in cur:
+                data = cur[stem]
+                break
+        if not data:
+            # Genuinely unknown policy → fail OPEN (no false weak signal;
+            # _recommendation_fit keeps chunks with no grade evidence).
+            return {}
         from backend.scorecard import build_scorecard
 
+        slug = data.get("insurer_slug") or (
+            policy_id.split("__", 1)[0] if "__" in policy_id else ""
+        )
+        ir = _insurer_reviews(slug)
         prof = None
         if profile is not None:
             prof = {
@@ -225,7 +281,7 @@ def _scorecard_signal(policy_id: str, profile=None) -> dict:
                     "existing_cover_inr", "copay_pct",
                 )
             }
-        sc = build_scorecard(facts or {"policy_id": policy_id}, profile=prof)
+        sc = build_scorecard(data, insurer_reviews=ir, profile=prof)
         # KI-280 (2026-05-16) — the Scorecard dataclass field is
         # `overall_score` (scorecard.py:95), NOT `overall`. The previous
         # getattr(sc, "overall", ...) ALWAYS returned None, so every

tests/test_scorecard_parity.py

@@ -0,0 +1,107 @@
+"""Regression guard — recommendation-path scorecard == marketplace scorecard.
+
+ROOT CAUSE THIS LOCKS DOWN (KI-FULLFACTS, 2026-05-17)
+-----------------------------------------------------
+`brain_tools._scorecard_signal` used to feed `build_scorecard` the 7-key
+eligibility subset (`_load_policy_facts`), which is below build_scorecard's
+data-completeness floor → every recommended policy came back grade "—" /
+overall 0 → the Bug #71 >=70 fitness gate dropped 100% of them → the
+recommendation `citations` array was always empty → CitedPolicyCards never
+rendered. Meanwhile /api/policies/all scored the SAME policies correctly
+(HDFC ERGO Optima Restore = A) because it feeds the FULL curated layer
+(main._load_curated_facts, KI-219/251 canonical precedence).
+
+The fix makes `_scorecard_signal` reuse that EXACT function. This test makes
+the two paths *provably* unable to diverge again: for a representative
+spread of policies, the recommendation-path GRADE LETTER must equal the
+marketplace GRADE LETTER. (Overall scores may differ by a few points
+because the marketplace overlays EXTRACTED_DIR data on top; the LETTER —
+what _recommendation_fit gates on — must match.)
+"""
+from __future__ import annotations
+
+import sys
+import unittest
+from pathlib import Path
+
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+if str(_REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT))
+
+
+class TestScorecardParity(unittest.TestCase):
+    """Rec-path _scorecard_signal grade letter == marketplace grade letter."""
+
+    @classmethod
+    def setUpClass(cls):
+        from backend.main import _load_curated_facts
+        from backend.scorecard import build_scorecard
+        from backend.brain_tools import _scorecard_signal, _insurer_reviews
+
+        cls._scorecard_signal = staticmethod(_scorecard_signal)
+        cur = _load_curated_facts()
+
+        # Marketplace grade for a policy_id = build_scorecard on the SAME
+        # full curated dict + reviews the /api/policies/all path uses.
+        def _mkt_grade(pid: str):
+            data = cur.get(pid)
+            if not data:
+                return None
+            slug = data.get("insurer_slug") or (
+                pid.split("__", 1)[0] if "__" in pid else ""
+            )
+            sc = build_scorecard(
+                data, insurer_reviews=_insurer_reviews(slug), profile=None
+            )
+            return sc.grade
+
+        cls._mkt_grade = staticmethod(_mkt_grade)
+        # A representative spread across grade bands + insurers, incl. the
+        # user's own policy (HDFC ERGO Optima Restore — must be a strong A).
+        cls._sample = [
+            "hdfc-ergo__optima-restore",
+            "hdfc-ergo__my-health-sampoorna-suraksha",
+            "hdfc-ergo__my-optima-secure",
+            "oriental-insurance__happy-family-floater",
+            "star-health__family-health-optima",
+        ]
+
+    def test_rec_path_grade_matches_marketplace_grade(self):
+        mismatches = []
+        for pid in self._sample:
+            mkt = self._mkt_grade(pid)
+            if mkt is None:
+                continue  # policy not in curated layer in this env — skip
+            rec = (self._scorecard_signal(pid, profile=None) or {}).get("_grade")
+            if rec != mkt:
+                mismatches.append(f"{pid}: rec={rec!r} marketplace={mkt!r}")
+        self.assertEqual(
+            mismatches, [],
+            "recommendation-path scorecard grade diverged from the "
+            "marketplace grade — the two paths must feed build_scorecard "
+            "the SAME curated facts (see KI-FULLFACTS):\n  "
+            + "\n  ".join(mismatches),
+        )
+
+    def test_optima_restore_is_a_strong_recommendable_grade(self):
+        # The user's own policy — a genuinely strong plan. It must NOT come
+        # back as the data-starved "—"/0 sentinel, and must clear the Bug
+        # #71 recommendation fitness floor so its card can render.
+        from backend.single_brain import _recommendation_fit
+
+        sig = self._scorecard_signal("hdfc-ergo__optima-restore", profile=None)
+        self.assertIn(sig.get("_grade"), ("A", "B"),
+                      f"Optima Restore must be A/B, got {sig!r}")
+        strong, overall, grade = _recommendation_fit({
+            "_overall_score": sig.get("_overall_score"),
+            "_grade": sig.get("_grade"),
+        })
+        self.assertTrue(
+            strong,
+            f"Optima Restore must clear the rec-fit floor "
+            f"(grade={grade} overall={overall})",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()