release-skill 0.9.15 → 0.9.17

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

@@ -0,0 +1,109 @@
+---
+name: release-verify
+description: Post-publish verification including remote state recheck, exact npm installation smoke, and consumer plugin install verification
+---
+
+> **Qoder 安装入口解析协议**：在调用 CLI 前，Agent 必须从宿主当前已加载技能的元数据中取得本 `SKILL.md` 的实际绝对路径，并将该字面量记为 `SKILL_FILE`。
+> `SKILL_FILE` 不是环境变量；禁止从工作目录、可执行搜索路径、源码仓库或 shell 调用上下文猜测。若宿主未提供该绝对路径，立即停止并报告安装定位失败。
+> 对 `SKILL_FILE` 执行 `realpath`，取其目录向上两级得到 `PLUGIN_ROOT`；校验真实技能路径匹配 `PLUGIN_ROOT/skills/*/SKILL.md` 且仍位于插件根内（路径包含检查）。
+> 令 `RELEASE_SKILL_ENTRY=PLUGIN_ROOT/bin/release-skill.mjs`，对入口执行 `realpath` containment、`lstat` 非符号链接且为普通文件校验。
+> 每一次 shell 工具调用都必须在同一个调用中用上述已验证绝对值设置 `RELEASE_SKILL_ENTRY`，然后执行 `node "$RELEASE_SKILL_ENTRY" ...`；不得依赖前一次 shell 的变量。
+>
+
+# release-verify
+
+## 触发
+
+用户请求验证发布结果完整性，或发布流程自动进入 verify 阶段。
+
+## 当前状态
+
+verify 是发布流程的最终验证阶段，是唯一能将状态提升到 `VERIFIED` 的命令。
+它执行远端状态重检、精确 npm 安装烟雾测试和消费者插件安装验证。
+verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再次派生运行。
+
+计划声明 `postVerify` hook 时，`postverify` 命令负责执行独立的收尾阶段。它接收
+`VERIFIED` verify run、同一计划的 approval，以及逐个传入的 checkpoint approval，
+然后原样调用现有 `postVerifyRelease`。该命令产生独立的 `postverify` run，不读取或写入
+ship state；hook approval 缺失、错误或过期时，在 hook 执行前失败关闭。
+
+**注意**: distribute gate (W1) 已经实现并集成在标准 verify 流程中。verify 现在会检查 postPublish 分发状态（git mirror + marketplace index），只有当所有外部动作都完成并通过验证时才达到 VERIFIED。
+
+**工作流兼容性**:
+- `docs-only`: consumer-verify preserved (步骤⑧)
+- `config-only`: scene B completes full chain including verify
+- `marketplace-only`: delegates to workspace's exclusive skill for final verification
+- `full-happy-end`: standard complete path with all gates
+
+所有工作流 profile 最终都路由到此 verify 命令作为终态验证门。
+
+## 职责与边界
+
+验证远端所有自动化 action 的实际状态与冻结计划一致。执行精确 `<package>@<version>` npm 安装到隔离目录，验证包名、版本、静态入口闭包，并在配置时验证 bin 路径安全和 CLI 烟雾输出。对 Claude/Codex marketplace distribution 执行全新隔离消费者安装验证。新计划中的 Kimi/CodeBuddy 安装只返回 `manualFollowUps`，明确标记 `verifiedBySystem: false`，不阻塞 `VERIFIED`；缺少该策略字段的旧冻结计划继续走历史 attestation 兼容路径。
+
+0.9.3 的稳定隔离安装树记录只消费宿主命令退出后的隔离树观察：宿主附加 link 记录自身但不跟随，声明载荷 symlink 失败关闭，legacy 全树语义保持不变。该观察属于安装树事实，不替代远端状态、发布计划或 `VERIFIED` 判断。
+
+**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。
+
+**不确定性停止**: 任何验证失败立即停止，不进行部分降级。
+
+## 正向执行路径
+
+1. 确认有 `--run` 路径（必需），且源 run 状态为 PUBLISHED
+2. 使用插件根相对路径运行 CLI；命令调用本身即授权执行已配置的 verification gate 和 smoke process
+3. 检查 exit code 和结构化状态：`VERIFIED`（全部通过）/ 失败（具体错误）
+4. 只有 `VERIFIED` 才是发布 happy end
+5. 达到 `VERIFIED` 后先检查计划是否声明 `postVerify` hook：直接收尾使用独立的 `postverify --plan --approval --run --hook-approval`，由该命令产生 `DISTRIBUTED` postVerify run；若仍由持久化 ship state 承担编排，则使用 `ship --hook-approval` 完成同一阶段，再把最终 run 路径交给 `release-finish`。没有 postVerify hook 时，把当前 verify run 路径交给 `release-finish`。随后按清单主动询问分支合并和本机宿主插件更新；发布策略已包含分支动作时略过合并询问
+
+## 确定性脚本调用
+
+```bash
+# 从插件根运行
+node "$RELEASE_SKILL_ENTRY" verify --root <path> --plan <plan-path> --run <run-path> --json
+# 独立执行已 VERIFIED 计划的 postVerify hook；每个 requiresApproval hook 单独传入批准记录
+node "$RELEASE_SKILL_ENTRY" postverify --root <path> \
+  --plan <plan-path> --approval <approval-path> --run <verified-run-path> \
+  --hook-approval <immutable-hook-approval-path> --json
+```
+
+## 验证步骤
+
+1. 加载并验证 release plan schema 和 digest
+2. 加载源 run，验证 planDigest 匹配和 checkpoint 完整性
+3. 对每个 plan action 执行 adapter.verify()（远端状态重检）
+4. 对每个 npm distribution 执行隔离安装烟雾测试
+5. 对 Claude/Codex marketplace distribution 执行全新隔离消费者安装验证；收集 Kimi/CodeBuddy 的非阻塞 `manualFollowUps`
+6. 全部通过 → `VERIFIED`
+
+`postverify` 不属于上述远端验证步骤。它只处理已经达到 `VERIFIED` 的计划，并把
+`postVerify` 阶段的执行结果写入独立 run。
+
+## 发布后收尾
+
+`VERIFIED` 不代表要自动修改开发分支或本机宿主。进入 `release-finish` 后，只有用户明确同意，才执行对应的本地动作。本机插件更新失败不会改变发布终态。
+核心 prepare、publish、verify 流程跨平台；WorkBuddy 的本机收尾探测和更新仅支持 macOS。
+
+## 烟雾测试
+
+- 在 `os.tmpdir()` 创建隔离目录
+- 执行 `npm install <package>@<version>` 带安全标志
+- 验证安装的 `package.json` name 和 version 精确匹配
+- 无条件静态验证已安装包中具体 `bin`/`main`/`module`/`types`/`typings`/`exports`
+  目标是普通文件；失败时不得写入 `VERIFIED`
+- 若配置了 `smokeBin`：验证 bin 路径安全（无逃逸、无 symlink），从精确安装根、隔离 HOME 和最小环境执行并验证输出；这会运行已安装代码，必须显式授权
+- 若未配置 `smokeBin`：跳过运行代码，但静态入口闭包检查仍然强制执行
+
+## 常见错误
+
+| 场景 | 状态 | 处理 |
+|------|------|------|
+| 源 run 非 PUBLISHED | GATE_FAILED | 拒绝执行；VERIFIED 是终态 |
+| 源 run 有 incomplete checkpoint | GATE_FAILED | 拒绝执行 |
+| 远端状态不匹配 | POST_PUBLISH_VERIFY_FAILED | 停止 |
+| npm 安装失败 | POST_PUBLISH_VERIFY_FAILED | 停止 |
+| CLI 烟雾输出不匹配 | POST_PUBLISH_VERIFY_FAILED | 停止 |
+| consumer gate / smokeBin 执行失败 | GATE_FAILED | 检查失败原因，修复后重试 |

package/adapters/qoder/src/schemas/adapter-build-manifest.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/adapter-build-manifest.json",
+  "title": "Skill Family adapter build manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "hostId", "pathCategory", "sourceClosure", "members", "digest"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "skill-family.adapter-build-manifest" },
+    "hostId": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,63}$" },
+    "pathCategory": { "$ref": "#/$defs/category" },
+    "sourceClosure": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["digest", "members"],
+      "properties": {
+        "digest": { "$ref": "#/$defs/sha256" },
+        "members": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/sourceMember" } }
+      }
+    },
+    "members": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/outputMember" } },
+    "digest": { "$ref": "#/$defs/sha256" }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "relativePath": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\)(?!.*\\u0000)[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$" },
+    "category": {
+      "type": "object", "additionalProperties": false, "required": ["id", "scope", "anchor", "relPath"],
+      "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,63}$" }, "scope": { "enum": ["user", "project"] }, "anchor": { "enum": ["user-home", "project-root"] }, "relPath": { "$ref": "#/$defs/relativePath" } }
+    },
+    "sourceMember": {
+      "type": "object", "additionalProperties": false, "required": ["sourcePath", "sha256", "bytes"],
+      "properties": { "sourcePath": { "$ref": "#/$defs/relativePath" }, "sha256": { "$ref": "#/$defs/sha256" }, "bytes": { "type": "integer", "minimum": 0 } }
+    },
+    "outputMember": {
+      "type": "object", "additionalProperties": false, "required": ["sourcePath", "target", "sha256", "bytes"],
+      "properties": { "sourcePath": { "$ref": "#/$defs/relativePath" }, "target": { "$ref": "#/$defs/relativePath" }, "sha256": { "$ref": "#/$defs/sha256" }, "bytes": { "type": "integer", "minimum": 0 } }
+    }
+  }
+}

package/adapters/qoder/src/schemas/adapter-peer-verification-request.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/adapter-peer-verification-request.json",
+  "title": "Skill Family peer adapter verification request",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "skillFamilyId", "peers"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "skill-family.adapter-peer-verification-request" },
+    "skillFamilyId": { "$ref": "#/$defs/id" },
+    "peers": {
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 16,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["peerId", "hostId", "pathCategory", "logicalMappings"],
+        "properties": {
+          "peerId": { "$ref": "#/$defs/id" },
+          "hostId": { "$ref": "#/$defs/id" },
+          "pathCategory": { "$ref": "#/$defs/category" },
+          "logicalMappings": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 128,
+            "items": { "$ref": "#/$defs/logicalMapping" }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,63}$" },
+    "relativePath": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\)(?!.*\\u0000)[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$" },
+    "category": {
+      "type": "object", "additionalProperties": false, "required": ["id", "scope", "anchor", "relPath"],
+      "properties": { "id": { "$ref": "#/$defs/id" }, "scope": { "enum": ["user", "project"] }, "anchor": { "enum": ["user-home", "project-root"] }, "relPath": { "$ref": "#/$defs/relativePath" } }
+    },
+    "logicalMapping": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["logicalId", "skillId", "sourcePath", "entryType", "userInvocable"],
+      "properties": {
+        "logicalId": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,63}$" },
+        "skillId": { "$ref": "#/$defs/id" },
+        "sourcePath": { "$ref": "#/$defs/relativePath" },
+        "entryType": { "const": "skill" },
+        "userInvocable": { "type": "boolean" }
+      }
+    }
+  }
+}

package/adapters/qoder/src/schemas/adapter-peer-verification-result.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/adapter-peer-verification-result.json",
+  "title": "Skill Family peer adapter verification result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "status", "decision", "skillFamilyId", "commonSourceClosure", "peers"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "skill-family.adapter-peer-verification-result" },
+    "status": { "const": "verified" },
+    "decision": { "const": "peer-verification" },
+    "skillFamilyId": { "$ref": "#/$defs/id" },
+    "commonSourceClosure": { "$ref": "https://contracts.skill-family.example/v1/adapter-build-manifest.json#/properties/sourceClosure" },
+    "peers": {
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 16,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["peerId", "hostId", "pathCategory", "manifest", "logicalMappings"],
+        "properties": {
+          "peerId": { "$ref": "#/$defs/id" },
+          "hostId": { "$ref": "#/$defs/id" },
+          "pathCategory": { "$ref": "https://contracts.skill-family.example/v1/adapter-peer-verification-request.json#/$defs/category" },
+          "manifest": { "$ref": "https://contracts.skill-family.example/v1/adapter-build-manifest.json" },
+          "logicalMappings": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 128,
+            "items": { "$ref": "#/$defs/resultMapping" }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,63}$" },
+    "resultMapping": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["logicalId", "skillId", "sourcePath", "target", "entryType", "userInvocable"],
+      "properties": {
+        "logicalId": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,63}$" },
+        "skillId": { "$ref": "https://contracts.skill-family.example/v1/adapter-peer-verification-request.json#/$defs/id" },
+        "sourcePath": { "$ref": "https://contracts.skill-family.example/v1/adapter-peer-verification-request.json#/$defs/relativePath" },
+        "target": { "$ref": "https://contracts.skill-family.example/v1/adapter-peer-verification-request.json#/$defs/relativePath" },
+        "entryType": { "const": "skill" },
+        "userInvocable": { "type": "boolean" }
+      }
+    }
+  }
+}

package/adapters/qoder/src/schemas/adapter-source.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/adapter-source.json",
+  "title": "Skill Family adapter source",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "skillFamilyId", "skills"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "skill-family.adapter-source" },
+    "skillFamilyId": { "$ref": "#/$defs/id" },
+    "skills": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "files"],
+        "properties": {
+          "id": { "$ref": "#/$defs/id" },
+          "files": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["path", "content"],
+              "properties": {
+                "path": { "$ref": "#/$defs/relativePath" },
+                "content": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,63}$" },
+    "relativePath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\)(?!.*\\u0000)[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$"
+    }
+  }
+}

package/adapters/qoder/src/schemas/audit-baseline-pin.schema.json

@@ -0,0 +1,163 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/audit-baseline-pin.json",
+  "title": "AuditBaselinePin",
+  "description": "Audit baseline pin contract (GAP-5 / SG-28, FVD-005 lineage). The frozen document an independent audit uses to pin one approved Contracts version: the audit-surface digest, per-document digests (registry, error codes, rules, kernel protocol), per-schema digests, and the frozen engine facts. Pins are append-only, one file per contracts version, generated mechanically from describeAuditSurface(); a live surface that no longer matches its pin is AUD-BASE-001, a failed pin/lock comparison is AUD-LOCK-001 (codes owned by the audit namespace). The supersedes field records the predecessor pin file name so the pin lineage stays mechanically traceable.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "kind",
+    "provenance",
+    "frozenAt",
+    "contractsVersion",
+    "auditSurfaceVersion",
+    "digestAlgorithm",
+    "note",
+    "surfaceDigest",
+    "documentDigests",
+    "schemaDigests",
+    "facts"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "skill-family.audit-baseline-pin" },
+    "provenance": {
+      "enum": ["product-compatibility-fixture", "independent-audit"],
+      "description": "Authorship class of the pin. product-compatibility-fixture: generated mechanically on the product side from describeAuditSurface(); independent-audit: authored by an independent audit consumer."
+    },
+    "frozenAt": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+      "description": "Calendar date (YYYY-MM-DD) on which the pin was frozen."
+    },
+    "contractsVersion": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "Contracts version this pin freezes."
+    },
+    "auditSurfaceVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Audit consumption surface version the pin was derived from."
+    },
+    "digestAlgorithm": {
+      "const": "sha256",
+      "description": "Digest algorithm; sha256 is the only admitted value."
+    },
+    "note": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable provenance note."
+    },
+    "supersedes": {
+      "type": "string",
+      "pattern": "^contracts-[0-9]+\\.[0-9]+\\.[0-9]+\\.pin\\.json$",
+      "description": "File name of the predecessor baseline pin this pin supersedes (FVD-005 lineage); omitted only for the first pin of a lineage."
+    },
+    "surfaceDigest": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$",
+      "description": "sha256 hex of the canonical JSON of the full audit surface (digestAuditSurface)."
+    },
+    "documentDigests": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["registry", "errorCodes", "rules", "kernelProtocol"],
+      "properties": {
+        "registry": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "errorCodes": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "rules": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "kernelProtocol": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+      }
+    },
+    "schemaDigests": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+      "description": "Map of schema $id to the sha256 hex digest of the canonical JSON of that schema document."
+    },
+    "facts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "contractObjects",
+        "checkTypes",
+        "mandatoryRuleIds",
+        "ruleBudget",
+        "errorCodes",
+        "kernelOperations",
+        "kernelTerminalStates",
+        "validationPolicies",
+        "supportedDialects",
+        "errorCodeStabilityPolicy",
+        "schemaIdNamespace"
+      ],
+      "properties": {
+        "contractObjects": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "checkTypes": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "mandatoryRuleIds": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "ruleBudget": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["firstVersionMax", "absoluteMax"],
+          "properties": {
+            "firstVersionMax": { "type": "integer", "minimum": 1 },
+            "absoluteMax": { "type": "integer", "minimum": 1 }
+          }
+        },
+        "errorCodes": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^SFC[0-9]{4}$" }
+        },
+        "kernelOperations": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "kernelTerminalStates": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "validationPolicies": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": {
+              "anyOf": [{ "type": "boolean" }, { "type": "string" }]
+            }
+          }
+        },
+        "supportedDialects": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "errorCodeStabilityPolicy": { "type": "string", "minLength": 1 },
+        "schemaIdNamespace": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/adapters/qoder/src/schemas/declared-read-surface-result.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/declared-read-surface-result.json",
+  "title": "DeclaredReadSurfaceResult",
+  "description": "Static verification result for a declared fs read surface (FND-ADR-010). The mechanism collects every `.mjs`/`.js` module under the scanned root, compares each module's `import {...} from \"node:fs\"` named imports against the consumer-declared reader set, and forbids every write-family fs API across the whole tree. The verdict semantics are a closed three-rule enumeration carried in violations[].rule: undeclared-module-imports-fs, fs-api-outside-declared-set, write-family-fs-api. Scope and bias direction are declared in the contract: static syntax surface only (ESM named imports plus whole-source substring detection), conservative approximation (comments and string literals containing write-family API names also hit; static syntax-level violations are never under-reported), no execution of the scanned modules, no model call, no network. The result carries no timestamp.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "kind",
+    "ok",
+    "violations",
+    "scannedModules",
+    "scope",
+    "guarantees"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "skill-family.declared-read-surface-result" },
+    "ok": { "type": "boolean" },
+    "violations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["module", "rule"],
+        "properties": {
+          "module": { "type": "string", "minLength": 1 },
+          "api": { "type": "string", "minLength": 1 },
+          "rule": {
+            "enum": [
+              "undeclared-module-imports-fs",
+              "fs-api-outside-declared-set",
+              "write-family-fs-api"
+            ]
+          }
+        }
+      }
+    },
+    "scannedModules": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "scope": { "const": "esm-named-imports-only" },
+    "guarantees": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "syntax-surface-only",
+          "conservative-approximation",
+          "no-execution",
+          "no-model-calls",
+          "no-network-access"
+        ]
+      }
+    }
+  }
+}

package/adapters/qoder/src/schemas/engineering-baseline.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/engineering-baseline.json",
+  "title": "EngineeringBaseline",
+  "description": "Business-neutral identity for an engineering baseline. The contract carries the provider-owned baseline identity, canonical rule lineage references, and the Foundation reference implementation identity; it does not carry rule bodies, effects, equivalence, or exemption semantics.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "kind",
+    "provider",
+    "id",
+    "version",
+    "digest",
+    "canonicalRuleRefs",
+    "referenceImplementation"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "skill-family.engineering-baseline" },
+    "provider": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Provider that owns the baseline identity, for example an independent Audit implementation."
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Provider-scoped stable baseline identifier."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "Semantic version of the provider-owned baseline identity."
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$",
+      "description": "SHA-256 digest of the canonical JSON of this document with digest omitted."
+    },
+    "canonicalRuleRefs": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/canonicalRuleRef" },
+      "description": "Sorted, unique references to provider-owned canonical rule lineages. Rule bodies and decisions remain outside this contract."
+    },
+    "referenceImplementation": {
+      "$ref": "#/$defs/referenceImplementation",
+      "description": "Identity of the Foundation reference implementation used by the baseline provider."
+    }
+  },
+  "$defs": {
+    "canonicalRuleRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "revision", "revisionDigest"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "revision": { "type": "integer", "minimum": 1 },
+        "revisionDigest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+      }
+    },
+    "referenceImplementation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["foundationVersion", "profile", "skeletonDigest"],
+      "properties": {
+        "foundationVersion": {
+          "type": "string",
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
+        },
+        "profile": { "type": "string", "minLength": 1 },
+        "skeletonDigest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+      }
+    }
+  }
+}