/fix report: group findings by analysis, dedup, code-span-safe MDX escaping

- Key Findings now grouped under each analysis's restated question so
results from different questions don't read as one contradictory list
- dedup exact-duplicate findings within a record
- _mdx_escape leaves inline code spans verbatim (`product_id` no longer
renders as `product\_id`)

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

src/agents/report/generator.py

@@ -13,6 +13,7 @@ Chain construction mirrors `agents/slow_path/assembler.py`.
 
 from __future__ import annotations
 
+import re
 from datetime import UTC, datetime
 from pathlib import Path
 
@@ -98,12 +99,18 @@ def _get_default_chain() -> Runnable:
 
 
 def _collect_findings(records: list[AnalysisRecord]) -> list[ReportFinding]:
-    # Findings are distinct insights — not deduped; each traces to its record.
-    return [
-        ReportFinding(text=text, record_ids=[rec.record_id])
-        for rec in records
-        for text in rec.findings
-    ]
+    # Each finding traces to its record. Deduped *within* a record (an Assembler run
+    # occasionally repeats a line); kept across records so the grouped render can show
+    # each analysis's own findings under its own question.
+    out: list[ReportFinding] = []
+    for rec in records:
+        seen: set[str] = set()
+        for text in rec.findings:
+            if text in seen:
+                continue
+            seen.add(text)
+            out.append(ReportFinding(text=text, record_ids=[rec.record_id]))
+    return out
 
 
 def _collect_notes(records: list[AnalysisRecord], field: str) -> list[AttributedNote]:
@@ -190,21 +197,39 @@ def _build_human_content(
     return "\n\n".join(sections)
 
 
+# Inline code spans (one or more backticks). Content inside is already literal in
+# Markdown/MDX, so escaping within them would only surface a visible backslash
+# (e.g. `product\_id`). We keep code spans verbatim and escape only around them.
+_CODE_SPAN_RE = re.compile(r"`+[^`]*`+")
+
+
 def _mdx_escape(text: str) -> str:
     """Escape Markdown/MDX syntax characters in a dynamic value.
 
     Applied only to values authored outside the renderer (LLM findings/caveats,
     user objective/questions, catalog source & table names, tool names) so that
     identifiers like ``XL_S_129`` don't italicize and stray ``<``/``{`` don't break
-    MDX compilation. NOT applied to the executive summary (its prompt allows light
-    inline emphasis) nor to the structural markdown the renderer emits itself.
+    MDX compilation. Content inside inline code spans is left verbatim (already
+    literal). NOT applied to the executive summary (its prompt allows light inline
+    emphasis) nor to the structural markdown the renderer emits itself.
     """
     if not text:
         return text
-    out = text.replace("\\", "\\\\")
-    for ch in ("<", "{", "|", "_", "*"):
-        out = out.replace(ch, "\\" + ch)
-    return out
+
+    def _esc(s: str) -> str:
+        s = s.replace("\\", "\\\\")
+        for ch in ("<", "{", "|", "_", "*"):
+            s = s.replace(ch, "\\" + ch)
+        return s
+
+    out: list[str] = []
+    pos = 0
+    for m in _CODE_SPAN_RE.finditer(text):
+        out.append(_esc(text[pos : m.start()]))
+        out.append(m.group(0))  # keep the code span verbatim
+        pos = m.end()
+    out.append(_esc(text[pos:]))
+    return "".join(out)
 
 
 def _render_markdown(report: AnalysisReport) -> str:
@@ -234,10 +259,28 @@ def _render_markdown(report: AnalysisReport) -> str:
         parts.append("## Executive Summary\n" + report.executive_summary)
 
     if report.findings:
-        lines = ["## Key Findings"]
-        for i, f in enumerate(report.findings, 1):
-            lines.append(f"{i}. {_mdx_escape(f.text)}")
-        parts.append("\n".join(lines))
+        # Group findings by their originating analysis (record) so results from
+        # different questions read as separate analyses, not one flat, seemingly
+        # contradictory list. Subheadings (the restated question) appear only when
+        # more than one analysis contributed.
+        by_record: dict[str, list[ReportFinding]] = {}
+        for f in report.findings:
+            by_record.setdefault(f.record_ids[0] if f.record_ids else "", []).append(f)
+        ordered = [rid for rid in report.record_goals if rid in by_record]
+        ordered += [rid for rid in by_record if rid not in ordered]
+        grouped = sum(1 for rid in ordered if by_record.get(rid)) > 1
+
+        blocks = ["## Key Findings"]
+        for rid in ordered:
+            group = by_record.get(rid)
+            if not group:
+                continue
+            block: list[str] = []
+            if grouped:
+                block.append(f"### {_mdx_escape(report.record_goals.get(rid) or 'Analysis')}")
+            block.extend(f"{i}. {_mdx_escape(f.text)}" for i, f in enumerate(group, 1))
+            blocks.append("\n".join(block))
+        parts.append("\n\n".join(blocks))
 
     # ## EDA — reserved for future exploratory visuals; charts wrapped as MDX
     # components will render here. Emitted only when it has content; omitted today.
@@ -354,6 +397,7 @@ class ReportGenerator:
             generated_at=datetime.now(UTC),
             problem_statement=ps,
             record_ids=[r.record_id for r in records],
+            record_goals={r.record_id: r.goal_restated for r in records},
             executive_summary=executive_summary,
             findings=findings,
             caveats=caveats,

src/agents/report/schemas.py

@@ -82,6 +82,10 @@ class AnalysisReport(BaseModel):
     # Frozen snapshots.
     problem_statement: ProblemStatement = Field(default_factory=ProblemStatement)
     record_ids: list[str] = Field(default_factory=list)  # records used (snapshot)
+    # record_id -> restated question, in record order. Lets the renderer group Key
+    # Findings per analysis so results from different questions aren't a flat list
+    # that reads as contradictory. Rebuilt-empty on dedorch read-back (markdown only).
+    record_goals: dict[str, str] = Field(default_factory=dict)
     # LLM-authored.
     executive_summary: str = ""
     # Deterministic pass-through from records.