@starci/skills 1.1.0 → 1.2.0

package/templates/kinds/mutations.schema.json

@@ -1,65 +1,65 @@
-{
-  "$id": "kind:mutations",
-  "title": "Every mutation one source-writing step made or planned, the contract it filled, and the single commit that carries them on the session branch; under mode dry the commit is null and the record is a plan.",
-  "type": "object",
-  "additionalProperties": false,
-  "required": ["mode", "contractFingerprint", "base", "branch", "commit", "operations", "changes"],
-  "properties": {
-    "mode": { "enum": ["apply", "dry"] },
-    "contractFingerprint": { "$ref": "#/$defs/hash" },
-    "base": { "$ref": "#/$defs/gitHead" },
-    "branch": { "type": "string", "pattern": "^session/[A-Za-z0-9._-]+$" },
-    "commit": { "$ref": "#/$defs/nullableGitHead" },
-    "operations": {
-      "type": "array",
-      "minItems": 1,
-      "maxItems": 64,
-      "items": { "$ref": "#/$defs/operation" }
-    },
-    "changes": {
-      "type": "array",
-      "minItems": 1,
-      "maxItems": 256,
-      "items": { "$ref": "#/$defs/change" }
-    }
-  },
-  "$defs": {
-    "hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
-    "nullableHash": { "oneOf": [{ "$ref": "#/$defs/hash" }, { "type": "null" }] },
-    "gitHead": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
-    "nullableGitHead": { "oneOf": [{ "$ref": "#/$defs/gitHead" }, { "type": "null" }] },
-    "identifier": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
-    "facet": { "enum": ["transport", "writer", "store", "transaction", "idempotency", "migration", "exception-identity", "authorization", "concurrency"] },
-    "proofKind": { "enum": ["unit", "integration", "migration-replay", "conformance-read", "runtime-probe"] },
-    "operation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["operationId", "name", "transport", "writerRef", "storeRefs", "transactionBoundary", "idempotencyKind", "migrationRefs", "authorityDecisionIds", "facets", "proofKinds"],
-      "properties": {
-        "operationId": { "$ref": "#/$defs/identifier" },
-        "name": { "type": "string", "minLength": 1, "maxLength": 256 },
-        "transport": { "enum": ["graphql-mutation", "graphql-query", "rest", "worker", "cron", "event-consumer"] },
-        "writerRef": { "type": "string", "minLength": 1, "maxLength": 1024 },
-        "storeRefs": { "type": "array", "maxItems": 64, "items": { "type": "string", "minLength": 1 } },
-        "transactionBoundary": { "enum": ["single-transaction", "per-item", "read-only", "none"] },
-        "idempotencyKind": { "enum": ["none", "natural-key", "request-token", "event-id"] },
-        "migrationRefs": { "type": "array", "maxItems": 64, "items": { "type": "string", "minLength": 1 } },
-        "authorityDecisionIds": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "type": "string", "pattern": "^BA-[0-9]+$" } },
-        "facets": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/$defs/facet" } },
-        "proofKinds": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/$defs/proofKind" } }
-      }
-    },
-    "change": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["path", "change", "operationId", "beforeHash", "afterHash"],
-      "properties": {
-        "path": { "type": "string", "minLength": 1, "maxLength": 1024 },
-        "change": { "enum": ["added", "modified", "deleted"] },
-        "operationId": { "$ref": "#/$defs/identifier" },
-        "beforeHash": { "$ref": "#/$defs/nullableHash" },
-        "afterHash": { "$ref": "#/$defs/nullableHash" }
-      }
-    }
-  }
-}
+{
+  "$id": "kind:mutations",
+  "title": "Every mutation one source-writing step made or planned, the contract it filled, and the single commit that carries them on the session branch; under mode dry the commit is null and the record is a plan.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["mode", "contractFingerprint", "base", "branch", "commit", "operations", "changes"],
+  "properties": {
+    "mode": { "enum": ["apply", "dry"] },
+    "contractFingerprint": { "$ref": "#/$defs/hash" },
+    "base": { "$ref": "#/$defs/gitHead" },
+    "branch": { "type": "string", "pattern": "^session/[A-Za-z0-9._-]+$" },
+    "commit": { "$ref": "#/$defs/nullableGitHead" },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 64,
+      "items": { "$ref": "#/$defs/operation" }
+    },
+    "changes": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 256,
+      "items": { "$ref": "#/$defs/change" }
+    }
+  },
+  "$defs": {
+    "hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "nullableHash": { "oneOf": [{ "$ref": "#/$defs/hash" }, { "type": "null" }] },
+    "gitHead": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "nullableGitHead": { "oneOf": [{ "$ref": "#/$defs/gitHead" }, { "type": "null" }] },
+    "identifier": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "facet": { "enum": ["transport", "writer", "store", "transaction", "idempotency", "migration", "exception-identity", "authorization", "concurrency"] },
+    "proofKind": { "enum": ["unit", "integration", "migration-replay", "conformance-read", "runtime-probe"] },
+    "operation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["operationId", "name", "transport", "writerRef", "storeRefs", "transactionBoundary", "idempotencyKind", "migrationRefs", "authorityDimensionIds", "facets", "proofKinds"],
+      "properties": {
+        "operationId": { "$ref": "#/$defs/identifier" },
+        "name": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "transport": { "enum": ["graphql-mutation", "graphql-query", "rest", "worker", "cron", "event-consumer"] },
+        "writerRef": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "storeRefs": { "type": "array", "maxItems": 64, "items": { "type": "string", "minLength": 1 } },
+        "transactionBoundary": { "enum": ["single-transaction", "per-item", "read-only", "none"] },
+        "idempotencyKind": { "enum": ["none", "natural-key", "request-token", "event-id"] },
+        "migrationRefs": { "type": "array", "maxItems": 64, "items": { "type": "string", "minLength": 1 } },
+        "authorityDimensionIds": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" } },
+        "facets": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/$defs/facet" } },
+        "proofKinds": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/$defs/proofKind" } }
+      }
+    },
+    "change": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "change", "operationId", "beforeHash", "afterHash"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "change": { "enum": ["added", "modified", "deleted"] },
+        "operationId": { "$ref": "#/$defs/identifier" },
+        "beforeHash": { "$ref": "#/$defs/nullableHash" },
+        "afterHash": { "$ref": "#/$defs/nullableHash" }
+      }
+    }
+  }
+}

package/templates/kinds/route.schema.json

@@ -34,10 +34,12 @@
       "minLength": 1
     },
     "routeFingerprint": {
-      "$ref": "#/$defs/fingerprint"
+      "$ref": "#/$defs/fingerprint",
+      "description": "sha256 over the bytes of the portable declaration followed by the bytes of the hydrated route, each exactly as stored on disk, with no normalisation."
     },
     "identityFingerprint": {
-      "$ref": "#/$defs/fingerprint"
+      "$ref": "#/$defs/fingerprint",
+      "description": "sha256 over the bytes of .workspaces/device-state.json, exactly as stored on disk, with no normalisation."
     },
     "sourceHead": {
       "$ref": "#/$defs/gitHead"

package/templates/kinds/stack-model.schema.json

@@ -2,7 +2,7 @@
   "$id": "kind:stack-model",
   "type": "object",
   "additionalProperties": false,
-  "required": ["decisionId", "selectedAlternativeId", "alternatives", "boundaries", "stores", "components"],
+  "required": ["decisionId", "selectedAlternativeId", "alternatives", "boundaries", "stores", "components", "operations"],
   "$defs": {
     "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
     "verdict": {
@@ -70,6 +70,28 @@
         }
       }
     },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 64,
+      "description": "One row per write this decision commits to. The implementation restates these unchanged as the operations of its mutation record; it may not add one, and it may not choose its own writer.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["operationId", "name", "transport", "writerRef", "storeRefs", "transactionBoundary", "idempotencyKind", "migrationRefs", "authorityDimensionIds"],
+        "properties": {
+          "operationId": { "$ref": "#/$defs/id" },
+          "name": { "type": "string", "minLength": 1, "maxLength": 256 },
+          "transport": { "enum": ["graphql-mutation", "graphql-query", "rest", "worker", "cron", "event-consumer"] },
+          "writerRef": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "The one file path this operator names: the implementation may not choose its own writer." },
+          "storeRefs": { "type": "array", "maxItems": 64, "items": { "type": "string", "minLength": 1 } },
+          "transactionBoundary": { "enum": ["single-transaction", "per-item", "read-only", "none"] },
+          "idempotencyKind": { "enum": ["none", "natural-key", "request-token", "event-id"] },
+          "migrationRefs": { "type": "array", "maxItems": 64, "items": { "type": "string", "minLength": 1 } },
+          "authorityDimensionIds": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "$ref": "#/$defs/id" }, "description": "The coverage-matrix dimensions of the bound business head this operation implements." }
+        }
+      }
+    },
     "components": {
       "type": "array",
       "minItems": 1,

package/templates/kinds/workspace-route-binding.contract.json

@@ -5,8 +5,8 @@
     { "heading": "^## Binding$", "table": "| Field | Value |", "rows": ["Project", "Role", "Portable route", "Hydrated route", "Source head"], "cell": { "Value": "\\S" } },
     { "heading": "^## Checkout$", "table": "| Field | Value |", "rows": ["Disk path", "Git root", "Git repository", "Branch", "Repository kind", "Directory", "Source head", "Mutation readiness", "Businesses root"], "cell": { "Value": "\\S" } },
     { "heading": "^## Policy$", "table": "| Field | Value |", "rows": ["Worktree branches", "Mutation branch"], "cell": { "Value": "\\S" } },
-    { "heading": "^## Write roots$", "table": "| Path | Why |", "minRows": 1, "cell": { "Path": "\\S", "Why": "\\S" } },
+    { "heading": "^## Write roots$", "table": "| Path | Why |", "cell": { "Path": "\\S", "Why": "\\S" } },
     { "heading": "^## Runtime$", "table": "| Field | Value |", "cell": { "Value": "\\S" } },
-    { "heading": "^## Findings$", "table": "| Code | Subject | Statement |", "minRows": 1, "cell": { "Code": "^`(ROUTE_HYDRATED_FROM_PORTABLE|RUNTIME_CONSUMED_NOT_OWNED|IDENTITY_ROSTER_SEALED|PROVENANCE_HEAD_BOUND|CACHED_ROUTE_REUSED|WORKTREE_BRANCH_FORBIDDEN)`$", "Subject": "\\S", "Statement": "\\S" } }
+    { "heading": "^## Findings$", "table": "| Code | Subject | Statement |", "minRows": 1, "cell": { "Code": "^`(ROUTE_HYDRATED_FROM_PORTABLE|RUNTIME_CONSUMED_NOT_OWNED|IDENTITY_ROSTER_SEALED|PROVENANCE_HEAD_BOUND|CACHED_ROUTE_REUSED|WORKTREE_BRANCH_FORBIDDEN|WORKTREE_BRANCH_SESSION_ONLY)`$", "Subject": "\\S", "Statement": "\\S" } }
   ]
 }

package/templates/step/response.schema.json

@@ -109,6 +109,16 @@
       "minLength": 1,
       "maxLength": 2000,
       "description": "One paragraph for a person: why the branch blocked or waits, when the kind files could not be written"
+    },
+    "boundProfile": {
+      "type": "string",
+      "pattern": "^[a-z][a-z-]*$",
+      "description": "The profile operator.json binds; recorded with ranProfile when the processor ran a stand-in (resources/orchestrator.json#profileEquivalents)"
+    },
+    "ranProfile": {
+      "type": "string",
+      "pattern": "^[a-z][a-z-]*$",
+      "description": "The profile that actually ran the branch"
     }
   },
   "allOf": [

package/templates/step/state.schema.json

@@ -0,0 +1,205 @@
+{
+  "$id": "step:state",
+  "description": "state.json at the session root; the orchestrator writes it, no agent does. Documented in resources/orchestrator.json#session.manifest.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "project",
+    "startedAt",
+    "status",
+    "chain",
+    "steps",
+    "requestHashes"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "project": {
+      "type": "string",
+      "minLength": 1
+    },
+    "workflow": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "startedAt": {
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "enum": [
+        "running",
+        "blocked",
+        "done",
+        "stopped"
+      ]
+    },
+    "chain": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "array",
+        "minItems": 1,
+        "items": {
+          "type": "string",
+          "pattern": "^[0-9]+/[0-9]+$"
+        }
+      }
+    },
+    "steps": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string",
+        "pattern": "^[a-z]+(?:\\.[a-z]+)+$"
+      }
+    },
+    "current": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "pattern": "^[0-9]+/[0-9]+$"
+    },
+    "leases": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "agent",
+          "holds"
+        ],
+        "properties": {
+          "agent": {
+            "type": "string"
+          },
+          "holds": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "requestHashes": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string",
+        "pattern": "^sha256:[0-9a-f]{64}$"
+      }
+    },
+    "resumes": {
+      "description": "branch \"N/M\" that re-enters a blocked branch: which one, and the stop it answered",
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "resumes",
+          "stop"
+        ],
+        "properties": {
+          "resumes": {
+            "type": "string",
+            "pattern": "^[0-9]+/[0-9]+$"
+          },
+          "stop": {
+            "type": "string",
+            "pattern": "^[A-Z][A-Z0-9_]+$"
+          }
+        }
+      }
+    },
+    "stoppedAt": {
+      "description": "where the session ended: a terminating stop, a response that failed a validator (stop null), or a person",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "branch",
+        "operator",
+        "stop",
+        "why"
+      ],
+      "properties": {
+        "branch": {
+          "type": "string",
+          "pattern": "^[0-9]+/[0-9]+$"
+        },
+        "operator": {
+          "type": "string"
+        },
+        "stop": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[A-Z][A-Z0-9_]+$"
+        },
+        "domain": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "route": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "why": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "substitutions": {
+      "description": "codes the orchestrator read as UNKNOWN_STOP: branch -> the code the agent wrote",
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "transitions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "at",
+          "branch",
+          "event"
+        ],
+        "properties": {
+          "at": {
+            "type": "string"
+          },
+          "branch": {
+            "type": "string",
+            "pattern": "^[0-9]+/[0-9]+(?:/[a-z][a-z-]*)?$"
+          },
+          "event": {
+            "enum": [
+              "dispatched",
+              "waiting",
+              "resumed",
+              "done",
+              "blocked",
+              "invalid",
+              "resolved"
+            ]
+          },
+          "note": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/workflows/README.md

@@ -11,6 +11,9 @@ How the entry uses them:
 2. If none matches, compose a chain from the operators' `## Next` tables and `routing.json`, under the
    same rules `scripts/validate-workflows.mjs` enforces on these files:
    - every branch names a real operator and presets only fields that operator declares;
+   - every Requirements field with no Default is either preset or listed under the branch's `asks`, so a
+     chain says up front which fields the entry must take from the mission scope or ask a person for
+     before that branch starts;
    - every required Input of a branch is produced by an earlier step;
    - branches of one step share no write alias (two operators may not write the same checkout or
      root at once; `frontend.surface.audit` fans out by matrix entry because it writes nothing);

package/workflows/README.vi.md

@@ -11,6 +11,9 @@ Cửa vào dùng chúng như sau:
 2. Không khớp cái nào thì tự ghép chuỗi từ bảng `## Next` của các operator và `routing.json`, theo
    đúng luật mà `scripts/validate-workflows.mjs` ép lên các file này:
    - mỗi nhánh gọi tên một operator có thật và chỉ preset field mà operator đó khai;
+   - mọi field Requirements không có Default thì hoặc được preset, hoặc nằm trong `asks` của nhánh, để
+     chuỗi nói trước những field nào cửa vào phải lấy từ phạm vi nhiệm vụ hay hỏi người trước khi nhánh
+     đó chạy;
    - mọi Input bắt buộc của một nhánh phải do một bậc trước sinh ra;
    - các nhánh cùng bậc không chung alias ghi (hai operator không được cùng ghi một checkout hay một
      root; `frontend.surface.audit` toả theo entry của matrix vì nó không ghi gì);

package/workflows/backend-feature.json

@@ -19,7 +19,11 @@
         "operator": "business.decide",
         "requirements": {
           "mode": "model"
-        }
+        },
+        "asks": [
+          "featureId",
+          "targetState"
+        ]
       }
     ],
     [
@@ -28,12 +32,21 @@
         "requirements": {
           "alternatives": 1,
           "selectionPolicy": "automatic"
-        }
+        },
+        "asks": [
+          "objective",
+          "constraints"
+        ]
       }
     ],
     [
       {
-        "operator": "backend.source.apply"
+        "operator": "backend.source.apply",
+        "asks": [
+          "featureId",
+          "outcome",
+          "mutableFileRefs"
+        ]
       }
     ],
     [
@@ -46,12 +59,20 @@
         "operator": "business.decide",
         "requirements": {
           "mode": "reconcile"
-        }
+        },
+        "asks": [
+          "featureId",
+          "targetState"
+        ]
       }
     ],
     [
       {
-        "operator": "git.publish"
+        "operator": "git.publish",
+        "asks": [
+          "boundary",
+          "approval"
+        ]
       }
     ]
   ],

package/workflows/content-unit.json

@@ -11,7 +11,10 @@
         "operator": "content.generate",
         "requirements": {
           "maxReviewRounds": 2
-        }
+        },
+        "asks": [
+          "unit"
+        ]
       }
     ]
   ],

package/workflows/frontend-new-surface.json

@@ -16,8 +16,7 @@
       {
         "operator": "workspace.bind",
         "requirements": {
-          "role": "fe",
-          "runtimeNeed": "consume"
+          "role": "fe"
         }
       }
     ],
@@ -26,7 +25,11 @@
         "operator": "business.decide",
         "requirements": {
           "mode": "model"
-        }
+        },
+        "asks": [
+          "featureId",
+          "targetState"
+        ]
       }
     ],
     [
@@ -35,7 +38,10 @@
         "requirements": {
           "intent": "create",
           "changeLevel": "new"
-        }
+        },
+        "asks": [
+          "target"
+        ]
       }
     ],
     [
@@ -65,7 +71,11 @@
     ],
     [
       {
-        "operator": "git.publish"
+        "operator": "git.publish",
+        "asks": [
+          "boundary",
+          "approval"
+        ]
       }
     ]
   ],

package/workflows/frontend-reconstruct.json

@@ -10,8 +10,7 @@
       {
         "operator": "workspace.bind",
         "requirements": {
-          "role": "fe",
-          "runtimeNeed": "consume"
+          "role": "fe"
         }
       }
     ],
@@ -21,7 +20,10 @@
         "requirements": {
           "intent": "modify",
           "changeLevel": "reconstruct"
-        }
+        },
+        "asks": [
+          "target"
+        ]
       }
     ],
     [
@@ -51,7 +53,11 @@
     ],
     [
       {
-        "operator": "git.publish"
+        "operator": "git.publish",
+        "asks": [
+          "boundary",
+          "approval"
+        ]
       }
     ]
   ],

package/workflows/frontend-refine.json

@@ -10,8 +10,7 @@
       {
         "operator": "workspace.bind",
         "requirements": {
-          "role": "fe",
-          "runtimeNeed": "consume"
+          "role": "fe"
         }
       }
     ],
@@ -21,7 +20,10 @@
         "requirements": {
           "intent": "audit-repair",
           "changeLevel": "refine"
-        }
+        },
+        "asks": [
+          "target"
+        ]
       }
     ],
     [
@@ -51,7 +53,11 @@
     ],
     [
       {
-        "operator": "git.publish"
+        "operator": "git.publish",
+        "asks": [
+          "boundary",
+          "approval"
+        ]
       }
     ]
   ],