okstra 0.146.0 → 0.147.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,50 @@
+"""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", {}),
+    }
+
+
+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] = 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] = 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/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]

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

@@ -0,0 +1,69 @@
+"""Render schema-v2 data directly into a task-specific HTML document."""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+import okstra_vendor  # noqa: F401  # registers vendored dependency aliases
+from jinja2 import Environment, FileSystemLoader, StrictUndefined, select_autoescape
+
+from ..final_report_schema import load_schema_for_data, validate
+from .models import HtmlRunMeta
+from .router import HtmlRenderError, resolve_html_route
+
+
+def _sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _templates_root(start: Path | None = None) -> Path:
+    if start is not None:
+        return start
+    here = Path(__file__).resolve()
+    for parent in [here, *here.parents]:
+        candidate = parent / "templates" / "reports"
+        if candidate.is_dir():
+            return candidate
+    raise HtmlRenderError("could not locate templates/reports")
+
+
+def _html_path(data_path: Path) -> Path:
+    suffix = ".data.json"
+    if not data_path.name.endswith(suffix):
+        raise HtmlRenderError(f"v2 report path must end with {suffix}: {data_path}")
+    return data_path.with_name(data_path.name.removesuffix(suffix) + ".html")
+
+
+def render_v2_html_view(
+    data_path: Path,
+    markdown_path: Path,
+    *,
+    run_meta: HtmlRunMeta,
+    templates_root: Path | None = None,
+) -> Path:
+    data = json.loads(data_path.read_text(encoding="utf-8"))
+    errors = validate(data, load_schema_for_data(data))
+    if errors:
+        raise HtmlRenderError("invalid v2 final-report data: " + "; ".join(errors[:5]))
+    if not markdown_path.is_file():
+        raise HtmlRenderError(f"v2 markdown sibling not found: {markdown_path}")
+    route = resolve_html_route(run_meta.task_type)
+    view = route.view_builder(data)
+    root = _templates_root(templates_root)
+    env = Environment(loader=FileSystemLoader(str(root)), autoescape=select_autoescape(("html",)), undefined=StrictUndefined)
+    response_js = (root / "report.js").read_text(encoding="utf-8")
+    base_js = (root / "html/assets/base.js").read_text(encoding="utf-8")
+    context = {
+        **view.context,
+        "runMeta": run_meta,
+        "taskType": view.task_type,
+        "dataSha256": _sha256(data_path),
+        "markdownSha256": _sha256(markdown_path),
+        "clarificationItems": data.get("clarificationItems", []),
+        "css": (root / "html/assets/base.css").read_text(encoding="utf-8"),
+        "js": response_js + "\n" + base_js,
+    }
+    output_path = _html_path(data_path)
+    output_path.write_text(env.get_template(route.template_name).render(**context), encoding="utf-8")
+    return output_path

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

@@ -0,0 +1,40 @@
+"""Fail-closed task-type routing for schema-v2 HTML views."""
+from __future__ import annotations
+
+from ..report_contract import html_template_for
+from .models import HtmlRoute
+from .view_models.change_impact_analysis import build_change_impact_analysis_view
+from .view_models.error_analysis import build_error_analysis_view
+from .view_models.feature_analysis import build_feature_analysis_view
+from .view_models.final_verification import build_final_verification_view
+from .view_models.improvement_discovery import build_improvement_discovery_view
+from .view_models.implementation import build_implementation_view
+from .view_models.implementation_planning import build_implementation_planning_view
+from .view_models.project_analysis import build_project_analysis_view
+from .view_models.release_handoff import build_release_handoff_view
+from .view_models.requirements_discovery import build_requirements_discovery_view
+
+
+class HtmlRenderError(ValueError):
+    """Raised when a v2 task has no dedicated human view."""
+
+
+VIEW_BUILDERS = {
+    "requirements-discovery": build_requirements_discovery_view,
+    "improvement-discovery": build_improvement_discovery_view,
+    "error-analysis": build_error_analysis_view,
+    "project-analysis": build_project_analysis_view,
+    "feature-analysis": build_feature_analysis_view,
+    "change-impact-analysis": build_change_impact_analysis_view,
+    "implementation-planning": build_implementation_planning_view,
+    "implementation": build_implementation_view,
+    "final-verification": build_final_verification_view,
+    "release-handoff": build_release_handoff_view,
+}
+
+
+def resolve_html_route(task_type: str) -> HtmlRoute:
+    builder = VIEW_BUILDERS.get(task_type)
+    if builder is None:
+        raise HtmlRenderError(f"no v2 html view builder for {task_type}")
+    return HtmlRoute(template_name=html_template_for(task_type), view_builder=builder)

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

@@ -0,0 +1 @@
+"""Task-specific human report view builders."""

package/runtime/python/okstra_ctl/report_html/view_models/change_impact_analysis.py

@@ -0,0 +1,38 @@
+"""Human-first change-impact-analysis view model."""
+from __future__ import annotations
+
+from ..common import analysis_review_ids, audit_context
+from ..models import HumanReportView, VisualEdge, VisualNode
+from ..visualizations import flow_figure
+
+
+def _impact_figure(change: dict):
+    nodes = [
+        VisualNode(row["id"], row["target"], "affected", row["level"], row["impactKind"])
+        for row in change.get("impactItems", [])
+    ]
+    edges: list[VisualEdge] = []
+    for index, row in enumerate(change.get("dependencyBlastRadius", []), start=1):
+        target_id = f"BR-{index:03d}"
+        nodes.append(VisualNode(target_id, row["affectedTarget"], "downstream", "risk", row["direction"]))
+        edges.append(VisualEdge(row["sourceImpactId"], target_id, row["direction"], "impact"))
+    return flow_figure(nodes=tuple(nodes), edges=tuple(edges), title="Change blast radius")
+
+
+def build_change_impact_analysis_view(data: dict) -> HumanReportView:
+    change = data["changeImpactAnalysis"]
+    figure = _impact_figure(change)
+    context = {
+        "humanSummary": data["humanSummary"],
+        "change": change,
+        "narrative": change["userNarrative"],
+        "blastRadiusFigure": figure,
+        "analysisReviewIds": analysis_review_ids(data),
+        "audit": audit_context(data),
+    }
+    return HumanReportView(
+        task_type="change-impact-analysis",
+        template_name="html/tasks/change-impact-analysis.template.html",
+        context=context,
+        figures=(figure,),
+    )