okstra 0.146.1 → 0.148.0

package/runtime/python/okstra_ctl/render_final_report.py

@@ -1,11 +1,10 @@
 """Render `final-report-<task-type>-<seq>.md` from its JSON SSOT.
 
 The JSON SSOT lives next to the rendered markdown as
-``final-report-<task-type>-<seq>.data.json``. The schema for that file is
-``schemas/final-report-v1.0.schema.json``. Report-writer-worker writes the
-data.json in Phase 6; this renderer + the Jinja2 template at
-``templates/reports/final-report.template.md`` deterministically produce
-the canonical user-facing markdown.
+``final-report-<task-type>-<seq>.data.json``. Its ``schemaVersion`` selects the
+matching final-report schema. Report-writer-worker writes the data.json in
+Phase 6; this renderer + the matching Jinja2 template deterministically
+produce the canonical AI-facing markdown.
 
 Why this exists: prior to v0.32, report-writer-worker wrote the markdown
 directly. Free-form authoring led to silent contract violations — missing
@@ -13,13 +12,10 @@ columns in the Execution Status table, omitted §4 phase-continuation
 rows, ad-hoc ``## Index`` sections. Routing everything through one
 template + schema cuts those failure modes to zero.
 
-The top-of-report ``## Index`` is now a *deterministic* post-render
-section: after Jinja2 renders the body, ``_inject_index_and_anchors``
-appends a scroll anchor to every heading and every ID-defining table row,
-links in-body ID references to their definition, and builds the index
-(section list + ID index) — so every ``FU-001`` / ``E-001`` / ``S-001``
-token is clickable and the reader can jump to any section. This runs on
-every render (including the Phase 7 re-render) and is idempotent.
+For schema-v1 compatibility, the top-of-report ``## Index`` remains a
+deterministic post-render section built by ``_inject_index_and_anchors``.
+Schema v2 keeps its compact fixed AI-handoff order and does not inject the
+legacy reader index; the task-specific HTML provides the human navigation.
 
 Phase 7 mutation flow: ``okstra-token-usage.py --substitute-data`` fills
 the ``tokenUsage`` and ``executionStatus[].totalTokens`` etc. cells in
@@ -27,9 +23,9 @@ data.json, then re-invokes this renderer so the markdown stays in sync.
 The markdown is never hand-edited.
 
 As of v0.33+, the renderer itself is the schema-enforcement seam: data.json
-is validated against ``schemas/final-report-v1.0.schema.json`` before any
-Jinja2 rendering begins, so schema violations are caught at write-time
-rather than only by the post-hoc ``validators/validate-run.py``.
+is validated against its version-selected schema before any Jinja2 rendering
+begins, so schema violations are caught at write-time rather than only by the
+post-hoc ``validators/validate-run.py``.
 """
 from __future__ import annotations
 
@@ -48,16 +44,37 @@ from typing import Any
 import okstra_vendor  # noqa: F401 — side effect: sys.modules aliases
 from jinja2 import ChainableUndefined, Environment, FileSystemLoader
 
-from okstra_ctl.final_report_schema import SchemaError, load_schema, validate as schema_validate
+from okstra_ctl.final_report_schema import (
+    SchemaError,
+    load_schema_for_data,
+    validate as schema_validate,
+)
 from okstra_ctl.i18n import I18nError, SUPPORTED_LANGS, load_dictionary, make_jinja_global
 from okstra_ctl.md_table import UNESCAPED_PIPE_RE, to_cell_text
 from okstra_ctl.models import UnknownModelError, resolve_model_metadata
+from okstra_ctl.report_contract import TASK_TYPE_DATA_PROPERTY
 from okstra_ctl.schema_excerpt import excerpt_cut_from_version
 from okstra_ctl.seeding import installed_version
 
 
-DEFAULT_TEMPLATE_REL = ("templates", "reports", "final-report.template.md")
-
+TEMPLATE_BY_SCHEMA_VERSION = {
+    "1.0": ("templates", "reports", "final-report.template.md"),
+    "2.0": ("templates", "reports", "final-report-v2.template.md"),
+}
+DEFAULT_TEMPLATE_REL = TEMPLATE_BY_SCHEMA_VERSION["1.0"]
+
+TASK_DELIVERABLE_TITLES = {
+    "requirements-discovery": "Requirements Discovery",
+    "improvement-discovery": "Improvement Discovery",
+    "error-analysis": "Error Analysis",
+    "project-analysis": "Project Analysis",
+    "feature-analysis": "Feature Analysis",
+    "change-impact-analysis": "Change Impact Analysis",
+    "implementation-planning": "Implementation Planning",
+    "implementation": "Implementation",
+    "final-verification": "Final Verification",
+    "release-handoff": "Release Handoff",
+}
 
 class FinalReportRenderError(RuntimeError):
     """Raised when the data.json cannot be rendered. Wraps jinja2 errors
@@ -438,12 +455,11 @@ def _inject_index_and_anchors(markdown: str, dictionary: dict | None) -> str:
 
 
 def inject_index_into_file(md_path: Path, *, report_language: str = "en") -> int:
-    """Apply the top-of-report index + scroll anchors to an already-written
-    markdown report, in place. This is the seam for task-types that author
-    the markdown free-form (``improvement-discovery``) instead of through the
-    data.json renderer — every other task-type gets the same treatment inside
-    ``render()``. Idempotent (the index anchor guards re-runs). Returns the
-    number of bytes written.
+    """Apply the legacy top-of-report index to an existing Markdown report.
+
+    This remains for schema-v1 and quick compatibility artifacts. Schema-v2
+    reports use the fixed AI-handoff structure and never call this seam.
+    Idempotent; returns the number of bytes written.
     """
     if not md_path.is_file():
         raise FinalReportRenderError(f"report markdown not found: {md_path}")
@@ -470,7 +486,7 @@ def _enforce_schema(data: dict) -> None:
     Phase 7 재렌더를 hard-fail 시키는 것은 과도하다.
     """
     try:
-        schema = load_schema()
+        schema = load_schema_for_data(data)
     except SchemaError as exc:
         print(
             f"render-final-report: schema not locatable; skipping schema enforcement ({exc})",
@@ -544,6 +560,7 @@ def _build_environment(template_dir: Path) -> Environment:
     env.filters["yaml_scalar"] = _yaml_scalar
     env.filters["yaml_inline_list"] = _yaml_inline_list
     env.filters["model_detail"] = _model_detail
+    env.filters["json_block"] = _json_markdown_block
     # `mdcell` neutralises the two things in worker prose that can break a
     # markdown table row: a literal `|` (splits the row) and a newline
     # (truncates it, dropping every later column). Table-cell interpolations
@@ -558,6 +575,61 @@ def _build_environment(template_dir: Path) -> Environment:
     return env
 
 
+def _json_markdown_block(value: Any) -> str:
+    serialized = json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True)
+    return "\n".join(f"    {line}" for line in serialized.splitlines())
+
+
+def _without_human_narrative(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {
+            key: _without_human_narrative(item)
+            for key, item in value.items()
+            if key != "userNarrative"
+        }
+    if isinstance(value, list):
+        return [_without_human_narrative(item) for item in value]
+    return value
+
+
+def _ai_markdown_context(data: dict) -> dict:
+    context = _with_optional_defaults(data)
+    header = data.get("header") if isinstance(data.get("header"), dict) else {}
+    task_type = header.get("taskType", "")
+    property_name = TASK_TYPE_DATA_PROPERTY.get(task_type, "")
+    context["aiTaskDeliverableTitle"] = TASK_DELIVERABLE_TITLES.get(
+        task_type, task_type
+    )
+    context["aiTaskDeliverable"] = _without_human_narrative(
+        data.get(property_name, {})
+    )
+    context["aiEvidenceLedger"] = {
+        "evidence": data.get("evidence", {}),
+        "missingInformation": data.get("missingInformation", []),
+        "endStateCoverage": data.get("endStateCoverage", []),
+        "analysisCommon": data.get("analysisCommon"),
+    }
+    context["aiRoutingContract"] = {
+        "recommendedNextSteps": data.get("recommendedNextSteps", []),
+        "followUpTasks": data.get("followUpTasks", []),
+    }
+    context["aiDecisionContext"] = {
+        "rationale": data.get("rationale", {}),
+        "summary": data.get("summary", []),
+        "ticketCoverage": data.get("ticketCoverage"),
+        "finalVerdict": data.get("finalVerdict", {}),
+    }
+    context["aiBlockingIds"] = [
+        row.get("id")
+        for row in data.get("clarificationItems", [])
+        if isinstance(row, dict)
+        and row.get("status") in {"open", "answered"}
+        and row.get("blocks") in {"approval", "next-phase"}
+        and isinstance(row.get("id"), str)
+    ]
+    return context
+
+
 def resolve_report_language(data: dict, *, override: str | None) -> str:
     """우선순위: override > data.meta.reportLanguage > 'en'."""
     if override is not None:
@@ -638,8 +710,14 @@ def render(
 
     try:
         template = env.get_template(template_path.name)
-        rendered = template.render(**_with_optional_defaults(data))
-        rendered = _inject_index_and_anchors(rendered, dictionary)
+        context = (
+            _ai_markdown_context(data)
+            if data.get("schemaVersion") == "2.0"
+            else _with_optional_defaults(data)
+        )
+        rendered = template.render(**context)
+        if data.get("schemaVersion") == "1.0":
+            rendered = _inject_index_and_anchors(rendered, dictionary)
         return _ventilate_prose(rendered)
     except I18nError as exc:
         raise FinalReportRenderError(
@@ -680,6 +758,36 @@ def find_default_template(start: Path | None = None) -> Path:
     )
 
 
+def find_default_template_for_data(
+    data: dict, start: Path | None = None
+) -> Path:
+    """Locate the Markdown template selected by ``data.schemaVersion``."""
+    version = data.get("schemaVersion")
+    try:
+        relative_path = TEMPLATE_BY_SCHEMA_VERSION[version]
+    except KeyError as exc:
+        raise FinalReportRenderError(
+            f"unsupported final-report schemaVersion: {version}"
+        ) from exc
+
+    okstra_home = os.environ.get("OKSTRA_HOME")
+    if okstra_home:
+        candidate = Path(okstra_home).joinpath(*relative_path)
+        if candidate.is_file():
+            return candidate
+
+    here = Path(start or __file__).resolve()
+    for parent in [here, *here.parents]:
+        candidate = parent.joinpath(*relative_path)
+        if candidate.is_file():
+            return candidate
+
+    raise FinalReportRenderError(
+        f"could not locate {relative_path[-1]}. Set OKSTRA_HOME or run from a "
+        "checkout that contains templates/reports/."
+    )
+
+
 def _bundle_excerpt_path(data_path: Path) -> Path | None:
     """The task bundle's schema excerpt, found by walking up from *data_path*."""
     for ancestor in data_path.resolve().parents:
@@ -746,7 +854,7 @@ def render_to_file(
     # 프로젝트의 .okstra 트리만 위로 뒤지다 templates/reports 를 못 찾아
     # 설치본에서 항상 'could not locate template' 으로 실패한다(OKSTRA_HOME 을
     # 수동 설정해야 했던 원인). 프로젝트별 override 는 --template 으로 한다.
-    resolved_template = template_path or find_default_template()
+    resolved_template = template_path or find_default_template_for_data(data)
     try:
         rendered = render(
             data,

package/runtime/python/okstra_ctl/report_contract.py

@@ -0,0 +1,124 @@
+"""Single registry for public final-report task contracts."""
+from __future__ import annotations
+
+
+CURRENT_REPORT_SCHEMA_VERSION = "2.0"
+LEGACY_REPORT_SCHEMA_VERSION = "1.0"
+
+PUBLIC_REPORT_TASK_TYPES = (
+    "requirements-discovery",
+    "improvement-discovery",
+    "error-analysis",
+    "project-analysis",
+    "feature-analysis",
+    "change-impact-analysis",
+    "implementation-planning",
+    "implementation",
+    "final-verification",
+    "release-handoff",
+)
+
+TASK_TYPE_DATA_PROPERTY = {
+    "requirements-discovery": "requirementsDiscovery",
+    "improvement-discovery": "improvementDiscovery",
+    "error-analysis": "errorAnalysis",
+    "project-analysis": "projectAnalysis",
+    "feature-analysis": "featureAnalysis",
+    "change-impact-analysis": "changeImpactAnalysis",
+    "implementation-planning": "implementationPlanning",
+    "implementation": "implementation",
+    "final-verification": "finalVerification",
+    "release-handoff": "releaseHandoff",
+}
+
+TASK_TYPE_HTML_TEMPLATE = {
+    task_type: f"html/tasks/{task_type}.template.html"
+    for task_type in PUBLIC_REPORT_TASK_TYPES
+}
+
+TASK_TYPE_REQUIRED_HUMAN_FIELDS = {
+    "requirements-discovery": (
+        "requirementsDiscovery.requestVerbatim",
+        "requirementsDiscovery.systemInterpretation",
+        "requirementsDiscovery.classification",
+        "requirementsDiscovery.confirmedRequirements",
+        "requirementsDiscovery.unresolvedRequirements",
+    ),
+    "improvement-discovery": (
+        "improvementDiscovery.candidates",
+        "improvementDiscovery.lensCoverage",
+    ),
+    "error-analysis": (
+        "errorAnalysis.symptomVerbatim",
+        "errorAnalysis.observableFailure",
+        "errorAnalysis.causeCandidates.confidence",
+        "errorAnalysis.causeCandidates.falsifyingEvidenceChecked",
+        "errorAnalysis.causeCandidates.disproveWith",
+    ),
+    "project-analysis": (
+        "projectAnalysis.components",
+        "projectAnalysis.entryPoints",
+        "projectAnalysis.dataStores",
+        "projectAnalysis.externalSystems",
+        "projectAnalysis.rankedHotspots",
+        "projectAnalysis.qualityCoverage",
+        "projectAnalysis.featureIndex",
+    ),
+    "feature-analysis": (
+        "featureAnalysis.flows",
+        "featureAnalysis.domainRules",
+        "featureAnalysis.stateChanges",
+        "featureAnalysis.externalInteractions",
+        "featureAnalysis.testCoverage",
+    ),
+    "change-impact-analysis": (
+        "changeImpactAnalysis.impactItems",
+        "changeImpactAnalysis.dependencyBlastRadius",
+        "changeImpactAnalysis.unaffectedBoundaries",
+        "changeImpactAnalysis.compatibilityImpact",
+        "changeImpactAnalysis.migrationImpact",
+        "changeImpactAnalysis.rollbackImpact",
+        "changeImpactAnalysis.securityAndPerformanceImpact",
+        "changeImpactAnalysis.planningInputs",
+    ),
+    "implementation-planning": (
+        "implementationPlanning.optionCandidates",
+        "implementationPlanning.tradeoffMatrix",
+        "implementationPlanning.recommendedOption",
+        "implementationPlanning.stageMap",
+        "implementationPlanning.validationChecklist",
+        "implementationPlanning.rollbackStrategy",
+    ),
+    "implementation": (
+        "implementation.diffSummary",
+        "implementation.requirementCoverage",
+        "implementation.validationEvidence",
+        "implementation.manualUserTest",
+    ),
+    "final-verification": (
+        "finalVerification.validationEvidence",
+        "finalVerification.acceptanceBlockers",
+        "finalVerification.residualRisk",
+        "finalVerification.manualUserTest",
+    ),
+    "release-handoff": (
+        "releaseHandoff.userSelections",
+        "releaseHandoff.featureBranchState",
+        "releaseHandoff.pullRequestOutcome",
+        "releaseHandoff.mergeConflictProbe",
+    ),
+}
+
+
+def report_property_for(task_type: str) -> str:
+    try:
+        return TASK_TYPE_DATA_PROPERTY[task_type]
+    except KeyError as exc:
+        raise ValueError(f"unsupported public report task type: {task_type}") from exc
+
+
+def html_template_for(task_type: str) -> str:
+    try:
+        return TASK_TYPE_HTML_TEMPLATE[task_type]
+    except KeyError as exc:
+        raise ValueError(f"no task-specific html template for: {task_type}") from exc

package/runtime/python/okstra_ctl/report_finalize.py

@@ -227,7 +227,7 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
                         ctx.workspace_root, "okstra-render-report-views.py"
                     )
                 ),
-                str(markdown_path),
+                str(ctx.data_path),
                 "--task-key",
                 ctx.task_key,
                 "--task-type",

package/runtime/python/okstra_ctl/report_html/__init__.py

@@ -0,0 +1,10 @@
+"""Task-specific human HTML rendering for final-report schema v2."""
+
+
+def render_v2_html_view(*args, **kwargs):
+    """Load the vendored template runtime only when a v2 view is rendered."""
+    from .render import render_v2_html_view as render
+
+    return render(*args, **kwargs)
+
+__all__ = ["render_v2_html_view"]

package/runtime/python/okstra_ctl/report_html/common.py

@@ -0,0 +1,86 @@
+"""Common data transformations that carry no task-specific section order."""
+from __future__ import annotations
+
+
+def audit_context(data: dict) -> dict[str, object]:
+    return {
+        "crossVerification": data.get("crossVerification", {}),
+        "executionStatus": data.get("executionStatus", []),
+        "tokenUsage": data.get("tokenUsage", {}),
+    }
+
+
+_LEDGER_TEXT_KEYS = ("statement", "evidence", "hypothesis", "question")
+_LEDGER_SOURCE_KEYS = ("source", "confidence", "reason")
+
+
+def _first_filled(row: dict, keys: tuple[str, ...]) -> str:
+    for key in keys:
+        value = row.get(key)
+        if value:
+            return str(value)
+    return ""
+
+
+def _ledger_row(row: dict) -> dict[str, object]:
+    """Flatten one evidence row into the single shape the ledger renders.
+
+    Every row type that reaches the ledger is ``additionalProperties: false``
+    and names its content and source differently, so no row carries another
+    row type's keys:
+
+    - ``evidence.primary`` — ``evidence`` / ``source``
+    - ``evidence.secondary`` — ``hypothesis`` / ``confidence``
+    - ``analysisCommon.confirmedFacts`` — ``statement`` / ``currentCodeEvidence``
+    - ``analysisCommon.inferences`` — ``statement`` / ``confidence``
+    - ``analysisCommon.unknowns`` — ``question`` / ``reason``
+
+    Only this function knows which block a row came from, so the key hunt
+    belongs here rather than in the template.
+    """
+    return {
+        "id": row.get("id", ""),
+        "text": _first_filled(row, _LEDGER_TEXT_KEYS),
+        "codeEvidence": row.get("currentCodeEvidence") or [],
+        "source": _first_filled(row, _LEDGER_SOURCE_KEYS),
+    }
+
+
+def evidence_index(data: dict) -> dict[str, object]:
+    rows: dict[str, object] = {}
+    for section in ("primary", "secondary"):
+        for row in data.get("evidence", {}).get(section, []):
+            row_id = row.get("id")
+            if row_id:
+                rows[row_id] = _ledger_row(row)
+    analysis = data.get("analysisCommon", {})
+    for collection in ("confirmedFacts", "inferences", "unknowns"):
+        for row in analysis.get(collection, []):
+            row_id = row.get("id")
+            if row_id:
+                rows[row_id] = _ledger_row(row)
+    return rows
+
+
+def _collect_ids(value: object, found: set[str]) -> None:
+    if isinstance(value, dict):
+        row_id = value.get("id")
+        if isinstance(row_id, str) and row_id:
+            found.add(row_id)
+        for nested in value.values():
+            _collect_ids(nested, found)
+    elif isinstance(value, list):
+        for nested in value:
+            _collect_ids(nested, found)
+
+
+def analysis_review_ids(data: dict) -> tuple[str, ...]:
+    found: set[str] = set()
+    _collect_ids(data.get("analysisCommon", {}), found)
+    task_type = data.get("header", {}).get("taskType", "")
+    from ..report_contract import TASK_TYPE_DATA_PROPERTY
+
+    property_name = TASK_TYPE_DATA_PROPERTY.get(task_type)
+    if property_name:
+        _collect_ids(data.get(property_name, {}), found)
+    return tuple(sorted(found))

package/runtime/python/okstra_ctl/report_html/filters.py

@@ -0,0 +1,104 @@
+"""Jinja filters for the task-specific HTML report."""
+from __future__ import annotations
+
+import html
+import json
+import re
+
+import okstra_vendor  # noqa: F401  # registers vendored dependency aliases
+from markupsafe import Markup, escape
+
+_INLINE_CODE = re.compile(r"`([^`]+)`")
+_SENTENCE_END = re.compile(r"(?<=[.!?])\s+")
+_SENTENCES_PER_PARAGRAPH = 2
+
+
+def audit_json(value: object) -> Markup:
+    """Serialize an audit payload for reading inside a ``<pre>`` text node.
+
+    Jinja's ``tojson`` guards a ``<script>`` context, so it escapes quotes and
+    angle brackets as ``\\uXXXX`` and leaves shell commands and non-ASCII
+    evidence unreadable. A text node only needs ``&``, ``<`` and ``>`` escaped,
+    hence ``quote=False`` — quotes carry no meaning outside an attribute value.
+    """
+    rendered = json.dumps(value, indent=2, ensure_ascii=False, sort_keys=True)
+    return Markup(html.escape(rendered, quote=False))
+
+
+def inline_code(value: object) -> Markup:
+    """Convert paired backticks to ``<code>``, escaping everything else.
+
+    Workers author report prose with Markdown conventions, so an identifier
+    arrives wrapped in backticks. ``escape`` also covers quotes, unlike
+    ``audit_json`` above, which is text-node only.
+    """
+    text = "" if value is None else str(value)
+    out: list[str] = []
+    cursor = 0
+    for match in _INLINE_CODE.finditer(text):
+        out.append(str(escape(text[cursor:match.start()])))
+        out.append(f"<code>{escape(match.group(1))}</code>")
+        cursor = match.end()
+    out.append(str(escape(text[cursor:])))
+    return Markup("".join(out))
+
+
+def _grouped_paragraphs(text: str) -> list[str]:
+    explicit = [block.strip() for block in re.split(r"\n\s*\n", text) if block.strip()]
+    if len(explicit) > 1:
+        return explicit
+    sentences = [s.strip() for s in _SENTENCE_END.split(text.strip()) if s.strip()]
+    if len(sentences) <= _SENTENCES_PER_PARAGRAPH:
+        return [text.strip()] if text.strip() else []
+    return [
+        " ".join(sentences[i:i + _SENTENCES_PER_PARAGRAPH])
+        for i in range(0, len(sentences), _SENTENCES_PER_PARAGRAPH)
+    ]
+
+
+def paragraphs(value: object) -> Markup:
+    """Split prose into ``<p>`` blocks, converting inline code inside each.
+
+    ``userNarrative`` prose arrives as one unbroken run of sentences, so the
+    reader gets no paragraph boundary anywhere in the document. An author who
+    did supply blank lines keeps their own boundaries.
+    """
+    text = "" if value is None else str(value)
+    return Markup("".join(f"<p>{inline_code(block)}</p>" for block in _grouped_paragraphs(text)))
+
+
+def evidence_refs(refs: object, index: object) -> Markup:
+    """Render evidence ids as anchors when the ledger defines them.
+
+    A citation whose id has no ledger row would link to a missing anchor, so it
+    stays text. No schema behind this filter constrains that text to an id —
+    most of it is prose citing a ``path:line``, so it takes ``inline_code`` like
+    every other prose cell. An anchor's own text is the id it links to and gets
+    no ``<code>`` wrapper.
+    """
+    rows = index if isinstance(index, dict) else {}
+    items = refs if isinstance(refs, (list, tuple)) else []
+    out: list[str] = []
+    for ref in items:
+        if str(ref) not in rows:
+            out.append(str(inline_code(ref)))
+            continue
+        text = escape(str(ref))
+        out.append(f'<a href="#ev-{text}">{text}</a>')
+    return Markup(", ".join(out))
+
+
+def code_evidence(rows: object) -> Markup:
+    """Render ``currentCodeEvidence`` entries as ``path:line`` code spans."""
+    items = rows if isinstance(rows, (list, tuple)) else []
+    out: list[str] = []
+    for row in items:
+        if not isinstance(row, dict):
+            continue
+        path = str(row.get("path", "")).strip()
+        if not path:
+            continue
+        line = row.get("line")
+        ref = f"{path}:{line}" if line else path
+        out.append(f"<code>{escape(ref)}</code>")
+    return Markup(", ".join(out))

package/runtime/python/okstra_ctl/report_html/models.py

@@ -0,0 +1,59 @@
+"""Stable view-model types shared by task-specific HTML renderers."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+
+@dataclass(frozen=True)
+class HtmlRunMeta:
+    task_key: str
+    task_type: str
+    seq: str
+    source_report: str
+
+
+@dataclass(frozen=True)
+class VisualNode:
+    id: str
+    label: str
+    group: str
+    status: str
+    detail: str
+
+
+@dataclass(frozen=True)
+class VisualEdge:
+    source: str
+    target: str
+    label: str
+    kind: str
+
+
+@dataclass(frozen=True)
+class FigureModel:
+    figure_id: str
+    kind: str
+    title: str
+    summary: str
+    nodes: tuple[VisualNode, ...]
+    edges: tuple[VisualEdge, ...]
+    svg: str
+
+    @property
+    def table_row_ids(self) -> tuple[str, ...]:
+        return tuple(node.id for node in self.nodes)
+
+
+@dataclass(frozen=True)
+class HumanReportView:
+    task_type: str
+    template_name: str
+    context: dict[str, object]
+    figures: tuple[FigureModel, ...]
+
+
+@dataclass(frozen=True)
+class HtmlRoute:
+    template_name: str
+    view_builder: Callable[[dict], HumanReportView]