okstra 0.122.0 → 0.124.0

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

@@ -408,6 +408,7 @@
           "minItems": 1,
           "items": { "$ref": "#/$defs/ImplementationPlanStage" }
         },
+        "designPreparation": { "$ref": "#/$defs/DesignPreparation" },
         "stepwiseExecution": {
           "description": "Legacy flat summary kept for compatibility only. New reports use stageMap/stages.",
           "type": "array",
@@ -1296,6 +1297,337 @@
       }
     },
 
+    "DesignPreparation": {
+      "type": "object",
+      "required": ["mode", "reason", "items"],
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "enum": ["assessed", "no-design-inputs"] },
+        "reason": { "type": "string", "minLength": 1 },
+        "items": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/DesignPrepItem" }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "mode": { "const": "no-design-inputs" } }
+          },
+          "then": { "properties": { "items": { "maxItems": 0 } } }
+        }
+      ]
+    },
+
+    "DesignPrepKnownFact": {
+      "type": "object",
+      "required": ["statement", "evidence"],
+      "additionalProperties": false,
+      "properties": {
+        "statement": { "type": "string", "minLength": 1 },
+        "evidence": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "DesignPrepProposal": {
+      "type": "object",
+      "required": ["summary", "details", "assumptions", "evidence", "confidence"],
+      "additionalProperties": false,
+      "properties": {
+        "summary": { "type": "string", "minLength": 1 },
+        "details": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "assumptions": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "evidence": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "confidence": { "enum": ["low", "medium", "high"] }
+      }
+    },
+
+    "DesignPrepHumanConfirmation": {
+      "type": "object",
+      "required": ["required", "reason", "suggestedAction"],
+      "additionalProperties": false,
+      "properties": {
+        "required": { "type": "boolean" },
+        "reason": { "type": "string", "minLength": 1 },
+        "suggestedAction": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "DesignPrepReviewPoint": {
+      "type": "object",
+      "required": ["phase"],
+      "additionalProperties": false,
+      "properties": {
+        "phase": { "enum": ["implementation", "final-verification"] },
+        "stage": { "type": "integer", "minimum": 1 }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "phase": { "const": "implementation" } } },
+          "then": { "required": ["stage"] }
+        }
+      ]
+    },
+
+    "DesignPrepItem": {
+      "type": "object",
+      "required": [
+        "id",
+        "kind",
+        "title",
+        "stageRefs",
+        "status",
+        "need",
+        "knownFacts",
+        "openQuestions",
+        "aiProposal",
+        "humanConfirmation"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^PREP-[0-9]{3}$" },
+        "kind": {
+          "enum": [
+            "domain-contract",
+            "persistence-schema",
+            "external-interface",
+            "transaction-consistency",
+            "transformation-mapping",
+            "lifecycle-state-machine",
+            "rollout-observability",
+            "manual-user-test",
+            "other"
+          ]
+        },
+        "title": { "type": "string", "minLength": 1 },
+        "stageRefs": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "integer", "minimum": 1 }
+        },
+        "status": {
+          "enum": ["ready", "provisional", "blocked", "not-applicable"]
+        },
+        "need": { "type": "string", "minLength": 1 },
+        "knownFacts": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/DesignPrepKnownFact" }
+        },
+        "openQuestions": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "aiProposal": { "$ref": "#/$defs/DesignPrepProposal" },
+        "humanConfirmation": {
+          "$ref": "#/$defs/DesignPrepHumanConfirmation"
+        },
+        "workingAssumption": { "type": "string", "minLength": 1 },
+        "guardrails": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "reviewAt": { "$ref": "#/$defs/DesignPrepReviewPoint" },
+        "ifStillOpen": { "enum": ["block", "follow-up"] },
+        "requestPath": {
+          "type": "string",
+          "pattern": "^design-prep-requests/design-prep-request-[0-9]+-PREP-[0-9]{3}\\.md$"
+        },
+        "blockReason": { "type": "string", "minLength": 1 },
+        "requiredDecision": { "type": "string", "minLength": 1 },
+        "notApplicableReason": { "type": "string", "minLength": 1 },
+        "replanTriggerFields": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[^.\\s]+(\\.[^.\\s]+)*$"
+          }
+        }
+      },
+      "oneOf": [
+        {
+          "properties": { "status": { "const": "ready" } },
+          "allOf": [
+            { "not": { "required": ["workingAssumption"] } },
+            { "not": { "required": ["blockReason"] } },
+            { "not": { "required": ["requiredDecision"] } },
+            { "not": { "required": ["notApplicableReason"] } },
+            { "not": { "required": ["requestPath"] } }
+          ]
+        },
+        {
+          "properties": { "status": { "const": "provisional" } },
+          "required": [
+            "workingAssumption",
+            "guardrails",
+            "reviewAt",
+            "ifStillOpen",
+            "requestPath"
+          ],
+          "allOf": [
+            { "not": { "required": ["blockReason"] } },
+            { "not": { "required": ["requiredDecision"] } },
+            { "not": { "required": ["notApplicableReason"] } }
+          ]
+        },
+        {
+          "properties": {
+            "status": { "const": "blocked" },
+            "humanConfirmation": {
+              "properties": { "required": { "const": true } }
+            }
+          },
+          "required": [
+            "blockReason",
+            "requiredDecision",
+            "reviewAt",
+            "ifStillOpen",
+            "requestPath"
+          ],
+          "allOf": [
+            { "not": { "required": ["workingAssumption"] } },
+            { "not": { "required": ["guardrails"] } },
+            { "not": { "required": ["notApplicableReason"] } }
+          ]
+        },
+        {
+          "properties": { "status": { "const": "not-applicable" } },
+          "required": ["notApplicableReason"],
+          "allOf": [
+            { "not": { "required": ["workingAssumption"] } },
+            { "not": { "required": ["guardrails"] } },
+            { "not": { "required": ["reviewAt"] } },
+            { "not": { "required": ["ifStillOpen"] } },
+            { "not": { "required": ["blockReason"] } },
+            { "not": { "required": ["requiredDecision"] } },
+            { "not": { "required": ["requestPath"] } }
+          ]
+        }
+      ]
+    },
+
+    "TriggerEvidence": {
+      "type": "object",
+      "required": ["step", "field", "match"],
+      "additionalProperties": false,
+      "properties": {
+        "step": {
+          "type": ["integer", "null"],
+          "minimum": 1
+        },
+        "field": { "enum": ["files", "action"] },
+        "match": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "InlineDesignContract": {
+      "type": "object",
+      "required": ["summary", "details", "evidence"],
+      "additionalProperties": false,
+      "properties": {
+        "summary": { "type": "string", "minLength": 1 },
+        "details": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "evidence": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+
+    "DesignSurfaceCoverage": {
+      "type": "object",
+      "required": ["kind", "triggerEvidence", "disposition"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "enum": [
+            "domain-contract",
+            "persistence-schema",
+            "external-interface",
+            "transaction-consistency",
+            "transformation-mapping",
+            "lifecycle-state-machine",
+            "rollout-observability",
+            "manual-user-test",
+            "other"
+          ]
+        },
+        "triggerEvidence": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/TriggerEvidence" }
+        },
+        "disposition": {
+          "enum": ["inline-contract", "prep-item", "not-applicable"]
+        },
+        "inlineContract": { "$ref": "#/$defs/InlineDesignContract" },
+        "prepItemId": {
+          "type": "string",
+          "pattern": "^PREP-[0-9]{3}$"
+        },
+        "prepItemIds": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^PREP-[0-9]{3}$" }
+        },
+        "rationale": { "type": "string", "minLength": 1 }
+      },
+      "oneOf": [
+        {
+          "properties": { "disposition": { "const": "inline-contract" } },
+          "required": ["inlineContract"],
+          "allOf": [
+            { "not": { "required": ["prepItemId"] } },
+            { "not": { "required": ["prepItemIds"] } },
+            { "not": { "required": ["rationale"] } }
+          ]
+        },
+        {
+          "properties": { "disposition": { "const": "prep-item" } },
+          "allOf": [
+            { "not": { "required": ["inlineContract"] } },
+            { "not": { "required": ["rationale"] } }
+          ],
+          "oneOf": [
+            {
+              "required": ["prepItemId"],
+              "not": { "required": ["prepItemIds"] }
+            },
+            {
+              "required": ["prepItemIds"],
+              "not": { "required": ["prepItemId"] }
+            }
+          ]
+        },
+        {
+          "properties": { "disposition": { "const": "not-applicable" } },
+          "required": ["rationale"],
+          "allOf": [
+            { "not": { "required": ["inlineContract"] } },
+            { "not": { "required": ["prepItemId"] } },
+            { "not": { "required": ["prepItemIds"] } }
+          ]
+        }
+      ]
+    },
+
     "ImplementationPlanStage": {
       "type": "object",
       "required": [
@@ -1364,6 +1696,10 @@
           "maxItems": 6,
           "items": { "$ref": "#/$defs/StageStepRow" }
         },
+        "designSurfaceCoverage": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/DesignSurfaceCoverage" }
+        },
         "exitContract": { "type": "string", "minLength": 1 },
         "stageValidation": { "type": "string", "minLength": 1 }
       }

package/runtime/skills/_fragments/bash-invocation-rule.md

@@ -0,0 +1 @@
+Run one Bash tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):

package/runtime/skills/_fragments/preflight-outdated-cli.md

@@ -0,0 +1 @@
+If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).

package/runtime/skills/_fragments/python-bootstrap-note.md

@@ -0,0 +1 @@
+Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.