okstra 0.202.0 → 0.204.0

package/runtime/schemas/agent-profile-v1.schema.json

@@ -0,0 +1,46 @@
+{
+  "type": "object",
+  "required": ["schemaVersion", "id", "roles"],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "id": { "type": "string", "minLength": 1 },
+    "roles": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "required": ["mode", "roleId", "dutyId", "min", "recommended", "max"],
+            "properties": {
+              "mode": { "const": "static" },
+              "roleId": { "type": "string", "minLength": 1 },
+              "dutyId": { "type": "string", "minLength": 1 },
+              "min": { "type": "integer", "minimum": 0 },
+              "recommended": { "type": "integer", "minimum": 0 },
+              "max": { "type": "integer", "minimum": 0 }
+            },
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "required": ["mode", "roleId", "dutyId", "sourceRoleIds", "activation"],
+            "properties": {
+              "mode": { "const": "dynamic" },
+              "roleId": { "type": "string", "minLength": 1 },
+              "dutyId": { "type": "string", "minLength": 1 },
+              "sourceRoleIds": {
+                "type": "array",
+                "minItems": 1,
+                "uniqueItems": true,
+                "items": { "type": "string", "minLength": 1 }
+              },
+              "activation": { "const": "per-selected-source" }
+            },
+            "additionalProperties": false
+          }
+        ]
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/runtime/schemas/agent-role-v1.schema.json

@@ -0,0 +1,29 @@
+{
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "id",
+    "legacyAliases",
+    "identity",
+    "responsibilities",
+    "requiredCapabilities",
+    "prohibitions"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "id": { "type": "string", "minLength": 1 },
+    "legacyAliases": { "$ref": "#/$defs/stringList" },
+    "identity": { "type": "string", "minLength": 1 },
+    "responsibilities": { "$ref": "#/$defs/stringList" },
+    "requiredCapabilities": { "$ref": "#/$defs/stringList" },
+    "prohibitions": { "$ref": "#/$defs/stringList" }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "stringList": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    }
+  }
+}

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

@@ -905,110 +905,103 @@
       "description": "RENDER_IF taskType == release-handoff. §5.6 deliverables.",
       "required": [
         "handoffScope",
+        "sourceVerificationReports",
         "featureBranchState",
         "userSelections",
         "localCheckoutOutcome",
         "executedCommands",
         "commitList",
         "mergeConflictProbe",
-        "pullRequestOutcome",
+        "pullRequestOutcomes",
         "routingRecommendation",
         "userNarrative"
       ],
       "additionalProperties": false,
-      "allOf": [
-        {
-          "if": {
-            "properties": {
-              "handoffScope": {
-                "properties": {
-                  "mode": {
-                    "const": "stage-group"
-                  }
-                },
-                "required": [
-                  "mode"
-                ]
-              }
-            },
-            "required": [
-              "handoffScope"
-            ]
-          },
-          "then": {
-            "required": [
-              "sourceVerificationReports"
-            ]
-          },
-          "else": {
-            "required": [
-              "sourceVerificationReport"
-            ]
-          }
-        }
-      ],
       "properties": {
         "handoffScope": {
           "type": "object",
           "required": [
-            "mode"
+            "stages",
+            "releaseBase"
           ],
           "additionalProperties": false,
-          "description": "Which shape of handoff this was. 'whole-task' turns the verified task branch into one PR; 'stage-group' merges a user-selected subset of verified stages into a collector branch and opens the PR from that. Without it a reader cannot tell one report from the other, and in stage-group mode cannot tell which stages shipped — the branch name alone does not say.",
+          "description": "What this handoff delivered. One stage is one PR, so the stage list is the PR list, and `stagePlan` is the only place a reader learns which branch each PR sat on — and therefore in what order the stack must be merged.",
           "properties": {
-            "mode": {
-              "enum": [
-                "whole-task",
-                "stage-group"
-              ]
-            },
             "stages": {
               "type": "array",
+              "minItems": 1,
               "items": {
                 "type": "integer",
                 "minimum": 1
               }
             },
-            "collectorBranch": {
-              "type": "string"
+            "releaseBase": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The base branch the user picked for the run. A stage that sits on another stage does NOT target it — see stagePlan[].baseBranch."
             },
-            "mergeCommits": {
+            "stagePlan": {
               "type": "array",
-              "description": "Assemble's merge commit SHAs, in the order the stages were merged into the collector branch. Without them the collector branch's contents cannot be traced back to the stages that produced them once the branch moves on.",
+              "description": "`okstra handoff pr-plan` output, one row per stage. Without it the merge order of a stacked PR set cannot be reconstructed once the branches move.",
               "items": {
-                "type": "string",
-                "minLength": 7
+                "type": "object",
+                "required": [
+                  "stage",
+                  "headBranch",
+                  "baseKind",
+                  "baseBranch"
+                ],
+                "additionalProperties": false,
+                "properties": {
+                  "stage": {
+                    "type": "integer",
+                    "minimum": 1
+                  },
+                  "headBranch": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "headCommit": {
+                    "type": "string"
+                  },
+                  "baseKind": {
+                    "enum": [
+                      "release-base",
+                      "stage",
+                      "merge-base"
+                    ]
+                  },
+                  "baseBranch": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "baseCommit": {
+                    "type": "string"
+                  },
+                  "baseStages": {
+                    "type": "array",
+                    "description": "The predecessor stages this row's base carries. Empty for a release-base row.",
+                    "items": {
+                      "type": "integer",
+                      "minimum": 1
+                    }
+                  },
+                  "baseMergeCommits": {
+                    "type": "array",
+                    "description": "Merge commits pr-plan created on a merge-base branch. The only commits release-handoff is allowed to produce.",
+                    "items": {
+                      "type": "string",
+                      "minLength": 7
+                    }
+                  }
+                }
               }
-            },
-            "dependencyClosureVerdict": {
-              "type": "string",
-              "minLength": 1,
-              "description": "Whether the selected stages are closed under their dependencies, and on what basis. A stage-group PR that ships a stage without its predecessor is the failure this records."
-            }
-          }
-        },
-        "sourceVerificationReport": {
-          "type": "object",
-          "description": "whole-task mode: the one final-verification report this handoff ships. Required unless handoffScope.mode is stage-group.",
-          "required": [
-            "path",
-            "verdictTokenQuote"
-          ],
-          "additionalProperties": false,
-          "properties": {
-            "path": {
-              "type": "string",
-              "minLength": 1
-            },
-            "verdictTokenQuote": {
-              "type": "string",
-              "minLength": 1
             }
           }
         },
         "sourceVerificationReports": {
           "type": "array",
-          "description": "stage-group mode: one row per selected stage, because that handoff ships several verified stages and a single report path cannot say which stage each verdict belongs to.",
+          "description": "One row per selected stage. Each stage ships its own PR under its own verdict, so a single report path cannot say which stage a verdict belongs to.",
           "minItems": 1,
           "items": {
             "type": "object",
@@ -1048,6 +1041,11 @@
                 "checked-out"
               ]
             },
+            "stage": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "The stage whose branch was checked out. Checkout is per stage, so a branch name without it leaves the reader matching branch suffixes by hand."
+            },
             "branch": {
               "type": "string"
             },
@@ -1173,6 +1171,14 @@
             "userChoice": {
               "type": "string"
             },
+            "conflictingStages": {
+              "type": "array",
+              "description": "The stages whose head did not merge cleanly into their own PR base. The probe runs per stage, so a bare path list cannot say which PR is affected.",
+              "items": {
+                "type": "integer",
+                "minimum": 1
+              }
+            },
             "conflictingPaths": {
               "type": "array",
               "items": {
@@ -1181,32 +1187,41 @@
             }
           }
         },
-        "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"
+        "pullRequestOutcomes": {
+          "type": "array",
+          "description": "One row per selected stage — one stage is one PR. A single outcome object cannot say which stage was created, reused or skipped.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "stage",
+              "kind"
+            ],
+            "properties": {
+              "stage": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "kind": {
+                "enum": [
+                  "no-action",
+                  "created",
+                  "reused",
+                  "skipped"
+                ]
+              },
+              "url": {
+                "type": "string"
+              },
+              "title": {
+                "type": "string"
+              },
+              "baseBranch": {
+                "type": "string"
+              },
+              "reason": {
+                "type": "string"
+              }
             }
           }
         },
@@ -1582,6 +1597,7 @@
               "enum": [
                 "release-handoff",
                 "release-handoff(stage-group)",
+                "final-verification",
                 "error-analysis",
                 "implementation-option-selection",
                 "implementation-planning",
@@ -9687,6 +9703,11 @@
       ],
       "additionalProperties": false,
       "properties": {
+        "stage": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Which stage's PR carries this commit. One stage is one PR, so a flat commit list across several stages cannot be attributed without it."
+        },
         "shortSha": {
           "type": "string",
           "minLength": 7

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

@@ -905,110 +905,103 @@
       "description": "RENDER_IF taskType == release-handoff. §5.6 deliverables.",
       "required": [
         "handoffScope",
+        "sourceVerificationReports",
         "featureBranchState",
         "userSelections",
         "localCheckoutOutcome",
         "executedCommands",
         "commitList",
         "mergeConflictProbe",
-        "pullRequestOutcome",
+        "pullRequestOutcomes",
         "routingRecommendation",
         "userNarrative"
       ],
       "additionalProperties": false,
-      "allOf": [
-        {
-          "if": {
-            "properties": {
-              "handoffScope": {
-                "properties": {
-                  "mode": {
-                    "const": "stage-group"
-                  }
-                },
-                "required": [
-                  "mode"
-                ]
-              }
-            },
-            "required": [
-              "handoffScope"
-            ]
-          },
-          "then": {
-            "required": [
-              "sourceVerificationReports"
-            ]
-          },
-          "else": {
-            "required": [
-              "sourceVerificationReport"
-            ]
-          }
-        }
-      ],
       "properties": {
         "handoffScope": {
           "type": "object",
           "required": [
-            "mode"
+            "stages",
+            "releaseBase"
           ],
           "additionalProperties": false,
-          "description": "Which shape of handoff this was. 'whole-task' turns the verified task branch into one PR; 'stage-group' merges a user-selected subset of verified stages into a collector branch and opens the PR from that. Without it a reader cannot tell one report from the other, and in stage-group mode cannot tell which stages shipped — the branch name alone does not say.",
+          "description": "What this handoff delivered. One stage is one PR, so the stage list is the PR list, and `stagePlan` is the only place a reader learns which branch each PR sat on — and therefore in what order the stack must be merged.",
           "properties": {
-            "mode": {
-              "enum": [
-                "whole-task",
-                "stage-group"
-              ]
-            },
             "stages": {
               "type": "array",
+              "minItems": 1,
               "items": {
                 "type": "integer",
                 "minimum": 1
               }
             },
-            "collectorBranch": {
-              "type": "string"
+            "releaseBase": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The base branch the user picked for the run. A stage that sits on another stage does NOT target it — see stagePlan[].baseBranch."
             },
-            "mergeCommits": {
+            "stagePlan": {
               "type": "array",
-              "description": "Assemble's merge commit SHAs, in the order the stages were merged into the collector branch. Without them the collector branch's contents cannot be traced back to the stages that produced them once the branch moves on.",
+              "description": "`okstra handoff pr-plan` output, one row per stage. Without it the merge order of a stacked PR set cannot be reconstructed once the branches move.",
               "items": {
-                "type": "string",
-                "minLength": 7
+                "type": "object",
+                "required": [
+                  "stage",
+                  "headBranch",
+                  "baseKind",
+                  "baseBranch"
+                ],
+                "additionalProperties": false,
+                "properties": {
+                  "stage": {
+                    "type": "integer",
+                    "minimum": 1
+                  },
+                  "headBranch": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "headCommit": {
+                    "type": "string"
+                  },
+                  "baseKind": {
+                    "enum": [
+                      "release-base",
+                      "stage",
+                      "merge-base"
+                    ]
+                  },
+                  "baseBranch": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "baseCommit": {
+                    "type": "string"
+                  },
+                  "baseStages": {
+                    "type": "array",
+                    "description": "The predecessor stages this row's base carries. Empty for a release-base row.",
+                    "items": {
+                      "type": "integer",
+                      "minimum": 1
+                    }
+                  },
+                  "baseMergeCommits": {
+                    "type": "array",
+                    "description": "Merge commits pr-plan created on a merge-base branch. The only commits release-handoff is allowed to produce.",
+                    "items": {
+                      "type": "string",
+                      "minLength": 7
+                    }
+                  }
+                }
               }
-            },
-            "dependencyClosureVerdict": {
-              "type": "string",
-              "minLength": 1,
-              "description": "Whether the selected stages are closed under their dependencies, and on what basis. A stage-group PR that ships a stage without its predecessor is the failure this records."
-            }
-          }
-        },
-        "sourceVerificationReport": {
-          "type": "object",
-          "description": "whole-task mode: the one final-verification report this handoff ships. Required unless handoffScope.mode is stage-group.",
-          "required": [
-            "path",
-            "verdictTokenQuote"
-          ],
-          "additionalProperties": false,
-          "properties": {
-            "path": {
-              "type": "string",
-              "minLength": 1
-            },
-            "verdictTokenQuote": {
-              "type": "string",
-              "minLength": 1
             }
           }
         },
         "sourceVerificationReports": {
           "type": "array",
-          "description": "stage-group mode: one row per selected stage, because that handoff ships several verified stages and a single report path cannot say which stage each verdict belongs to.",
+          "description": "One row per selected stage. Each stage ships its own PR under its own verdict, so a single report path cannot say which stage a verdict belongs to.",
           "minItems": 1,
           "items": {
             "type": "object",
@@ -1048,6 +1041,11 @@
                 "checked-out"
               ]
             },
+            "stage": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "The stage whose branch was checked out. Checkout is per stage, so a branch name without it leaves the reader matching branch suffixes by hand."
+            },
             "branch": {
               "type": "string"
             },
@@ -1173,6 +1171,14 @@
             "userChoice": {
               "type": "string"
             },
+            "conflictingStages": {
+              "type": "array",
+              "description": "The stages whose head did not merge cleanly into their own PR base. The probe runs per stage, so a bare path list cannot say which PR is affected.",
+              "items": {
+                "type": "integer",
+                "minimum": 1
+              }
+            },
             "conflictingPaths": {
               "type": "array",
               "items": {
@@ -1181,32 +1187,41 @@
             }
           }
         },
-        "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"
+        "pullRequestOutcomes": {
+          "type": "array",
+          "description": "One row per selected stage — one stage is one PR. A single outcome object cannot say which stage was created, reused or skipped.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "stage",
+              "kind"
+            ],
+            "properties": {
+              "stage": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "kind": {
+                "enum": [
+                  "no-action",
+                  "created",
+                  "reused",
+                  "skipped"
+                ]
+              },
+              "url": {
+                "type": "string"
+              },
+              "title": {
+                "type": "string"
+              },
+              "baseBranch": {
+                "type": "string"
+              },
+              "reason": {
+                "type": "string"
+              }
             }
           }
         },
@@ -1582,6 +1597,7 @@
               "enum": [
                 "release-handoff",
                 "release-handoff(stage-group)",
+                "final-verification",
                 "error-analysis",
                 "implementation-option-selection",
                 "implementation-planning",
@@ -9839,6 +9855,11 @@
       ],
       "additionalProperties": false,
       "properties": {
+        "stage": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Which stage's PR carries this commit. One stage is one PR, so a flat commit list across several stages cannot be attributed without it."
+        },
         "shortSha": {
           "type": "string",
           "minLength": 7