okstra 0.146.0 → 0.147.0

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

@@ -0,0 +1,48 @@
+"""Human-first error-analysis view model."""
+from __future__ import annotations
+
+from ..common import audit_context
+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,
+        "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,38 @@
+"""Human-first feature-analysis view model."""
+from __future__ import annotations
+
+from ..common import analysis_review_ids, audit_context
+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),
+        "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,46 @@
+"""Human-first final-verification view model."""
+from __future__ import annotations
+
+from ..common import audit_context
+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",
+        "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,46 @@
+"""Human-first implementation delivery view model."""
+from __future__ import annotations
+
+from ..common import audit_context
+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,
+        "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,102 @@
+"""Human-first implementation-planning view and approval state."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from ..common import audit_context
+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"}
+        ],
+        "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,42 @@
+"""Human-first improvement-discovery view model."""
+from __future__ import annotations
+
+from ..common import audit_context
+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,
+        "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,53 @@
+"""Human-first release-handoff view model."""
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+from ..common import audit_context
+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", "")),
+        "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,54 @@
+"""Human-first requirements-discovery view model."""
+from __future__ import annotations
+
+from ..common import audit_context
+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", []),
+        "audit": audit_context(data),
+    }
+    return HumanReportView(
+        "requirements-discovery",
+        "html/tasks/requirements-discovery.template.html",
+        context,
+        (figure,),
+    )

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

@@ -0,0 +1,113 @@
+"""Deterministic inline-SVG builders with table-compatible node IDs."""
+from __future__ import annotations
+
+import html
+from dataclasses import replace
+from typing import Iterable, Sequence
+
+from .models import FigureModel, VisualEdge, VisualNode
+
+
+def _node_positions(nodes: Sequence[VisualNode]) -> dict[str, tuple[int, int]]:
+    groups = {group: index for index, group in enumerate(sorted({n.group for n in nodes}))}
+    rows: dict[str, int] = {}
+    positions: dict[str, tuple[int, int]] = {}
+    for node in nodes:
+        row = rows.get(node.group, 0)
+        rows[node.group] = row + 1
+        positions[node.id] = (50 + groups[node.group] * 260, 55 + row * 100)
+    return positions
+
+
+def _svg_document(nodes: Sequence[VisualNode], edges: Sequence[VisualEdge]) -> str:
+    positions = _node_positions(nodes)
+    width = max((x for x, _ in positions.values()), default=50) + 230
+    height = max((y for _, y in positions.values()), default=55) + 90
+    parts = [f'<svg viewBox="0 0 {width} {height}" role="img" xmlns="http://www.w3.org/2000/svg">']
+    for edge in edges:
+        if edge.source not in positions or edge.target not in positions:
+            continue
+        x1, y1 = positions[edge.source]
+        x2, y2 = positions[edge.target]
+        parts.append(f'<line x1="{x1 + 90}" y1="{y1 + 25}" x2="{x2 + 90}" y2="{y2 + 25}" class="edge edge-{html.escape(edge.kind)}" />')
+    for node in nodes:
+        x, y = positions[node.id]
+        node_id = html.escape(node.id)
+        label = html.escape(node.label)
+        status = html.escape(node.status)
+        detail = html.escape(node.detail)
+        parts.append(
+            f'<g data-node-id="{node_id}" class="node node-{status}">'
+            f"<title>{label}: {status}. {detail}</title>"
+            f'<rect x="{x}" y="{y}" width="180" height="50" rx="8"/>'
+            f'<text x="{x + 12}" y="{y + 30}">{label}</text></g>'
+        )
+    parts.append("</svg>")
+    return "".join(parts)
+
+
+def dependency_figure(*, nodes: Sequence[VisualNode], edges: Sequence[VisualEdge], title: str) -> FigureModel:
+    ordered_nodes = tuple(sorted(nodes, key=lambda node: node.id))
+    ordered_edges = tuple(sorted(edges, key=lambda edge: (edge.source, edge.target, edge.label)))
+    return FigureModel(
+        figure_id="dependency-graph",
+        kind="dependency",
+        title=title,
+        summary=f"{len(ordered_nodes)} nodes and {len(ordered_edges)} relationships",
+        nodes=ordered_nodes,
+        edges=ordered_edges,
+        svg=_svg_document(ordered_nodes, ordered_edges),
+    )
+
+
+def flow_figure(*, nodes: Sequence[VisualNode], edges: Sequence[VisualEdge], title: str) -> FigureModel:
+    return replace(dependency_figure(nodes=nodes, edges=edges, title=title), kind="flow", figure_id="flow-graph")
+
+
+def decision_flow_figure(*, nodes: Sequence[VisualNode], edges: Sequence[VisualEdge], title: str) -> FigureModel:
+    return replace(
+        dependency_figure(nodes=nodes, edges=edges, title=title),
+        kind="decision-flow",
+        figure_id="decision-flow",
+    )
+
+
+def cause_graph_figure(*, nodes: Sequence[VisualNode], edges: Sequence[VisualEdge], title: str) -> FigureModel:
+    return replace(
+        dependency_figure(nodes=nodes, edges=edges, title=title),
+        kind="cause-graph",
+        figure_id="cause-graph",
+    )
+
+
+def stage_map_figure(*, nodes: Sequence[VisualNode], edges: Sequence[VisualEdge], title: str) -> FigureModel:
+    return replace(
+        dependency_figure(nodes=nodes, edges=edges, title=title),
+        kind="stage-map",
+        figure_id="stage-map",
+    )
+
+
+def change_map_figure(*, nodes: Sequence[VisualNode], title: str) -> FigureModel:
+    return replace(
+        dependency_figure(nodes=nodes, edges=(), title=title),
+        kind="change-map",
+        figure_id="change-map",
+    )
+
+
+def matrix_figure(*, items: Iterable[VisualNode], title: str, x_label: str, y_label: str) -> FigureModel:
+    nodes = tuple(items)
+    summary = f"{len(nodes)} items compared by {x_label} and {y_label}"
+    return replace(dependency_figure(nodes=nodes, edges=(), title=title), kind="matrix", figure_id="matrix", summary=summary)
+
+
+def coverage_figure(*, rows: Iterable[VisualNode], title: str) -> FigureModel:
+    nodes = tuple(rows)
+    return replace(dependency_figure(nodes=nodes, edges=(), title=title), kind="coverage", figure_id="coverage")
+
+
+def timeline_figure(*, events: Iterable[VisualNode], title: str) -> FigureModel:
+    nodes = tuple(events)
+    edges = tuple(VisualEdge(nodes[i].id, nodes[i + 1].id, "next", "sequence") for i in range(len(nodes) - 1))
+    return replace(dependency_figure(nodes=nodes, edges=edges, title=title), kind="timeline", figure_id="timeline")

package/runtime/python/okstra_ctl/report_view_artifacts.py

@@ -5,7 +5,10 @@ from pathlib import Path
 
 
 def html_view_path(report_path: Path) -> Path:
-    """Return the self-contained HTML view path for a final-report markdown."""
+    """Return the HTML sibling for a final-report Markdown or data path."""
+    if report_path.name.endswith(".data.json"):
+        stem = report_path.name.removesuffix(".data.json")
+        return report_path.with_name(stem + ".html")
     return report_path.with_suffix(".html")