okstra 0.174.0 → 0.176.0

package/runtime/schemas/convergence-groups-v2.0.schema.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://okstra.dev/schemas/convergence-groups-v2.0.json",
+  "title": "OKSTRA Convergence Grouped Input (v2.0)",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "executionIdentityVersion",
+    "taskKey",
+    "runManifestPath",
+    "config",
+    "workers",
+    "groups"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": "2.0" },
+    "executionIdentityVersion": { "const": 2 },
+    "taskKey": { "type": "string", "pattern": "\\S" },
+    "runManifestPath": {
+      "type": "string",
+      "pattern": "^\\.okstra/(?!\\.{1,2}(?:/|$))(?!.*?/\\.{1,2}(?:/|$))[^/\\\\\\r\\n]+(?:/[^/\\\\\\r\\n]+)*$"
+    },
+    "config": { "$ref": "#/$defs/Config" },
+    "workers": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/Worker" }
+    },
+    "groups": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Group" }
+    }
+  },
+  "$defs": {
+    "Config": {
+      "type": "object",
+      "required": ["enabled", "adversarial", "maxRounds", "effectiveMaxRounds", "verificationMode"],
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "adversarial": { "type": "boolean" },
+        "maxRounds": { "type": "integer", "minimum": 1, "maximum": 3 },
+        "effectiveMaxRounds": { "type": "integer", "minimum": 1, "maximum": 3 },
+        "verificationMode": { "enum": ["lightweight", "full-reanalysis"] }
+      }
+    },
+    "Worker": {
+      "type": "object",
+      "required": [
+        "workerId",
+        "audience",
+        "participantRef",
+        "sourceRoleExecutionRef"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "workerId": { "type": "string", "pattern": "\\S" },
+        "audience": { "enum": ["analysis", "report-writer"] },
+        "participantRef": { "type": "string", "pattern": "\\S" },
+        "sourceRoleExecutionRef": { "type": "string", "pattern": "\\S" }
+      }
+    },
+    "Group": {
+      "type": "object",
+      "required": ["findingId", "summary", "category", "ticketIds", "originWorker", "originEvidence", "discoveredBy", "sourceItems"],
+      "additionalProperties": false,
+      "properties": {
+        "findingId": { "type": "string", "pattern": "\\S" },
+        "summary": { "type": "string", "pattern": "\\S" },
+        "category": { "type": "string", "pattern": "\\S" },
+        "ticketIds": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "\\S" }
+        },
+        "originWorker": { "type": "string", "pattern": "\\S" },
+        "originEvidence": { "type": "string", "pattern": "\\S" },
+        "evidenceArtifacts": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/EvidenceArtifact" }
+        },
+        "discoveredBy": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": { "$ref": "#/$defs/Discovery" }
+        },
+        "sourceItems": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/SourceItem" }
+        }
+      }
+    },
+    "EvidenceArtifact": {
+      "type": "object",
+      "required": ["path", "sha256", "command", "environment"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "pattern": "^\\.okstra/(?!\\.{1,2}(?:/|$))(?!.*?/\\.{1,2}(?:/|$))[^/\\\\\\r\\n]+(?:/[^/\\\\\\r\\n]+)*$"
+        },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "command": { "type": "string", "pattern": "\\S" },
+        "environment": { "type": "string", "pattern": "\\S" }
+      }
+    },
+    "Discovery": {
+      "type": "object",
+      "required": ["itemId", "evidence"],
+      "additionalProperties": false,
+      "properties": {
+        "itemId": { "type": "string", "pattern": "\\S" },
+        "evidence": { "type": "string", "pattern": "\\S" }
+      }
+    },
+    "SourceItem": {
+      "type": "object",
+      "required": ["worker", "itemId"],
+      "additionalProperties": false,
+      "properties": {
+        "worker": { "type": "string", "pattern": "\\S" },
+        "itemId": { "type": "string", "pattern": "\\S" }
+      }
+    }
+  }
+}

package/runtime/schemas/execution-manifest-v2.schema.json

@@ -0,0 +1,340 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://okstra.dev/schemas/execution-manifest-v2.json",
+  "title": "OKSTRA Execution Manifest (v2)",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "executionIdentityVersion",
+    "entryMode",
+    "participantAssignments",
+    "roleExecutions",
+    "invocations",
+    "attempts",
+    "attemptEvidenceSeals",
+    "mutationRecoveryDecisions"
+  ],
+  "properties": {
+    "schemaVersion": {"const": "2.0"},
+    "executionIdentityVersion": {"const": 2},
+    "entryMode": {"enum": ["current-session", "new-session"]},
+    "participantAssignments": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/ParticipantAssignment"}
+    },
+    "roleExecutions": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/RoleExecution"}
+    },
+    "invocations": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/Invocation"}
+    },
+    "attempts": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/Attempt"}
+    },
+    "attemptEvidenceSeals": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/AttemptEvidenceSeal"}
+    },
+    "mutationRecoveryDecisions": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/MutationRecoveryDecision"}
+    }
+  },
+  "additionalProperties": true,
+  "$defs": {
+    "Digest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "NullableDigest": {
+      "type": ["string", "null"],
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "WorkerWriteCapability": {
+      "type": ["object", "null"],
+      "required": ["maxBoundaryPrecision"],
+      "properties": {
+        "maxBoundaryPrecision": {
+          "enum": ["exact-path", "directory-boundary", "none"]
+        }
+      },
+      "additionalProperties": false
+    },
+    "ParticipantAssignment": {
+      "type": "object",
+      "required": [
+        "participantRef",
+        "provider",
+        "modelRef",
+        "modelId",
+        "runner",
+        "hostRuntime",
+        "hostModelValue",
+        "sessionRef",
+        "windowRef",
+        "workerWriteCapability",
+        "entryMode",
+        "status"
+      ],
+      "properties": {
+        "participantRef": {"type": "string", "pattern": "\\S"},
+        "provider": {"type": "string", "pattern": "\\S"},
+        "modelRef": {"type": ["string", "null"]},
+        "modelId": {"type": "string", "pattern": "\\S"},
+        "runner": {"type": "string", "pattern": "\\S"},
+        "hostRuntime": {"type": "string", "pattern": "\\S"},
+        "hostModelValue": {"type": ["string", "null"]},
+        "sessionRef": {"type": ["string", "null"]},
+        "windowRef": {"type": ["string", "null"]},
+        "workerWriteCapability": {"$ref": "#/$defs/WorkerWriteCapability"},
+        "entryMode": {"enum": ["current-session", "new-session"]},
+        "status": {"type": "string", "pattern": "\\S"}
+      },
+      "additionalProperties": false
+    },
+    "HostModelBinding": {
+      "type": ["object", "null"],
+      "required": [
+        "runner",
+        "catalogExecutionValue",
+        "resolvedExecutionValue",
+        "hostModelValue",
+        "bindingFidelity",
+        "workerWriteCapability"
+      ],
+      "properties": {
+        "runner": {"type": "string", "pattern": "\\S"},
+        "catalogExecutionValue": {"type": "string"},
+        "resolvedExecutionValue": {"type": "string"},
+        "hostModelValue": {"type": ["string", "null"]},
+        "bindingFidelity": {"enum": ["exact", "channel", "unsupported"]},
+        "workerWriteCapability": {"$ref": "#/$defs/WorkerWriteCapability"}
+      },
+      "additionalProperties": false
+    },
+    "ServedModelAttestation": {
+      "type": "object",
+      "required": ["observedModel", "normalizedModelRef", "level", "source"],
+      "properties": {
+        "observedModel": {"type": ["string", "null"]},
+        "normalizedModelRef": {"type": ["string", "null"]},
+        "level": {"enum": ["exact", "channel", "unknown"]},
+        "source": {
+          "enum": ["provider-output", "native-api", "cli-handoff", "unavailable"]
+        }
+      },
+      "additionalProperties": false
+    },
+    "WritePolicy": {
+      "type": "object",
+      "required": ["artifactPolicy", "sourcePolicy", "gitPolicy", "auxiliaryPolicy"],
+      "properties": {
+        "artifactPolicy": {
+          "type": "object",
+          "required": ["allowedRoot", "allowedPaths"],
+          "properties": {
+            "allowedRoot": {"type": "string", "pattern": "^/"},
+            "allowedPaths": {"type": "array", "items": {"type": "string", "pattern": "\\S"}, "minItems": 1, "uniqueItems": true}
+          },
+          "additionalProperties": false
+        },
+        "sourcePolicy": {
+          "type": "object",
+          "required": ["mode", "allowedRoot", "plannedPaths", "protectedPaths"],
+          "properties": {
+            "mode": {"enum": ["source-readonly", "project-mutation"]},
+            "allowedRoot": {"type": "string", "pattern": "^/"},
+            "plannedPaths": {"type": "array", "items": {"type": "string", "pattern": "\\S"}, "uniqueItems": true},
+            "protectedPaths": {"type": "array", "items": {"type": "string", "pattern": "\\S"}, "uniqueItems": true}
+          },
+          "additionalProperties": false
+        },
+        "gitPolicy": {
+          "type": "object",
+          "required": ["mode"],
+          "properties": {
+            "mode": {"enum": ["disabled", "fast-forward-descendant-chain"]},
+            "worktreeGitDir": {"type": "string", "pattern": "^/"},
+            "gitCommonDir": {"type": "string", "pattern": "^/"},
+            "expectedBaseCommit": {"type": "string", "pattern": "\\S"},
+            "allowedBranchRef": {"type": "string", "pattern": "^refs/heads/"},
+            "commitMode": {"const": "fast-forward-descendant-chain"}
+          },
+          "additionalProperties": false
+        },
+        "auxiliaryPolicy": {
+          "type": "object",
+          "required": ["scratchRoots", "generatedPaths", "externalRoots"],
+          "properties": {
+            "scratchRoots": {"type": "array", "items": {"type": "string", "pattern": "^/"}, "uniqueItems": true},
+            "generatedPaths": {"type": "array", "items": {"type": "string", "pattern": "\\S"}, "uniqueItems": true},
+            "externalRoots": {"type": "array", "items": {"type": "string", "pattern": "^/"}, "uniqueItems": true}
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "WriteEnforcement": {
+      "type": "object",
+      "required": ["boundaryPrecision", "mutationAudit", "attribution", "auditedRoots", "observationCoverage", "unobservedWriteSurfaces"],
+      "properties": {
+        "boundaryPrecision": {"enum": ["exact-path", "directory-boundary", "none"]},
+        "mutationAudit": {"enum": ["none", "batch"]},
+        "attribution": {"enum": ["call", "batch-unattributed"]},
+        "auditedRoots": {"type": "array", "items": {"type": "string", "pattern": "^/"}, "minItems": 1, "uniqueItems": true},
+        "observationCoverage": {"enum": ["complete", "scoped", "partial"]},
+        "unobservedWriteSurfaces": {"type": "array", "items": {"type": "string", "pattern": "\\S"}, "uniqueItems": true}
+      },
+      "additionalProperties": false
+    },
+    "RoleExecution": {
+      "type": "object",
+      "required": [
+        "roleExecutionRef",
+        "participantRef",
+        "sourceRoleExecutionRef",
+        "role",
+        "provider",
+        "modelRef",
+        "modelId",
+        "ordinal",
+        "executionLabel",
+        "modelSpecDigest",
+        "binding",
+        "servedModelAttestation",
+        "status"
+      ],
+      "properties": {
+        "roleExecutionRef": {"type": "string", "pattern": "\\S"},
+        "participantRef": {"type": "string", "pattern": "\\S"},
+        "sourceRoleExecutionRef": {"type": ["string", "null"]},
+        "role": {"type": "string", "pattern": "\\S"},
+        "provider": {"type": "string", "pattern": "\\S"},
+        "modelRef": {"type": ["string", "null"]},
+        "modelId": {"type": "string", "pattern": "\\S"},
+        "ordinal": {"type": "integer", "minimum": 1},
+        "executionLabel": {"type": "string", "pattern": "\\S"},
+        "modelSpecDigest": {"$ref": "#/$defs/NullableDigest"},
+        "binding": {"$ref": "#/$defs/HostModelBinding"},
+        "servedModelAttestation": {"$ref": "#/$defs/ServedModelAttestation"},
+        "status": {"type": "string", "pattern": "\\S"}
+      },
+      "additionalProperties": false
+    },
+    "Invocation": {
+      "type": "object",
+      "required": [
+        "invocationRef",
+        "participantRef",
+        "roleExecutionRef",
+        "sourceInvocationRef",
+        "recoveryRef",
+        "dutyId",
+        "dispatchKind",
+        "round",
+        "inputDigest",
+        "writePolicy",
+        "writePolicyDigest",
+        "writeEnforcement"
+      ],
+      "properties": {
+        "invocationRef": {"type": "string", "pattern": "\\S"},
+        "participantRef": {"type": "string", "pattern": "\\S"},
+        "roleExecutionRef": {"type": "string", "pattern": "\\S"},
+        "sourceInvocationRef": {"type": ["string", "null"]},
+        "recoveryRef": {"type": ["string", "null"]},
+        "dutyId": {"type": "string", "pattern": "\\S"},
+        "dispatchKind": {"type": "string", "pattern": "\\S"},
+        "round": {"type": "integer", "minimum": 1},
+        "inputDigest": {"$ref": "#/$defs/Digest"},
+        "writePolicy": {"$ref": "#/$defs/WritePolicy"},
+        "writePolicyDigest": {"$ref": "#/$defs/Digest"},
+        "writeEnforcement": {"$ref": "#/$defs/WriteEnforcement"}
+      },
+      "additionalProperties": false
+    },
+    "Attempt": {
+      "type": "object",
+      "required": [
+        "invocationRef",
+        "attempt",
+        "startedAt",
+        "finishedAt",
+        "status",
+        "resultPath",
+        "errorPath",
+        "changeSummary",
+        "evidenceSealRef"
+      ],
+      "properties": {
+        "invocationRef": {"type": "string", "pattern": "\\S"},
+        "attempt": {"type": "integer", "minimum": 1},
+        "startedAt": {"type": "string", "pattern": "\\S"},
+        "finishedAt": {"type": ["string", "null"]},
+        "status": {"type": "string", "pattern": "\\S"},
+        "resultPath": {"type": ["string", "null"]},
+        "errorPath": {"type": ["string", "null"]},
+        "changeSummary": {"type": "object"},
+        "evidenceSealRef": {"type": ["string", "null"]}
+      },
+      "additionalProperties": false
+    },
+    "AttemptEvidenceSeal": {
+      "type": "object",
+      "required": [
+        "sealRef",
+        "attemptRef",
+        "capturedAt",
+        "sourceDiffDigest",
+        "gitProjectionDigest",
+        "changedPaths",
+        "hostEventStream",
+        "artifacts"
+      ],
+      "properties": {
+        "sealRef": {"type": "string", "pattern": "\\S"},
+        "attemptRef": {"type": "string", "pattern": "\\S"},
+        "capturedAt": {"type": "string", "pattern": "\\S"},
+        "sourceDiffDigest": {"$ref": "#/$defs/Digest"},
+        "gitProjectionDigest": {"$ref": "#/$defs/Digest"},
+        "changedPaths": {"type": "array", "items": {"type": "string"}},
+        "hostEventStream": {"type": "object"},
+        "hostEventStreamRef": {"type": ["string", "null"]},
+        "artifacts": {"type": "array", "items": {"type": "object"}}
+      },
+      "additionalProperties": true
+    },
+    "MutationRecoveryDecision": {
+      "type": "object",
+      "required": [
+        "recoveryRef",
+        "sourceInvocationRef",
+        "sourceAttemptRef",
+        "decision"
+      ],
+      "properties": {
+        "recoveryRef": {"type": "string", "pattern": "\\S"},
+        "sourceInvocationRef": {"type": "string"},
+        "sourceAttemptRef": {"type": "string"},
+        "sourceEvidenceSealRef": {"type": ["string", "null"]},
+        "originalBaselineDigest": {"type": "string"},
+        "terminalSourceDiffDigest": {"type": "string"},
+        "terminalGitChainDigest": {"type": "string"},
+        "verifierRoleExecutionRef": {"type": ["string", "null"]},
+        "verifierInvocationRef": {"type": ["string", "null"]},
+        "recoveredEvidenceRefs": {"type": "array"},
+        "recoveredOutOfPlanEdits": {"type": "array"},
+        "unmetObligations": {"type": "array", "items": {"type": "string"}},
+        "decision": {
+          "enum": ["carry-forward", "reject", "cleanup-confirmed"]
+        },
+        "reason": {"type": "string"}
+      },
+      "additionalProperties": true
+    }
+  }
+}

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

@@ -29,6 +29,31 @@
       "const": "2.0",
       "description": "Schema version. Renderer refuses to process unknown versions."
     },
+    "executionIdentityVersion": {
+      "type": "integer",
+      "enum": [1, 2]
+    },
+    "executionRoles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "roleExecutionRef",
+          "role",
+          "executionLabel"
+        ],
+        "properties": {
+          "roleExecutionRef": {"type": "string"},
+          "role": {"type": "string"},
+          "provider": {"type": "string"},
+          "modelRef": {"type": ["string", "null"]},
+          "ordinal": {"type": "integer"},
+          "executionLabel": {"type": "string"},
+          "status": {"type": "string"}
+        },
+        "additionalProperties": true
+      }
+    },
     "humanSummary": {
       "$ref": "#/$defs/HumanSummary"
     },
@@ -1350,8 +1375,26 @@
           }
         },
         "routingRecommendation": {
-          "type": "string",
-          "minLength": 1
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "target",
+            "rationale"
+          ],
+          "properties": {
+            "target": {
+              "enum": [
+                "final-verification",
+                "error-analysis",
+                "implementation-planning",
+                "implementation"
+              ]
+            },
+            "rationale": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
         },
         "userNarrative": {
           "$ref": "#/$defs/ImplementationUserNarrative"
@@ -1503,9 +1546,29 @@
           }
         },
         "routingRecommendation": {
-          "type": "string",
-          "minLength": 1,
-          "pattern": "(^|[^A-Za-z-])(release-handoff\\(stage-group\\)|release-handoff|done|implementation|error-analysis|implementation-option-selection|implementation-planning)([^A-Za-z-]|$)"
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "target",
+            "rationale"
+          ],
+          "properties": {
+            "target": {
+              "enum": [
+                "release-handoff",
+                "release-handoff(stage-group)",
+                "error-analysis",
+                "implementation-option-selection",
+                "implementation-planning",
+                "implementation",
+                "done"
+              ]
+            },
+            "rationale": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
         },
         "userNarrative": {
           "$ref": "#/$defs/FinalVerificationUserNarrative"

package/runtime/skills/okstra-inspect/facets/recap.md

@@ -24,6 +24,8 @@ okstra recap assemble <resolved-target> --project-root <projectRoot>
 
 Parse the stdout JSON (`{taskKey, runCount, transitions[], latestPhaseStates}`) and narrate the per-run before/after transitions. For each `transitions[]` entry, show `fromPhase → toPhase` (previous run currentPhase → this run currentPhase), `status`, `lastCompletedPhase`, `nextRecommendedPhase`, and `reportPath` in chronological order. If `runCount == 0`, answer only "This task has no recorded runs." and do not claim to have read any file.
 
+`nextRecommendedPhase` in each entry is an **object** `{phase, status, rationale}`, not a phase-name string. Narrate it as `phase` when `phase` is non-empty, and as what `status` says otherwise — `pending` (that run did not settle the route), `blocked` (it stopped on something outside the run), `terminal` (the lifecycle ended there). Printing the object itself puts a raw dict in front of the reader.
+
 For a run that has a `reportPath`, read that final-report to enrich the summary only when the user wants a deeper one (do not read them all automatically).
 
 ### recap.3 — Free-form Q&A loop

package/runtime/skills/okstra-inspect/facets/report.md

@@ -27,7 +27,7 @@ D. **Specific task-type (fallback):** `latestReportPath` is task-type-agnostic.
 1. Verify `latestReportPath` is non-empty AND the file exists on disk. Either signal indicates report presence (tolerant).
 2. If present, display the path and ask the user whether to read it.
 3. If absent, check `task-manifest.json` signals:
-   - `latestReportPath` empty/missing AND `currentStatus != completed` AND `workStatus != done` AND `workflow.routingStatus` not completion-like → `This task is not yet complete (currentStatus: <currentStatus>, workStatus: <workStatus>).`
+   - `latestReportPath` empty/missing AND `currentStatus != completed` AND `workStatus != done` AND `workflow.nextRecommendedPhase.status != "terminal"` → `This task is not yet complete (currentStatus: <currentStatus>, workStatus: <workStatus>).`
    - Any signal indicates completion but the file is missing → `Report file does not exist: <path>`
 
 `workStatus` enum: `todo | in-progress | blocked | done`. `currentStatus`: `completed` / `contract-violated` etc. `"completed"` string does NOT exist in `workStatus` — do not confuse the two.