release-skill 0.4.2 → 0.5.1

package/adapters/claude/bin/rules.json

@@ -0,0 +1,104 @@
+{
+  "schemaVersion": 1,
+  "kind": "skill-family.contracts.rules",
+  "contractsVersion": "1.5.0",
+  "budget": {
+    "firstVersionMax": 20,
+    "absoluteMax": 30,
+    "note": "Mechanical gate: runChecks fails with SFC1008 when the mandatory rule count exceeds firstVersionMax, and fails harder when it exceeds absoluteMax. The count includes every rule with severity mandatory, including budget rules themselves."
+  },
+  "checkTypes": [
+    {
+      "type": "schema.compile",
+      "description": "Each registered schema must compile under its declared dialect; an uncompilable schema fails with SFC1012."
+    },
+    {
+      "type": "schema.unique-id",
+      "description": "No two registered schemas may share a $id; duplicates fail with SFC1003."
+    },
+    {
+      "type": "protocol.unique-name",
+      "description": "No two registered protocols may share the same name and version; duplicates fail with SFC1004."
+    },
+    {
+      "type": "schema.ref-resolves",
+      "description": "Every $ref in registered schemas must resolve within the registered schema set; unresolved targets fail with SFC1005."
+    },
+    {
+      "type": "schema.dialect-declared",
+      "description": "Every registered schema must declare a dialect from the supported set, consistent with its $schema URI; violations fail with SFC1006."
+    },
+    {
+      "type": "fixture.positive-passes",
+      "description": "Every fixture expecting validity must validate against its target schema under its declared dialect and policy; mismatches fail with SFC1010."
+    },
+    {
+      "type": "fixture.negative-coded",
+      "description": "Every fixture expecting invalidity must fail with exactly its declared stable error code; mismatches fail with SFC1010."
+    },
+    {
+      "type": "error-code.registered",
+      "description": "Every error code declared in fixture expectations must exist in the frozen error registry; unknown codes fail with SFC1009."
+    },
+    {
+      "type": "rules.budget",
+      "description": "The mandatory rule count must stay within the first-version budget (and never exceed the absolute cap); excess fails with SFC1008."
+    }
+  ],
+  "rules": [
+    {
+      "ruleId": "CR-001",
+      "severity": "mandatory",
+      "checkType": "schema.compile",
+      "target": { "registry": "schemas" }
+    },
+    {
+      "ruleId": "CR-006",
+      "severity": "mandatory",
+      "checkType": "schema.unique-id",
+      "target": { "registry": "schemas" }
+    },
+    {
+      "ruleId": "CR-007",
+      "severity": "mandatory",
+      "checkType": "protocol.unique-name",
+      "target": { "registry": "protocols" }
+    },
+    {
+      "ruleId": "CR-008",
+      "severity": "mandatory",
+      "checkType": "schema.ref-resolves",
+      "target": { "registry": "schemas" }
+    },
+    {
+      "ruleId": "CR-009",
+      "severity": "mandatory",
+      "checkType": "schema.dialect-declared",
+      "target": { "registry": "schemas" }
+    },
+    {
+      "ruleId": "CR-010",
+      "severity": "mandatory",
+      "checkType": "fixture.positive-passes",
+      "target": { "fixtures": "expect-valid" }
+    },
+    {
+      "ruleId": "CR-011",
+      "severity": "mandatory",
+      "checkType": "fixture.negative-coded",
+      "target": { "fixtures": "expect-invalid" }
+    },
+    {
+      "ruleId": "CR-012",
+      "severity": "mandatory",
+      "checkType": "error-code.registered",
+      "target": { "references": "fixture-expectations" }
+    },
+    {
+      "ruleId": "CR-013",
+      "severity": "mandatory",
+      "checkType": "rules.budget",
+      "target": { "budget": "firstVersionMax" }
+    }
+  ]
+}

package/adapters/claude/skills/release-assess/SKILL.md

@@ -44,6 +44,8 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offlin
 
 offline assess 不访问 GitHub/npm 认证，因此不会以顶层 `AUTH_MISSING` 作为正常诊断结果；生产认证缺口由 help 的 `readiness.productionPublish` 和发布前在线门禁报告。
 
+在线模式下 npm 版本检查区分两种失败：registry 明确返回 E404/ETARGET 才算「版本不存在，无 gap」；网络、认证、超时等检查失败会以 `NPM_VERSION_CHECK_FAILED`（warning 级 gap）显式报告，不得把检查失败当作「版本未发布」。
+
 重试时只保留最新结构化错误码和失败门，不沿用早期猜测。
 
 ## 后续引导

package/adapters/claude/skills/release-help/SKILL.md

@@ -38,9 +38,11 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offlin
 # 日常发布快速路径：仅在发布前确认一次可读计划摘要，状态文件可恢复
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> --target-version <version> --json
 # 开发阶段执行声明 hooks 并生成 prepare 可复用的内容绑定收据
+# 配置时刻即授权（FM-16 处置 A）：hook 是任意本地进程、无隔离、触发前无确认点，
 # 命令调用本身即授权执行配置中的 hooks
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" hooks validate --root <path> --json
 # 仅旧冻结计划兼容：记录历史 Kimi/CodeBuddy 人工证明
+# （本地自声明收据，证明力弱：--actor 仅非空字符串校验、无外部签名核验；新计划不适用）
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" attest --root <path> \
   --platform <kimi|codebuddy> --plugin <id> --result <passed|failed> --actor <person> --json
 # 发布文档刷新：默认只读演练
@@ -59,7 +61,7 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> \
 - **只读演练**：`docs refresh --unit <id> --json` 输出逐文件相对路径、locale、新旧摘要、`version`、`locales`、`inputDigest`、`refreshDigest` 和 `nextCommand.argv`；候选无变化时 `status: "clean"`。
 - **确认写入**：必须同时提供 `--write`、精确 `--confirm-refresh <refreshDigest>` 和 `--ack-local-document-write`，全部目标作为一个事务提交；成功后立即复演必须为 `clean`。
 
-**授权边界**：本地发布文档写入授权只覆盖声明的本地文档目标，不是 Git 提交、push、publish 或安装的授权。hook/gate 由对应命令调用直接授权。写入后必须审阅、提交，再重新 prepare。
+**授权边界**：本地发布文档写入授权只覆盖声明的本地文档目标，不是 Git 提交、push、publish 或安装的授权。hook/gate 由对应命令调用直接授权——在 project.yaml 配置 hook 即完成授权（配置时刻即授权契约，FM-16 处置 A）：hook 是任意本地进程、无文件系统/网络隔离、触发前无确认点，配置者须对其内容负责；恢复触发前强制确认门为后续加固项。写入后必须审阅、提交，再重新 prepare。
 
 ## 故障路由
 

package/adapters/claude/skills/release-prepare/SKILL.md

@@ -11,9 +11,9 @@ description: Freeze an immutable release plan with local configuration, document
 
 ## 职责与边界
 
-运行项目构建/测试 hook，生成公开快照并扫描泄漏，冻结不可变发布计划。prepare 自身不调用发布 adapter，但会执行用户配置的 hook。hook 是任意本地进程，不受文件系统/网络隔离，可能产生项目目录外的副作用或远端写入。
+运行项目构建/测试 hook，生成公开快照并扫描泄漏，冻结不可变发布计划。prepare 自身不调用发布 adapter，但会执行用户配置的 hook。
 
-**Hook 与 Gate 执行**: 命令调用本身即授权执行已配置的 hook 和 gate，不再设置额外人工授权环节。
+**Hook 授权契约（配置时刻即授权，FM-16 处置 A）**: hook 是任意本地进程——在 `.release-skill/project.yaml` 中配置 hook 命令即完成授权，构成「配置时刻即授权」的显式契约。hook 不提供沙箱、无文件系统/网络隔离、触发前无确认点，命令调用本身即授权执行已配置的 hook 和 gate，不再设置额外人工授权环节；hook 可能产生项目目录外的副作用或远端写入，配置者须对其内容负责。恢复「触发前强制确认门」属于后续加固项（属设计变更，需随新版本引入），当前版本不提供该确认门。
 
 **阶段通过规则**: 本阶段的通过只能由 CLI exit code 0 和结构化状态码 `PREPARED` 确认。Agent 无权自行宣布计划冻结成功。
 

package/adapters/claude/skills/release-verify/SKILL.md

@@ -19,6 +19,8 @@ verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再
 
 验证远端所有自动化 action 的实际状态与冻结计划一致。执行精确 `<package>@<version>` npm 安装到隔离目录，验证包名、版本、静态入口闭包，并在配置时验证 bin 路径安全和 CLI 烟雾输出。对 Claude/Codex marketplace distribution 执行全新隔离消费者安装验证。新计划中的 Kimi/CodeBuddy 安装只返回 `manualFollowUps`，明确标记 `verifiedBySystem: false`，不阻塞 `VERIFIED`；缺少该策略字段的旧冻结计划继续走历史 attestation 兼容路径。
 
+**attestation 证明力边界**: `attest` 命令记录的旧计划兼容人工证明（`humanConfirmed: true` → `PASSED_MANUAL`）是本地自声明收据，不是签名见证：`--actor` 仅做非空字符串校验，无外部签名或身份核验，任何能运行 CLI 的进程都能自称任意 actor；伪造收据需写 `.release-skill` authority 目录，与直接改写收据文件属同一信任边界。因此旧兼容路径的人工证明只用于旧冻结计划收尾，不构成独立可审计的人工见证。新计划的 Kimi/CodeBuddy 安装一律走 `manualFollowUps`（`verifiedBySystem: false`），不参与 `VERIFIED` 终态判定。
+
 **阶段通过规则**: 只有 CLI exit code 0 和结构化状态码 `VERIFIED` 才是完整终态。
 
 **源 run 要求**: `--run` 必需；源 run 的所有 checkpoint 必须为 succeeded 或 skipped。

package/adapters/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"
@@ -19,7 +19,7 @@
     ],
     "defaultPrompt": [
       "Assess this project for release readiness.",
-      "Prepare a release plan for version 0.4.2.",
+      "Prepare a release plan for version 0.5.1.",
       "Help me understand the release workflow."
     ]
   }

package/adapters/codex/bin/error-codes.json

@@ -0,0 +1,154 @@
+{
+  "schemaVersion": 1,
+  "kind": "skill-family.contracts.error-codes",
+  "contractsVersion": "1.5.0",
+  "policy": {
+    "format": "^SFC[0-9]{4}$",
+    "ranges": [
+      {
+        "prefix": "SFC1",
+        "category": "contract",
+        "note": "Contracts authority errors: schemas, registry, dialects, rules, fixtures."
+      },
+      {
+        "prefix": "SFC2",
+        "category": "kernel",
+        "note": "Kernel protocol operation errors."
+      },
+      {
+        "prefix": "SFC3",
+        "category": "report",
+        "note": "Report contract errors: digest binding, mandatory elements, fact drift. Style findings are never coded here; they are advisory output of the report check, not errors."
+      }
+    ],
+    "stability": "Codes are append-only. A frozen code is never reused for a different meaning; a deprecated code stays reserved. New codes require a contracts change."
+  },
+  "codes": [
+    {
+      "code": "SFC1001",
+      "name": "SCHEMA_VALIDATION_FAILED",
+      "category": "contract",
+      "stableSince": "1.0.0",
+      "meaning": "A document failed validation against its registered schema under the declared dialect and policy."
+    },
+    {
+      "code": "SFC1002",
+      "name": "UNKNOWN_SCHEMA_ID",
+      "category": "contract",
+      "stableSince": "1.0.0",
+      "meaning": "The referenced $id is not present in the schema registry."
+    },
+    {
+      "code": "SFC1003",
+      "name": "DUPLICATE_SCHEMA_ID",
+      "category": "contract",
+      "stableSince": "1.0.0",
+      "meaning": "Two schema registrations share the same $id; the registration is mechanically rejected."
+    },
+    {
+      "code": "SFC1004",
+      "name": "DUPLICATE_PROTOCOL_NAME",
+      "category": "contract",
+      "stableSince": "1.0.0",
+      "meaning": "Two protocol registrations share the same name and version; the registration is mechanically rejected."
+    },
+    {
+      "code": "SFC1005",
+      "name": "UNRESOLVED_REF",
+      "category": "contract",
+      "stableSince": "1.0.0",
+      "meaning": "A $ref target cannot be resolved within the registered schema set."
+    },
+    {
+      "code": "SFC1006",
+      "name": "UNSUPPORTED_DIALECT",
+      "category": "contract",
+      "stableSince": "1.0.0",
+      "meaning": "The declared JSON Schema dialect is not in the frozen supported dialect set."
+    },
+    {
+      "code": "SFC1007",
+      "name": "UNKNOWN_CHECK_TYPE",
+      "category": "contract",
+      "stableSince": "1.0.0",
+      "meaning": "A rule uses a check type outside the finite set of nine."
+    },
+    {
+      "code": "SFC1008",
+      "name": "RULE_BUDGET_EXCEEDED",
+      "category": "contract",
+      "stableSince": "1.0.0",
+      "meaning": "The mandatory rule count exceeds the first-version budget or the absolute cap."
+    },
+    {
+      "code": "SFC1009",
+      "name": "UNKNOWN_ERROR_CODE",
+      "category": "contract",
+      "stableSince": "1.0.0",
+      "meaning": "A fixture expectation references an error code that is not in this frozen registry."
+    },
+    {
+      "code": "SFC1010",
+      "name": "FIXTURE_EXPECTATION_MISMATCH",
+      "category": "contract",
+      "stableSince": "1.0.0",
+      "meaning": "A fixture did not behave as declared: a valid-expecting fixture failed, or an invalid-expecting fixture did not fail with the declared stable code."
+    },
+    {
+      "code": "SFC1011",
+      "name": "UNKNOWN_PROTOCOL",
+      "category": "contract",
+      "stableSince": "1.0.0",
+      "meaning": "A request references a protocol name/version that is not registered."
+    },
+    {
+      "code": "SFC1012",
+      "name": "SCHEMA_COMPILE_FAILED",
+      "category": "contract",
+      "stableSince": "1.0.0",
+      "meaning": "A registered schema does not compile under its declared dialect (the schema document itself is invalid)."
+    },
+    {
+      "code": "SFC2002",
+      "name": "UNKNOWN_OPERATION",
+      "category": "kernel",
+      "stableSince": "1.0.0",
+      "meaning": "The requested operation name is not in the frozen operation vocabulary of the referenced protocol version."
+    },
+    {
+      "code": "SFC2003",
+      "name": "INVALID_PARAMS",
+      "category": "kernel",
+      "stableSince": "1.0.0",
+      "meaning": "Operation params do not satisfy the frozen params contract of the requested operation."
+    },
+    {
+      "code": "SFC2004",
+      "name": "EXECUTION_FAILED",
+      "category": "kernel",
+      "stableSince": "1.0.0",
+      "meaning": "The mechanism runtime failed while executing a well-formed operation; details carry the mechanism evidence. Demonstrable only by a mechanism runtime, not by static contracts checks."
+    },
+    {
+      "code": "SFC3001",
+      "name": "REPORT_DIGEST_MISMATCH",
+      "category": "report",
+      "stableSince": "1.2.0",
+      "meaning": "A report binding digest (model, result, or report digest) does not match the recomputed sha256 digest, or the report is not the canonical render of its model; the binding is stale or tampered and is never trusted."
+    },
+    {
+      "code": "SFC3002",
+      "name": "REPORT_ELEMENT_MISSING",
+      "category": "report",
+      "stableSince": "1.2.0",
+      "meaning": "A mandatory report element is absent, empty where it must not be, or declared in an unsupported form: the conclusion, non-empty evidence, risks/next-action sections, a supported locale, or a coded outcome for failed/blocked runs. No half report is issued for a missing element."
+    },
+    {
+      "code": "SFC3003",
+      "name": "REPORT_FACT_DRIFT",
+      "category": "report",
+      "stableSince": "1.2.0",
+      "meaning": "A report model misstates the bound operation result's terminal state/errors, or rendered report bytes diverge from the deterministic re-render of the bound report model: fact fields rewritten, sections deleted, duplicated, or injected."
+    }
+  ]
+}

package/adapters/codex/bin/kernel-protocol.json

@@ -0,0 +1,60 @@
+{
+  "schemaVersion": 1,
+  "kind": "skill-family.kernel-protocol",
+  "name": "skill-family.kernel.operation",
+  "version": 1,
+  "status": "stable",
+  "contractsVersion": "1.5.0",
+  "description": "Frozen v1 kernel protocol: request/result envelope, operation lifecycle states, and the operation vocabulary. Extensible only by a new protocol version; v1 content is frozen.",
+  "states": ["accepted", "running", "succeeded", "failed", "rejected"],
+  "initialStates": ["accepted", "rejected"],
+  "terminalStates": ["succeeded", "failed", "rejected"],
+  "transitions": [
+    { "from": "accepted", "to": "running" },
+    { "from": "accepted", "to": "failed" },
+    { "from": "running", "to": "succeeded" },
+    { "from": "running", "to": "failed" }
+  ],
+  "stateRules": {
+    "intake": "A well-formed request enters accepted; an intake rejection (for example an unregistered protocol) enters rejected directly.",
+    "result": "An operation-result carries only terminal states; non-terminal states are never serialized in results.",
+    "synchronous": "A synchronous mechanism implementation may move accepted through running to a terminal state without exposing intermediate states."
+  },
+  "operations": [
+    {
+      "name": "validate",
+      "status": "stable",
+      "description": "Validate one document against one registered schema under a declared dialect and policy.",
+      "params": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["schemaId", "document"],
+        "properties": {
+          "schemaId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Registered $id of the target schema."
+          },
+          "document": {
+            "type": "object",
+            "description": "The document to validate."
+          },
+          "dialect": {
+            "type": "string",
+            "description": "Optional dialect override; must be in the supported dialect set."
+          },
+          "policy": {
+            "type": "string",
+            "description": "Optional validation policy name; defaults to strict."
+          }
+        }
+      }
+    }
+  ],
+  "resultContract": {
+    "outputs": {
+      "validate": "On success, outputs.report is an object with valid (boolean) and errors (array of normalized validation findings)."
+    },
+    "errors": "Every error entry carries a code from the frozen contracts error registry."
+  }
+}

package/adapters/codex/bin/registry.json

@@ -0,0 +1,179 @@
+{
+  "schemaVersion": 1,
+  "kind": "skill-family.contracts.registry",
+  "contractsVersion": "1.5.0",
+  "note": "Protocol-name and schema-$id registry. Registration mechanically rejects duplicate protocol name/version (SFC1004) and duplicate $id (SFC1003). This file is the single registration surface; adding an entry is a contracts change.",
+  "protocols": [
+    {
+      "name": "skill-family.kernel.operation",
+      "version": 1,
+      "status": "stable",
+      "definition": "src/kernel-protocol.json",
+      "description": "Kernel request/result envelope protocol for mechanism operations."
+    }
+  ],
+  "schemas": [
+    {
+      "$id": "https://contracts.skill-family.example/v1/project-manifest.json",
+      "object": "project-manifest",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/project-manifest.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/profile-descriptor.json",
+      "object": "profile-descriptor",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/profile-descriptor.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/managed-file-lock.json",
+      "object": "managed-file-lock",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/managed-file-lock.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/operation-request.json",
+      "object": "operation-request",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/operation-request.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/operation-result.json",
+      "object": "operation-result",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/operation-result.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/migration-manifest.json",
+      "object": "migration-manifest",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/migration-manifest.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/report-model.json",
+      "object": "report-model",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/report-model.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/report-binding.json",
+      "object": "report-binding",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/report-binding.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/host-descriptor.json",
+      "object": "host-descriptor",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/host-descriptor.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/host-registry.json",
+      "object": "host-registry",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/host-registry.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/adapter-source.json",
+      "object": "adapter-source",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/adapter-source.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/host-capability-fact.json",
+      "object": "host-capability-fact",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/host-capability-fact.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/host-probe-result.json",
+      "object": "host-probe-result",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/host-probe-result.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/adapter-build-manifest.json",
+      "object": "adapter-build-manifest",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/adapter-build-manifest.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/host-operation-plan.json",
+      "object": "host-operation-plan",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/host-operation-plan.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/host-operation-receipt.json",
+      "object": "host-operation-receipt",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/host-operation-receipt.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/state-event-envelope.json",
+      "object": "state-event-envelope",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/state-event-envelope.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/state-snapshot-metadata.json",
+      "object": "state-snapshot-metadata",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/state-snapshot-metadata.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/token-estimate-result.json",
+      "object": "token-estimate-result",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/token-estimate-result.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/surface-scan-policy.json",
+      "object": "surface-scan-policy",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/surface-scan-policy.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/declared-read-surface-result.json",
+      "object": "declared-read-surface-result",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/declared-read-surface-result.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/structured-scan-policy.json",
+      "object": "structured-scan-policy",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/structured-scan-policy.schema.json"
+    }
+  ],
+  "dialects": {
+    "supported": ["draft-07", "2020-12"],
+    "metaSchemaUris": {
+      "draft-07": "http://json-schema.org/draft-07/schema#",
+      "2020-12": "https://json-schema.org/draft/2020-12/schema"
+    },
+    "note": "Draft detection maps a schema $schema URI to a dialect name via metaSchemaUris; validation is routed to the matching Ajv class."
+  }
+}