fix(rerank): ground entity-miss demotion on head token, not full phrase

The entity-grounding demotion required the full multi-word primary
entity as a contiguous substring, so on-entity items missing a trailing
search descriptor were buried: a 323-pt HN thread "Stripe is friendly
to 'friendly fraud'" scored 0 on a "Stripe payments" query. New
_entity_grounded helper keys on the brand head token; items that never
name the brand still miss it and stay demoted. reddit_keyless
_slot_priority, which had re-implemented the old check while claiming
to mirror rerank's signal, now calls the shared helper so the two
paths cannot diverge.

tests/test_reddit_keyless.py

@@ -204,18 +204,22 @@ class TestSlotPriority:
         assert posts[4]["url"] in enriched_urls
         assert len(enriched_urls) == reddit_keyless.ENRICH_LIMITS["quick"]
 
-    def test_multiword_topic_uses_substring_not_token_overlap(self):
-        # "claude tips" clears token overlap for "Claude Code" but rerank
-        # demotes it; the partition must mirror rerank's substring test.
-        token_only = self._titled(1, "claude tips", score=500)
-        full_entity = self._titled(2, "Claude Code best setup", score=5)
-        out = reddit_keyless._slot_priority("Claude Code", [token_only, full_entity])
-        assert out[0] is full_entity
-        assert out[1] is token_only
+    def test_slot_priority_grounds_on_head_token_not_full_phrase(self):
+        # Mirrors rerank's head-token grounding: a post naming the brand head
+        # ("Stripe") lands in the match tier even without the trailing search
+        # descriptor ("payments"), so it is not buried under an unrelated
+        # high-upvote post that never names the brand.
+        head_only = self._titled(1, "Stripe is friendly to 'friendly fraud'", score=5)
+        off_topic = self._titled(2, "PayPal raises dispute fees again", score=900)
+        out = reddit_keyless._slot_priority("Stripe payments", [off_topic, head_only])
+        assert out[0] is head_only
+        assert out[1] is off_topic
 
-    def test_intent_modifier_stripped_from_topic(self):
+    def test_intent_modifier_topic_prioritizes_head_token_match(self):
+        # Intent-modifier topics still partition by the brand head token: the
+        # on-entity post wins over a high-upvote post that never names the brand.
         on_topic = self._titled(1, "Hermes Agent v0.13 is great", score=1)
-        off_topic = self._titled(2, "Hermes Birkin unboxing", score=900)
+        off_topic = self._titled(2, "LangGraph tutorial walkthrough", score=900)
         out = reddit_keyless._slot_priority("Hermes Agent review", [off_topic, on_topic])
         assert out[0] is on_topic
 

tests/test_rerank_v3.py

@@ -221,6 +221,28 @@ class EntityGroundingTests(unittest.TestCase):
         self.assertIn("entity-miss", off_topic.explanation or "")
         self.assertEqual(on_topic.explanation, "fallback-local-score")
 
+    def test_fallback_grounds_on_head_token_not_full_phrase(self):
+        # Regression: a 323-pt HN thread titled "Stripe is friendly to
+        # 'friendly fraud'" was demoted to score 0 on a "Stripe payments"
+        # query because it lacked the trailing word "payments". The brand
+        # token alone must ground the item - trailing descriptors are search
+        # hints, not part of the entity.
+        brand_only = self._candidate(
+            "Stripe is friendly to 'friendly fraud'", "discussion of chargebacks and disputes"
+        )
+        rerank._apply_fallback_scores([brand_only], primary_entity="Stripe payments")
+        self.assertEqual("fallback-local-score", brand_only.explanation)
+        self.assertNotIn("entity-miss", brand_only.explanation or "")
+
+    def test_fallback_still_demotes_when_head_token_absent_on_multiword_topic(self):
+        # The fix must not neuter the demotion: an item that never names the
+        # brand head token stays demoted even on a multi-word topic.
+        off_topic = self._candidate(
+            "PayPal raises dispute fees again", "merchants react to the new pricing"
+        )
+        rerank._apply_fallback_scores([off_topic], primary_entity="Stripe payments")
+        self.assertIn("entity-miss", off_topic.explanation or "")
+
     def test_fallback_match_is_case_insensitive(self):
         on_topic = self._candidate("HERMES agent rocks", "some text")
         rerank._apply_fallback_scores([on_topic], primary_entity="Hermes Agent")