feat: expand coach retrieval with equipment and goal overlays

src/pozify/knowledge_cards.py

@@ -13,8 +13,10 @@ CARD_TYPE_ORDER = {
     "exercise": 0,
     "variation": 1,
     "issue": 2,
-    "goal": 3,
-    "safety_rule": 4,
+    "equipment": 3,
+    "goal": 4,
+    "goal_overlay": 5,
+    "safety_rule": 6,
 }
 
 
@@ -81,6 +83,45 @@ def _card(
     )
 
 
+def _equipment_card(
+    equipment: str,
+    title: str,
+    summary: str,
+    coaching_point: str,
+) -> KnowledgeCard:
+    return _card(
+        f"equipment:{equipment}",
+        "equipment",
+        (equipment,),
+        title,
+        summary,
+        (
+            "Treat equipment as context for cue wording, not as a new issue.",
+        ),
+        (coaching_point,),
+    )
+
+
+def _goal_overlay_card(
+    exercise: str,
+    goal: str,
+    title: str,
+    summary: str,
+    coaching_points: tuple[str, ...],
+) -> KnowledgeCard:
+    return _card(
+        f"goal_overlay:{exercise}:{goal}",
+        "goal_overlay",
+        (f"{exercise}:{goal}",),
+        title,
+        summary,
+        (
+            "Use this overlay only as a prioritization hint for the detected exercise and goal.",
+        ),
+        coaching_points,
+    )
+
+
 CARD_REGISTRY: tuple[KnowledgeCard, ...] = (
     _card(
         "exercise:squat",
@@ -300,6 +341,84 @@ CARD_REGISTRY: tuple[KnowledgeCard, ...] = (
         ("Limit the number of corrections in a single summary.",),
         ("Pick the top one or two form priorities for next time.",),
     ),
+    _equipment_card(
+        "bodyweight",
+        "Bodyweight Context",
+        "Bodyweight sessions should keep cues simple and focused on repeatable control.",
+        "Prefer control and repeatability cues that do not assume external load adjustments.",
+    ),
+    _equipment_card(
+        "dumbbell",
+        "Dumbbell Context",
+        "Dumbbell sessions can use load-management cues, but only as context rather than a requirement.",
+        "If range or symmetry drifts, favor tempo or setup cues before suggesting heavier changes.",
+    ),
+    _equipment_card(
+        "barbell",
+        "Barbell Context",
+        "Barbell sessions may benefit from setup and path-consistency cues, while still staying grounded in the evidence.",
+        "Keep the coaching focused on bar path, balance, and repeatable setup when the evidence supports it.",
+    ),
+    _goal_overlay_card(
+        "squat",
+        "strength",
+        "Squat Strength Overlay",
+        "For strength-focused squats, prioritize the highest-value rep-quality cue rather than many small changes.",
+        (
+            "Lead with the one squat fix that most affects repeatable depth or balance.",
+            "Keep the next-session plan short and repeatable.",
+        ),
+    ),
+    _goal_overlay_card(
+        "squat",
+        "beginner_practice",
+        "Squat Beginner Overlay",
+        "For beginner-practice squats, keep the tone encouraging and corrections minimal.",
+        (
+            "Explain what looked stable before introducing the top squat fix.",
+            "Use simple depth or balance language rather than stacking many cues.",
+        ),
+    ),
+    _goal_overlay_card(
+        "push_up",
+        "beginner_practice",
+        "Push-up Beginner Overlay",
+        "For beginner-practice push-ups, prioritize body-line control and simple repeatable cues.",
+        (
+            "Keep push-up corrections to one or two cues that the athlete can repeat next set.",
+            "Treat valid regressions or grip variations as context, not failure.",
+        ),
+    ),
+    _goal_overlay_card(
+        "push_up",
+        "endurance",
+        "Push-up Endurance Overlay",
+        "For endurance-oriented push-ups, explain what changed later in the set before suggesting fixes.",
+        (
+            "Call out late-set body-line or depth drift when the rep evidence shows it.",
+            "Use pacing and consistency cues for the next session plan.",
+        ),
+    ),
+    _goal_overlay_card(
+        "shoulder_press",
+        "strength",
+        "Shoulder Press Strength Overlay",
+        "For strength-focused presses, prioritize clean top position and left-right consistency.",
+        (
+            "Lead with the top-position or symmetry cue that most affected repeatable reps.",
+            "Keep the next-session plan focused on one or two overhead pressing priorities.",
+        ),
+    ),
+    _goal_overlay_card(
+        "shoulder_press",
+        "mobility",
+        "Shoulder Press Mobility Overlay",
+        "For mobility-oriented presses, stay descriptive about range consistency without diagnosing restriction.",
+        (
+            "Describe the observed top-range consistency without speculating about limitations.",
+            "Favor smooth controlled reps for the next-session comparison.",
+        ),
+    ),
     _card(
         "safety:no_diagnosis",
         "safety_rule",
@@ -552,6 +671,38 @@ def cards_for_labels(labels: list[str] | tuple[str, ...]) -> list[KnowledgeCard]
     )
 
 
+def prioritized_coaching_points(cards: list[KnowledgeCard], *, limit: int = 6) -> list[str]:
+    priority_order = {
+        "issue": 0,
+        "variation": 1,
+        "exercise": 2,
+        "equipment": 3,
+        "goal_overlay": 4,
+        "goal": 5,
+        "safety_rule": 6,
+    }
+    ordered_cards = sorted(
+        cards,
+        key=lambda card: (
+            priority_order.get(card.card_type, 99),
+            0 if card.source_kind == "external" else 1,
+            card.card_id,
+        ),
+    )
+    points: list[str] = []
+    seen: set[str] = set()
+    for card in ordered_cards:
+        for point in card.coaching_points:
+            normalized = point.strip()
+            if not normalized or normalized in seen:
+                continue
+            seen.add(normalized)
+            points.append(normalized)
+            if len(points) >= limit:
+                return points
+    return points
+
+
 def retrieve_cards_with_metadata(
     *,
     profile: UserProfile,
@@ -590,7 +741,10 @@ def retrieve_cards(
         variation.detected_variation,
         *variation.not_issues,
         *[issue.issue for issue in issues.issues],
+        profile.equipment,
         profile.goal,
+        f"{classification.exercise}:{profile.goal}",
+        f"{classification.exercise}:{profile.equipment}",
         "no_diagnosis",
         "no_injury_prevention_claim",
         "grounded_only",

src/pozify/slm/prompting.py

@@ -12,7 +12,7 @@ from pozify.contracts import (
     Variation,
     to_dict,
 )
-from pozify.knowledge_cards import KnowledgeCard
+from pozify.knowledge_cards import KnowledgeCard, prioritized_coaching_points
 
 
 def build_summary_evidence(
@@ -59,6 +59,7 @@ def build_summary_evidence(
             "issues": [to_dict(issue) for issue in issues.issues],
             "top_issue_intervals": top_issue_intervals,
         },
+        "priority_cues": prioritized_coaching_points(cards),
         "knowledge_cards": [to_dict(card) for card in cards],
     }
 
@@ -101,6 +102,7 @@ def build_coach_summary_prompt(
             "Do not diagnose injuries, pain, mobility deficits, or pathology.",
             "Do not claim injury prevention.",
             "Do not treat a valid detected variation or not-issue label as an error.",
+            "Use priority_cues as the first source for phrasing top fixes and next-session guidance.",
             "When referencing an issue or variation, include its exact label in "
             "backticks at least once.",
             "If evidence is limited or confidence is low, say so in confidence_notes.",

tests/test_coach_summary.py

@@ -26,9 +26,11 @@ from pozify.env import load_local_env
 import pozify.slm.providers as slm_providers
 from pozify.knowledge_cards import (
     clear_catalog_cache,
+    prioritized_coaching_points,
     retrieve_cards,
     retrieve_cards_with_metadata,
 )
+from pozify.slm.prompting import build_summary_evidence
 from pozify.steps import coach_summary, coach_summary_fallback, verifier
 
 
@@ -267,15 +269,17 @@ class CoachSummaryTests(unittest.TestCase):
 
         card_ids = [card.card_id for card in cards]
         self.assertEqual(
-            card_ids[:4],
+            card_ids[:5],
             [
                 "exercise:push_up",
                 "variation:wide_grip_push_up",
                 "issue:hip_sag",
+                "equipment:bodyweight",
                 "goal:beginner_practice",
             ],
         )
         self.assertIn("safety:no_diagnosis", card_ids)
+        self.assertIn("goal_overlay:push_up:beginner_practice", card_ids)
 
     def test_retrieval_metadata_reports_external_card_usage(self) -> None:
         retrieval = retrieve_cards_with_metadata(
@@ -332,6 +336,43 @@ class CoachSummaryTests(unittest.TestCase):
             self.assertEqual(push_up_card.source_kind, "external")
             self.assertEqual(push_up_card.source_path, str(pack_path.resolve()))
 
+    def test_prompt_evidence_includes_prioritized_cues(self) -> None:
+        cards = retrieve_cards(
+            profile=_profile(),
+            classification=_classification(),
+            variation=_variation(),
+            issues=_issues(),
+        )
+
+        evidence = build_summary_evidence(
+            profile=_profile(),
+            classification=_classification(),
+            reps=_reps(),
+            analysis=_analysis(),
+            variation=_variation(),
+            issues=_issues(),
+            cards=cards,
+        )
+
+        self.assertTrue(evidence["priority_cues"])
+        self.assertIn(
+            "Keep shoulders, hips, and ankles moving as one line.",
+            evidence["priority_cues"],
+        )
+
+    def test_prioritized_coaching_points_prefers_issue_and_context_cards(self) -> None:
+        cards = retrieve_cards(
+            profile=_profile(),
+            classification=_classification(),
+            variation=_variation(),
+            issues=_issues(),
+        )
+
+        points = prioritized_coaching_points(cards, limit=4)
+
+        self.assertLessEqual(len(points), 4)
+        self.assertIn("Keep shoulders, hips, and ankles moving as one line.", points)
+
     def test_coach_summary_falls_back_when_model_fails(self) -> None:
         cards = retrieve_cards(
             profile=_profile(),