Merge branch 'feature/issue-301-goal-email-insight-enrichment' into dev

Author: mottych

coaching/prompts/goal_created_email_insight/system.md

@@ -51,3 +51,5 @@ CONTENT GUIDELINES:
 - Do not invent facts not grounded in input context
 - Keep text ready for direct embedding into email templates
 - Avoid sensitive, risky, or policy-violating guidance
+- When vision, purpose, core values, goal-linked strategies, or measures are provided, you may briefly
+  connect the goal to that context (alignment or a gentle gap); keep it concise and appropriate for email

coaching/prompts/goal_created_email_insight/user.md

@@ -7,8 +7,15 @@ Context:
 - Tenant business name: {business_name}
 - User display name: {user_name}
 - Goal id: {goal_id}
+- Goal (full record as available): {goal}
 - Goal title: {goal_title}
 - Goal description: {goal_description}
+- Goal intent (WHAT/WHY if present): {goal_intent}
+- Business vision: {vision}
+- Business purpose: {purpose}
+- Core values: {core_values}
+- Strategies linked to this goal (may be empty): {existing_strategies_for_goal}
+- Measures linked to this goal (may be empty): {measures_formatted_for_goal}
 - Locale hint: {locale}
 
 Required behavior:
@@ -20,7 +27,8 @@ Required behavior:
    - one paragraph block
    - one list block with 2-4 short items
 4. Add one cta block when a safe and useful next action exists.
-5. Keep suggestions specific to this goal context.
+5. Keep suggestions specific to this goal context; use foundation and strategy/measure context when helpful,
+   without forcing a long alignment section.
 6. Do not output HTML or XML in any field.
 7. Do not add extra keys beyond the contract.
 

coaching/src/core/parameter_registry.py

@@ -1003,6 +1003,28 @@ def _register(param: ParameterDefinition) -> ParameterDefinition:
     )
 )
 
+_register(
+    ParameterDefinition(
+        name="measures_for_goal",
+        param_type=ParameterType.LIST,
+        description="Measures linked to the goal from payload goal_id (goalId or connections.goalIds).",
+        default=[],
+        retrieval_method="get_measures_summary",
+        extraction_path="measures_for_goal",
+    )
+)
+
+_register(
+    ParameterDefinition(
+        name="measures_formatted_for_goal",
+        param_type=ParameterType.STRING,
+        description="Formatted bullet list of measures linked to payload goal_id.",
+        default="No measures linked to this goal yet.",
+        retrieval_method="get_measures_summary",
+        extraction_path="measures_formatted_for_goal",
+    )
+)
+
 # -----------------------------------------------------------------------------
 # Action Parameters (from get_action_by_id)
 # -----------------------------------------------------------------------------

coaching/src/core/retrieval_method_registry.py

@@ -35,6 +35,64 @@ async def my_method(context: RetrievalContext) -> dict[str, Any]:
 logger = structlog.get_logger()
 
 
+def _strategies_linked_to_goal(
+    strategies: list[dict[str, Any]],
+    goal_id: str | None,
+) -> list[dict[str, Any]]:
+    """Return strategies whose goalId matches the payload goal (if any)."""
+    if not goal_id:
+        return []
+    gid = str(goal_id)
+    return [s for s in strategies if str(s.get("goalId", "")) == gid]
+
+
+def _format_strategy_lines(strategies: list[dict[str, Any]]) -> str:
+    """Human-readable bullet list for prompts (email / coaching)."""
+    if not strategies:
+        return "No strategies linked to this goal yet."
+    lines: list[str] = []
+    for s in strategies:
+        name = s.get("name") or "Unnamed strategy"
+        status = s.get("status") or ""
+        desc = (s.get("description") or "").strip()
+        head = f"- {name}" + (f" ({status})" if status else "")
+        if desc:
+            head += f": {desc[:280]}"
+        lines.append(head)
+    return "\n".join(lines)
+
+
+def _measures_linked_to_goal(
+    measures: list[dict[str, Any]],
+    goal_id: str | None,
+) -> list[dict[str, Any]]:
+    """Return measures linked to the goal via goalId or connections.goalIds."""
+    if not goal_id:
+        return []
+    gid = str(goal_id)
+    out: list[dict[str, Any]] = []
+    for m in measures:
+        if str(m.get("goalId", "")) == gid:
+            out.append(m)
+            continue
+        conns = m.get("connections") or {}
+        raw_goal_ids = conns.get("goalIds") or []
+        if gid in {str(x) for x in raw_goal_ids}:
+            out.append(m)
+    return out
+
+
+def _format_measure_lines(measures: list[dict[str, Any]]) -> str:
+    if not measures:
+        return "No measures linked to this goal yet."
+    lines: list[str] = []
+    for m in measures:
+        name = m.get("name") or "Unnamed measure"
+        status = m.get("status") or ""
+        lines.append(f"- {name}" + (f" ({status})" if status else ""))
+    return "\n".join(lines)
+
+
 @dataclass
 class RetrievalContext:
     """Context passed to retrieval methods.
@@ -789,6 +847,7 @@ async def get_strategy_by_id(context: RetrievalContext) -> dict[str, Any]:
         "strategies_count",
         "strategies_by_status",
         "strategies_by_type",
+        "strategies_formatted",
     ),
 )
 async def get_all_strategies(context: RetrievalContext) -> dict[str, Any]:
@@ -817,11 +876,16 @@ async def get_all_strategies(context: RetrievalContext) -> dict[str, Any]:
                 by_type[stype] = []
             by_type[stype].append(s)
 
+        goal_id = context.payload.get("goal_id")
+        linked = _strategies_linked_to_goal(strategies_list, goal_id if goal_id else None)
+        strategies_formatted = _format_strategy_lines(linked)
+
         return {
             "strategies": strategies_list,
             "strategies_count": len(strategies_list),
             "strategies_by_status": by_status,
             "strategies_by_type": by_type,
+            "strategies_formatted": strategies_formatted,
         }
     except Exception as e:
         logger.error(
@@ -834,6 +898,7 @@ async def get_all_strategies(context: RetrievalContext) -> dict[str, Any]:
             "strategies_count": 0,
             "strategies_by_status": {},
             "strategies_by_type": {},
+            "strategies_formatted": "No strategies linked to this goal yet.",
         }
 
 
@@ -850,6 +915,8 @@ async def get_all_strategies(context: RetrievalContext) -> dict[str, Any]:
         "measures_owner_breakdown",
         "measures_by_status",
         "at_risk_measures",
+        "measures_for_goal",
+        "measures_formatted_for_goal",
     ),
 )
 async def get_measures_summary(context: RetrievalContext) -> dict[str, Any]:
@@ -883,6 +950,13 @@ async def get_measures_summary(context: RetrievalContext) -> dict[str, Any]:
             if status in ("at_risk", "behind"):
                 at_risk.append(m)
 
+        goal_id = context.payload.get("goal_id")
+        measures_for_goal = _measures_linked_to_goal(
+            measures,
+            goal_id if goal_id else None,
+        )
+        measures_formatted_for_goal = _format_measure_lines(measures_for_goal)
+
         return {
             "measures_summary": data,
             "measures": measures,
@@ -893,6 +967,8 @@ async def get_measures_summary(context: RetrievalContext) -> dict[str, Any]:
             "measures_owner_breakdown": summary.get("byOwner", []),
             "measures_by_status": by_status,
             "at_risk_measures": at_risk,
+            "measures_for_goal": measures_for_goal,
+            "measures_formatted_for_goal": measures_formatted_for_goal,
         }
     except Exception as e:
         logger.error(
@@ -910,6 +986,8 @@ async def get_measures_summary(context: RetrievalContext) -> dict[str, Any]:
             "measures_owner_breakdown": [],
             "measures_by_status": {},
             "at_risk_measures": [],
+            "measures_for_goal": [],
+            "measures_formatted_for_goal": "No measures linked to this goal yet.",
         }
 
 

coaching/src/core/topic_registry.py

@@ -360,10 +360,19 @@ class TopicDefinition:
         parameter_refs=(
             _req("goal_id"),  # Required request parameter for goal context
             _opt_req("locale"),  # Optional localization hint (default en-US)
+            _onb("vision"),  # Business foundation — alignment to vision
+            _onb("purpose"),  # Business foundation — alignment to purpose
+            _onb("core_values"),  # Business foundation — alignment to values
+            _onb("business_name"),  # Tenant/business display context
+            _goal("goal"),  # Full goal record (get_goal_by_id / template enrichment)
             _goal("goal_title"),  # Auto-enriched from goal service
             _goal("goal_description"),  # Auto-enriched from goal service
+            _goal("goal_intent"),  # Goal intent / WHY for alignment framing
+            _strategies(
+                "existing_strategies_for_goal"
+            ),  # Goal-scoped strategies (strategies_formatted when goal_id set)
+            _measures("measures_formatted_for_goal"),  # Goal-scoped measures summary
             _user("user_name"),  # User display name context
-            _onb("business_name"),  # Tenant/business display context
         ),
     ),
     # ========== Section 4: Strategic Planning AI (6 endpoints) ==========

coaching/src/core/topic_seed_data.py

@@ -483,15 +483,24 @@ class TopicSeedData:
 - Suggest next steps that are realistic and immediate
 - Do not invent facts not grounded in input context
 - Keep text ready for direct embedding into email templates
-- Avoid sensitive, risky, or policy-violating guidance""",
+- Avoid sensitive, risky, or policy-violating guidance
+- Where business foundation (vision, purpose, values) and goal-linked strategies/measures are provided,
+  briefly reflect alignment or a constructive gap (without harsh judgment); stay email-appropriate.""",
         default_user_prompt="""Generate an email insight for the "goal created" trigger.
 
 Context:
 - Tenant business name: {business_name}
 - User display name: {user_name}
 - Goal id: {goal_id}
+- Goal (full record as available): {goal}
 - Goal title: {goal_title}
 - Goal description: {goal_description}
+- Goal intent (WHAT/WHY if present): {goal_intent}
+- Business vision: {vision}
+- Business purpose: {purpose}
+- Core values: {core_values}
+- Strategies linked to this goal (may be empty): {existing_strategies_for_goal}
+- Measures linked to this goal (may be empty): {measures_formatted_for_goal}
 - Locale hint: {locale}
 
 Required behavior:
@@ -501,7 +510,8 @@ class TopicSeedData:
    - one paragraph block
    - one list block with 2-4 short items
 4. Add one cta block when a safe and useful next action exists.
-5. Keep suggestions specific to this goal context.
+5. Keep suggestions specific to this goal context; use vision, purpose, values, strategies, and measures
+   only when they add clear value (do not force a long alignment lecture).
 6. Do not output HTML or XML in any field.
 7. Do not add extra keys beyond the contract.
 

coaching/tests/unit/core/test_retrieval_goal_scoped_enrichment.py

@@ -0,0 +1,81 @@
+"""Tests for goal-scoped strategy/measure enrichment in retrieval methods."""
+
+from unittest.mock import AsyncMock
+
+import pytest
+from coaching.src.core.retrieval_method_registry import (
+    RetrievalContext,
+    get_all_strategies,
+    get_measures_summary,
+)
+
+
+@pytest.mark.asyncio
+async def test_get_all_strategies_strategies_formatted_filters_by_goal_id() -> None:
+    """When goal_id is in the payload, strategies_formatted lists only matching strategies."""
+    client = AsyncMock()
+    client.get_strategies = AsyncMock(
+        return_value=[
+            {"id": "s1", "name": "Alpha", "goalId": "g1"},
+            {"id": "s2", "name": "Beta", "goalId": "g2"},
+        ]
+    )
+    ctx = RetrievalContext(
+        client=client,
+        tenant_id="t1",
+        user_id="u1",
+        payload={"goal_id": "g1"},
+    )
+    result = await get_all_strategies(ctx)
+    assert result["strategies_count"] == 2
+    assert "Alpha" in result["strategies_formatted"]
+    assert "Beta" not in result["strategies_formatted"]
+
+
+@pytest.mark.asyncio
+async def test_get_all_strategies_without_goal_id_empty_formatted() -> None:
+    """Without goal_id, strategies_formatted is the empty-linked message (no spurious bullets)."""
+    client = AsyncMock()
+    client.get_strategies = AsyncMock(
+        return_value=[{"id": "s1", "name": "Alpha", "goalId": "g1"}],
+    )
+    ctx = RetrievalContext(
+        client=client,
+        tenant_id="t1",
+        user_id="u1",
+        payload={},
+    )
+    result = await get_all_strategies(ctx)
+    assert result["strategies_formatted"] == "No strategies linked to this goal yet."
+
+
+@pytest.mark.asyncio
+async def test_get_measures_summary_measures_for_goal_filters() -> None:
+    """Measures linked by goalId or connections.goalIds appear in goal-scoped fields."""
+    client = AsyncMock()
+    client.get_measures_summary = AsyncMock(
+        return_value={
+            "measures": [
+                {"id": "m1", "name": "M1", "status": "on_track", "goalId": "g1"},
+                {
+                    "id": "m2",
+                    "name": "M2",
+                    "status": "on_track",
+                    "connections": {"goalIds": ["g2"]},
+                },
+            ],
+            "summary": {},
+            "healthScore": 0,
+        }
+    )
+    ctx = RetrievalContext(
+        client=client,
+        tenant_id="t1",
+        user_id="u1",
+        payload={"goal_id": "g1"},
+    )
+    result = await get_measures_summary(ctx)
+    assert len(result["measures_for_goal"]) == 1
+    assert result["measures_for_goal"][0]["name"] == "M1"
+    assert "M1" in result["measures_formatted_for_goal"]
+    assert "M2" not in result["measures_formatted_for_goal"]

coaching/tests/unit/core/test_topic_seed_data.py

@@ -87,3 +87,7 @@ def test_goal_created_email_insight_prompt_contract_constraints(self) -> None:
         assert '"schemaversion": "1.0"' in system_prompt
         assert "paragraph, list, cta" in system_prompt
         assert "return one json object only" in user_prompt
+        assert "{vision}" in seed.default_user_prompt
+        assert "{goal_intent}" in seed.default_user_prompt
+        assert "{existing_strategies_for_goal}" in seed.default_user_prompt
+        assert "{measures_formatted_for_goal}" in seed.default_user_prompt

docs/shared/Specifications/ai-api/email-insights-api-contract.md

@@ -1,7 +1,7 @@
 # Email Insights AI API Contract Specification
 
-**Version:** 2.0  
-**Last Updated:** March 27, 2026  
+**Version:** 2.1  
+**Last Updated:** April 8, 2026  
 **Status:** Approved for Full Cutover  
 **Scope:** Generic `email_insight` topics
 
@@ -11,6 +11,7 @@
 
 ## Revision Log
 
+- 2026-04-08 - v2.1 - Document server-side enrichment parameters for `goal_created_email_insight` (foundation + goal-scoped strategies/measures)
 - 2026-03-27 - v2.0 - Full-cutover generic topic contract with required service token for enrichment API calls
 - 2026-03-25 - v1.0 - Initial approved contract for activity-driven email insights v1 pilot
 
@@ -94,6 +95,17 @@ Cross-system request/response naming between PurposePath_Api and PurposePath_AI
 - AI service forwards token to standard backend user-facing API endpoints for enrichment.
 - Backend user-facing endpoints validate token through standard authentication/authorization components.
 
+### 4.5 Server-side enrichment (`goal_created_email_insight`)
+
+Orchestrators still supply topic input primarily via `goal_id` (and standard user/tenant context) plus `authContext` for enrichment API calls. The AI coaching service resolves additional **template parameters** (not required in the trigger `activityData` payload) using the same retrieval stack as other single-shot topics, including:
+
+- Business foundation: `vision`, `purpose`, `core_values`, `business_name`
+- Goal: full `goal` record plus `goal_title`, `goal_description`, `goal_intent` where available
+- Goal-scoped strategies: `existing_strategies_for_goal` (formatted list of strategies whose `goalId` matches `goal_id`)
+- Goal-scoped measures: `measures_formatted_for_goal` (formatted list of measures linked via `goalId` or `connections.goalIds`)
+
+Exact placeholder names and prompt wording live in topic seed data and deployed prompts; this section records **contractual expectation** that enrichment uses `goal_id` to scope strategies and measures.
+
 ---
 
 ## 5. AI Output Payload Contract (`purposepath.email-insight.v1`)