okstra 0.146.1 → 0.148.0

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

@@ -0,0 +1,76 @@
+"""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 .filters import audit_json, code_evidence, evidence_refs, inline_code, paragraphs
+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)
+    env.policies["json.dumps_kwargs"] = {"sort_keys": True, "ensure_ascii": False}
+    env.filters["audit_json"] = audit_json
+    env.filters["code_evidence"] = code_evidence
+    env.filters["evidence_refs"] = evidence_refs
+    env.filters["inline_code"] = inline_code
+    env.filters["paragraphs"] = paragraphs
+    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,39 @@
+"""Human-first change-impact-analysis view model."""
+from __future__ import annotations
+
+from ..common import analysis_review_ids, audit_context, evidence_index
+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),
+        "evidenceIndex": evidence_index(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,),
+    )

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

@@ -0,0 +1,49 @@
+"""Human-first error-analysis view model."""
+from __future__ import annotations
+
+from ..common import audit_context, evidence_index
+from ..models import HumanReportView, VisualEdge, VisualNode
+from ..visualizations import cause_graph_figure
+
+
+def _cause_figure(error: dict):
+    symptom = VisualNode(
+        "symptom", "Observed failure", "effect", "risk", error["observableFailure"]
+    )
+    causes = tuple(
+        VisualNode(
+            row["id"],
+            row["statement"],
+            "candidate",
+            row["confidence"],
+            row["disproveWith"],
+        )
+        for row in error.get("causeCandidates", [])
+    )
+    edges = tuple(
+        VisualEdge(row.id, symptom.id, "may cause", "hypothesis") for row in causes
+    )
+    return cause_graph_figure(
+        nodes=(symptom, *causes),
+        edges=edges,
+        title="Cause hypotheses and observed symptom",
+    )
+
+
+def build_error_analysis_view(data: dict) -> HumanReportView:
+    error = data["errorAnalysis"]
+    figure = _cause_figure(error)
+    context = {
+        "humanSummary": data["humanSummary"],
+        "error": error,
+        "narrative": error["userNarrative"],
+        "causeFigure": figure,
+        "evidenceIndex": evidence_index(data),
+        "audit": audit_context(data),
+    }
+    return HumanReportView(
+        "error-analysis",
+        "html/tasks/error-analysis.template.html",
+        context,
+        (figure,),
+    )

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

@@ -0,0 +1,39 @@
+"""Human-first feature-analysis view model."""
+from __future__ import annotations
+
+from ..common import analysis_review_ids, audit_context, evidence_index
+from ..models import HumanReportView, VisualNode
+from ..visualizations import flow_figure
+
+
+def _flow_nodes(feature: dict) -> tuple[VisualNode, ...]:
+    return tuple(
+        VisualNode(
+            id=row["id"],
+            label=row["kind"].title(),
+            group=row["kind"],
+            status="risk" if row["kind"] == "failure" else "stable",
+            detail=" → ".join(step["action"] for step in row.get("steps", [])),
+        )
+        for row in feature.get("flows", [])
+    )
+
+
+def build_feature_analysis_view(data: dict) -> HumanReportView:
+    feature = data["featureAnalysis"]
+    figure = flow_figure(nodes=_flow_nodes(feature), edges=(), title="Feature behavior paths")
+    context = {
+        "humanSummary": data["humanSummary"],
+        "feature": feature,
+        "narrative": feature["userNarrative"],
+        "flowFigure": figure,
+        "analysisReviewIds": analysis_review_ids(data),
+        "evidenceIndex": evidence_index(data),
+        "audit": audit_context(data),
+    }
+    return HumanReportView(
+        task_type="feature-analysis",
+        template_name="html/tasks/feature-analysis.template.html",
+        context=context,
+        figures=(figure,),
+    )

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

@@ -0,0 +1,47 @@
+"""Human-first final-verification view model."""
+from __future__ import annotations
+
+from ..common import audit_context, evidence_index
+from ..models import HumanReportView, VisualNode
+from ..visualizations import coverage_figure
+
+
+def _coverage_nodes(final: dict) -> tuple[VisualNode, ...]:
+    return tuple(
+        VisualNode(
+            row["id"],
+            row["requirement"],
+            "requirement",
+            row["status"],
+            row["artifact"],
+        )
+        for row in final["validationEvidence"]
+    )
+
+
+def build_final_verification_view(data: dict) -> HumanReportView:
+    final = data["finalVerification"]
+    figure = coverage_figure(
+        rows=_coverage_nodes(final), title="Requirement verification coverage"
+    )
+    audit = audit_context(data)
+    audit["deliveryEvidence"] = {
+        "sourceImplementation": final["sourceImplementationReport"],
+        "readonlyCommandLog": final["readonlyCommandLog"],
+    }
+    context = {
+        "humanSummary": data["humanSummary"],
+        "verdict": data["verdictCard"],
+        "final": final,
+        "narrative": final["userNarrative"],
+        "coverageFigure": figure,
+        "releaseAllowed": data["verdictCard"]["verdictToken"] == "accepted",
+        "evidenceIndex": evidence_index(data),
+        "audit": audit,
+    }
+    return HumanReportView(
+        "final-verification",
+        "html/tasks/final-verification.template.html",
+        context,
+        (figure,),
+    )

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

@@ -0,0 +1,47 @@
+"""Human-first implementation delivery view model."""
+from __future__ import annotations
+
+from ..common import audit_context, evidence_index
+from ..models import HumanReportView, VisualNode
+from ..visualizations import change_map_figure
+
+
+def _change_nodes(implementation: dict) -> tuple[VisualNode, ...]:
+    return tuple(
+        VisualNode(
+            row["file"],
+            row["file"],
+            row["planStep"],
+            row["action"],
+            row["lines"],
+        )
+        for row in implementation["diffSummary"]["files"]
+    )
+
+
+def build_implementation_view(data: dict) -> HumanReportView:
+    implementation = data["implementation"]
+    figure = change_map_figure(
+        nodes=_change_nodes(implementation), title="Delivered change areas"
+    )
+    audit = audit_context(data)
+    audit["deliveryEvidence"] = {
+        "commits": implementation["commitList"],
+        "rawDiffStat": implementation["diffSummary"]["rawStat"],
+        "verifiers": implementation["verifierResults"],
+        "validationCommands": implementation["validationEvidence"],
+    }
+    context = {
+        "humanSummary": data["humanSummary"],
+        "implementation": implementation,
+        "narrative": implementation["userNarrative"],
+        "changeFigure": figure,
+        "evidenceIndex": evidence_index(data),
+        "audit": audit,
+    }
+    return HumanReportView(
+        "implementation",
+        "html/tasks/implementation.template.html",
+        context,
+        (figure,),
+    )

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

@@ -0,0 +1,103 @@
+"""Human-first implementation-planning view and approval state."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from ..common import audit_context, evidence_index
+from ..models import HumanReportView, VisualEdge, VisualNode
+from ..visualizations import stage_map_figure
+
+
+@dataclass(frozen=True)
+class PlanApprovalState:
+    option_names: tuple[str, ...]
+    recommended_option: str
+    disabled_reason: str
+    blocker_ids: tuple[str, ...]
+
+
+def resolve_recommended_option(rec_name: str, names: tuple[str, ...]) -> str:
+    if rec_name in names:
+        return rec_name
+    matches = [
+        name
+        for name in names
+        if rec_name and (name.startswith(rec_name) or rec_name.startswith(name))
+    ]
+    return matches[0] if len(matches) == 1 else names[0]
+
+
+def plan_approval_state(data: dict) -> PlanApprovalState | None:
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        return None
+    names = tuple(
+        row["name"]
+        for row in planning.get("optionCandidates", [])
+        if isinstance(row, dict) and row.get("name")
+    )
+    if not names:
+        return None
+    recommended = planning.get("recommendedOption", {}).get("name", "")
+    blockers = tuple(
+        row["id"]
+        for row in data.get("clarificationItems", [])
+        if row.get("blocks") == "approval"
+        and row.get("status") in {"open", "answered"}
+    )
+    reason = f"승인 차단 항목 {len(blockers)}건 미해소" if blockers else ""
+    return PlanApprovalState(
+        names,
+        resolve_recommended_option(recommended, names),
+        reason,
+        blockers,
+    )
+
+
+def _stage_figure(planning: dict):
+    nodes = tuple(
+        VisualNode(
+            f"stage-{row['stage']}",
+            f"Stage {row['stage']} · {row['title']}",
+            "stage",
+            "planned",
+            row["exitContractSummary"],
+        )
+        for row in planning["stageMap"]
+    )
+    edges = tuple(
+        VisualEdge(f"stage-{dependency}", f"stage-{row['stage']}", "precedes", "dependency")
+        for row in planning["stageMap"]
+        for dependency in re.findall(r"\d+", row["dependsOn"])
+    )
+    return stage_map_figure(nodes=nodes, edges=edges, title="Implementation stage dependencies")
+
+
+def build_implementation_planning_view(data: dict) -> HumanReportView:
+    planning = data["implementationPlanning"]
+    figure = _stage_figure(planning)
+    approval = plan_approval_state(data)
+    audit = audit_context(data)
+    audit["planBodyVerification"] = planning["planBodyVerification"]
+    context = {
+        "humanSummary": data["humanSummary"],
+        "planning": planning,
+        "narrative": planning["userNarrative"],
+        "stageFigure": figure,
+        "approval": approval,
+        "openDecisions": [
+            row
+            for row in data.get("clarificationItems", [])
+            if row.get("blocks") == "approval"
+            and row.get("status") in {"open", "answered"}
+        ],
+        "evidenceIndex": evidence_index(data),
+        "audit": audit,
+    }
+    return HumanReportView(
+        "implementation-planning",
+        "html/tasks/implementation-planning.template.html",
+        context,
+        (figure,),
+    )

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

@@ -0,0 +1,43 @@
+"""Human-first improvement-discovery view model."""
+from __future__ import annotations
+
+from ..common import audit_context, evidence_index
+from ..models import HumanReportView, VisualNode
+from ..visualizations import matrix_figure
+
+
+def _candidate_nodes(improvement: dict) -> tuple[VisualNode, ...]:
+    return tuple(
+        VisualNode(
+            row["id"],
+            row["title"],
+            f"effort-{row['effort']}",
+            row["severity"],
+            row["expectedBehaviorAfter"],
+        )
+        for row in improvement.get("candidates", [])
+    )
+
+
+def build_improvement_discovery_view(data: dict) -> HumanReportView:
+    improvement = data["improvementDiscovery"]
+    figure = matrix_figure(
+        items=_candidate_nodes(improvement),
+        title="Candidate impact and effort",
+        x_label="effort",
+        y_label="severity",
+    )
+    context = {
+        "humanSummary": data["humanSummary"],
+        "improvement": improvement,
+        "narrative": improvement["userNarrative"],
+        "matrixFigure": figure,
+        "evidenceIndex": evidence_index(data),
+        "audit": audit_context(data),
+    }
+    return HumanReportView(
+        "improvement-discovery",
+        "html/tasks/improvement-discovery.template.html",
+        context,
+        (figure,),
+    )

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

@@ -0,0 +1,54 @@
+"""Human-first project-analysis view model."""
+from __future__ import annotations
+
+from ..common import audit_context, evidence_index
+from ..models import HumanReportView, VisualEdge, VisualNode
+from ..visualizations import dependency_figure
+
+
+def _component_nodes(project: dict) -> tuple[VisualNode, ...]:
+    return tuple(
+        VisualNode(
+            id=row["id"],
+            label=row["name"],
+            group=(row.get("paths") or ["project"])[0].split("/", 1)[0],
+            status="stable",
+            detail=row["responsibility"],
+        )
+        for row in project.get("components", [])
+    )
+
+
+def _dependency_edges(project: dict) -> tuple[VisualEdge, ...]:
+    return tuple(
+        VisualEdge(
+            source=row["fromComponentId"],
+            target=row["toComponentId"],
+            label=row.get("direction", "dependency"),
+            kind="dependency",
+        )
+        for row in project.get("dependencies", [])
+    )
+
+
+def build_project_analysis_view(data: dict) -> HumanReportView:
+    project = data["projectAnalysis"]
+    architecture = dependency_figure(
+        nodes=_component_nodes(project),
+        edges=_dependency_edges(project),
+        title="Project architecture and dependencies",
+    )
+    context = {
+        "humanSummary": data["humanSummary"],
+        "project": project,
+        "narrative": project["userNarrative"],
+        "architectureFigure": architecture,
+        "evidenceIndex": evidence_index(data),
+        "audit": audit_context(data),
+    }
+    return HumanReportView(
+        task_type="project-analysis",
+        template_name="html/tasks/project-analysis.template.html",
+        context=context,
+        figures=(architecture,),
+    )

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

@@ -0,0 +1,54 @@
+"""Human-first release-handoff view model."""
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+from ..common import audit_context, evidence_index
+from ..models import HumanReportView, VisualNode
+from ..visualizations import timeline_figure
+
+
+def _safe_http_url(value: str) -> str:
+    parsed = urlparse(value)
+    return value if parsed.scheme in {"http", "https"} and parsed.netloc else ""
+
+
+def _timeline_nodes(handoff: dict) -> tuple[VisualNode, ...]:
+    selection = handoff["userSelections"]["h1"]
+    branch = handoff["featureBranchState"]["branchName"]
+    conflict = handoff["mergeConflictProbe"]["kind"]
+    pr = handoff["pullRequestOutcome"]["kind"]
+    return (
+        VisualNode("selection", selection, "handoff", "completed", "User-selected handoff"),
+        VisualNode("branch", branch, "handoff", "completed", "Feature branch state"),
+        VisualNode("conflict", conflict, "handoff", conflict, "Merge conflict probe"),
+        VisualNode("pull-request", pr, "handoff", pr, "Pull request outcome"),
+    )
+
+
+def build_release_handoff_view(data: dict) -> HumanReportView:
+    handoff = data["releaseHandoff"]
+    figure = timeline_figure(
+        events=_timeline_nodes(handoff), title="Release handoff timeline"
+    )
+    audit = audit_context(data)
+    audit["deliveryEvidence"] = {
+        "executedCommands": handoff["executedCommands"],
+        "commits": handoff["commitList"],
+        "sourceVerification": handoff["sourceVerificationReport"],
+    }
+    context = {
+        "humanSummary": data["humanSummary"],
+        "handoff": handoff,
+        "narrative": handoff["userNarrative"],
+        "handoffFigure": figure,
+        "prUrl": _safe_http_url(handoff["pullRequestOutcome"].get("url", "")),
+        "evidenceIndex": evidence_index(data),
+        "audit": audit,
+    }
+    return HumanReportView(
+        "release-handoff",
+        "html/tasks/release-handoff.template.html",
+        context,
+        (figure,),
+    )

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

@@ -0,0 +1,55 @@
+"""Human-first requirements-discovery view model."""
+from __future__ import annotations
+
+from ..common import audit_context, evidence_index
+from ..models import HumanReportView, VisualEdge, VisualNode
+from ..visualizations import decision_flow_figure
+
+
+def _routing_figure(data: dict, requirements: dict):
+    current = data["header"]["taskKey"]
+    nodes = {
+        current: VisualNode(
+            current,
+            "Current requirements task",
+            "current",
+            "active",
+            requirements["systemInterpretation"],
+        )
+    }
+    edges = []
+    for row in requirements.get("taskDependencies", []):
+        source = row["fromTaskKey"]
+        target = row["toTaskKey"]
+        nodes.setdefault(
+            source, VisualNode(source, source, "current", "active", row["relation"])
+        )
+        nodes.setdefault(
+            target, VisualNode(target, target, "next", "pending", row["relation"])
+        )
+        edges.append(VisualEdge(source, target, row["relation"], "dependency"))
+    return decision_flow_figure(
+        nodes=tuple(nodes.values()),
+        edges=tuple(edges),
+        title="Requirement routing and task dependencies",
+    )
+
+
+def build_requirements_discovery_view(data: dict) -> HumanReportView:
+    requirements = data["requirementsDiscovery"]
+    figure = _routing_figure(data, requirements)
+    context = {
+        "humanSummary": data["humanSummary"],
+        "requirements": requirements,
+        "narrative": requirements["userNarrative"],
+        "routingFigure": figure,
+        "clarificationItems": data.get("clarificationItems", []),
+        "evidenceIndex": evidence_index(data),
+        "audit": audit_context(data),
+    }
+    return HumanReportView(
+        "requirements-discovery",
+        "html/tasks/requirements-discovery.template.html",
+        context,
+        (figure,),
+    )