okstra 0.31.0 → 0.32.0

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

@@ -0,0 +1,1391 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://okstra.dev/schemas/final-report-v1.0.json",
+  "title": "OKSTRA Final Report Data (v1.0)",
+  "description": "JSON SSOT for okstra final-report generation. Written by report-writer-worker in Phase 6, consumed by okstra-render-final-report.py to produce the canonical markdown.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "frontmatter",
+    "header",
+    "verdictCard",
+    "summary",
+    "executionStatus",
+    "tokenUsage",
+    "crossVerification",
+    "finalVerdict",
+    "evidence",
+    "missingInformation",
+    "clarificationItems",
+    "recommendedNextSteps",
+    "followUpTasks"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "const": "1.0",
+      "description": "Schema version. Renderer refuses to process unknown versions."
+    },
+
+    "frontmatter": {
+      "type": "object",
+      "required": [
+        "title",
+        "id",
+        "tags",
+        "status",
+        "aliases",
+        "date",
+        "taskId",
+        "taskGroup",
+        "projectId",
+        "taskType",
+        "workerId"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "id": { "type": "string", "minLength": 1 },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "status": { "enum": ["in-progress", "completed", "draft"] },
+        "aliases": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "date": {
+          "type": "string",
+          "description": "ISO 8601 date or datetime. Renderer emits verbatim."
+        },
+        "taskId": { "type": "string", "minLength": 1 },
+        "taskGroup": { "type": "string", "minLength": 1 },
+        "projectId": { "type": "string", "minLength": 1 },
+        "taskType": { "$ref": "#/$defs/TaskType" },
+        "workerId": { "const": "report-writer" }
+      }
+    },
+
+    "header": {
+      "type": "object",
+      "required": [
+        "taskKey",
+        "createdAt",
+        "taskType",
+        "reportOwner",
+        "reportAuthor",
+        "leadModel",
+        "okstraVersion"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "taskKey": { "type": "string", "minLength": 1 },
+        "createdAt": { "type": "string", "minLength": 1 },
+        "taskType": { "$ref": "#/$defs/TaskType" },
+        "reportOwner": { "const": "Claude lead" },
+        "reportAuthor": {
+          "enum": ["Report writer worker", "Claude lead"],
+          "description": "Lead-authored fallback is only valid for release-handoff or recorded report-writer dispatch failure."
+        },
+        "leadModel": { "type": "string", "minLength": 1 },
+        "okstraVersion": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "approvalBlock": {
+      "type": "object",
+      "description": "RENDER_IF taskType == implementation-planning. Renderer emits the User Approval Request section.",
+      "required": ["approved"],
+      "additionalProperties": false,
+      "properties": {
+        "approved": {
+          "type": "boolean",
+          "description": "When true, renders `- [x] Approved`; when false, `- [ ] Approved`. Plan Body Verification gate decides which."
+        }
+      }
+    },
+
+    "clarificationCarryIn": {
+      "type": "object",
+      "description": "RENDER_IF non-empty. Carry-in clarifications from the previous run.",
+      "required": ["sourceFile"],
+      "additionalProperties": false,
+      "properties": {
+        "sourceFile": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Project-relative path to the prior run's clarification-response sidecar."
+        }
+      }
+    },
+
+    "verdictCard": {
+      "type": "object",
+      "description": "Top-of-report at-a-glance card. Values MUST byte-match finalVerdict and recommendedNextSteps[0]; renderer fills both from this data structure so divergence is impossible.",
+      "required": [
+        "finalConclusion",
+        "verdictToken",
+        "direction",
+        "approvalRequired",
+        "nextStep"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "finalConclusion": { "type": "string", "minLength": 1 },
+        "verdictToken": { "$ref": "#/$defs/VerdictToken" },
+        "direction": { "$ref": "#/$defs/Direction" },
+        "approvalRequired": { "type": "boolean" },
+        "nextStep": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "summary": {
+      "type": "array",
+      "description": "## Summary of the Problem or Verification Target. 3-5 rows.",
+      "minItems": 1,
+      "maxItems": 8,
+      "items": { "$ref": "#/$defs/SummaryRow" }
+    },
+
+    "ticketCoverage": {
+      "oneOf": [
+        {
+          "type": "object",
+          "description": "Single-ticket run: one-line `- Single ticket run: <ticket>`.",
+          "required": ["singleTicket"],
+          "additionalProperties": false,
+          "properties": {
+            "singleTicket": { "type": "string", "minLength": 1 }
+          }
+        },
+        {
+          "type": "object",
+          "description": "Multi-ticket run: reverse index table.",
+          "required": ["rows"],
+          "additionalProperties": false,
+          "properties": {
+            "rows": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "$ref": "#/$defs/TicketCoverageRow" }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "description": "Omit Ticket Coverage entirely (release-handoff / final-verification).",
+          "required": ["omit"],
+          "additionalProperties": false,
+          "properties": {
+            "omit": { "const": true }
+          }
+        }
+      ]
+    },
+
+    "executionStatus": {
+      "type": "array",
+      "description": "## Execution Status by Agent. One row per worker incl. lead. Token cells stay null until Phase 7 token-usage step fills them.",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/ExecutionStatusRow" }
+    },
+
+    "tokenUsage": {
+      "type": "object",
+      "description": "## Token Usage Summary. All numeric cells are null in Phase 6 and filled by Phase 7 token-usage step.",
+      "required": ["lead", "worker", "grand", "cli"],
+      "additionalProperties": false,
+      "properties": {
+        "lead": { "$ref": "#/$defs/TokenUsageRow" },
+        "worker": { "$ref": "#/$defs/TokenUsageRow" },
+        "grand": { "$ref": "#/$defs/TokenUsageRow" },
+        "cli": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["costUsd"],
+          "properties": {
+            "costUsd": {
+              "oneOf": [
+                { "type": "number", "minimum": 0 },
+                { "type": "null" }
+              ]
+            }
+          }
+        }
+      }
+    },
+
+    "crossVerification": {
+      "type": "object",
+      "required": ["consensus", "differences"],
+      "additionalProperties": false,
+      "properties": {
+        "roundHistory": {
+          "oneOf": [
+            {
+              "type": "object",
+              "description": "Convergence-enabled run.",
+              "required": ["rounds", "round2SkippedReason"],
+              "additionalProperties": false,
+              "properties": {
+                "rounds": {
+                  "type": "array",
+                  "items": { "$ref": "#/$defs/RoundHistoryRow" }
+                },
+                "round2SkippedReason": {
+                  "enum": [
+                    "queue-empty",
+                    "max-rounds-1",
+                    "all-reverify-non-result",
+                    "not-skipped",
+                    "convergence-disabled",
+                    "single-analyser-only"
+                  ]
+                }
+              }
+            },
+            {
+              "type": "object",
+              "description": "Convergence disabled (omit the sub-table entirely).",
+              "required": ["disabled"],
+              "additionalProperties": false,
+              "properties": {
+                "disabled": { "const": true }
+              }
+            }
+          ]
+        },
+        "consensus": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ConsensusRow" }
+        },
+        "differences": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/DifferenceRow" }
+        }
+      }
+    },
+
+    "finalVerdict": {
+      "type": "object",
+      "required": [
+        "finalConclusion",
+        "verdictToken",
+        "direction",
+        "rationaleRowIds",
+        "nextStep"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "finalConclusion": { "type": "string", "minLength": 1 },
+        "verdictToken": { "$ref": "#/$defs/VerdictToken" },
+        "direction": { "$ref": "#/$defs/Direction" },
+        "rationaleRowIds": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "nextStep": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "evidence": {
+      "type": "object",
+      "required": ["primary"],
+      "additionalProperties": false,
+      "properties": {
+        "primary": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/PrimaryEvidenceRow" }
+        },
+        "secondary": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/SecondaryEvidenceRow" }
+        }
+      }
+    },
+
+    "missingInformation": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/RiskRow" }
+    },
+
+    "implementationPlanning": {
+      "type": "object",
+      "description": "RENDER_IF taskType == implementation-planning. §4.5 deliverables.",
+      "required": [
+        "optionCandidates",
+        "tradeoffMatrix",
+        "recommendedOption",
+        "stepwiseExecution",
+        "dependencyMigrationRisk",
+        "validationChecklist",
+        "rollbackStrategy",
+        "planBodyVerification"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "optionCandidates": {
+          "type": "array",
+          "minItems": 2,
+          "items": { "$ref": "#/$defs/OptionCandidate" }
+        },
+        "tradeoffMatrix": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/TradeoffRow" }
+        },
+        "recommendedOption": { "$ref": "#/$defs/RecommendedOption" },
+        "stepwiseExecution": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/StepRow" }
+        },
+        "dependencyMigrationRisk": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/DependencyRow" }
+        },
+        "validationChecklist": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/ValidationCheckRow" }
+        },
+        "rollbackStrategy": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/RollbackRow" }
+        },
+        "planBodyVerification": { "$ref": "#/$defs/PlanBodyVerification" }
+      }
+    },
+
+    "releaseHandoff": {
+      "type": "object",
+      "description": "RENDER_IF taskType == release-handoff. §4.6 deliverables.",
+      "required": [
+        "sourceVerificationReport",
+        "featureBranchState",
+        "userSelections",
+        "executedCommands",
+        "commitList",
+        "mergeConflictProbe",
+        "pullRequestOutcome",
+        "routingRecommendation"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "sourceVerificationReport": {
+          "type": "object",
+          "required": ["path", "verdictTokenQuote"],
+          "additionalProperties": false,
+          "properties": {
+            "path": { "type": "string", "minLength": 1 },
+            "verdictTokenQuote": { "type": "string", "minLength": 1 }
+          }
+        },
+        "featureBranchState": {
+          "type": "object",
+          "required": ["branchName", "gitStatusShort", "existingPrUrl"],
+          "additionalProperties": false,
+          "properties": {
+            "branchName": { "type": "string", "minLength": 1 },
+            "gitStatusShort": { "type": "string" },
+            "existingPrUrl": { "type": "string" }
+          }
+        },
+        "userSelections": {
+          "type": "object",
+          "required": ["h1", "h3"],
+          "additionalProperties": false,
+          "properties": {
+            "h1": { "enum": ["local only", "push + PR", "skip"] },
+            "h2": { "type": "string" },
+            "h3": { "enum": ["use as-is", "edit then proceed", "cancel"] }
+          }
+        },
+        "executedCommands": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ExecutedCommandRow" }
+        },
+        "commitList": {
+          "oneOf": [
+            {
+              "type": "array",
+              "items": { "$ref": "#/$defs/CommitRow" }
+            },
+            {
+              "type": "object",
+              "required": ["empty"],
+              "additionalProperties": false,
+              "properties": { "empty": { "const": true } }
+            }
+          ]
+        },
+        "mergeConflictProbe": {
+          "type": "object",
+          "required": ["kind"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "enum": ["not-run", "clean", "conflicts"]
+            },
+            "baseBranch": { "type": "string" },
+            "baseSha": { "type": "string" },
+            "userChoice": { "type": "string" },
+            "conflictingPaths": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        },
+        "pullRequestOutcome": {
+          "type": "object",
+          "required": ["kind"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "enum": ["no-action", "created", "reused", "skipped"]
+            },
+            "url": { "type": "string" },
+            "title": { "type": "string" },
+            "baseBranch": { "type": "string" },
+            "reason": { "type": "string" }
+          }
+        },
+        "routingRecommendation": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "implementation": {
+      "type": "object",
+      "description": "RENDER_IF taskType == implementation. §4.7 deliverables.",
+      "required": [
+        "approvedPlanReference",
+        "commitList",
+        "diffSummary",
+        "outOfPlanEdits",
+        "validationEvidence",
+        "verifierResults",
+        "rollbackVerification",
+        "routingRecommendation"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "approvedPlanReference": {
+          "type": "object",
+          "required": ["planFile", "approvalEvidence", "executorWorktreePath", "baseRefSha"],
+          "additionalProperties": false,
+          "properties": {
+            "planFile": { "type": "string", "minLength": 1 },
+            "approvalEvidence": { "type": "string", "minLength": 1 },
+            "executorWorktreePath": { "type": "string", "minLength": 1 },
+            "baseRefSha": { "type": "string", "minLength": 1 }
+          }
+        },
+        "commitList": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/CommitWithStepRow" }
+        },
+        "diffSummary": {
+          "type": "object",
+          "required": ["rawStat", "files"],
+          "additionalProperties": false,
+          "properties": {
+            "rawStat": { "type": "string" },
+            "files": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/DiffFileRow" }
+            }
+          }
+        },
+        "outOfPlanEdits": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/OutOfPlanEditRow" }
+        },
+        "validationEvidence": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/ValidationEvidenceRow" }
+        },
+        "verifierResults": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/VerifierResultBlock" }
+        },
+        "rollbackVerification": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/RollbackVerificationRow" }
+        },
+        "routingRecommendation": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "finalVerification": {
+      "type": "object",
+      "description": "RENDER_IF taskType == final-verification. §4.8 deliverables.",
+      "required": [
+        "sourceImplementationReport",
+        "acceptanceBlockers",
+        "residualRisk",
+        "validationEvidence",
+        "readonlyCommandLog",
+        "routingRecommendation"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "sourceImplementationReport": {
+          "type": "object",
+          "required": ["path", "commitListQuote", "worktreePath", "baseHeadSha", "gitStatusShort"],
+          "additionalProperties": false,
+          "properties": {
+            "path": { "type": "string" },
+            "commitListQuote": { "type": "string" },
+            "worktreePath": { "type": "string" },
+            "baseHeadSha": { "type": "string" },
+            "gitStatusShort": { "type": "string" }
+          }
+        },
+        "acceptanceBlockers": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/AcceptanceBlockerRow" }
+        },
+        "residualRisk": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ResidualRiskRow" }
+        },
+        "validationEvidence": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/RequirementCoverageRow" }
+        },
+        "readonlyCommandLog": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ReadonlyCommandRow" }
+        },
+        "routingRecommendation": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "clarificationItems": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ClarificationRow" }
+    },
+
+    "recommendedNextSteps": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/RecommendedStep" }
+    },
+
+    "followUpTasks": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/FollowUpRow" }
+    }
+  },
+
+  "allOf": [
+    {
+      "description": "implementation-planning task-type requires §4.5 block.",
+      "if": {
+        "properties": { "header": { "properties": { "taskType": { "const": "implementation-planning" } } } },
+        "required": ["header"]
+      },
+      "then": {
+        "required": ["implementationPlanning", "approvalBlock"]
+      }
+    },
+    {
+      "description": "release-handoff task-type requires §4.6 block.",
+      "if": {
+        "properties": { "header": { "properties": { "taskType": { "const": "release-handoff" } } } },
+        "required": ["header"]
+      },
+      "then": {
+        "required": ["releaseHandoff"]
+      }
+    },
+    {
+      "description": "implementation task-type requires §4.7 block.",
+      "if": {
+        "properties": { "header": { "properties": { "taskType": { "const": "implementation" } } } },
+        "required": ["header"]
+      },
+      "then": {
+        "required": ["implementation"]
+      }
+    },
+    {
+      "description": "final-verification task-type requires §4.8 block.",
+      "if": {
+        "properties": { "header": { "properties": { "taskType": { "const": "final-verification" } } } },
+        "required": ["header"]
+      },
+      "then": {
+        "required": ["finalVerification"]
+      }
+    },
+    {
+      "description": "Non-terminal task-types MUST emit one phase-continuation row in followUpTasks.",
+      "if": {
+        "properties": {
+          "header": {
+            "properties": {
+              "taskType": {
+                "enum": [
+                  "requirements-discovery",
+                  "implementation-planning",
+                  "error-analysis",
+                  "implementation",
+                  "final-verification"
+                ]
+              }
+            }
+          }
+        },
+        "required": ["header"]
+      },
+      "then": {
+        "properties": {
+          "followUpTasks": {
+            "type": "array",
+            "minItems": 1,
+            "contains": {
+              "type": "object",
+              "properties": {
+                "origin": { "const": "phase-continuation" }
+              },
+              "required": ["origin"]
+            }
+          }
+        }
+      }
+    },
+    {
+      "description": "final-verification verdict token must be one of accepted / conditional-accept / blocked.",
+      "if": {
+        "properties": { "header": { "properties": { "taskType": { "const": "final-verification" } } } },
+        "required": ["header"]
+      },
+      "then": {
+        "properties": {
+          "finalVerdict": {
+            "properties": {
+              "verdictToken": { "enum": ["accepted", "conditional-accept", "blocked"] }
+            }
+          }
+        }
+      }
+    },
+    {
+      "description": "Non-final-verification verdict token must be `not-applicable`.",
+      "if": {
+        "properties": {
+          "header": {
+            "properties": {
+              "taskType": { "not": { "const": "final-verification" } }
+            }
+          }
+        },
+        "required": ["header"]
+      },
+      "then": {
+        "properties": {
+          "finalVerdict": {
+            "properties": {
+              "verdictToken": { "const": "not-applicable" }
+            }
+          }
+        }
+      }
+    }
+  ],
+
+  "$defs": {
+    "TaskType": {
+      "enum": [
+        "requirements-discovery",
+        "error-analysis",
+        "implementation-planning",
+        "implementation",
+        "final-verification",
+        "release-handoff",
+        "quick"
+      ]
+    },
+
+    "VerdictToken": {
+      "enum": ["accepted", "conditional-accept", "blocked", "not-applicable"]
+    },
+
+    "Direction": {
+      "enum": [
+        "continue-investigation",
+        "begin-implementation",
+        "approve",
+        "reject",
+        "hold"
+      ]
+    },
+
+    "TicketId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Ticket key (external) or task-fallback (task-id verbatim) or literal `unknown` when truly unidentified. Empty string is never valid."
+    },
+
+    "Priority": {
+      "enum": ["P0", "P1", "P2"]
+    },
+
+    "FollowUpOrigin": {
+      "enum": [
+        "phase-continuation",
+        "out-of-plan",
+        "verifier-concern",
+        "scope-boundary",
+        "open-question",
+        "manual"
+      ]
+    },
+
+    "ClarificationKind": {
+      "enum": ["material", "decision", "data-point"]
+    },
+
+    "ClarificationBlocks": {
+      "enum": ["approval", "next-phase", "none"]
+    },
+
+    "ClarificationStatus": {
+      "enum": ["open", "answered", "resolved", "obsolete"]
+    },
+
+    "WorkerStatus": {
+      "enum": ["completed", "error", "timeout", "not-run", "synthesis-only"]
+    },
+
+    "SourceItem": {
+      "type": "string",
+      "pattern": "^[a-z][a-z-]*:[A-Za-z0-9._-]+$",
+      "description": "Source-item reference in the form `<worker>:<item-id>`, e.g. `claude:F-001`, `codex:1.1`, `lead:mcp-1`. Bare worker-name lists are deprecated; every source must carry its origin item ID."
+    },
+
+    "SummaryRow": {
+      "type": "object",
+      "required": ["id", "ticketId", "summary", "source"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^P-\\d{3,}$" },
+        "ticketId": { "$ref": "#/$defs/TicketId" },
+        "summary": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "TicketCoverageRow": {
+      "type": "object",
+      "required": ["ticketId", "sections", "relatedIds"],
+      "additionalProperties": false,
+      "properties": {
+        "ticketId": { "$ref": "#/$defs/TicketId" },
+        "sections": { "type": "string", "minLength": 1 },
+        "relatedIds": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "ExecutionStatusRow": {
+      "type": "object",
+      "required": ["agent", "role", "model", "status", "summary"],
+      "additionalProperties": false,
+      "properties": {
+        "agent": { "enum": ["Claude Code", "Codex", "Gemini"] },
+        "role": { "type": "string", "minLength": 1 },
+        "model": { "type": "string", "minLength": 1 },
+        "status": { "$ref": "#/$defs/WorkerStatus" },
+        "summary": { "type": "string", "minLength": 1 },
+        "totalTokens": {
+          "oneOf": [
+            { "type": "integer", "minimum": 0 },
+            { "type": "null" }
+          ]
+        },
+        "billableTokens": {
+          "oneOf": [
+            { "type": "integer", "minimum": 0 },
+            { "type": "null" }
+          ]
+        },
+        "costUsd": {
+          "oneOf": [
+            { "type": "number", "minimum": 0 },
+            { "type": "null" }
+          ]
+        },
+        "cliTotalTokens": {
+          "oneOf": [
+            { "type": "integer", "minimum": 0 },
+            { "type": "null" }
+          ]
+        },
+        "cliCostUsd": {
+          "oneOf": [
+            { "type": "number", "minimum": 0 },
+            { "type": "null" }
+          ]
+        },
+        "durationMs": {
+          "oneOf": [
+            { "type": "integer", "minimum": 0 },
+            { "type": "null" }
+          ]
+        }
+      }
+    },
+
+    "TokenUsageRow": {
+      "type": "object",
+      "required": ["totalTokens", "billableTokens", "costUsd"],
+      "additionalProperties": false,
+      "properties": {
+        "totalTokens": {
+          "oneOf": [
+            { "type": "integer", "minimum": 0 },
+            { "type": "null" }
+          ]
+        },
+        "billableTokens": {
+          "oneOf": [
+            { "type": "integer", "minimum": 0 },
+            { "type": "null" }
+          ]
+        },
+        "costUsd": {
+          "oneOf": [
+            { "type": "number", "minimum": 0 },
+            { "type": "null" }
+          ]
+        }
+      }
+    },
+
+    "RoundHistoryRow": {
+      "type": "object",
+      "required": [
+        "round",
+        "inputQueueSize",
+        "resolvedCount",
+        "carriedForwardCount",
+        "dispatches",
+        "skippedWorkers"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "round": { "type": "integer", "minimum": 0 },
+        "inputQueueSize": { "type": "integer", "minimum": 0 },
+        "resolvedCount": { "type": "integer", "minimum": 0 },
+        "carriedForwardCount": { "type": "integer", "minimum": 0 },
+        "dispatches": { "type": "string" },
+        "skippedWorkers": { "type": "string" }
+      }
+    },
+
+    "ConsensusRow": {
+      "type": "object",
+      "required": ["id", "ticketId", "statement", "sourceItems", "evidence"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^C-\\d{3,}$" },
+        "ticketId": { "$ref": "#/$defs/TicketId" },
+        "statement": { "type": "string", "minLength": 1 },
+        "sourceItems": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/SourceItem" }
+        },
+        "evidence": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "DifferenceRow": {
+      "type": "object",
+      "required": ["id", "ticketId", "disagreement", "workersPosition", "evidence"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^D-\\d{3,}$" },
+        "ticketId": { "$ref": "#/$defs/TicketId" },
+        "disagreement": { "type": "string", "minLength": 1 },
+        "workersPosition": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["worker", "itemId", "position"],
+            "additionalProperties": false,
+            "properties": {
+              "worker": { "type": "string", "minLength": 1 },
+              "itemId": { "type": "string" },
+              "position": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "evidence": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "PrimaryEvidenceRow": {
+      "type": "object",
+      "required": ["id", "ticketId", "evidence", "sourceItems", "source"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^E-\\d{3,}$" },
+        "ticketId": { "$ref": "#/$defs/TicketId" },
+        "evidence": { "type": "string", "minLength": 1 },
+        "sourceItems": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/SourceItem" }
+        },
+        "source": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "SecondaryEvidenceRow": {
+      "type": "object",
+      "required": ["id", "ticketId", "hypothesis", "confidence"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^S-\\d{3,}$" },
+        "ticketId": { "$ref": "#/$defs/TicketId" },
+        "hypothesis": { "type": "string", "minLength": 1 },
+        "confidence": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "RiskRow": {
+      "type": "object",
+      "required": ["id", "ticketId", "item", "risk", "owner"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^R-\\d{3,}$" },
+        "ticketId": { "$ref": "#/$defs/TicketId" },
+        "item": { "type": "string", "minLength": 1 },
+        "risk": { "type": "string", "minLength": 1 },
+        "owner": { "type": "string", "minLength": 1 },
+        "source": { "type": "string" }
+      }
+    },
+
+    "OptionCandidate": {
+      "type": "object",
+      "required": ["name", "fileStructure", "interfaces", "blastRadius"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "fileStructure": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "ticketId", "action", "path", "summary"],
+            "additionalProperties": false,
+            "properties": {
+              "id": { "type": "string", "pattern": "^OF-\\d{3,}$" },
+              "ticketId": { "$ref": "#/$defs/TicketId" },
+              "action": { "enum": ["Create", "Modify", "Delete"] },
+              "path": { "type": "string", "minLength": 1 },
+              "summary": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "interfaces": { "type": "string" },
+        "blastRadius": { "type": "string" }
+      }
+    },
+
+    "TradeoffRow": {
+      "type": "object",
+      "required": ["option", "complexity", "risk", "reversibility", "testCoverageCost", "rolloutCost"],
+      "additionalProperties": false,
+      "properties": {
+        "option": { "type": "string", "minLength": 1 },
+        "complexity": { "type": "string", "minLength": 1 },
+        "risk": { "type": "string", "minLength": 1 },
+        "reversibility": { "type": "string", "minLength": 1 },
+        "testCoverageCost": { "type": "string", "minLength": 1 },
+        "rolloutCost": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "RecommendedOption": {
+      "type": "object",
+      "required": ["name", "coreReason", "rationale", "rejectedSummary"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "coreReason": { "type": "string", "minLength": 1 },
+        "rationale": { "type": "string", "minLength": 1 },
+        "rejectedSummary": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "StepRow": {
+      "type": "object",
+      "required": ["step", "ticketId", "action", "files", "commandOrTest", "expectedOutcome"],
+      "additionalProperties": false,
+      "properties": {
+        "step": { "type": "integer", "minimum": 1 },
+        "ticketId": { "$ref": "#/$defs/TicketId" },
+        "action": { "type": "string", "minLength": 1 },
+        "files": { "type": "string", "minLength": 1 },
+        "commandOrTest": { "type": "string", "minLength": 1 },
+        "expectedOutcome": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "DependencyRow": {
+      "type": "object",
+      "required": ["id", "kind", "item", "impact", "mitigation"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^DM-\\d{3,}$" },
+        "kind": {
+          "enum": ["order", "backfill", "flag-precondition", "repo-sequencing", "other"]
+        },
+        "item": { "type": "string", "minLength": 1 },
+        "impact": { "type": "string", "minLength": 1 },
+        "mitigation": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "ValidationCheckRow": {
+      "type": "object",
+      "required": ["phase", "ticketId", "check", "commandOrObservation", "expectedOutcome"],
+      "additionalProperties": false,
+      "properties": {
+        "phase": { "enum": ["pre", "mid", "post"] },
+        "ticketId": { "$ref": "#/$defs/TicketId" },
+        "check": { "type": "string", "minLength": 1 },
+        "commandOrObservation": { "type": "string", "minLength": 1 },
+        "expectedOutcome": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "RollbackRow": {
+      "type": "object",
+      "required": ["id", "step", "action", "triggerSignal", "verificationMethod"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^RB-\\d{3,}$" },
+        "step": { "type": "integer", "minimum": 1 },
+        "action": { "type": "string", "minLength": 1 },
+        "triggerSignal": { "type": "string", "minLength": 1 },
+        "verificationMethod": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "PlanBodyVerification": {
+      "type": "object",
+      "required": ["roundCount", "gateResult", "verdictSummary", "verdictDetails", "dissentLog"],
+      "additionalProperties": false,
+      "properties": {
+        "roundCount": { "type": "integer", "minimum": 0 },
+        "gateResult": {
+          "enum": [
+            "passed",
+            "passed-with-dissent",
+            "blocked-by-disagreement",
+            "aborted-non-result"
+          ]
+        },
+        "verdictSummary": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["planItem", "ticketId", "section", "classification"],
+            "additionalProperties": false,
+            "properties": {
+              "planItem": {
+                "type": "string",
+                "pattern": "^P-(Opt|Step|Dep|Val|Rb)-\\d+$"
+              },
+              "ticketId": { "$ref": "#/$defs/TicketId" },
+              "section": { "type": "string", "minLength": 1 },
+              "classification": {
+                "type": "string",
+                "pattern": "^(full-consensus|partial-consensus|worker-unique|majority-disagree → C-\\d+)$"
+              }
+            }
+          }
+        },
+        "verdictDetails": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["planItem", "worker", "verdict"],
+            "additionalProperties": false,
+            "properties": {
+              "planItem": { "type": "string", "minLength": 1 },
+              "worker": { "type": "string", "minLength": 1 },
+              "verdict": {
+                "enum": ["AGREE", "DISAGREE", "SUPPLEMENT", "verification-error"]
+              },
+              "breakageKind": { "type": "string" },
+              "note": { "type": "string" }
+            }
+          }
+        },
+        "dissentLog": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["planItem", "workerRole", "body"],
+            "additionalProperties": false,
+            "properties": {
+              "planItem": { "type": "string", "minLength": 1 },
+              "workerRole": { "type": "string", "minLength": 1 },
+              "body": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+
+    "ExecutedCommandRow": {
+      "type": "object",
+      "required": ["number", "command", "exitCode", "outputSummary"],
+      "additionalProperties": false,
+      "properties": {
+        "number": { "type": "integer", "minimum": 1 },
+        "command": { "type": "string", "minLength": 1 },
+        "exitCode": { "type": "integer" },
+        "outputSummary": { "type": "string" }
+      }
+    },
+
+    "CommitRow": {
+      "type": "object",
+      "required": ["shortSha", "fullSha", "subject", "files"],
+      "additionalProperties": false,
+      "properties": {
+        "shortSha": { "type": "string", "minLength": 7 },
+        "fullSha": { "type": "string", "minLength": 40 },
+        "subject": { "type": "string", "minLength": 1 },
+        "files": { "type": "string" }
+      }
+    },
+
+    "CommitWithStepRow": {
+      "type": "object",
+      "required": ["number", "shortSha", "fullSha", "planStep", "subject", "files"],
+      "additionalProperties": false,
+      "properties": {
+        "number": { "type": "integer", "minimum": 1 },
+        "shortSha": { "type": "string", "minLength": 7 },
+        "fullSha": { "type": "string", "minLength": 40 },
+        "planStep": { "type": "string", "minLength": 1 },
+        "subject": { "type": "string", "minLength": 1 },
+        "files": { "type": "string" }
+      }
+    },
+
+    "DiffFileRow": {
+      "type": "object",
+      "required": ["file", "action", "lines", "planStep"],
+      "additionalProperties": false,
+      "properties": {
+        "file": { "type": "string", "minLength": 1 },
+        "action": { "enum": ["created", "modified", "deleted"] },
+        "lines": { "type": "string", "minLength": 1 },
+        "planStep": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "OutOfPlanEditRow": {
+      "type": "object",
+      "required": ["id", "file", "rationale", "trigger"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^OOP-\\d{3,}$" },
+        "file": { "type": "string", "minLength": 1 },
+        "rationale": { "type": "string", "minLength": 1 },
+        "trigger": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "ValidationEvidenceRow": {
+      "type": "object",
+      "required": ["phase", "command", "exitCode", "outputTail"],
+      "additionalProperties": false,
+      "properties": {
+        "phase": { "enum": ["pre", "mid", "post"] },
+        "command": { "type": "string", "minLength": 1 },
+        "exitCode": { "type": "integer" },
+        "outputTail": { "type": "string" },
+        "tddEvidence": { "type": "string" }
+      }
+    },
+
+    "VerifierResultBlock": {
+      "type": "object",
+      "required": ["verifier", "verdict", "readOnlyCommandLog", "independentValidationRerun"],
+      "additionalProperties": false,
+      "properties": {
+        "verifier": { "type": "string", "minLength": 1 },
+        "verdict": { "enum": ["PASS", "CONCERNS", "FAIL"] },
+        "readOnlyCommandLog": { "type": "string" },
+        "independentValidationRerun": { "type": "string" },
+        "styleLintTypecheck": { "type": "string" },
+        "declinedFixRecommendations": { "type": "string" },
+        "discrepancy": { "type": "string" }
+      }
+    },
+
+    "RollbackVerificationRow": {
+      "type": "object",
+      "required": ["category", "rollbackCommand", "verification", "result"],
+      "additionalProperties": false,
+      "properties": {
+        "category": {
+          "enum": ["Pure code", "Feature-flag-gated", "Schema/config/stateful"]
+        },
+        "rollbackCommand": { "type": "string", "minLength": 1 },
+        "verification": { "type": "string", "minLength": 1 },
+        "result": {
+          "enum": ["ok", "unable — route back to planning"]
+        }
+      }
+    },
+
+    "AcceptanceBlockerRow": {
+      "type": "object",
+      "required": ["id", "severity", "statement", "evidence", "followUpPhase"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^AB-\\d{3,}$" },
+        "severity": { "enum": ["critical", "major", "minor"] },
+        "statement": { "type": "string", "minLength": 1 },
+        "evidence": { "type": "string", "minLength": 1 },
+        "followUpPhase": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "ResidualRiskRow": {
+      "type": "object",
+      "required": ["id", "item", "owner", "escalationTrigger"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^RR-\\d{3,}$" },
+        "item": { "type": "string", "minLength": 1 },
+        "owner": { "type": "string", "minLength": 1 },
+        "escalationTrigger": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "RequirementCoverageRow": {
+      "type": "object",
+      "required": ["id", "requirement", "artifact", "status"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^VE-\\d{3,}$" },
+        "requirement": { "type": "string", "minLength": 1 },
+        "artifact": { "type": "string", "minLength": 1 },
+        "status": {
+          "type": "string",
+          "pattern": "^(covered|blocker AB-\\d{3,}|gap)$"
+        }
+      }
+    },
+
+    "ReadonlyCommandRow": {
+      "type": "object",
+      "required": ["number", "tier", "command", "exitCode", "outputTail"],
+      "additionalProperties": false,
+      "properties": {
+        "number": { "type": "integer", "minimum": 1 },
+        "tier": { "enum": [1, 2] },
+        "command": { "type": "string", "minLength": 1 },
+        "exitCode": { "type": "integer" },
+        "outputTail": { "type": "string" }
+      }
+    },
+
+    "ClarificationRow": {
+      "type": "object",
+      "required": ["id", "ticketId", "kind", "statement", "expectedForm", "blocks", "status"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^C-\\d{3,}$" },
+        "ticketId": { "$ref": "#/$defs/TicketId" },
+        "kind": { "$ref": "#/$defs/ClarificationKind" },
+        "statement": { "type": "string", "minLength": 1 },
+        "expectedForm": { "type": "string", "minLength": 1 },
+        "blocks": { "$ref": "#/$defs/ClarificationBlocks" },
+        "status": { "$ref": "#/$defs/ClarificationStatus" },
+        "userInput": { "type": "string" }
+      }
+    },
+
+    "RecommendedStep": {
+      "type": "object",
+      "required": ["text"],
+      "additionalProperties": false,
+      "properties": {
+        "text": { "type": "string", "minLength": 1 },
+        "commands": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["label", "claudeCode", "terminal"],
+            "additionalProperties": false,
+            "properties": {
+              "label": { "type": "string", "minLength": 1 },
+              "claudeCode": { "type": "string", "minLength": 1 },
+              "terminal": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+
+    "FollowUpRow": {
+      "type": "object",
+      "required": [
+        "id",
+        "ticketId",
+        "origin",
+        "newTaskId",
+        "title",
+        "suggestedTaskType",
+        "scope",
+        "reason",
+        "priority",
+        "autoSpawn"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^FU-\\d{3,}$" },
+        "ticketId": { "$ref": "#/$defs/TicketId" },
+        "origin": { "$ref": "#/$defs/FollowUpOrigin" },
+        "newTaskId": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "suggestedTaskType": { "$ref": "#/$defs/TaskType" },
+        "scope": { "type": "string", "minLength": 1 },
+        "reason": { "type": "string", "minLength": 1 },
+        "priority": { "$ref": "#/$defs/Priority" },
+        "autoSpawn": { "enum": ["yes", "no"] }
+      },
+      "allOf": [
+        {
+          "description": "phase-continuation rows MUST have autoSpawn=no (advances via /okstra-run, no new dir).",
+          "if": {
+            "properties": { "origin": { "const": "phase-continuation" } }
+          },
+          "then": {
+            "properties": { "autoSpawn": { "const": "no" } }
+          }
+        }
+      ]
+    }
+  }
+}