@starci/skills 1.1.0

package/templates/kinds/mutations.schema.json

@@ -0,0 +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" }
+      }
+    }
+  }
+}

package/templates/kinds/platform-operation-receipt.contract.json

@@ -0,0 +1,76 @@
+{
+  "kind": "platform-operation-receipt",
+  "title": "^# platform-operation-receipt — (observability|sonar|tunnel) [A-Za-z0-9._/-]+$",
+  "sections": [
+    {
+      "heading": "^## Binding$",
+      "table": "| Field | Value |",
+      "rows": [
+        "Operator",
+        "Step",
+        "Project",
+        "Service",
+        "Service kind",
+        "Owner",
+        "Approval",
+        "Desired state",
+        "Inventory fingerprint"
+      ],
+      "cell": {
+        "Value": "\\S"
+      }
+    },
+    {
+      "heading": "^## Convergence$",
+      "table": "| Field | Value |",
+      "exactRows": 1,
+      "rows": [
+        "Convergence"
+      ],
+      "cell": {
+        "Value": "^(converged|already-converged)$"
+      }
+    },
+    {
+      "heading": "^## Inventoried resources$",
+      "table": "| Resource | Kind | Revision | Owner |",
+      "minRows": 1,
+      "cell": {
+        "Kind": "^(observability|sonar|tunnel)$",
+        "Revision": "\\S"
+      }
+    },
+    {
+      "heading": "^## Port holders$",
+      "table": "| Port | Holder | Evidence |",
+      "cell": {
+        "Port": "^[0-9]{1,5}$"
+      }
+    },
+    {
+      "heading": "^## Mutations$",
+      "table": "| Effect | Resource | Before | After |",
+      "cell": {
+        "Effect": "^`(update-config|restart-service|upsert-dashboard|update-remote-write|create-project|assign-profile|assign-gate|enforce-setting|create-tunnel|update-tunnel-route|upsert-proxied-dns)`$"
+      }
+    },
+    {
+      "heading": "^## Checks$",
+      "table": "| Check | Resource | Status | Evidence |",
+      "minRows": 1,
+      "cell": {
+        "Status": "^(passed|failed)$",
+        "Evidence": "\\S"
+      }
+    },
+    {
+      "heading": "^## Findings$",
+      "table": "| Code | Resource | Port | Holder | Statement |",
+      "minRows": 1,
+      "cell": {
+        "Code": "^`(SHARED_SERVICE_INVENTORIED|PORT_COORDINATION_REQUIRED|ALREADY_CONVERGED|PARTIAL_MUTATION|PRODUCT_DEPLOYMENT_DECLINED)`$",
+        "Statement": "\\S"
+      }
+    }
+  ]
+}

package/templates/kinds/platform-operation-receipt.skeleton.md

@@ -0,0 +1,54 @@
+# platform-operation-receipt — observability prometheus/shared
+
+One paragraph: which shared service was inventoried, which approved delta was applied, and which
+proof set was proved. Written by `platform.operate` as `response/response.md`. It proves the shared
+service reached the approved state; it proves nothing about any product.
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Operator | `platform.operate` |
+| Step | `step-1/parallel-1` |
+| Project | `starci-academy` |
+| Service | `prometheus/shared` |
+| Service kind | observability |
+| Owner | `platform-team` |
+| Approval | `@worktrees/debts/be.md#metrics-approval` |
+| Desired state | `sha256:0000000000000000000000000000000000000000000000000000000000000000` |
+| Inventory fingerprint | `sha256:1111111111111111111111111111111111111111111111111111111111111111` |
+
+## Convergence
+
+| Field | Value |
+| --- | --- |
+| Convergence | already-converged |
+
+## Inventoried resources
+
+| Resource | Kind | Revision | Owner |
+| --- | --- | --- | --- |
+| `prometheus/shared` | observability | r-14 | `platform-team` |
+
+## Port holders
+
+| Port | Holder | Evidence |
+| --- | --- | --- |
+
+## Mutations
+
+| Effect | Resource | Before | After |
+| --- | --- | --- | --- |
+
+## Checks
+
+| Check | Resource | Status | Evidence |
+| --- | --- | --- | --- |
+| `service-health` | `prometheus/shared` | passed | `logs/health.txt` |
+
+## Findings
+
+| Code | Resource | Port | Holder | Statement |
+| --- | --- | --- | --- | --- |
+| `SHARED_SERVICE_INVENTORIED` | `prometheus/shared` | — | — | the service was inventoried before anything changed |
+| `ALREADY_CONVERGED` | `prometheus/shared` | — | — | the service already matched the approved plan |

package/templates/kinds/probes.schema.json

@@ -0,0 +1,130 @@
+{
+  "$id": "kind:probes",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "deadlineSeconds",
+    "elapsedSeconds",
+    "backoffSeconds",
+    "observations",
+    "finalCondition"
+  ],
+  "properties": {
+    "deadlineSeconds": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "elapsedSeconds": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "backoffSeconds": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "observations": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 256,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "observedAt",
+          "condition",
+          "activeReleaseIds",
+          "activeDigest",
+          "availableTargets",
+          "probeResults"
+        ],
+        "properties": {
+          "observedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "condition": {
+            "enum": [
+              "progressing",
+              "failing",
+              "steady"
+            ]
+          },
+          "activeReleaseIds": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 8,
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "pattern": "^release:[A-Za-z0-9._-]+$"
+            }
+          },
+          "activeDigest": {
+            "oneOf": [
+              {
+                "type": "string",
+                "pattern": "^sha256:[0-9a-f]{64}$"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "availableTargets": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "probeResults": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "probeId",
+                "status",
+                "observedStatus",
+                "observedAt"
+              ],
+              "properties": {
+                "probeId": {
+                  "type": "string",
+                  "pattern": "^[a-z0-9][a-z0-9-]*$"
+                },
+                "status": {
+                  "enum": [
+                    "pass",
+                    "fail"
+                  ]
+                },
+                "observedStatus": {
+                  "oneOf": [
+                    {
+                      "type": "integer",
+                      "minimum": 100,
+                      "maximum": 599
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "observedAt": {
+                  "type": "string",
+                  "format": "date-time"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "finalCondition": {
+      "enum": [
+        "progressing",
+        "failing",
+        "steady",
+        "deadline-exceeded"
+      ]
+    }
+  }
+}

package/templates/kinds/proof.schema.json

@@ -0,0 +1,17 @@
+{
+  "$id": "kind:proof",
+  "title": "One declared proof of one operation, with the command that was run and what came back; the file is named <operationId>.<proofKind>.json.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["operationId", "proofKind", "commandRef", "exitCode", "result", "output", "statement", "contractFingerprint"],
+  "properties": {
+    "operationId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "proofKind": { "enum": ["unit", "integration", "migration-replay", "conformance-read", "runtime-probe"] },
+    "commandRef": { "type": "string", "minLength": 1, "maxLength": 1024 },
+    "exitCode": { "type": "integer", "minimum": 0, "maximum": 255 },
+    "result": { "enum": ["passed", "failed"] },
+    "output": { "type": "string", "minLength": 1, "maxLength": 8192 },
+    "statement": { "type": "string", "minLength": 1, "maxLength": 4096 },
+    "contractFingerprint": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+  }
+}

package/templates/kinds/quality-verification.contract.json

@@ -0,0 +1,87 @@
+{
+  "kind": "quality-verification",
+  "title": "^# quality-verification — [0-9a-f]{40}$",
+  "sections": [
+    {
+      "heading": "^## Binding$",
+      "table": "| Field | Value |",
+      "rows": [
+        "Operator",
+        "Step",
+        "Checkout",
+        "Head",
+        "Session branch",
+        "Predecessors"
+      ],
+      "cell": {
+        "Value": "\\S"
+      }
+    },
+    {
+      "heading": "^## Gate plan$",
+      "table": "| Gate | Required | Command | Configuration |",
+      "minRows": 1,
+      "cell": {
+        "Gate": "^`(format|lint|typecheck|build|unit-coverage|integration|e2e|sonar)`$",
+        "Required": "^(yes|no)$"
+      }
+    },
+    {
+      "heading": "^## Results$",
+      "table": "| Gate | Status | Exit code | Evidence | Classification | Statement |",
+      "minRows": 1,
+      "cell": {
+        "Gate": "^`(format|lint|typecheck|build|unit-coverage|integration|e2e|sonar)`$",
+        "Status": "^(pass|fail|external-blocker|skipped-not-requested)$",
+        "Classification": "^(in-boundary|boundary-drift|flaky|external-blocker|—)$",
+        "Statement": "\\S"
+      }
+    },
+    {
+      "heading": "^## Coverage$",
+      "table": "| Metric | Measured | Threshold | Verdict |",
+      "cell": {
+        "Metric": "^(statements|lines|functions|branches)$",
+        "Verdict": "^(at-or-above|below)$"
+      }
+    },
+    {
+      "heading": "^## Sonar$",
+      "table": "| Field | Value |",
+      "rows": [
+        "Scope",
+        "Finding"
+      ],
+      "cell": {
+        "Value": "\\S"
+      }
+    },
+    {
+      "heading": "^## Debts$",
+      "table": "| Debt | Gate | Approval | Owner | Expires | Statement |",
+      "cell": {
+        "Gate": "^`(format|lint|typecheck|build|unit-coverage|integration|e2e|sonar)`$"
+      }
+    },
+    {
+      "heading": "^## Findings$",
+      "table": "| Code | Gate | Statement |",
+      "minRows": 1,
+      "cell": {
+        "Code": "^`(PREDECESSOR_CONSUMED|SONAR_NEW_CODE_ONLY|E2E_NOT_REQUESTED|COVERAGE_BELOW_THRESHOLD|FLAKY_CONFIRMED|DEBT_DECLARED)`$",
+        "Statement": "\\S"
+      }
+    },
+    {
+      "heading": "^## Verdict$",
+      "table": "| Field | Value |",
+      "exactRows": 1,
+      "rows": [
+        "Verdict"
+      ],
+      "cell": {
+        "Value": "^`(pass|fail)`$"
+      }
+    }
+  ]
+}

package/templates/kinds/quality-verification.skeleton.md

@@ -0,0 +1,58 @@
+# quality-verification — 1111111111111111111111111111111111111111
+
+One paragraph: which delivery was verified, on which head, and what the verdict rests on. Written by
+`quality.verify` as `response/response.md`. A red verdict is a complete invocation; only an inability
+to reach any verdict at all is a stop.
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Operator | `quality.verify` |
+| Step | `step-1/parallel-1` |
+| Checkout | `@workspaces/be` |
+| Head | `1111111111111111111111111111111111111111` |
+| Session branch | `session/s-1` |
+| Predecessors | `step-1/parallel-1/response/response.md`, `step-1/parallel-1/response/changes.md` |
+
+## Gate plan
+
+| Gate | Required | Command | Configuration |
+| --- | --- | --- | --- |
+| `lint` | yes | `package.json#scripts.lint` | `eslint.config.mjs` |
+
+## Results
+
+| Gate | Status | Exit code | Evidence | Classification | Statement |
+| --- | --- | --- | --- | --- | --- |
+| `lint` | pass | 0 | `gates/lint.log` | — | zero errors and zero warnings |
+
+## Coverage
+
+| Metric | Measured | Threshold | Verdict |
+| --- | --- | --- | --- |
+| branches | 81.4 | 80 | at-or-above |
+
+## Sonar
+
+| Field | Value |
+| --- | --- |
+| Scope | new-code |
+| Finding | — |
+
+## Debts
+
+| Debt | Gate | Approval | Owner | Expires | Statement |
+| --- | --- | --- | --- | --- | --- |
+
+## Findings
+
+| Code | Gate | Statement |
+| --- | --- | --- |
+| `PREDECESSOR_CONSUMED` | — | the producer receipt was consumed unchanged at the frozen head |
+
+## Verdict
+
+| Field | Value |
+| --- | --- |
+| Verdict | `pass` |

package/templates/kinds/release-deployment.contract.json

@@ -0,0 +1,85 @@
+{
+  "kind": "release-deployment",
+  "title": "^# release-deployment — release:[A-Za-z0-9._-]+$",
+  "sections": [
+    {
+      "heading": "^## Binding$",
+      "table": "| Field | Value |",
+      "rows": [
+        "Operator",
+        "Step",
+        "Project",
+        "Release",
+        "Artifact",
+        "Digest",
+        "Target",
+        "Environment",
+        "Replaced release",
+        "Approval",
+        "Manifest",
+        "Steady deadline",
+        "Rollback identity"
+      ],
+      "cell": {
+        "Value": "\\S"
+      }
+    },
+    {
+      "heading": "^## Outcome$",
+      "table": "| Field | Value |",
+      "exactRows": 2,
+      "rows": [
+        "Outcome",
+        "Branch"
+      ],
+      "cell": {
+        "Value": "^(deployed|rolled-back|none|recover|rollback)$"
+      }
+    },
+    {
+      "heading": "^## Steps$",
+      "table": "| Step | State | Revision before | Revision after | Statement |",
+      "minRows": 1,
+      "cell": {
+        "Step": "^`(authorize|manifest-validate|plan|execution-root-init|credential-resolve|host-prepare|artifact-build|artifact-publish|migrate|domain-reconcile|rollout|monitor|recover|rollback|proof)`$",
+        "State": "^(applied|no-op|skipped|failed)$",
+        "Statement": "\\S"
+      }
+    },
+    {
+      "heading": "^## Monitoring$",
+      "table": "| Field | Value |",
+      "rows": [
+        "Deadline",
+        "Elapsed",
+        "Backoff",
+        "Final condition"
+      ],
+      "cell": {
+        "Value": "\\S"
+      }
+    },
+    {
+      "heading": "^## Steady state$",
+      "table": "| Metric | Value |",
+      "cell": {
+        "Value": "\\S"
+      }
+    },
+    {
+      "heading": "^## Findings$",
+      "table": "| Code | Step | Statement |",
+      "cell": {
+        "Code": "^`(IDEMPOTENT_NO_OP|PROBE_TRANSIENT|TARGET_UNAVAILABLE|SUPERSEDED_TARGET_ACTIVE|FOREIGN_RELEASE_OBSERVED|APPROVED_ACTION_REPEATED)`$",
+        "Statement": "\\S"
+      }
+    },
+    {
+      "heading": "^## Fallbacks taken$",
+      "table": "| Code | Action |",
+      "cell": {
+        "Code": "^`[A-Z][A-Z0-9_]+`$"
+      }
+    }
+  ]
+}

package/templates/kinds/release-deployment.skeleton.md

@@ -0,0 +1,67 @@
+# release-deployment — release:2026.01.10-1
+
+One paragraph: which immutable release reached which target, under which authorization, and what the
+steady state rests on. Written by `release.deploy` as `response/response.md`. A rolled-back run is a
+terminal outcome of its own and never reads as delivery of the release it rejected.
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Operator | `release.deploy` |
+| Step | `step-1/parallel-1` |
+| Project | `starci-academy` |
+| Release | `release:2026.01.10-1` |
+| Artifact | `@remote/ghcr/starci/academy-api` |
+| Digest | `sha256:1111111111111111111111111111111111111111111111111111111111111111` |
+| Target | `production/api` |
+| Environment | production |
+| Replaced release | `release:2026.01.03-2` |
+| Approval | `@worktrees/businesses/features/release/model.json#deploy-grant` |
+| Manifest | `.stacks/production/api.manifest.json` |
+| Steady deadline | 600 |
+| Rollback identity | `release:2026.01.03-2` |
+
+## Outcome
+
+| Field | Value |
+| --- | --- |
+| Outcome | deployed |
+| Branch | none |
+
+## Steps
+
+| Step | State | Revision before | Revision after | Statement |
+| --- | --- | --- | --- | --- |
+| `authorize` | applied | — | — | the declared grant covers this project, environment and target |
+| `rollout` | applied | 4 | 5 | the target moved to the immutable digest |
+| `monitor` | applied | — | — | the window was observed to its end |
+
+## Monitoring
+
+| Field | Value |
+| --- | --- |
+| Deadline | 600 |
+| Elapsed | 420 |
+| Backoff | 30 |
+| Final condition | steady |
+
+## Steady state
+
+| Metric | Value |
+| --- | --- |
+| Active digest | `sha256:1111111111111111111111111111111111111111111111111111111111111111` |
+| Available targets | 1 of 1 |
+| Superseded active | 0 |
+| Window elapsed | 300 |
+
+## Findings
+
+| Code | Step | Statement |
+| --- | --- | --- |
+| `IDEMPOTENT_NO_OP` | `host-prepare` | the host already matched the declaration |
+
+## Fallbacks taken
+
+| Code | Action |
+| --- | --- |