okstra 0.155.0 → 0.156.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.155.0",
+  "version": "0.156.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.155.0",
-  "builtAt": "2026-08-06T15:13:07.664Z",
+  "package": "0.156.0",
+  "builtAt": "2026-08-07T06:39:03.548Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/report_finalize.py

@@ -110,11 +110,30 @@ def task_id(manifest: Mapping[str, Any]) -> str:
     raise FinalizeError(f"cannot infer task id from taskKey: {task_key}")
 
 
-def run_seq(manifest: Mapping[str, Any]) -> str:
+def _category_seq(manifest: Mapping[str, Any], category: str) -> str:
     seqs = manifest.get("runSequencesByCategory")
     if not isinstance(seqs, Mapping):
         raise FinalizeError("run manifest has no runSequencesByCategory object")
-    return require_string(seqs, "manifests")
+    return require_string(seqs, category)
+
+
+def run_seq(manifest: Mapping[str, Any]) -> str:
+    """How many times this task type has run — what a lead event records."""
+    return _category_seq(manifest, "manifests")
+
+
+def report_seq(manifest: Mapping[str, Any]) -> str:
+    """The `reports` sequence — the one the final-report filename carries.
+
+    Categories advance independently (`paths.compute_run_paths`), so a run whose
+    predecessor produced no report reuses the free report slot and `run_seq`
+    outruns this one. This value reaches `render-report-views --seq`, which
+    stamps it into the HTML `runMeta` naming the exported
+    `user-response-<task-type>-<seq>.md`; `user_response.write_sidecar` derives
+    that same name from the report path, so anything but `reports` makes the two
+    answer paths write different files for one report.
+    """
+    return _category_seq(manifest, "reports")
 
 
 def task_manifest_path(project_root: Path, manifest: Mapping[str, Any]) -> Path:
@@ -204,7 +223,7 @@ class FinalizeContext:
             task_key=require_string(manifest, "taskKey"),
             task_type=require_string(manifest, "taskType"),
             task_group=task_group(manifest),
-            seq=run_seq(manifest),
+            seq=report_seq(manifest),
             final_status_path=resolve_optional_path(
                 project_root, manifest.get("finalStatusPath")
             ),

package/runtime/python/okstra_ctl/stage_map.py

@@ -218,6 +218,103 @@ def parse_stage_map_file(path: Path) -> list[StageMapStage]:
     return parse_stage_map_text(text, source_plan_path=str(resolved))
 
 
+def _require_data_positive_int(
+    value: Any, field: str, row_number: int, source_plan_path: str,
+) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+        raise StageMapError(
+            "stage_map",
+            f"structured Stage Map row {row_number} has invalid {field} {value!r}",
+            source_plan_path,
+        )
+    return value
+
+
+def _require_data_text(
+    value: Any, field: str, row_number: int, source_plan_path: str,
+) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise StageMapError(
+            "stage_map",
+            f"structured Stage Map row {row_number} has invalid {field} {value!r}",
+            source_plan_path,
+        )
+    return value
+
+
+def _parse_data_stage_map_row(
+    value: Any, row_number: int, source_plan_path: str,
+) -> StageMapStage:
+    if not isinstance(value, dict):
+        raise StageMapError(
+            "stage_map",
+            f"structured Stage Map row {row_number} must be an object",
+            source_plan_path,
+        )
+    stage_number = _require_data_positive_int(
+        value.get("stage"), "stage", row_number, source_plan_path
+    )
+    step_count = _require_data_positive_int(
+        value.get("stepCount"), "stepCount", row_number, source_plan_path
+    )
+    title = _require_data_text(
+        value.get("title"), "title", row_number, source_plan_path
+    )
+    depends_on = _require_data_text(
+        value.get("dependsOn"), "dependsOn", row_number, source_plan_path
+    )
+    exit_summary = _require_data_text(
+        value.get("exitContractSummary"),
+        "exitContractSummary",
+        row_number,
+        source_plan_path,
+    )
+    return StageMapStage(
+        stage_number,
+        title,
+        _parse_depends_on(depends_on.strip(), row_number, source_plan_path),
+        step_count,
+        exit_summary,
+    )
+
+
+def _parse_schema_v2_stage_map(
+    data: dict[str, Any], source_plan_path: str,
+) -> list[StageMapStage]:
+    planning = data.get("implementationPlanning")
+    stage_map = planning.get("stageMap") if isinstance(planning, dict) else None
+    if not isinstance(stage_map, list) or not stage_map:
+        raise StageMapError(
+            "stage_map",
+            "structured report requires a non-empty implementationPlanning.stageMap",
+            source_plan_path,
+        )
+    stages = [
+        _parse_data_stage_map_row(value, row_number, source_plan_path)
+        for row_number, value in enumerate(stage_map, start=1)
+    ]
+    _validate_stage_numbers(stages, source_plan_path)
+    return stages
+
+
+def _parse_stage_map_source(markdown_path: Path) -> list[StageMapStage]:
+    resolved = markdown_path.resolve()
+    data_path = resolved.with_suffix(".data.json")
+    if not data_path.exists():
+        return parse_stage_map_file(resolved)
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise StageMapError("stage_map", str(exc), str(data_path)) from exc
+    if not isinstance(data, dict):
+        raise StageMapError(
+            "stage_map", "structured report must be an object", str(data_path)
+        )
+    if data.get("schemaVersion") != "2.0":
+        return parse_stage_map_file(resolved)
+    return _parse_schema_v2_stage_map(data, str(data_path))
+
+
 def stage_map_records(stages: Iterable[StageMapStage]) -> list[dict[str, Any]]:
     return [
         {
@@ -256,7 +353,7 @@ def load_task_stage_map(
     return StageMapSnapshot(
         "ready",
         str(resolved),
-        stage_map_records(parse_stage_map_file(resolved)),
+        stage_map_records(_parse_stage_map_source(resolved)),
     )