okstra 0.148.1 → 0.150.0

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

@@ -4,7 +4,7 @@ from __future__ import annotations
 import re
 from dataclasses import dataclass
 
-from ..common import audit_context, evidence_index
+from ..common import evidence_index
 from ..models import HumanReportView, VisualEdge, VisualNode
 from ..visualizations import stage_map_figure
 
@@ -46,7 +46,7 @@ def plan_approval_state(data: dict) -> PlanApprovalState | None:
         if row.get("blocks") == "approval"
         and row.get("status") in {"open", "answered"}
     )
-    reason = f"승인 차단 항목 {len(blockers)}건 미해소" if blockers else ""
+    reason = f"{len(blockers)} approval blocker(s) unresolved" if blockers else ""
     return PlanApprovalState(
         names,
         resolve_recommended_option(recommended, names),
@@ -78,8 +78,6 @@ 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,
@@ -93,7 +91,6 @@ def build_implementation_planning_view(data: dict) -> HumanReportView:
             and row.get("status") in {"open", "answered"}
         ],
         "evidenceIndex": evidence_index(data),
-        "audit": audit,
     }
     return HumanReportView(
         "implementation-planning",

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

@@ -1,7 +1,7 @@
 """Human-first improvement-discovery view model."""
 from __future__ import annotations
 
-from ..common import audit_context, evidence_index
+from ..common import evidence_index
 from ..models import HumanReportView, VisualNode
 from ..visualizations import matrix_figure
 
@@ -33,7 +33,6 @@ def build_improvement_discovery_view(data: dict) -> HumanReportView:
         "narrative": improvement["userNarrative"],
         "matrixFigure": figure,
         "evidenceIndex": evidence_index(data),
-        "audit": audit_context(data),
     }
     return HumanReportView(
         "improvement-discovery",

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

@@ -1,9 +1,9 @@
 """Human-first project-analysis view model."""
 from __future__ import annotations
 
-from ..common import audit_context, evidence_index
+from ..common import evidence_index
 from ..models import HumanReportView, VisualEdge, VisualNode
-from ..visualizations import dependency_figure
+from ..visualizations import dependency_figure, infrastructure_figure, workflow_figure
 
 
 def _component_nodes(project: dict) -> tuple[VisualNode, ...]:
@@ -14,6 +14,7 @@ def _component_nodes(project: dict) -> tuple[VisualNode, ...]:
             group=(row.get("paths") or ["project"])[0].split("/", 1)[0],
             status="stable",
             detail=row["responsibility"],
+            paths=tuple(row.get("paths") or ()),
         )
         for row in project.get("components", [])
     )
@@ -31,6 +32,88 @@ def _dependency_edges(project: dict) -> tuple[VisualEdge, ...]:
     )
 
 
+def _infrastructure_figure(project: dict):
+    """The components that hold a boundary, and what sits on the far side.
+
+    The dependency graph answers "what calls what inside the code". Where the
+    data lives and which outside service the code depends on is a different
+    question with different nodes, and reading it off a component graph means
+    reconstructing it from adapter paths.
+    """
+    components = {row["id"]: row for row in project.get("components", [])}
+    nodes: list[VisualNode] = []
+    edges: list[VisualEdge] = []
+    seen: set[str] = set()
+
+    def owner_node(component_id: str) -> str | None:
+        row = components.get(component_id)
+        if row is None:
+            return None
+        if row["id"] not in seen:
+            seen.add(row["id"])
+            nodes.append(
+                VisualNode(row["id"], row["name"], "component", "stable", row["responsibility"], note="Component")
+            )
+        return row["id"]
+
+    for index, row in enumerate(project.get("dataStores", []), start=1):
+        store_id = f"store-{index}"
+        nodes.append(
+            VisualNode(store_id, row["name"], "store", "store", row.get("readBoundary", ""), note="Data store")
+        )
+        source = owner_node(row.get("ownerComponentId", ""))
+        if source:
+            edges.append(VisualEdge(source, store_id, "reads · writes", "storage"))
+    for index, row in enumerate(project.get("externalSystems", []), start=1):
+        system_id = f"external-{index}"
+        nodes.append(
+            VisualNode(system_id, row["name"], "external", "external", row.get("direction", ""), note="External system")
+        )
+        edges.append(VisualEdge(row.get("adapter", "adapter"), system_id, row.get("direction", ""), "external"))
+        if row.get("adapter") and row["adapter"] not in seen:
+            seen.add(row["adapter"])
+            nodes.append(
+                VisualNode(row["adapter"], row["adapter"], "adapter", "stable", "Adapter", note="Adapter")
+            )
+    return infrastructure_figure(
+        nodes=tuple(nodes), edges=tuple(edges), title="Infrastructure and boundaries"
+    )
+
+
+def _workflow_figure(project: dict):
+    """Each workflow's steps, as the path a request takes between components."""
+    components = {row["id"]: row for row in project.get("components", [])}
+    nodes: list[VisualNode] = []
+    edges: list[VisualEdge] = []
+    seen: set[str] = set()
+    for flow in project.get("workflows", []):
+        steps = sorted(flow.get("steps", []), key=lambda step: step.get("order", 0))
+        for step in steps:
+            component_id = step.get("componentId", "")
+            if component_id and component_id not in seen:
+                seen.add(component_id)
+                row = components.get(component_id, {})
+                nodes.append(
+                    VisualNode(
+                        component_id,
+                        row.get("name", component_id),
+                        "component",
+                        "stable",
+                        step.get("action", ""),
+                    )
+                )
+        for first, second in zip(steps, steps[1:]):
+            edges.append(
+                VisualEdge(
+                    first.get("componentId", ""),
+                    second.get("componentId", ""),
+                    second.get("action", "next"),
+                    "workflow",
+                )
+            )
+    return workflow_figure(nodes=tuple(nodes), edges=tuple(edges), title="Workflows")
+
+
 def build_project_analysis_view(data: dict) -> HumanReportView:
     project = data["projectAnalysis"]
     architecture = dependency_figure(
@@ -38,17 +121,20 @@ def build_project_analysis_view(data: dict) -> HumanReportView:
         edges=_dependency_edges(project),
         title="Project architecture and dependencies",
     )
+    infrastructure = _infrastructure_figure(project)
+    workflows = _workflow_figure(project) if project.get("workflows") else None
     context = {
         "humanSummary": data["humanSummary"],
         "project": project,
+        "infrastructureFigure": infrastructure,
+        "workflowFigure": workflows,
         "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,),
+        figures=tuple(f for f in (architecture, infrastructure, workflows) if f),
     )

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

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 from urllib.parse import urlparse
 
-from ..common import audit_context, evidence_index
+from ..common import evidence_index
 from ..models import HumanReportView, VisualNode
 from ..visualizations import timeline_figure
 
@@ -31,12 +31,6 @@ def build_release_handoff_view(data: dict) -> HumanReportView:
     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,
@@ -44,7 +38,6 @@ def build_release_handoff_view(data: dict) -> HumanReportView:
         "handoffFigure": figure,
         "prUrl": _safe_http_url(handoff["pullRequestOutcome"].get("url", "")),
         "evidenceIndex": evidence_index(data),
-        "audit": audit,
     }
     return HumanReportView(
         "release-handoff",

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

@@ -1,7 +1,7 @@
 """Human-first requirements-discovery view model."""
 from __future__ import annotations
 
-from ..common import audit_context, evidence_index
+from ..common import evidence_index
 from ..models import HumanReportView, VisualEdge, VisualNode
 from ..visualizations import decision_flow_figure
 
@@ -15,6 +15,7 @@ def _routing_figure(data: dict, requirements: dict):
             "current",
             "active",
             requirements["systemInterpretation"],
+            note="This task",
         )
     }
     edges = []
@@ -22,10 +23,12 @@ def _routing_figure(data: dict, requirements: dict):
         source = row["fromTaskKey"]
         target = row["toTaskKey"]
         nodes.setdefault(
-            source, VisualNode(source, source, "current", "active", row["relation"])
+            source,
+            VisualNode(source, source, "current", "active", row["relation"], note="This task"),
         )
         nodes.setdefault(
-            target, VisualNode(target, target, "next", "pending", row["relation"])
+            target,
+            VisualNode(target, target, "next", "pending", row["relation"], note="Next task"),
         )
         edges.append(VisualEdge(source, target, row["relation"], "dependency"))
     return decision_flow_figure(
@@ -45,7 +48,6 @@ def build_requirements_discovery_view(data: dict) -> HumanReportView:
         "routingFigure": figure,
         "clarificationItems": data.get("clarificationItems", []),
         "evidenceIndex": evidence_index(data),
-        "audit": audit_context(data),
     }
     return HumanReportView(
         "requirements-discovery",

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

@@ -13,23 +13,124 @@ _COLUMN_WIDTH = 260
 _ROW_HEIGHT = 100
 
 
-def _node_positions(nodes: Sequence[VisualNode]) -> dict[str, tuple[int, int]]:
-    """Lay out one column per group, wrapping tall groups into extra columns."""
-    groups = sorted({n.group for n in nodes})
+def _group_columns(nodes: Sequence[VisualNode]) -> list[list[str]]:
+    """One column per group, wrapping a tall group into extra columns.
+
+    This is the layout for a figure with no edges — a coverage or matrix view,
+    where the group is the only structure there is to show.
+    """
     counts: dict[str, int] = {}
     column_offset: dict[str, int] = {}
     offset = 0
-    for group in groups:
+    for group in sorted({n.group for n in nodes}):
         column_offset[group] = offset
         size = sum(1 for n in nodes if n.group == group)
         offset += max(1, -(-size // _ROWS_PER_COLUMN))
-    positions: dict[str, tuple[int, int]] = {}
+    columns: list[list[str]] = [[] for _ in range(max(offset, 1))]
     for node in nodes:
         index = counts.get(node.group, 0)
         counts[node.group] = index + 1
-        column = column_offset[node.group] + index // _ROWS_PER_COLUMN
-        row = index % _ROWS_PER_COLUMN
-        positions[node.id] = (50 + column * _COLUMN_WIDTH, 55 + row * _ROW_HEIGHT)
+        columns[column_offset[node.group] + index // _ROWS_PER_COLUMN].append(node.id)
+    return columns
+
+
+def _depths(node_ids: list[str], edges: Sequence[VisualEdge]) -> dict[str, int]:
+    """Longest path from a root, so a node sits past every one it depends on.
+
+    Relaxing until nothing moves settles the longest path; a cycle would relax
+    forever, so the pass count bounds it — a dependency graph that loops has no
+    correct layering anyway, and stopping leaves it readable rather than hung.
+    """
+    depth = {node_id: 0 for node_id in node_ids}
+    links = [(e.source, e.target) for e in edges if e.source in depth and e.target in depth]
+    for _ in range(len(depth)):
+        settled = True
+        for source, target in links:
+            if depth[target] < depth[source] + 1:
+                depth[target] = depth[source] + 1
+                settled = False
+        if settled:
+            break
+    return depth
+
+
+_ORDERING_SWEEPS = 4
+
+
+def _ordered_by_neighbours(
+    column: list[str], neighbours: list[str], links: list[tuple[str, str]], *, backward: bool
+) -> list[str]:
+    """Sort a column to sit opposite the nodes it connects to.
+
+    One direction is not enough: ordering a column by its parents can pull it
+    out of line with its children, so the sweeps alternate.
+    """
+    rank = {node_id: index for index, node_id in enumerate(neighbours)}
+    original = {node_id: index for index, node_id in enumerate(column)}
+
+    def key(node_id: str) -> tuple[float, int]:
+        if backward:
+            related = [rank[t] for s, t in links if s == node_id and t in rank]
+        else:
+            related = [rank[s] for s, t in links if t == node_id and s in rank]
+        centre = sum(related) / len(related) if related else float(original[node_id])
+        return (centre, original[node_id])
+
+    return sorted(column, key=key)
+
+
+def _uncross(columns: list[list[str]], links: list[tuple[str, str]]) -> list[list[str]]:
+    """Alternate forward and backward barycentre sweeps until they settle."""
+    for sweep in range(_ORDERING_SWEEPS):
+        before = [list(column) for column in columns]
+        if sweep % 2 == 0:
+            for index in range(1, len(columns)):
+                columns[index] = _ordered_by_neighbours(
+                    columns[index], columns[index - 1], links, backward=False
+                )
+        else:
+            for index in range(len(columns) - 2, -1, -1):
+                columns[index] = _ordered_by_neighbours(
+                    columns[index], columns[index + 1], links, backward=True
+                )
+        if columns == before:
+            break
+    return columns
+
+
+def _layer_columns(nodes: Sequence[VisualNode], edges: Sequence[VisualEdge]) -> list[list[str]]:
+    """Columns by dependency depth, with the unconnected nodes held back.
+
+    A node with no edge has no place in the dependency story, and letting it
+    take a slot pushed the nodes that do relate to each other apart. They get
+    their own columns after the graph.
+    """
+    linked = {e.source for e in edges} | {e.target for e in edges}
+    connected = [n.id for n in nodes if n.id in linked]
+    loose = [n.id for n in nodes if n.id not in linked]
+    depth = _depths(connected, edges)
+    links = [(e.source, e.target) for e in edges if e.source in depth and e.target in depth]
+
+    columns: list[list[str]] = []
+    for level in range(max(depth.values(), default=-1) + 1):
+        columns.append([node_id for node_id in connected if depth[node_id] == level])
+    columns = _uncross(columns, links)
+    for index in range(0, len(loose), _ROWS_PER_COLUMN):
+        columns.append(loose[index:index + _ROWS_PER_COLUMN])
+    return columns or [[]]
+
+
+def _node_positions(
+    nodes: Sequence[VisualNode], edges: Sequence[VisualEdge] = ()
+) -> dict[str, tuple[int, int]]:
+    columns = _layer_columns(nodes, edges) if edges else _group_columns(nodes)
+    positions: dict[str, tuple[int, int]] = {}
+    for column_index, column in enumerate(columns):
+        for row_index, node_id in enumerate(column):
+            positions[node_id] = (
+                50 + column_index * _COLUMN_WIDTH,
+                55 + row_index * _ROW_HEIGHT,
+            )
     return positions
 
 
@@ -41,7 +142,7 @@ _ARROW_MARKER = (
 
 
 def _svg_document(nodes: Sequence[VisualNode], edges: Sequence[VisualEdge]) -> str:
-    positions = _node_positions(nodes)
+    positions = _node_positions(nodes, edges)
     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">']
@@ -51,10 +152,28 @@ def _svg_document(nodes: Sequence[VisualNode], edges: Sequence[VisualEdge]) -> s
             continue
         x1, y1 = positions[edge.source]
         x2, y2 = positions[edge.target]
+        # Leave the source box on its right edge and arrive on the target's
+        # left, so a left-to-right layering reads as one direction of travel.
+        start_x, end_x = (x1 + 180, x2) if x2 > x1 else ((x1, x2 + 180) if x2 < x1 else (x1 + 90, x2 + 90))
+        start_y, end_y = y1 + 25, y2 + 25
+        span = abs(x2 - x1) // _COLUMN_WIDTH
+        if span > 1:
+            # An edge that skips a column would otherwise be drawn straight
+            # through the boxes standing in it. Arcing it clear of the band is
+            # what removes the crossings the layering itself cannot.
+            # Clamped so a long skip from the top row still arcs inside
+            # the canvas instead of being drawn off it.
+            lift = max(10, min(start_y, end_y) - 30 - 12 * span)
+            geometry = (
+                f'<path d="M {start_x} {start_y} Q {(start_x + end_x) // 2} {lift} {end_x} {end_y}" '
+                f'fill="none"'
+            )
+        else:
+            geometry = f'<line x1="{start_x}" y1="{start_y}" x2="{end_x}" y2="{end_y}"'
         parts.append(
             f'<g class="edge-group"><title>{html.escape(edge.label)}</title>'
-            f'<line x1="{x1 + 90}" y1="{y1 + 25}" x2="{x2 + 90}" y2="{y2 + 25}" '
-            f'class="edge edge-{html.escape(edge.kind)}" marker-end="url(#edge-arrow)" /></g>'
+            f'{geometry} class="edge edge-{html.escape(edge.kind)}" '
+            f'marker-end="url(#edge-arrow)" /></g>'
         )
     for node in nodes:
         x, y = positions[node.id]
@@ -86,6 +205,22 @@ def dependency_figure(*, nodes: Sequence[VisualNode], edges: Sequence[VisualEdge
     )
 
 
+def infrastructure_figure(*, nodes: Sequence[VisualNode], edges: Sequence[VisualEdge], title: str) -> FigureModel:
+    return replace(
+        dependency_figure(nodes=nodes, edges=edges, title=title),
+        kind="infrastructure",
+        figure_id="infrastructure-graph",
+    )
+
+
+def workflow_figure(*, nodes: Sequence[VisualNode], edges: Sequence[VisualEdge], title: str) -> FigureModel:
+    return replace(
+        dependency_figure(nodes=nodes, edges=edges, title=title),
+        kind="workflow",
+        figure_id="workflow-graph",
+    )
+
+
 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")