okstra 0.200.0 → 0.201.0

package/runtime/python/okstra_token_usage/report.py

@@ -21,6 +21,7 @@ from okstra_ctl.design_prep import (  # noqa: E402
 from okstra_ctl.usage_cells import duration_ms_from_bounds  # noqa: E402
 
 from .task_totals import task_cumulative_usage  # noqa: E402
+from .blocks import accounting_workers  # noqa: E402
 
 
 class SubstituteRefusedError(RuntimeError):
@@ -155,7 +156,7 @@ def _cache_reads(summary: dict, team_state: dict) -> dict[str, int]:
     lead = _cache_read_tokens(team_state.get("leadUsage"))
     worker = sum(
         _cache_read_tokens(entry.get("usage"))
-        for entry in team_state.get("workers") or []
+        for entry in accounting_workers(team_state)
         if isinstance(entry, dict)
     )
     worker += _cache_read_tokens(summary.get("unattributedWorkerUsage"))
@@ -171,7 +172,7 @@ def _cache_read_tokens(usage: object) -> int:
 
 def _worker_detail_rows(team_state: dict) -> list[dict]:
     rows = []
-    for worker in team_state.get("workers") or []:
+    for worker in accounting_workers(team_state):
         if isinstance(worker, dict):
             rows.append(
                 _worker_detail_row(_worker_detail_label(worker), worker.get("usage") or {})
@@ -212,6 +213,37 @@ def populate_data_token_cells(data_path: Path, team_state: dict) -> int:
     data = json.loads(data_path.read_text(encoding="utf-8"))
     changes = 0
 
+    changes += _populate_summary_token_cells(data, summary, team_state, data_path)
+
+    # Execution Status by Agent — per-row token / cost / duration.
+    # `collect.py` writes lead usage to `team_state["leadUsage"]` (flat
+    # usage_block), while worker usage lives at `worker["usage"]`. Wrap
+    # the lead block so `_populate_execution_row` can read both shapes
+    # via the same `source["usage"]` path.
+    lead_source = {"usage": team_state.get("leadUsage") or {}}
+    workers = accounting_workers(team_state)
+    rows = data.get("executionStatus") or []
+    used_workers: set[int] = set()
+    for row in rows:
+        role = row.get("role", "")
+        if "lead" in role.lower():
+            _populate_execution_row(row, lead_source)
+            changes += 1
+            continue
+        idx = _match_worker_index(row, workers, used_workers)
+        if idx is not None:
+            used_workers.add(idx)
+            _populate_execution_row(row, workers[idx])
+            changes += 1
+
+    data_path.write_text(
+        json.dumps(data, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+    return changes
+
+
+def _populate_summary_token_cells(data: dict, summary: dict, team_state: dict, data_path: Path) -> int:
     # Token Usage Summary table — four rows.
     cost = summary.get("estimatedCostUsd") or {}
     lead_cost = cost.get("lead") or 0
@@ -245,34 +277,7 @@ def populate_data_token_cells(data_path: Path, team_state: dict) -> int:
     cumulative = task_cumulative_usage(data_path)
     if cumulative is not None:
         token_usage["taskCumulative"] = cumulative
-    changes += 4
-
-    # Execution Status by Agent — per-row token / cost / duration.
-    # `collect.py` writes lead usage to `team_state["leadUsage"]` (flat
-    # usage_block), while worker usage lives at `worker["usage"]`. Wrap
-    # the lead block so `_populate_execution_row` can read both shapes
-    # via the same `source["usage"]` path.
-    lead_source = {"usage": team_state.get("leadUsage") or {}}
-    workers = team_state.get("workers") or []
-    rows = data.get("executionStatus") or []
-    used_workers: set[int] = set()
-    for row in rows:
-        role = row.get("role", "")
-        if "lead" in role.lower():
-            _populate_execution_row(row, lead_source)
-            changes += 1
-            continue
-        idx = _match_worker_index(row, workers, used_workers)
-        if idx is not None:
-            used_workers.add(idx)
-            _populate_execution_row(row, workers[idx])
-            changes += 1
-
-    data_path.write_text(
-        json.dumps(data, indent=2, ensure_ascii=False) + "\n",
-        encoding="utf-8",
-    )
-    return changes
+    return 4
 
 
 def populate_token_cells(

package/runtime/python/okstra_token_usage/task_totals.py

@@ -16,6 +16,8 @@ from __future__ import annotations
 import json
 from pathlib import Path
 
+from .blocks import normalize_usage_block, usage_blocks
+
 _TEAM_STATE_GLOB = "runs/*/state/team-state-*.json"
 _SUMMED_KEYS = (
     ("totalTokens", "totalTokens"),
@@ -40,17 +42,6 @@ def _task_root(data_path: Path) -> Path | None:
     return parents[3]
 
 
-def _usage_blocks(team_state: dict) -> list[dict]:
-    blocks = [team_state.get("leadUsage") or {}]
-    for worker in team_state.get("workers") or []:
-        if isinstance(worker, dict):
-            blocks.append(worker.get("usage") or {})
-    unattributed = (team_state.get("usageSummary") or {}).get("unattributedWorkerUsage")
-    if isinstance(unattributed, dict):
-        blocks.append(unattributed)
-    return [block for block in blocks if isinstance(block, dict)]
-
-
 def _number(value: object) -> int | float:
     if isinstance(value, bool) or not isinstance(value, (int, float)):
         return 0
@@ -76,7 +67,7 @@ def task_cumulative_usage(data_path: Path) -> dict | None:
             continue
         if not isinstance(team_state, dict):
             continue
-        blocks = _usage_blocks(team_state)
+        blocks = [normalize_usage_block(block) for block in usage_blocks(team_state)]
         measured = sum(_number(block.get("totalTokens")) for block in blocks)
         if measured <= 0:
             continue

package/runtime/schemas/final-report-v2.0.schema.json

@@ -25,6 +25,7 @@
   ],
   "additionalProperties": false,
   "properties": {
+    "technicalVerification": {"$ref": "#/$defs/TechnicalVerification"},
     "schemaVersion": {
       "const": "2.0",
       "description": "Schema version. Renderer refuses to process unknown versions."
@@ -1664,6 +1665,86 @@
     }
   },
   "allOf": [
+    {
+      "if": {
+        "properties": {
+          "header": {
+            "properties": {
+              "taskType": {
+                "const": "technical-verification"
+              }
+            }
+          }
+        },
+        "required": [
+          "header"
+        ]
+      },
+      "then": {
+        "required": [
+          "technicalVerification"
+        ],
+        "properties": {
+          "frontmatter": {
+            "properties": {
+              "approved": {
+                "const": false
+              }
+            }
+          },
+          "implementationOptionSelection": false,
+          "implementationPlanning": false,
+          "implementation": false,
+          "finalVerification": false,
+          "releaseHandoff": false,
+          "errorAnalysis": false,
+          "requirementsDiscovery": false,
+          "improvementDiscovery": false,
+          "analysisCommon": false,
+          "projectAnalysis": false,
+          "featureAnalysis": false,
+          "changeImpactAnalysis": false,
+          "followUpTasks": {
+            "contains": {
+              "properties": {
+                "origin": {
+                  "const": "phase-continuation"
+                }
+              },
+              "required": [
+                "origin"
+              ]
+            },
+            "minContains": 1,
+            "maxContains": 1,
+            "items": {
+              "if": {
+                "properties": {
+                  "origin": {
+                    "const": "phase-continuation"
+                  }
+                },
+                "required": [
+                  "origin"
+                ]
+              },
+              "then": {
+                "properties": {
+                  "suggestedTaskType": {
+                    "const": "implementation-option-selection"
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "else": {
+        "properties": {
+          "technicalVerification": false
+        }
+      }
+    },
     {
       "description": "Frontmatter approval input matches the implementation-planning contract.",
       "if": {
@@ -2013,6 +2094,7 @@
             "properties": {
               "taskType": {
                 "enum": [
+                  "technical-verification",
                   "requirements-discovery",
                   "project-analysis",
                   "feature-analysis",
@@ -2192,6 +2274,7 @@
     }
   ],
   "oneOf": [
+    {"required": ["technicalVerification"]},
     {
       "required": [
         "requirementsDiscovery"
@@ -3073,7 +3156,8 @@
           "enum": [
             "pending-direction-selection",
             "implementation-planning",
-            "blocked"
+            "blocked",
+            "technical-verification"
           ]
         },
         "userNarrative": {
@@ -3635,6 +3719,17 @@
       ],
       "additionalProperties": false,
       "properties": {
+        "resolutionKind": {
+          "type": "string",
+          "enum": ["user-decision", "technical-verification"],
+          "description": "Optional for historical reads; blocked report publication requires explicit classification."
+        },
+        "clarificationRefs": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {"type": "string", "pattern": "^C-[0-9]{3}$"},
+          "description": "User decisions require nonempty references to actual clarification records, including answered records."
+        },
         "fact": {
           "type": "string",
           "minLength": 1
@@ -3950,7 +4045,7 @@
         },
         "stageRefs": {
           "type": "array",
-          "minItems": 1,
+          "minItems": 0,
           "uniqueItems": true,
           "items": {
             "type": "integer",
@@ -3959,7 +4054,7 @@
         },
         "stepRefs": {
           "type": "array",
-          "minItems": 1,
+          "minItems": 0,
           "uniqueItems": true,
           "items": {
             "type": "string",
@@ -3968,7 +4063,7 @@
         },
         "validationRefs": {
           "type": "array",
-          "minItems": 1,
+          "minItems": 0,
           "uniqueItems": true,
           "items": {
             "type": "string",
@@ -3977,7 +4072,7 @@
         },
         "fileRefs": {
           "type": "array",
-          "minItems": 1,
+          "minItems": 0,
           "uniqueItems": true,
           "items": {
             "type": "string",
@@ -3987,10 +4082,59 @@
         "status": {
           "enum": [
             "covered",
-            "not-covered"
+            "not-covered",
+            "externally-tracked"
           ]
+        },
+        "crossProjectDependencyRefs": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^XP-[0-9]{3,}$"
+          }
         }
-      }
+      },
+      "oneOf": [
+        {
+          "properties": {
+            "status": {
+              "enum": [
+                "covered",
+                "not-covered"
+              ]
+            },
+            "stageRefs": {
+              "minItems": 1
+            },
+            "stepRefs": {
+              "minItems": 1
+            },
+            "validationRefs": {
+              "minItems": 1
+            },
+            "fileRefs": {
+              "minItems": 1
+            },
+            "crossProjectDependencyRefs": {
+              "maxItems": 0
+            }
+          }
+        },
+        {
+          "required": [
+            "crossProjectDependencyRefs"
+          ],
+          "properties": {
+            "status": {
+              "const": "externally-tracked"
+            },
+            "crossProjectDependencyRefs": {
+              "minItems": 1
+            }
+          }
+        }
+      ]
     },
     "SelectedDirectionCoverageSummary": {
       "type": "object",
@@ -4056,8 +4200,155 @@
         }
       }
     },
+    "TechnicalVerification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "sourceReport",
+        "sourceDataSha256",
+        "scope",
+        "checks",
+        "routing"
+      ],
+      "properties": {
+        "sourceReport": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sourceDataSha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "scope": {
+          "const": "technical-evidence-only"
+        },
+        "checks": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "candidateId",
+              "factIndex",
+              "fact",
+              "hypothesis",
+              "procedure",
+              "confirmingSignal",
+              "rejectingSignal",
+              "status",
+              "commands",
+              "observation",
+              "limitations"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^TV-[0-9]{3}$"
+              },
+              "candidateId": {
+                "type": "string",
+                "pattern": "^IO-[0-9]{3}$"
+              },
+              "factIndex": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "fact": {
+                "type": "string",
+                "minLength": 1
+              },
+              "hypothesis": {
+                "type": "string",
+                "minLength": 1
+              },
+              "procedure": {
+                "type": "string",
+                "minLength": 1
+              },
+              "confirmingSignal": {
+                "type": "string",
+                "minLength": 1
+              },
+              "rejectingSignal": {
+                "type": "string",
+                "minLength": 1
+              },
+              "status": {
+                "enum": [
+                  "supported",
+                  "refuted",
+                  "inconclusive",
+                  "not-run"
+                ]
+              },
+              "commands": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "command",
+                    "cwd",
+                    "exitCode",
+                    "logPath"
+                  ],
+                  "properties": {
+                    "command": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "cwd": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "exitCode": {
+                      "type": "integer"
+                    },
+                    "logPath": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                }
+              },
+              "observation": {
+                "type": "string",
+                "minLength": 1
+              },
+              "limitations": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            }
+          }
+        },
+        "routing": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "nextTaskType",
+            "rationale"
+          ],
+          "properties": {
+            "nextTaskType": {
+              "const": "implementation-option-selection"
+            },
+            "rationale": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      }
+    },
     "TaskType": {
       "enum": [
+        "technical-verification",
         "requirements-discovery",
         "improvement-discovery",
         "error-analysis",