[KM-652] fix(report,chat): align report gate with readiness + cleanup

- T-D: generate_report only 409'd on zero records — it ignored problem_validated
and whether any analysis actually succeeded, so the button could 201 a
findings-empty report while Help said "not ready". Extract report_floor()
(validated goal + >=1 substantive analyze_* success) as the single source of
truth; is_report_ready composes it (+ its delta-check), and the report API
gates on it (no delta — a new version is always allowed, decision 4A).

- T-E: document that reports require ENABLE_SLOW_PATH=on (only the slow path
persists AnalysisRecords; no records => 409 by design), and return a clear
"still needs ..." 409 instead of a bare "no analyses recorded".

- T-F: drop the dead source_hint derivation + _intent_to_source_hint — the
intent event is consumed by the endpoint's cache gate and never forwarded to
the frontend; fix the misleading comment.

- T-G: document the history-blind chat cache key (message-only) limitation;
history-aware key deferred to the endpoint owner.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/agents/chat_handler.py

@@ -269,11 +269,11 @@ class ChatHandler:
                 else stub_analysis_state(problem_validated=False),
             )
 
-        # Back-compat: the frontend still reads `source_hint` off the intent event.
-        # Derive it from the (effective) intent until the frontend migrates to `intent`.
+        # The `intent` event is consumed by the endpoint (it gates response caching
+        # on the effective intent) and is NOT forwarded to the frontend. We emit the
+        # post-gate intent so the cache keys on what actually ran.
         event_data = decision.model_dump()
         event_data["intent"] = intent
-        event_data["source_hint"] = _intent_to_source_hint(intent)
         yield {"event": "intent", "data": json.dumps(event_data)}
 
         rewritten = decision.rewritten_query or message
@@ -597,15 +597,6 @@ class _ScopedCatalogReader:
         return catalog.model_copy(update={"sources": scoped or catalog.sources})
 
 
-def _intent_to_source_hint(intent: str) -> str:
-    """Map a router intent to the legacy `source_hint` value (frontend back-compat)."""
-    if intent == "structured_flow":
-        return "structured"
-    if intent == "unstructured_flow":
-        return "unstructured"
-    return "chat"
-
-
 def _build_sources(
     intent: str,
     user_id: str,

src/agents/report/readiness.py

@@ -85,17 +85,20 @@ def _has_successful_analysis(record) -> bool:
     )
 
 
-async def is_report_ready(
+async def report_floor(
     analysis_id: str | None,
     state: AnalysisState,
     *,
     record_store=None,
-    report_store=None,
-) -> ReportReadiness:
-    """Return whether a report can be generated for this analysis, and the gaps if not.
-
-    `record_store` / `report_store` are injectable for tests; they default to the
-    real Postgres stores.
+) -> tuple[list[str], list]:
+    """The report **floor**: a validated goal + ≥1 substantive analysis.
+
+    Returns `(missing, substantive_records)`. This is the shared gate both the Help
+    readiness signal AND the report API enforce, so the button and Help can't drift
+    (T-D / T11). It deliberately excludes the delta-since-report check — that is
+    advisory and lives only in `is_report_ready`; the report button is always allowed
+    to cut a new version (decision 4A). Fails closed (counts as missing analysis) on
+    a record-store read error. `record_store` is injectable for tests.
     """
     missing: list[str] = []
     if not state.problem_validated:
@@ -109,15 +112,34 @@ async def is_report_ready(
             substantive = [r for r in records if _has_successful_analysis(r)]
         except Exception as exc:  # noqa: BLE001 — never-throw; fail closed to not-ready
             logger.warning(
-                "is_report_ready: record store read failed — not ready",
+                "report_floor: record store read failed — not ready",
                 analysis_id=analysis_id,
                 error=str(exc),
             )
-            missing.append(_MISSING_ANALYSIS)
-            return ReportReadiness(ready=False, missing=missing)
+            return [*missing, _MISSING_ANALYSIS], []
 
     if not substantive:
         missing.append(_MISSING_ANALYSIS)
+    return missing, substantive
+
+
+async def is_report_ready(
+    analysis_id: str | None,
+    state: AnalysisState,
+    *,
+    record_store=None,
+    report_store=None,
+) -> ReportReadiness:
+    """Return whether a report can be generated for this analysis, and the gaps if not.
+
+    `record_store` / `report_store` are injectable for tests; they default to the
+    real Postgres stores.
+    """
+    missing, substantive = await report_floor(
+        analysis_id, state, record_store=record_store
+    )
+
+    if not substantive:
         # No analyses to report on → the delta check is moot.
         return ReportReadiness(ready=not missing, missing=missing)
 

src/api/v1/chat.py

@@ -85,6 +85,10 @@ def _chat_cache_key(room_id: str, user_id: str, message: str) -> str:
     # user_id is part of the key so one user's cached answer can never be
     # replayed to another (R5); room_id stays first so the room-wide clear
     # endpoint can keep matching on a `chat:{room_id}:*` prefix.
+    # LIMITATION (T-G): the key omits conversation history, so a repeated message
+    # replays its cached answer even if the conversation has since moved on. Only
+    # the stateless `chat` intent is cached, so the blast radius is small — but a
+    # history-aware key (hash of last-N turns) would close it. Flagged to Harry.
     return f"{settings.redis_prefix}chat:{room_id}:{user_id}:{message}"
 
 

src/api/v1/report.py

@@ -9,6 +9,11 @@ Generation reads persisted AnalysisRecords + Problem Statement, makes one LLM ca
 (the executive summary), and persists an immutable versioned artifact. The
 ReportGenerator + ReportStore are process singletons (the generator caches its LLM
 chain warm across requests, like ChatHandler).
+
+Note (T-E): AnalysisRecords are only persisted by the slow path, so reports require
+`ENABLE_SLOW_PATH=on`. With it off, no records exist and generation 409s — by design,
+not a bug. POST gates on the same floor as Help's readiness signal (validated goal +
+≥1 substantive analysis) so the button and Help never disagree.
 """
 
 from fastapi import APIRouter, HTTPException, Query, status
@@ -28,21 +33,19 @@ _generator = ReportGenerator()
 _store = ReportStore()
 
 
-async def _load_problem_statement(analysis_id: str) -> ProblemStatement:
-    """Freeze the analysis's validated problem statement into the report.
-
-    The Analysis State stores the PS as free text (the PS skill validates it);
-    map it into the report's structured `ProblemStatement.objective`. Never-throw:
-    a missing state row (legacy room) or read error degrades to an empty PS so the
-    report still generates from its records.
-    """
+async def _load_state(analysis_id: str):
+    """Load the AnalysisState (for the floor gate + problem statement). Never-throw."""
     try:
         from src.agents.state_store import AnalysisStateStore
 
-        state = await AnalysisStateStore().get(analysis_id)
+        return await AnalysisStateStore().get(analysis_id)
     except Exception as e:  # noqa: BLE001 — never block report generation on this
-        logger.warning("report: PS load failed; using empty", analysis_id=analysis_id, error=str(e))
-        return ProblemStatement()
+        logger.warning("report: state load failed", analysis_id=analysis_id, error=str(e))
+        return None
+
+
+def _problem_statement_from(state) -> ProblemStatement:
+    """Map the analysis's free-text problem statement into the report's structured PS."""
     if state is None or not state.problem_statement:
         return ProblemStatement()
     return ProblemStatement(objective=state.problem_statement)
@@ -84,11 +87,28 @@ async def generate_report(
     """Generate, persist, and return a new report version.
 
     Each call produces a new version (V1, V2, …) that snapshots the records and
-    Problem Statement it used. Server-side gate: at least one recorded analysis is
-    required.
+    Problem Statement it used. Server-side gate: the report **floor** — a validated
+    goal + ≥1 substantive analysis — the same floor Help's readiness signal uses, so
+    the button and Help can't disagree (T-D). The delta-since-report check is NOT
+    applied here: a new version is always allowed (decision 4A).
     """
+    from src.agents.gate import stub_analysis_state
+    from src.agents.report.readiness import report_floor
+
+    state = await _load_state(analysis_id)
+    floor_missing, _ = await report_floor(
+        analysis_id, state or stub_analysis_state(problem_validated=False)
+    )
+    if floor_missing:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Not ready to generate a report — still needs "
+            + ", ".join(floor_missing)
+            + ".",
+        )
+
     try:
-        problem_statement = await _load_problem_statement(analysis_id)
+        problem_statement = _problem_statement_from(state)
         report = await _generator.generate(
             analysis_id, user_id, problem_statement=problem_statement
         )