claude-dev-env 1.59.0 → 1.60.0

package/skills/autoconverge/workflow/render_report.py

@@ -1,65 +1,86 @@
-"""Render a convergence insights HTML report from an autoconverge workflow journal."""
+"""Render a visual convergence summary HTML report from an autoconverge journal."""
 
 import argparse
 import html
 import json
 import re
-import subprocess
 import sys
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TextIO
 
 from autoconverge_report_constants.render_report_constants import (
-    BAR_COLOR_ROUND,
-    BAR_COLOR_SEVERITY_CRITICAL,
-    BAR_COLOR_SEVERITY_MINOR,
-    BAR_COLOR_TESTS,
-    BAR_COLOR_THEME,
-    BAR_FILL_MAX_PERCENT,
+    CATEGORY_BUG,
+    CATEGORY_LABEL_BY_VALUE,
+    CATEGORY_SORT_ORDER,
+    CAUSE_MUTED_STYLE,
+    DEFAULT_FINDING_CATEGORY,
+    DEFAULT_FINDING_SEVERITY,
     GITHUB_PR_URL_TEMPLATE,
     HTML_DOCTYPE,
     HTML_HEAD_TEMPLATE,
     HTML_STYLE_BLOCK,
+    ISO_DATE_LENGTH,
+    ISSUE_CLASS_FIELD_AFTER_LINES,
+    ISSUE_CLASS_FIELD_BEFORE_LINES,
+    ISSUE_CLASS_FIELD_CATEGORY,
+    ISSUE_CLASS_FIELD_CAUSE,
+    ISSUE_CLASS_FIELD_COUNT,
+    ISSUE_CLASS_FIELD_MEDIUM,
+    ISSUE_CLASS_FIELD_PLAINNAME,
+    ISSUE_CLASS_FIELD_SEVERITY,
+    ISSUE_CLASS_FIELD_STATUS,
     JOURNAL_SIBLING_SUBAGENTS,
     JOURNAL_SIBLING_WORKFLOWS,
+    LABEL_CONVERGENCE_SUMMARY,
     LABEL_COPILOT_GATE,
     LABEL_PREFIX_FIX,
     LABEL_PREFIX_LENS,
     LABEL_RESOLVE_HEAD,
-    SEVERITY_BADGE_CLASS_BY_LEVEL,
-    SEVERITY_CRITICAL_BUCKET,
-    SEVERITY_CRITICAL_LEVELS,
-    SEVERITY_MINOR_BUCKET,
+    MEDIUM_CODE,
+    MEDIUM_TERMINAL,
+    SCENE_FIELD_CAPTION,
+    SCENE_FIELD_CONDITION,
+    SCENE_FIELD_RESULT,
+    SCENE_FIELD_TRIGGER,
+    SEVERITY_SORT_RANK,
+    SHORT_SHA_LENGTH,
+    STATUS_LABEL_BY_VALUE,
     STRUCTURED_OUTPUT_TOOL_NAME,
-    TEST_DEFINITION_PATTERN,
-    TEST_PATH_GLOBS,
-    THEME_FALLBACK,
-    THEME_PATH_SEGMENT_COUNT,
+    SUMMARY_FIELD_FIX_SCENES,
+    SUMMARY_FIELD_ISSUE_CLASSES,
+    SUMMARY_FIELD_PR_FIX,
+    SUMMARY_FIELD_PR_PROBLEM,
+    SUMMARY_FIELD_PROBLEM_SCENES,
+    SUMMARY_FIELD_VERDICT_LINE,
+    TIMELINE_AFTER_LABEL,
+    TIMELINE_AFTER_PILL,
+    TIMELINE_BEFORE_LABEL,
+    TIMELINE_BEFORE_PILL,
+    TIMELINE_TERMINAL_BAR_LABEL,
 )
 
 
 @dataclass(frozen=True)
 class RawFinding:
-    """A single finding from a lens or copilot-gate agent result, tagged with round context."""
+    """A single finding from a lens or copilot-gate agent result."""
 
     file: str
     line: int
     severity: str
     title: str
     detail: str
-    round_number: int
-    sha: str
+    category: str
 
 
 @dataclass(frozen=True)
 class FixRecord:
-    """The structured result of a fix agent, with round and base-sha context attached."""
+    """The structured result of a fix agent, with base-sha context attached."""
 
     new_sha: str
     pushed: bool
     resolved_without_commit: bool
-    round_number: int
+    summary: str
     base_sha: str
 
 
@@ -81,15 +102,10 @@ class RunData:
 
     generated_date: str
     total_finding_count: int
-    critical_finding_count: int
-    minor_finding_count: int
     fix_commit_count: int
-    tests_added_by_round: dict[int, int]
-    finding_count_by_round: dict[int, int]
-    finding_count_by_theme: dict[str, int]
-    all_critical_findings: list[RawFinding]
-    all_minor_findings: list[RawFinding]
+    all_distinct_findings: list[RawFinding]
     fix_by_round: dict[int, FixRecord]
+    convergence_summary: dict | None
 
 
 def _resolve_agents_dir(journal_path: Path) -> Path:
@@ -167,58 +183,6 @@ def _last_structured_input_in_line(
     return latest_input
 
 
-def _derive_theme(file_path: str) -> str:
-    """Return the first two slash-separated segments of a file path.
-
-    Args:
-        file_path: A relative file path string from a finding.
-
-    Returns:
-        A theme string like 'src/exports', the whole path when fewer than two
-        segments exist, or THEME_FALLBACK when the path is empty.
-    """
-    if not file_path:
-        return THEME_FALLBACK
-    segments = file_path.split("/")
-    return "/".join(segments[:THEME_PATH_SEGMENT_COUNT])
-
-
-def _count_tests_added(base_sha: str, new_sha: str, repo_path: Path) -> int:
-    """Count new test definitions introduced between two commits.
-
-    Args:
-        base_sha: The commit sha the round reviewed.
-        new_sha: The sha produced by the fix commit.
-        repo_path: Path to the git repository root.
-
-    Returns:
-        Number of newly added test-function definitions; 0 on any git error.
-    """
-    diff_command = [
-        "git",
-        "-C",
-        str(repo_path),
-        "diff",
-        f"{base_sha}..{new_sha}",
-        "--",
-        *TEST_PATH_GLOBS,
-    ]
-    try:
-        completed = subprocess.run(
-            diff_command,
-            capture_output=True,
-            text=True,
-            check=True,
-        )
-    except (subprocess.SubprocessError, OSError):
-        return 0
-
-    diff_text = completed.stdout
-    test_def_pattern = re.compile(TEST_DEFINITION_PATTERN, re.MULTILINE)
-
-    return len(test_def_pattern.findall(diff_text))
-
-
 def _build_dedup_key(file_path: str, line: int, title: str) -> tuple[str, int, str]:
     """Return a deduplication key for a finding.
 
@@ -233,13 +197,11 @@ def _build_dedup_key(file_path: str, line: int, title: str) -> tuple[str, int, s
     return (file_path, line, title.lower())
 
 
-def _parse_finding_from_dict(raw: dict, round_number: int, sha: str) -> RawFinding:
+def _parse_finding_from_dict(raw: dict) -> RawFinding:
     """Construct a RawFinding from a raw agent result dict.
 
     Args:
         raw: The raw finding dict from the agent result.
-        round_number: The round this finding belongs to.
-        sha: The commit sha this finding was discovered on.
 
     Returns:
         A RawFinding dataclass instance.
@@ -247,22 +209,18 @@ def _parse_finding_from_dict(raw: dict, round_number: int, sha: str) -> RawFindi
     return RawFinding(
         file=raw.get("file", ""),
         line=raw.get("line", 0),
-        severity=raw.get("severity", "P2"),
+        severity=raw.get("severity", DEFAULT_FINDING_SEVERITY),
         title=raw.get("title", ""),
         detail=raw.get("detail", ""),
-        round_number=round_number,
-        sha=sha,
+        category=raw.get("category", DEFAULT_FINDING_CATEGORY),
     )
 
 
-def _parse_fix_record(
-    agent_result: dict, round_number: int, base_sha: str
-) -> FixRecord:
+def _parse_fix_record(agent_result: dict, base_sha: str) -> FixRecord:
     """Construct a FixRecord from a fix agent's structured output.
 
     Args:
         agent_result: The structured output dict from the fix agent.
-        round_number: The round this fix belongs to.
         base_sha: The HEAD sha the round reviewed before fixing.
 
     Returns:
@@ -272,7 +230,7 @@ def _parse_fix_record(
         new_sha=agent_result.get("newSha", ""),
         pushed=bool(agent_result.get("pushed", False)),
         resolved_without_commit=bool(agent_result.get("resolvedWithoutCommit", False)),
-        round_number=round_number,
+        summary=agent_result.get("summary", ""),
         base_sha=base_sha,
     )
 
@@ -322,13 +280,11 @@ def _parse_progress_entries(
                 current_round_base_sha = sha
             raw_findings: list[dict] = agent_result.get("findings", [])
             for each_raw in raw_findings:
-                all_findings.append(
-                    _parse_finding_from_dict(each_raw, current_round, sha)
-                )
+                all_findings.append(_parse_finding_from_dict(each_raw))
 
         if is_fix:
             fix_by_round[current_round] = _parse_fix_record(
-                agent_result, current_round, current_round_base_sha
+                agent_result, current_round_base_sha
             )
 
     return all_findings, fix_by_round
@@ -355,19 +311,45 @@ def _dedup_findings(all_findings: list[RawFinding]) -> list[RawFinding]:
     return distinct
 
 
-def load_run_data(journal_path: Path, repo_path: Path) -> RunData:
+def _extract_convergence_summary(
+    progress_entries: list[dict], agents_dir: Path
+) -> dict | None:
+    """Return the convergence-summary StructuredOutput, or None when absent.
+
+    Args:
+        progress_entries: The workflowProgress list from the journal.
+        agents_dir: Directory containing per-agent .jsonl transcript files.
+
+    Returns:
+        The summarizer agent's last StructuredOutput input dict, or None when
+        no convergence-summary entry exists or its transcript is unreadable.
+    """
+    for each_entry in progress_entries:
+        if each_entry.get("label") != LABEL_CONVERGENCE_SUMMARY:
+            continue
+        agent_id = each_entry.get("agentId")
+        if not agent_id:
+            return None
+        transcript_path = agents_dir / f"agent-{agent_id}.jsonl"
+        return _extract_structured_output(transcript_path)
+    return None
+
+
+def load_run_data(journal_path: Path) -> RunData:
     """Parse a workflow journal and its agent transcripts into aggregated metrics.
 
     Args:
         journal_path: Path to the wf_<runId>.json journal file.
-        repo_path: Path to the git repository for counting tests added.
 
     Returns:
-        A RunData instance with all counts and finding lists populated.
+        A RunData instance with finding lists, fix records, and the summary populated.
     """
+    iso_date_length = ISO_DATE_LENGTH
     journal = json.loads(journal_path.read_text(encoding="utf-8"))
     timestamp: str = journal.get("timestamp", "")
-    generated_date = timestamp[:10] if len(timestamp) >= 10 else ""
+    generated_date = (
+        timestamp[:iso_date_length] if len(timestamp) >= iso_date_length else ""
+    )
 
     progress_entries: list[dict] = journal.get("workflowProgress", [])
     agents_dir = _resolve_agents_dir(journal_path)
@@ -376,305 +358,495 @@ def load_run_data(journal_path: Path, repo_path: Path) -> RunData:
         progress_entries, agents_dir
     )
     distinct_findings = _dedup_findings(all_raw_findings)
-
-    all_critical_findings: list[RawFinding] = []
-    all_minor_findings: list[RawFinding] = []
-    finding_count_by_round: dict[int, int] = {}
-    finding_count_by_theme: dict[str, int] = {}
-
-    for each_finding in distinct_findings:
-        severity = each_finding.severity
-        round_number = each_finding.round_number
-        theme = _derive_theme(each_finding.file)
-
-        if severity in SEVERITY_CRITICAL_LEVELS:
-            all_critical_findings.append(each_finding)
-        else:
-            all_minor_findings.append(each_finding)
-
-        finding_count_by_round[round_number] = (
-            finding_count_by_round.get(round_number, 0) + 1
-        )
-        finding_count_by_theme[theme] = finding_count_by_theme.get(theme, 0) + 1
+    convergence_summary = _extract_convergence_summary(progress_entries, agents_dir)
 
     fix_commit_count = sum(1 for each_fix in fix_by_round.values() if each_fix.pushed)
 
-    tests_added_by_round: dict[int, int] = {}
-    for each_round_number, each_fix in fix_by_round.items():
-        if not each_fix.pushed:
-            tests_added_by_round[each_round_number] = 0
-            continue
-        tests_added_by_round[each_round_number] = _count_tests_added(
-            each_fix.base_sha,
-            each_fix.new_sha,
-            repo_path,
-        )
-
     return RunData(
         generated_date=generated_date,
         total_finding_count=len(distinct_findings),
-        critical_finding_count=len(all_critical_findings),
-        minor_finding_count=len(all_minor_findings),
         fix_commit_count=fix_commit_count,
-        tests_added_by_round=tests_added_by_round,
-        finding_count_by_round=finding_count_by_round,
-        finding_count_by_theme=finding_count_by_theme,
-        all_critical_findings=all_critical_findings,
-        all_minor_findings=all_minor_findings,
+        all_distinct_findings=distinct_findings,
         fix_by_round=fix_by_round,
+        convergence_summary=convergence_summary,
     )
 
 
-def _render_bar_row(label: str, bar_value: int, max_value: int, color: str) -> str:
-    """Return an HTML .bar-row element for a single chart bar.
+def _is_summary_structurally_valid(convergence_summary: object) -> bool:
+    """Return whether the summary carries a verdict string and an issue-class list.
 
     Args:
-        label: The text label displayed on the left.
-        bar_value: The numeric value for this bar.
-        max_value: The maximum value across all bars in this chart.
-        color: The CSS hex color for the bar fill.
+        convergence_summary: The parsed convergence summary, which may be None or
+            any non-dict JSON value an agent emits in place of the expected object.
 
     Returns:
-        An HTML string for one .bar-row.
+        True when the summary is a dict whose verdictLine is a str and whose
+        issueClasses is a list, else False.
     """
-    fill_width = round(bar_value / max(max_value, 1) * BAR_FILL_MAX_PERCENT, 1)
-    escaped_label = html.escape(label)
-    return (
-        f'<div class="bar-row">'
-        f'<span class="bar-label">{escaped_label}</span>'
-        f'<div class="bar-track">'
-        f'<div class="bar-fill" style="width:{fill_width}%;background:{color};"></div>'
-        f"</div>"
-        f'<span class="bar-value">{bar_value}</span>'
-        f"</div>"
-    )
+    if not isinstance(convergence_summary, dict):
+        return False
+    verdict_line = convergence_summary.get(SUMMARY_FIELD_VERDICT_LINE)
+    issue_classes = convergence_summary.get(SUMMARY_FIELD_ISSUE_CLASSES)
+    return isinstance(verdict_line, str) and isinstance(issue_classes, list)
 
 
-def _render_chart_card(title: str, bar_rows_html: str) -> str:
-    """Return an HTML .chart-card wrapping the given bar rows.
+def _coerce_count(raw_count: object) -> int:
+    """Return a non-negative integer count from an LLM-authored field, else zero.
 
     Args:
-        title: The chart title displayed in uppercase.
-        bar_rows_html: Pre-rendered HTML for all bar rows.
+        raw_count: The count value as read from the convergence summary, which an
+            agent may emit as null, a non-numeric string, or a valid number.
 
     Returns:
-        An HTML string for one .chart-card.
+        The value parsed to an int, or 0 when it is null, non-numeric, or absent.
     """
-    escaped_title = html.escape(title)
+    if isinstance(raw_count, bool):
+        return int(raw_count)
+    if isinstance(raw_count, int):
+        return raw_count
+    if isinstance(raw_count, (float, str)):
+        try:
+            return int(float(raw_count))
+        except (TypeError, ValueError):
+            return 0
+    return 0
+
+
+def _pluralize(count: int, singular: str, plural: str) -> str:
+    """Return a 'count word' phrase choosing the singular or plural noun.
+
+    Args:
+        count: The quantity that decides the noun form.
+        singular: The noun to use when count is exactly one.
+        plural: The noun to use for every other count.
+
+    Returns:
+        A phrase like '1 fix commit' or '2 fix commits'.
+    """
+    noun = singular if count == 1 else plural
+    return f"{count} {noun}"
+
+
+def _render_verdict_banner(
+    convergence_summary: dict, run_data: RunData, final_sha_short: str
+) -> str:
+    """Return the verdict banner with the verdict line and a Python-computed sub-line.
+
+    Args:
+        convergence_summary: A structurally valid convergence summary.
+        run_data: Aggregated metrics from the journal.
+        final_sha_short: First eight characters of the final commit sha.
+
+    Returns:
+        An HTML .verdict banner string with a check circle, vtext, and vsub.
+    """
+    verdict_line = str(convergence_summary.get(SUMMARY_FIELD_VERDICT_LINE, ""))
+    fix_commit_phrase = _pluralize(
+        run_data.fix_commit_count, "fix commit", "fix commits"
+    )
+    vsub = f"{fix_commit_phrase} &middot; final commit {html.escape(final_sha_short)}"
     return (
-        f'<div class="chart-card">'
-        f'<div class="chart-title">{escaped_title}</div>'
-        f"{bar_rows_html}"
-        f"</div>"
+        '<div class="verdict">'
+        '<div class="check">&#10003;</div>'
+        "<div>"
+        f'<div class="vtext">{html.escape(verdict_line)}</div>'
+        f'<div class="vsub">{vsub}</div>'
+        "</div>"
+        "</div>"
     )
 
 
-def _render_severity_chart(critical_count: int, minor_count: int) -> str:
-    """Return a severity breakdown chart card.
+def _render_scene_row(scene: dict, is_problem: bool) -> str:
+    """Return one .scene row plus its caption for a problem-or-fix scene.
 
     Args:
-        critical_count: Total critical (P0/P1) findings.
-        minor_count: Total minor (P2) findings.
+        scene: A scene dict with trigger, condition, result, and caption.
+        is_problem: True for a problem scene (bad result), False for a fix scene.
 
     Returns:
-        An HTML .chart-card string.
+        An HTML .scene row followed by a .scene-cap caption line.
     """
-    max_count = max(critical_count, minor_count, 1)
-    rows = _render_bar_row(
-        SEVERITY_CRITICAL_BUCKET, critical_count, max_count, BAR_COLOR_SEVERITY_CRITICAL
-    ) + _render_bar_row(
-        SEVERITY_MINOR_BUCKET, minor_count, max_count, BAR_COLOR_SEVERITY_MINOR
-    )
-    return _render_chart_card("Findings by severity", rows)
+    trigger = html.escape(str(scene.get(SCENE_FIELD_TRIGGER, "")))
+    condition = str(scene.get(SCENE_FIELD_CONDITION, "")).strip()
+    result_text = html.escape(str(scene.get(SCENE_FIELD_RESULT, "")))
+    caption = html.escape(str(scene.get(SCENE_FIELD_CAPTION, "")))
 
+    result_class = "res-bad" if is_problem else "res-good"
+    result_mark = "&#10007;" if is_problem else "&#10003;"
+
+    parts = [f'<span class="chip">{trigger}</span>']
+    if condition:
+        parts.append('<span class="arrow">&rarr;</span>')
+        parts.append(f'<span class="note">{html.escape(condition)}</span>')
+    parts.append('<span class="arrow">&rarr;</span>')
+    parts.append(f'<span class="{result_class}">{result_mark} {result_text}</span>')
+
+    scene_row = f'<div class="scene">{"".join(parts)}</div>'
+    caption_row = f'<div class="scene-cap">{caption}</div>'
+    return scene_row + caption_row
 
-def _render_round_findings_chart(
-    round_count: int, finding_count_by_round: dict[int, int]
-) -> str:
-    """Return a per-round finding count chart card.
+
+def _render_pf_card(convergence_summary: dict, is_problem: bool) -> str:
+    """Return a single problem-or-fix card drawing its scenes or a fallback caption.
 
     Args:
-        round_count: Total number of rounds in the run.
-        finding_count_by_round: Mapping of round number to distinct finding count.
+        convergence_summary: A structurally valid convergence summary.
+        is_problem: True for the problem card, False for the fix card.
 
     Returns:
-        An HTML .chart-card string.
+        An HTML .pf card string with scene rows or a single fallback caption.
     """
-    all_counts = [finding_count_by_round.get(r, 0) for r in range(1, round_count + 1)]
-    max_count = max(all_counts + [1])
-    rows = "".join(
-        _render_bar_row(
-            f"Round {r}", finding_count_by_round.get(r, 0), max_count, BAR_COLOR_ROUND
+    if is_problem:
+        card_class = "problem"
+        tag_label = "Problem"
+        scenes_field = SUMMARY_FIELD_PROBLEM_SCENES
+        fallback_field = SUMMARY_FIELD_PR_PROBLEM
+    else:
+        card_class = "fix"
+        tag_label = "Fix"
+        scenes_field = SUMMARY_FIELD_FIX_SCENES
+        fallback_field = SUMMARY_FIELD_PR_FIX
+
+    scenes = [
+        each_scene
+        for each_scene in convergence_summary.get(scenes_field, [])
+        if isinstance(each_scene, dict)
+    ]
+    if scenes:
+        body = "".join(
+            _render_scene_row(each_scene, is_problem) for each_scene in scenes
         )
-        for r in range(1, round_count + 1)
+    else:
+        fallback_text = html.escape(str(convergence_summary.get(fallback_field, "")))
+        body = f'<div class="scene-cap">{fallback_text}</div>'
+
+    return (
+        f'<div class="pf {card_class}">'
+        f'<span class="pf-tag">{tag_label}</span>'
+        f"{body}"
+        "</div>"
     )
-    return _render_chart_card("Findings by round", rows)
 
 
-def _render_tests_chart(round_count: int, tests_added_by_round: dict[int, int]) -> str:
-    """Return a per-round tests-added chart card.
+def _render_pf_grid(convergence_summary: dict) -> str:
+    """Return the 'What this PR does' grid with a problem card and a fix card.
+
+    Args:
+        convergence_summary: A structurally valid convergence summary.
+
+    Returns:
+        An HTML .pf-grid string with both cards.
+    """
+    problem_card = _render_pf_card(convergence_summary, is_problem=True)
+    fix_card = _render_pf_card(convergence_summary, is_problem=False)
+    return f'<div class="pf-grid">{problem_card}{fix_card}</div>'
+
+
+def _render_panel_body(lines: list[str], medium: str) -> str:
+    """Return the inner HTML for a before-or-after panel body.
 
     Args:
-        round_count: Total number of rounds in the run.
-        tests_added_by_round: Mapping of round number to tests added count.
+        lines: The literal short lines to show, joined with line breaks.
+        medium: One of 'terminal', 'code', or 'text'.
 
     Returns:
-        An HTML .chart-card string.
+        An HTML panel-body string escaped and joined with <br>.
     """
-    all_counts = [tests_added_by_round.get(r, 0) for r in range(1, round_count + 1)]
-    max_count = max(all_counts + [1])
-    rows = "".join(
-        _render_bar_row(
-            f"Round {r}", tests_added_by_round.get(r, 0), max_count, BAR_COLOR_TESTS
+    escaped_lines = [html.escape(str(each_line)) for each_line in lines]
+    joined = "<br>".join(escaped_lines)
+    if medium == MEDIUM_TERMINAL:
+        return (
+            '<div class="terminal">'
+            '<div class="term-bar"><i class="r"></i><i class="y"></i><i class="g"></i>'
+            f"<span>{TIMELINE_TERMINAL_BAR_LABEL}</span></div>"
+            f'<div class="term-body">{joined}</div>'
+            "</div>"
         )
-        for r in range(1, round_count + 1)
+    panel_class = "code-panel" if medium == MEDIUM_CODE else "text-panel"
+    return f'<div class="{panel_class}">{joined}</div>'
+
+
+def _render_term_grid(issue_class: dict, medium: str) -> str:
+    """Return the before/after panel grid for one issue class.
+
+    Args:
+        issue_class: One issue-class dict from the summary.
+        medium: The medium that styles both panels.
+
+    Returns:
+        An HTML .term-grid string with a before panel and an after panel.
+    """
+    before_lines = list(issue_class.get(ISSUE_CLASS_FIELD_BEFORE_LINES, []))
+    after_lines = list(issue_class.get(ISSUE_CLASS_FIELD_AFTER_LINES, []))
+    before_body = _render_panel_body(before_lines, medium)
+    after_body = _render_panel_body(after_lines, medium)
+    return (
+        '<div class="term-grid">'
+        '<div class="term-wrap before">'
+        f'<div class="tlabel">{TIMELINE_BEFORE_LABEL} '
+        f'<span class="pill-x">{TIMELINE_BEFORE_PILL}</span></div>'
+        f"{before_body}"
+        "</div>"
+        '<div class="term-wrap after">'
+        f'<div class="tlabel">{TIMELINE_AFTER_LABEL} '
+        f'<span class="pill-c">{TIMELINE_AFTER_PILL}</span></div>'
+        f"{after_body}"
+        "</div>"
+        "</div>"
     )
-    return _render_chart_card("Tests added per round", rows)
 
 
-def _render_theme_chart(finding_count_by_theme: dict[str, int]) -> str:
-    """Return a findings-by-theme chart card.
+def _render_cause_line(issue_class: dict) -> str:
+    """Return the cause line plus a muted severity/category/count/status parenthetical.
 
     Args:
-        finding_count_by_theme: Mapping of theme string to distinct finding count.
+        issue_class: One issue-class dict from the summary.
 
     Returns:
-        An HTML .chart-card string.
+        An HTML .cause string.
     """
-    sorted_themes = sorted(
-        finding_count_by_theme.items(), key=lambda pair: pair[1], reverse=True
+    cause = html.escape(str(issue_class.get(ISSUE_CLASS_FIELD_CAUSE, "")))
+    severity = str(issue_class.get(ISSUE_CLASS_FIELD_SEVERITY, DEFAULT_FINDING_SEVERITY))
+    category = str(issue_class.get(ISSUE_CLASS_FIELD_CATEGORY, CATEGORY_BUG))
+    count = _coerce_count(issue_class.get(ISSUE_CLASS_FIELD_COUNT, 0))
+    status = str(issue_class.get(ISSUE_CLASS_FIELD_STATUS, ""))
+
+    category_label = CATEGORY_LABEL_BY_VALUE.get(category, category)
+    status_label = STATUS_LABEL_BY_VALUE.get(status, status)
+    parenthetical = (
+        f"({html.escape(severity)} {html.escape(category_label)} "
+        f"&middot; &times;{count} &middot; {html.escape(status_label)})"
     )
-    max_count = max((each_count for _, each_count in sorted_themes), default=1)
-    rows = "".join(
-        _render_bar_row(each_theme, each_count, max_count, BAR_COLOR_THEME)
-        for each_theme, each_count in sorted_themes
+    return (
+        '<div class="cause">'
+        f"<b>Why it happened:</b> {cause} "
+        f'<span style="{CAUSE_MUTED_STYLE}">{parenthetical}</span>'
+        "</div>"
     )
-    return _render_chart_card("Findings by theme", rows)
 
 
-def _render_fix_block(finding: RawFinding, fix_by_round: dict[int, FixRecord]) -> str:
-    """Return the green fix resolution sub-block for a finding card.
+def _issue_class_sort_key(issue_class: dict) -> tuple[int, int]:
+    """Return a sort key ordering bug classes first, then by severity.
 
     Args:
-        finding: The raw finding being described.
-        fix_by_round: Mapping of round number to fix record.
+        issue_class: One issue-class dict from the summary.
 
     Returns:
-        An HTML .bug-fix string describing how the finding was resolved.
+        A tuple of (category rank, severity rank); lower sorts first.
     """
-    round_number = finding.round_number
-    fix_record = fix_by_round.get(round_number)
+    category = issue_class.get(ISSUE_CLASS_FIELD_CATEGORY, CATEGORY_BUG)
+    severity = issue_class.get(ISSUE_CLASS_FIELD_SEVERITY, DEFAULT_FINDING_SEVERITY)
+    category_rank = CATEGORY_SORT_ORDER.get(category, len(CATEGORY_SORT_ORDER))
+    severity_rank = SEVERITY_SORT_RANK.get(severity, len(SEVERITY_SORT_RANK))
+    return (category_rank, severity_rank)
 
-    if fix_record is None:
-        return '<div class="bug-fix"><b>Fix:</b> resolved during convergence.</div>'
 
-    if fix_record.resolved_without_commit:
+def _render_issue_class_heading(issue_class: dict) -> str:
+    """Return the per-class heading with the plain bug name and an occurrence count.
+
+    Args:
+        issue_class: One issue-class dict from the summary.
+
+    Returns:
+        An HTML .bug-head block with the plain bug name and a finding-count chip.
+    """
+    plain_name = html.escape(str(issue_class.get(ISSUE_CLASS_FIELD_PLAINNAME, "")))
+    count = _coerce_count(issue_class.get(ISSUE_CLASS_FIELD_COUNT, 0))
+    count_phrase = html.escape(_pluralize(count, "finding", "findings"))
+    return (
+        '<div class="bug-head">'
+        f'<span class="bug-name">{plain_name}</span>'
+        f'<span class="bug-count">{count_phrase}</span>'
+        "</div>"
+    )
+
+
+def _render_issue_class_block(issue_class: dict) -> str:
+    """Return one issue-class block: a name heading, before/after panels, a cause line.
+
+    Args:
+        issue_class: One issue-class dict from the summary.
+
+    Returns:
+        An HTML fragment that opens with the .bug-head name heading, then a
+        .term-grid when panel lines exist, then the .cause line; the heading and
+        cause line alone when both before and after lines are empty.
+    """
+    heading = _render_issue_class_heading(issue_class)
+    medium = str(issue_class.get(ISSUE_CLASS_FIELD_MEDIUM, MEDIUM_TERMINAL))
+    before_lines = list(issue_class.get(ISSUE_CLASS_FIELD_BEFORE_LINES, []))
+    after_lines = list(issue_class.get(ISSUE_CLASS_FIELD_AFTER_LINES, []))
+
+    cause_line = _render_cause_line(issue_class)
+    if not before_lines and not after_lines:
+        return heading + cause_line
+
+    term_grid = _render_term_grid(issue_class, medium)
+    return heading + term_grid + cause_line
+
+
+def _render_issue_class_panels(convergence_summary: dict) -> str:
+    """Return the per-issue-class before/after panels and cause lines.
+
+    Args:
+        convergence_summary: A structurally valid convergence summary.
+
+    Returns:
+        An HTML fragment with one block per issue class, ordered bug classes
+        first then by severity.
+    """
+    issue_classes = [
+        each_class
+        for each_class in convergence_summary.get(SUMMARY_FIELD_ISSUE_CLASSES, [])
+        if isinstance(each_class, dict)
+    ]
+    if not issue_classes:
         return (
-            f'<div class="bug-fix"><b>Fix:</b> already resolved at HEAD in round {round_number}; '
-            f"threads closed.</div>"
+            '<p class="subtitle">No issues were caught &mdash; '
+            "every review lens was clean.</p>"
         )
+    sorted_classes = sorted(issue_classes, key=_issue_class_sort_key)
+    return "".join(
+        _render_issue_class_block(each_class) for each_class in sorted_classes
+    )
 
-    if not fix_record.new_sha:
-        return '<div class="bug-fix"><b>Fix:</b> resolved during convergence.</div>'
 
-    new_sha_short = fix_record.new_sha[:8]
+def _render_caught_lead(
+    convergence_summary: dict, run_data: RunData, round_count: int
+) -> str:
+    """Return the run-stats lead line that opens the caught section.
+
+    Args:
+        convergence_summary: A structurally valid convergence summary.
+        run_data: Aggregated metrics from the journal.
+        round_count: Total number of convergence rounds.
+
+    Returns:
+        An HTML .subtitle line stating bug-class, finding, round, and fix counts.
+    """
+    issue_classes = [
+        each_class
+        for each_class in convergence_summary.get(SUMMARY_FIELD_ISSUE_CLASSES, [])
+        if isinstance(each_class, dict)
+    ]
+    class_phrase = _pluralize(len(issue_classes), "bug class", "bug classes")
+    finding_phrase = _pluralize(run_data.total_finding_count, "finding", "findings")
+    round_phrase = _pluralize(round_count, "round", "rounds")
+    fix_phrase = _pluralize(run_data.fix_commit_count, "fix commit", "fix commits")
     return (
-        f'<div class="bug-fix"><b>Fix:</b> resolved in the round {round_number} fix commit '
-        f"<code>{html.escape(new_sha_short)}</code>.</div>"
+        f'<p class="subtitle">{class_phrase} ({finding_phrase} in all), '
+        f"caught and fixed across {round_phrase} in {fix_phrase}.</p>"
     )
 
 
-def _render_bug_card(
-    index: int,
-    finding: RawFinding,
-    fix_by_round: dict[int, FixRecord],
-    card_class: str,
-) -> str:
-    """Return an HTML .bug-card element for one finding.
+def _appendix_finding_sort_key(finding: RawFinding) -> tuple[int, int, str, int]:
+    """Return a sort key grouping appendix findings by category then severity.
 
     Args:
-        index: 1-based display index for the card.
-        finding: The raw finding to render.
-        fix_by_round: Mapping of round number to fix record for the fix sub-block.
-        card_class: Either 'crit' or 'minor'.
+        finding: One distinct finding.
 
     Returns:
-        An HTML string for one .bug-card.
+        A tuple of (category rank, severity rank, file, line).
     """
-    severity = finding.severity
-    badge_class = SEVERITY_BADGE_CLASS_BY_LEVEL.get(severity, "b-p2")
-    escaped_title = html.escape(finding.title)
-    escaped_detail = html.escape(finding.detail)
-    escaped_file = html.escape(finding.file)
-    line_number = finding.line
-    round_number = finding.round_number
+    category_rank = CATEGORY_SORT_ORDER.get(finding.category, len(CATEGORY_SORT_ORDER))
+    severity_rank = SEVERITY_SORT_RANK.get(finding.severity, len(SEVERITY_SORT_RANK))
+    return (category_rank, severity_rank, finding.file, finding.line)
 
-    fix_block = _render_fix_block(finding, fix_by_round)
 
-    return (
-        f'<div class="bug-card {card_class}">'
-        f'<div class="bug-head">'
-        f'<span class="bug-num">#{index}</span>'
-        f'<span class="bug-title">{escaped_title}</span>'
-        f'<div class="badges">'
-        f'<span class="badge {badge_class}">{html.escape(severity)}</span>'
-        f'<span class="badge b-fixed">Fixed</span>'
-        f"</div>"
-        f"</div>"
-        f'<div class="bug-impact">{escaped_detail}</div>'
-        f"{fix_block}"
-        f'<div class="bug-meta"><code>{escaped_file}</code>:{line_number} · round {round_number}</div>'
+def _render_appendix(findings: list[RawFinding]) -> str:
+    """Return a collapsed <details> appendix of raw distinct findings.
+
+    Args:
+        findings: The distinct findings to list, grouped by category then severity.
+
+    Returns:
+        An HTML <details> string listing each finding as 'file:line — P# — title'.
+    """
+    if not findings:
+        return ""
+    sorted_findings = sorted(findings, key=_appendix_finding_sort_key)
+    items = "".join(
+        f'<div class="appendix-item">'
+        f"{html.escape(each_finding.file)}:{each_finding.line} &mdash; "
+        f"{html.escape(each_finding.severity)} &mdash; "
+        f"{html.escape(each_finding.title)}"
         f"</div>"
+        for each_finding in sorted_findings
+    )
+    return (
+        '<details class="appendix">'
+        f"<summary>Raw findings ({len(findings)})</summary>"
+        f'<div class="appendix-body">{items}</div>'
+        "</details>"
     )
 
 
-def _render_stat(label: str, stat_value: int) -> str:
-    """Return an HTML .stat block for the summary stats row.
+def _render_summary_body(
+    run_data: RunData, round_count: int, final_sha_short: str
+) -> str:
+    """Return the body for a run that carries a valid convergence summary.
 
     Args:
-        label: The label displayed below the number.
-        stat_value: The numeric value to display.
+        run_data: Aggregated metrics from the journal.
+        round_count: Total number of convergence rounds.
+        final_sha_short: First eight characters of the final commit sha.
 
     Returns:
-        An HTML string for one .stat element.
+        An HTML body fragment: verdict banner, problem/fix cards, then a single
+        caught section that opens with a run-stats lead line and holds the
+        issue-class before/after panels, followed by the collapsed appendix.
     """
-    escaped_label = html.escape(label)
+    convergence_summary = run_data.convergence_summary
+    if convergence_summary is None:
+        return _render_degraded_body(run_data, round_count, final_sha_short)
+
+    verdict_banner = _render_verdict_banner(
+        convergence_summary, run_data, final_sha_short
+    )
+    pf_grid = _render_pf_grid(convergence_summary)
+    caught_lead = _render_caught_lead(convergence_summary, run_data, round_count)
+    issue_panels = _render_issue_class_panels(convergence_summary)
+    appendix = _render_appendix(run_data.all_distinct_findings)
     return (
-        f'<div class="stat">'
-        f'<div class="stat-value">{stat_value}</div>'
-        f'<div class="stat-label">{escaped_label}</div>'
-        f"</div>"
+        f"{verdict_banner}"
+        f"<h2>What this PR does</h2>{pf_grid}"
+        f"<h2>What was caught &mdash; and how it looked</h2>{caught_lead}{issue_panels}"
+        f"{appendix}"
     )
 
 
-def _render_finding_cards(
-    findings: list[RawFinding],
-    fix_by_round: dict[int, FixRecord],
-    card_class: str,
+def _render_degraded_body(
+    run_data: RunData, round_count: int, final_sha_short: str
 ) -> str:
-    """Return an HTML .bugs container with one .bug-card per finding.
+    """Return the minimal degraded body for a run with no valid summary.
 
     Args:
-        findings: The list of raw findings to render.
-        fix_by_round: Mapping of round number to fix record.
-        card_class: Either 'crit' or 'minor'.
+        run_data: Aggregated metrics from the journal.
+        round_count: Total number of convergence rounds.
+        final_sha_short: First eight characters of the final commit sha.
 
     Returns:
-        An HTML string for the .bugs container, or empty string when findings is empty.
+        An HTML body fragment: a plain run-stats note and the collapsed
+        raw-findings appendix, with no scene, table, rollup, or timeline markup.
     """
-    if not findings:
-        return ""
-    cards = "".join(
-        _render_bug_card(each_index + 1, each_finding, fix_by_round, card_class)
-        for each_index, each_finding in enumerate(findings)
+    fix_commit_phrase = _pluralize(
+        run_data.fix_commit_count, "fix commit", "fix commits"
     )
-    return f'<div class="bugs">{cards}</div>'
+    note = (
+        '<p class="subtitle">'
+        f"{run_data.total_finding_count} distinct findings across {round_count} "
+        f"rounds, resolved in {fix_commit_phrase}. "
+        f"Final commit <code>{html.escape(final_sha_short)}</code>."
+        "</p>"
+    )
+    appendix = _render_appendix(run_data.all_distinct_findings)
+    return f"{note}{appendix}"
 
 
 def render_report_html(
     run_data: RunData, pr_metadata: PrMetadata, generated_date: str
 ) -> str:
-    """Render the convergence insights report as an HTML string.
+    """Render the convergence summary report as an HTML string.
 
     Args:
         run_data: Aggregated metrics from the workflow journal and transcripts.
@@ -684,129 +856,43 @@ def render_report_html(
     Returns:
         A complete HTML document string.
     """
+    short_sha_length = SHORT_SHA_LENGTH
     pr_number = pr_metadata.number
     owner = html.escape(pr_metadata.owner)
     repo = html.escape(pr_metadata.repo)
-    final_sha_short = pr_metadata.final_sha[:8]
+    final_sha_short = pr_metadata.final_sha[:short_sha_length]
     round_count = pr_metadata.round_count
 
-    total_findings = run_data.total_finding_count
-    critical_count = run_data.critical_finding_count
-    minor_count = run_data.minor_finding_count
-    fix_commit_count = run_data.fix_commit_count
-    tests_added_total = sum(run_data.tests_added_by_round.values())
-
     head_html = HTML_HEAD_TEMPLATE.format(
         pr_number=pr_number,
         style_block=HTML_STYLE_BLOCK,
     )
 
     subtitle = (
-        f'<p class="subtitle">{owner}/{repo} · {total_findings} findings '
-        f"across {round_count} rounds · {html.escape(generated_date)}</p>"
+        f'<p class="subtitle">{owner}/{repo} &middot; '
+        f"{run_data.total_finding_count} findings over {round_count} rounds "
+        f"&middot; {html.escape(generated_date)}</p>"
     )
 
-    glance_caught = (
-        f'<div class="glance-section"><strong>What was caught:</strong> autoconverge ran '
-        f"{round_count} rounds and surfaced {total_findings} distinct findings — "
-        f"{critical_count} critical, {minor_count} minor.</div>"
-    )
-    glance_resolution = (
-        f'<div class="glance-section"><strong>Resolution:</strong> every finding was fixed '
-        f"before the PR was marked ready; {fix_commit_count} fix commits landed.</div>"
-    )
-    glance_status = (
-        f'<div class="glance-section"><strong>Status:</strong> the run converged on commit '
-        f"{html.escape(final_sha_short)}.</div>"
-    )
-    at_a_glance = (
-        f'<div class="at-a-glance">'
-        f'<div class="glance-title">At a Glance</div>'
-        f'<div class="glance-sections">'
-        f"{glance_caught}{glance_resolution}{glance_status}"
-        f"</div></div>"
-    )
-
-    nav_toc = (
-        '<nav class="nav-toc">'
-        '<a href="#numbers">The numbers</a>'
-        '<a href="#critical">Critical findings</a>'
-        '<a href="#minor">Minor findings</a>'
-        '<a href="#status">Status</a>'
-        "</nav>"
-    )
-
-    stats_row = (
-        '<div class="stats-row">'
-        + _render_stat("Findings", total_findings)
-        + _render_stat("Critical", critical_count)
-        + _render_stat("Minor", minor_count)
-        + _render_stat("Rounds", round_count)
-        + _render_stat("Fix commits", fix_commit_count)
-        + _render_stat("Tests added", tests_added_total)
-        + "</div>"
-    )
-
-    severity_chart = _render_severity_chart(critical_count, minor_count)
-    round_chart = _render_round_findings_chart(
-        round_count, run_data.finding_count_by_round
-    )
-    tests_chart = _render_tests_chart(round_count, run_data.tests_added_by_round)
-    theme_chart = _render_theme_chart(run_data.finding_count_by_theme)
-
-    charts_row_one = f'<div class="charts-row">{severity_chart}{round_chart}</div>'
-    charts_row_two = f'<div class="charts-row">{tests_chart}{theme_chart}</div>'
-
-    numbers_section = (
-        f'<h2 id="numbers">The numbers</h2>{charts_row_one}{charts_row_two}'
-    )
+    if _is_summary_structurally_valid(run_data.convergence_summary):
+        body_main = _render_summary_body(run_data, round_count, final_sha_short)
+    else:
+        body_main = _render_degraded_body(run_data, round_count, final_sha_short)
 
-    critical_cards = _render_finding_cards(
-        run_data.all_critical_findings, run_data.fix_by_round, "crit"
+    fix_commit_phrase = _pluralize(
+        run_data.fix_commit_count, "fix commit", "fix commits"
     )
-    critical_intro = '<p class="section-intro">P0 and P1 findings caught and fixed during the run.</p>'
-    critical_section = f'<h2 id="critical">Critical findings</h2>' + (
-        f"{critical_intro}{critical_cards}"
-        if run_data.all_critical_findings
-        else '<p class="section-intro">No critical findings.</p>'
-    )
-
-    minor_intro = (
-        '<p class="section-intro">P2 findings caught and fixed during the run.</p>'
-    )
-    minor_cards = _render_finding_cards(
-        run_data.all_minor_findings, run_data.fix_by_round, "minor"
-    )
-    minor_section = f'<h2 id="minor">Minor findings</h2>{minor_intro}{minor_cards}'
-
-    horizon_tip = (
-        f'<div class="horizon-tip">Final commit <code>{html.escape(final_sha_short)}</code> '
-        f"· {round_count} rounds · {fix_commit_count} fix commits.</div>"
-    )
-    status_section = (
-        f'<h2 id="status">Status</h2>'
-        f'<div class="horizon-card">'
-        f'<div class="horizon-title">Converged</div>'
-        f'<div class="horizon-possible">The run converged and the PR was marked ready.</div>'
-        f"{horizon_tip}"
-        f"</div>"
-    )
-
     footer = (
-        f"<footer>{owner}/{repo} · PR #{pr_number} · "
+        f"<footer>{owner}/{repo} &middot; PR #{pr_number} &middot; "
+        f"{run_data.total_finding_count} findings &middot; {round_count} rounds "
+        f"&middot; {fix_commit_phrase} &middot; "
         f"generated {html.escape(generated_date)} from the autoconverge run journal.</footer>"
     )
 
     body_content = (
-        f"<h1>PR #{pr_number} Convergence Insights</h1>"
+        f"<h1>PR #{pr_number} Convergence Summary</h1>"
         f"{subtitle}"
-        f"{at_a_glance}"
-        f"{nav_toc}"
-        f"{stats_row}"
-        f"{numbers_section}"
-        f"{critical_section}"
-        f"{minor_section}"
-        f"{status_section}"
+        f"{body_main}"
         f"{footer}"
     )
 
@@ -843,7 +929,7 @@ def _parse_pr_arg(pr_arg: str, err_stream: TextIO) -> tuple[str, str, int] | Non
 
 
 def main(out_stream: TextIO = sys.stdout, err_stream: TextIO = sys.stderr) -> int:
-    """Parse CLI arguments, load run data, render HTML, write the output file, and emit the path.
+    """Parse CLI arguments, load run data, render HTML, write the file, emit the path.
 
     Args:
         out_stream: Stream to write the output file path to on success.
@@ -853,7 +939,7 @@ def main(out_stream: TextIO = sys.stdout, err_stream: TextIO = sys.stderr) -> in
         Exit code (0 on success, 1 on argument error).
     """
     argument_parser = argparse.ArgumentParser(
-        description="Render autoconverge convergence insights HTML."
+        description="Render autoconverge convergence summary HTML."
     )
     argument_parser.add_argument(
         "--journal", required=True, help="Path to wf_<runId>.json"
@@ -865,14 +951,15 @@ def main(out_stream: TextIO = sys.stdout, err_stream: TextIO = sys.stderr) -> in
         "--rounds", required=True, type=int, help="Total round count"
     )
     argument_parser.add_argument(
-        "--repo", default=".", help="Path to the git repository root"
+        "--summary-file",
+        default=None,
+        help="Path to a JSON file with the convergence summary to inject",
     )
 
     parsed_args = argument_parser.parse_args()
 
     journal_path = Path(parsed_args.journal).resolve()
     out_path = Path(parsed_args.out)
-    repo_path = Path(parsed_args.repo).resolve()
 
     parsed_pr = _parse_pr_arg(parsed_args.pr, err_stream)
     if parsed_pr is None:
@@ -890,7 +977,11 @@ def main(out_stream: TextIO = sys.stdout, err_stream: TextIO = sys.stderr) -> in
         round_count=parsed_args.rounds,
     )
 
-    run_data = load_run_data(journal_path, repo_path)
+    run_data = load_run_data(journal_path)
+    if parsed_args.summary_file:
+        run_data.convergence_summary = json.loads(
+            Path(parsed_args.summary_file).read_text(encoding="utf-8")
+        )
     html_content = render_report_html(run_data, pr_metadata, run_data.generated_date)
 
     out_path.parent.mkdir(parents=True, exist_ok=True)