release-skill 0.9.17 → 0.9.19

package/adapters/cursor/src/schemas/migration-manifest.schema.json

@@ -0,0 +1,412 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/migration-manifest.json",
+  "title": "MigrationManifest",
+  "description": "Declares the migration state of one adoption target: the legacy infrastructure entries that must exit, each bound to its replacement, and any temporary exceptions. Every temporary exception carries exactly four mandatory fields (owner, reason, deadline, migrationTarget); an incomplete exception is never accepted. Path containment beyond shape is a mechanism concern owned by the harness: user-provided paths are only ever read inside the target root.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind"],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "kind": {
+      "const": "skill-family.migration-manifest"
+    },
+    "capabilityUseContext": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["scope", "locale"],
+      "properties": {
+        "scope": {
+          "type": "string",
+          "enum": ["contracts", "harness", "engineering-kit", "profile", "all"]
+        },
+        "locale": {
+          "type": "string",
+          "enum": ["en", "zh-CN"]
+        }
+      }
+    },
+    "capabilityUses": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 200,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["useId", "problemStatement", "constraints", "retainedGuarantees"],
+        "properties": {
+          "useId": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+            "maxLength": 80
+          },
+          "problemStatement": {
+            "allOf": [
+              { "$ref": "#/$defs/trimmedCapabilityUseText" },
+              { "type": "string", "maxLength": 1000 }
+            ]
+          },
+          "constraints": {
+            "type": "array",
+            "maxItems": 20,
+            "uniqueItems": true,
+            "items": {
+              "allOf": [
+                { "$ref": "#/$defs/trimmedCapabilityUseText" },
+                { "type": "string", "maxLength": 500 }
+              ]
+            }
+          },
+          "retainedGuarantees": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 20,
+            "uniqueItems": true,
+            "items": {
+              "allOf": [
+                { "$ref": "#/$defs/trimmedCapabilityUseText" },
+                { "type": "string", "maxLength": 500 }
+              ]
+            }
+          },
+            "catalogFilters": {
+            "type": "array",
+            "maxItems": 20,
+            "uniqueItems": true,
+            "items": {
+              "allOf": [
+                { "$ref": "#/$defs/trimmedCapabilityUseText" },
+                { "type": "string", "maxLength": 200 }
+              ]
+            }
+          }
+        }
+      }
+    },
+    "capabilityDecisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["useId", "disposition", "reason"],
+        "properties": {
+          "useId": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+            "maxLength": 80
+          },
+          "disposition": {
+            "type": "string",
+            "enum": ["direct-adoption", "compatibility-layer", "keep-business", "foundation-gap"]
+          },
+          "targetCapability": {
+            "type": "string",
+            "pattern": "^foundation\\.[a-z0-9\\-]+(\\.[a-z0-9\\-]+)+$"
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "required": ["disposition"],
+              "properties": {
+                "disposition": {
+                  "enum": ["direct-adoption", "compatibility-layer"]
+                }
+              }
+            },
+            "then": {
+              "required": ["targetCapability"],
+              "properties": { "targetCapability": { "type": "string" } }
+            }
+          },
+          {
+            "if": {
+              "required": ["disposition"],
+              "properties": {
+                "disposition": {
+                  "enum": ["keep-business", "foundation-gap"]
+                }
+              }
+            },
+            "then": {
+              "not": {
+                "required": ["targetCapability"],
+                "properties": { "targetCapability": { "type": "string" } }
+              }
+            }
+          }
+        ]
+      }
+    },
+    "manifestVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Monotonic manifest generation; bumped whenever the declared legacy/exception set changes."
+    },
+    "legacyInfra": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "replacedBy"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*$",
+            "description": "Relative POSIX path of one legacy implementation. Shape only: absolute paths, traversal, UNC/drive forms and symlink escapes are rejected by harness containment at assessment time, fail-closed."
+          },
+          "replacedBy": {
+            "oneOf": [
+              { "type": "string", "minLength": 1 },
+              { "type": "null" }
+            ],
+            "description": "The replacement facility (tool/command/module) that supersedes this legacy entry. An empty replacement is never a valid exit claim."
+          },
+          "useId": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+            "maxLength": 80
+          },
+          "recoveryRef": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "required": ["replacedBy"],
+              "properties": { "replacedBy": { "type": "null" } }
+            },
+            "then": {
+              "required": ["useId"],
+              "properties": { "useId": { "type": "string" } }
+            }
+          }
+        ]
+      }
+    },
+    "legacyReferences": {
+      "type": "array",
+      "description": "Legacy text references that must exit from retained files: each entry declares a file that is kept for other purposes, a literal text that must no longer appear in it, and the facility that replaces the old usage. The file itself is never deleted by this mechanism — only the old text must be absent.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "text", "replacedBy"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*$",
+            "description": "Relative POSIX path of a retained file. Shape only: containment is enforced at assessment time."
+          },
+          "text": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Exact literal text that must be absent from the file. No regex; byte-exact UTF-8 match."
+          },
+          "replacedBy": {
+            "oneOf": [
+              { "type": "string", "minLength": 1 },
+              { "type": "null" }
+            ],
+            "description": "The replacement facility that supersedes this old reference. Empty is never valid."
+          },
+          "useId": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+            "maxLength": 80
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "required": ["replacedBy"],
+              "properties": { "replacedBy": { "type": "null" } }
+            },
+            "then": {
+              "required": ["useId"],
+              "properties": { "useId": { "type": "string" } }
+            }
+          }
+        ]
+      }
+    },
+    "exceptions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["owner", "reason", "deadline", "migrationTarget"],
+        "properties": {
+          "owner": {
+            "type": "string",
+            "minLength": 1
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1
+          },
+          "deadline": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Parseable deadline; expiry is judged by the planning clock and never auto-renewed. Structural shape only — semantic parseability is a runtime finding."
+          },
+          "migrationTarget": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "targetProfile": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The profile id this target adopts. Completion requires it to equal the profile id of the adoption plan; a missing or mismatched binding is never completion."
+    },
+    "foundationPackages": {
+      "type": "array",
+      "description": "Exact Foundation package bindings: every entry pins a published name to an exact version and a sha256 tarball/content digest. Ranges, tags and floating aliases are not bindings.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "version", "digest"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "version": {
+            "type": "string",
+            "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+            "description": "Exact semver; no range operators."
+          },
+          "digest": {
+            "type": "string",
+            "pattern": "^sha256:[a-f0-9]{64}$",
+            "description": "Content digest as sha256:<64 lowercase hex>."
+          }
+        }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Evidence documents proving the adoption is verified: unit, integration, consumer and independent-audit evidence. Every value is a relative POSIX path inside the target root; existence and identity matching are judged by the completion gate, fail-closed.",
+      "properties": {
+        "unit": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*$"
+        },
+        "integration": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*$"
+        },
+        "consumer": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*$"
+        },
+        "independentAudit": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*$"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "trimmedCapabilityUseText": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)(?![\\s\\S]*\\u0000)[\\s\\S]+$"
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "required": ["capabilityUses"],
+        "properties": { "capabilityUses": { "type": "array" } }
+      },
+      "then": {
+        "required": ["capabilityUseContext"],
+        "properties": { "capabilityUseContext": { "type": "object" } }
+      },
+      "else": {
+        "not": {
+          "anyOf": [
+            {
+              "required": ["capabilityUseContext"],
+              "properties": { "capabilityUseContext": { "type": "object" } }
+            },
+            {
+              "required": ["capabilityDecisions"],
+              "properties": { "capabilityDecisions": { "type": "array" } }
+            }
+          ]
+        }
+      }
+    },
+    {
+      "if": {
+        "required": ["capabilityDecisions"],
+        "properties": { "capabilityDecisions": { "type": "array" } }
+      },
+      "then": {
+        "required": ["capabilityUses", "capabilityUseContext"],
+        "properties": {
+          "capabilityUses": { "type": "array" },
+          "capabilityUseContext": { "type": "object" }
+        }
+      }
+    },
+    {
+      "if": {
+        "required": ["legacyInfra"],
+        "properties": {
+          "legacyInfra": {
+            "type": "array",
+            "contains": {
+              "type": "object",
+              "required": ["useId"],
+              "properties": { "useId": { "type": "string" } }
+            }
+          }
+        }
+      },
+      "then": {
+        "required": ["capabilityUses", "capabilityUseContext"],
+        "properties": {
+          "capabilityUses": { "type": "array" },
+          "capabilityUseContext": { "type": "object" }
+        }
+      }
+    },
+    {
+      "if": {
+        "required": ["legacyReferences"],
+        "properties": {
+          "legacyReferences": {
+            "type": "array",
+            "contains": {
+              "type": "object",
+              "required": ["useId"],
+              "properties": { "useId": { "type": "string" } }
+            }
+          }
+        }
+      },
+      "then": {
+        "required": ["capabilityUses", "capabilityUseContext"],
+        "properties": {
+          "capabilityUses": { "type": "array" },
+          "capabilityUseContext": { "type": "object" }
+        }
+      }
+    }
+  ]
+}

package/adapters/cursor/src/schemas/observation-scope.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/observation-scope.json",
+  "title": "ObservationScope",
+  "description": "Observation scope extension (aligned with the audit-side plugin-project observation schema v2). Freezes the controlled vocabularies an observation record may use: observation scopes, the standard platform set (including the qoder/dsh extensions), severity levels, foundation adoption statuses, the path basis, token measurement subjects, missing-platform intents, and consumption forms. An observation record is conformant only when every vocabulary value it uses is contained in the frozen sets declared here; this object is the single mechanical reference so the two repositories never restate the vocabularies independently.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "kind",
+    "scopeVocabulary",
+    "standardPlatforms",
+    "severityLevels",
+    "adoptionStatuses",
+    "pathBasisVocabulary",
+    "measurementSubjects",
+    "missingPlatformIntents",
+    "consumptionForms"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "skill-family.observation-scope" },
+    "alignedObservationSchemaVersions": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Observation contract document versions these vocabularies align with (e.g. 1.0.0-candidate, 2.0.0-candidate)."
+    },
+    "scopeVocabulary": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "enum": ["skill", "plugin", "release"] }
+    },
+    "standardPlatforms": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "enum": ["claude-code", "codex", "kimi-code", "workbuddy", "qoder", "dsh"]
+      }
+    },
+    "severityLevels": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "enum": ["block", "error", "warning", "observe"] }
+    },
+    "adoptionStatuses": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "enum": ["foundation-adopted", "self-built", "exempted", "not-adopted", "unknown"]
+      }
+    },
+    "pathBasisVocabulary": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "enum": ["project-root-relative"] }
+    },
+    "measurementSubjects": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "enum": ["logical-source", "worst-projection"] }
+    },
+    "missingPlatformIntents": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "enum": ["unsupported", "planned", "experimental", "deprecated-host"]
+      }
+    },
+    "consumptionForms": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "enum": ["dependencies", "vendored-bundle", "tarball-pin", "none", "other"]
+      }
+    },
+    "note": {
+      "type": "string",
+      "description": "Optional human rationale; not consumed mechanically."
+    }
+  }
+}

package/adapters/cursor/src/schemas/operation-request.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/operation-request.json",
+  "title": "OperationRequest",
+  "description": "One kernel protocol request: a named operation with params, addressed to a registered protocol name/version. Envelope shape is frozen; the operation vocabulary is registered in the kernel protocol definition.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "protocol", "operationId", "operation", "params"],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "kind": {
+      "const": "skill-family.operation-request"
+    },
+    "protocol": {
+      "$ref": "#/$defs/protocolRef"
+    },
+    "operationId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$",
+      "description": "Caller-chosen identifier; unique per caller, echoed by the result."
+    },
+    "operation": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+      "description": "Operation name; must be in the frozen vocabulary of the referenced protocol version."
+    },
+    "params": {
+      "type": "object",
+      "description": "Operation-specific params. The frozen params contract of each operation lives in the kernel protocol definition, not here."
+    },
+    "requestedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Optional RFC 3339 date-time when the request was created."
+    }
+  },
+  "$defs": {
+    "protocolRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*(\\.[a-z][a-z0-9]*(-[a-z0-9]+)*)*$",
+          "description": "Registered protocol name (dot-separated kebab-case segments)."
+        },
+        "version": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Registered protocol version."
+        }
+      }
+    }
+  }
+}

package/adapters/cursor/src/schemas/operation-result.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/operation-result.json",
+  "title": "OperationResult",
+  "description": "Terminal result of one kernel protocol operation: terminal state, optional outputs, and stable-coded errors. A result never carries non-terminal states.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "protocol", "operationId", "operation", "state", "errors"],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "kind": {
+      "const": "skill-family.operation-result"
+    },
+    "protocol": {
+      "$ref": "#/$defs/protocolRef"
+    },
+    "operationId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$",
+      "description": "Echoes the request operationId."
+    },
+    "operation": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+      "description": "Echoes the request operation."
+    },
+    "state": {
+      "enum": ["succeeded", "failed", "rejected"],
+      "description": "Terminal states only; equals the kernel protocol terminalStates set."
+    },
+    "outputs": {
+      "type": ["object", "null"],
+      "description": "Operation-specific outputs; meaningful when state is succeeded."
+    },
+    "errors": {
+      "type": "array",
+      "description": "Empty when state is succeeded; at least one stable-coded error otherwise.",
+      "items": {
+        "$ref": "#/$defs/error"
+      }
+    },
+    "completedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Optional RFC 3339 date-time when the operation reached a terminal state."
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "state": {
+            "const": "succeeded"
+          }
+        },
+        "required": ["state"]
+      },
+      "then": {
+        "properties": {
+          "errors": {
+            "type": "array",
+            "maxItems": 0
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "state": {
+            "enum": ["failed", "rejected"]
+          }
+        },
+        "required": ["state"]
+      },
+      "then": {
+        "properties": {
+          "errors": {
+            "type": "array",
+            "minItems": 1
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "protocolRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*(\\.[a-z][a-z0-9]*(-[a-z0-9]+)*)*$",
+          "description": "Registered protocol name (dot-separated kebab-case segments)."
+        },
+        "version": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Registered protocol version."
+        }
+      }
+    },
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "message"],
+      "properties": {
+        "code": {
+          "type": "string",
+          "pattern": "^SFC[0-9]{4}$",
+          "description": "Stable error code from the frozen contracts error registry."
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path": {
+          "type": "string",
+          "description": "Optional JSON pointer into the offending document."
+        },
+        "details": {
+          "type": "object"
+        }
+      }
+    }
+  }
+}