release-skill 0.9.17 → 0.9.18

package/adapters/cursor/skills/release-setup/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: release-setup
+description: "首次接入 release-skill：只读发现发布单元与个性化验证候选，机械提取提案，经人工确认 setupDigest 后仅首次创建配置"
+---
+
+> **Cursor 安装入口解析协议**：在调用 CLI 前，Agent 必须从宿主当前已加载技能的元数据中取得本 `SKILL.md` 的实际绝对路径，并将该字面量记为 `SKILL_FILE`。
+> `SKILL_FILE` 不是环境变量；禁止从工作目录、可执行搜索路径、源码仓库或 shell 调用上下文猜测。若宿主未提供该绝对路径，立即停止并报告安装定位失败。
+> 对 `SKILL_FILE` 执行 `realpath`，取其目录向上两级得到 `PLUGIN_ROOT`；校验真实技能路径匹配 `PLUGIN_ROOT/skills/*/SKILL.md` 且仍位于插件根内（路径包含检查）。
+> 校验 `PLUGIN_ROOT/.cursor-plugin/plugin.json` 是根内的普通文件，且名称为 `release-skill`；清单缺失或不一致时停止。Cursor 不保证注入插件根变量。
+> 令 `RELEASE_SKILL_ENTRY=PLUGIN_ROOT/bin/release-skill.mjs`，对入口执行 `realpath` containment、`lstat` 非符号链接且为普通文件校验。
+> 每一次 shell 工具调用都必须在同一个调用中用上述已验证绝对值设置 `RELEASE_SKILL_ENTRY`，然后执行 `node "$RELEASE_SKILL_ENTRY" ...`；不得依赖前一次 shell 的变量。
+>
+
+# release-setup
+
+## 适用场景
+
+项目尚无 `.release-skill/project.yaml`，或用户要求初始化、接入、校准发布规则时使用。配置已存在时只审计并路由到 `release-assess`，不得重新生成。
+
+## 硬边界
+
+- 默认只读。README、slogan、CHANGELOG、业务脚本和已有配置均为人工权威内容，不得重写或覆盖。
+- 发现脚本不等于选择或授权。间接脚本以 `SIDE_EFFECTS_UNPROVEN` 排除；项目特有 hook/gate 只能人工增量注册。
+- 仓库、公开文件等证据冲突时停止自动提案，交给人工修正权威事实后重新发现。
+- npm 单元只读提取 `package.json` 的具体入口和旧 `npmRequiredPackagePaths`，报告
+  tracked/untracked/ignored/missing/non-regular 状态与覆盖漂移；这些是人工复核候选，
+  不得自动写入 `publicFiles` 或 `requiredPublicFiles`。
+- 写入只允许 create-once（仅创建一次），必须同时提供 answers 与精确 `setupDigest`；无安全原生写入能力时失败关闭。
+- Agent 的多次 shell 调用彼此独立；只能用首轮打印的会话目录绝对路径续接，不得假设变量仍存在。
+
+## 首次接入
+
+1. 检查入口：
+
+```bash
+node "$RELEASE_SKILL_ENTRY" help --json
+```
+
+2. 只读发现并机械提取提案。完整报告仅写入临时会话目录；不要设置 `trap EXIT`，确认前必须保留会话文件：
+
+```bash
+set -eu
+PROJECT=<项目绝对路径>
+SETUP_SESSION="$(mktemp -d "${TMPDIR:-/tmp}/release-setup.XXXXXX")"
+REPORT="$SETUP_SESSION/discovery.json"
+ANSWERS="$SETUP_SESSION/answers.json"
+printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
+set +e
+node "$RELEASE_SKILL_ENTRY" setup --root "$PROJECT" --json > "$REPORT"
+SETUP_STATUS=$?
+set -e
+[ "$SETUP_STATUS" -eq 0 ] || [ "$SETUP_STATUS" -eq 2 ] || exit "$SETUP_STATUS"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.compactSummary){console.error("compactSummary missing");process.exit(2)}process.stdout.write(JSON.stringify(r.compactSummary,null,2)+"\n")' "$REPORT"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if((r.proposalConflicts??[]).length){console.error("proposal conflicts require human resolution");process.exit(2)}if(!r.recommendedAnswers){console.error("recommendedAnswers missing");process.exit(2)}fs.writeFileSync(process.argv[2],JSON.stringify(r.recommendedAnswers,null,2)+"\n",{flag:"wx",mode:0o600})' "$REPORT" "$ANSWERS"
+```
+
+若 `proposalConflicts` 非空，暂停，让用户修正仓库/映射权威事实或 npm 入口候选，
+删除本会话目录后从第 2 步重跑，不得猜测选边。构建后才产生且被忽略的入口应先由
+人工确认构建流程与最终 tarball 边界，不能因为 setup 发现了路径就自动信任或纳入公开
+配置。无冲突时可人工增量编辑 `answers.json`：hook 写入
+`recommendedAnswers.projectConfig.hooks` 对应的 `projectConfig.hooks`；gate 写入
+`verificationGates`，并把同一 id 加入 `selectedGateIds`。人工文件保持
+`mode: preserve`，跨单元共享源使用 `sourceScope: workspace`。
+
+3. 使用上一步打印的两个绝对字面量重新赋值，运行绑定 dry-run；任何人工编辑后都必须重跑本步：
+
+```bash
+set -eu
+SETUP_SESSION=<上一步打印的会话目录绝对路径>
+PROJECT=<上一步打印的项目绝对路径>
+ANSWERS="$SETUP_SESSION/answers.json"
+BOUND_REPORT="$SETUP_SESSION/bound.json"
+node "$RELEASE_SKILL_ENTRY" setup --root "$PROJECT" --answers "$ANSWERS" --json > "$BOUND_REPORT"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.compactSummary||!r.setupDigest){console.error("bound setup report incomplete");process.exit(2)}process.stdout.write(JSON.stringify({compactSummary:r.compactSummary,setupDigest:r.setupDigest},null,2)+"\n")' "$BOUND_REPORT"
+printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
+```
+
+只向用户展示绑定摘要、配置差异和精确 `setupDigest`，取得一次明确确认。
+
+4. 确认后用原会话与已确认摘要首次创建。三个完整报告均重定向到文件，固定提取器成功后才清理会话目录：
+
+```bash
+set -eu
+SETUP_SESSION=<已确认会话目录的绝对路径>
+PROJECT=<已确认项目的绝对路径>
+CONFIRMED_SETUP_DIGEST=<用户确认的精确 setupDigest>
+ANSWERS="$SETUP_SESSION/answers.json"
+CREATED_REPORT="$SETUP_SESSION/created.json"
+POST_REPORT="$SETUP_SESSION/post-setup.json"
+ASSESS_REPORT="$SETUP_SESSION/assess.json"
+node "$RELEASE_SKILL_ENTRY" setup --root "$PROJECT" --answers "$ANSWERS" --write --confirm-setup "$CONFIRMED_SETUP_DIGEST" --json > "$CREATED_REPORT"
+node "$RELEASE_SKILL_ENTRY" setup --root "$PROJECT" --json > "$POST_REPORT"
+set +e
+node "$RELEASE_SKILL_ENTRY" assess --root "$PROJECT" --offline --json > "$ASSESS_REPORT"
+ASSESS_EXIT=$?
+set -e
+[ "$ASSESS_EXIT" -eq 0 ] || [ "$ASSESS_EXIT" -eq 1 ] || exit "$ASSESS_EXIT"
+node -e 'const fs=require("node:fs");const [c,p,a]=process.argv.slice(1).map(x=>JSON.parse(fs.readFileSync(x,"utf8")));if(c.status!=="CONFIG_CREATED"||p.status!=="ALREADY_CONFIGURED"){console.error("setup lifecycle verification failed");process.exit(2)}if(!["ASSESSED","NEEDS_INPUT","BLOCKED"].includes(a.status)){console.error("assessment report invalid");process.exit(2)}const blocking=(a.gaps??[]).filter(g=>g.severity==="error").map(({code,scope,message})=>({code,scope,message}));process.stdout.write(JSON.stringify({created:{status:c.status,compactSummary:c.compactSummary},postSetup:{status:p.status,compactSummary:p.compactSummary},assessment:{status:a.status,summary:a.summary,gapCount:(a.gaps??[]).length,blockingGaps:blocking}},null,2)+"\n")' "$CREATED_REPORT" "$POST_REPORT" "$ASSESS_REPORT"
+node -e 'require("node:fs").rmSync(process.argv[1],{recursive:true,force:false})' "$SETUP_SESSION"
+```
+
+## 接入评估（只读）
+
+对已配置项目运行接入评估，报告已满足、必选缺口、可选建议和不适用项；对未配置项目返回 `NOT_CONFIGURED` 并指向首次 setup：
+
+```bash
+node "$RELEASE_SKILL_ENTRY" setup --assess-adoption --root "$PROJECT" --json
+```
+
+- 完全只读：评估后仓库不新增任何文件，不修改配置，不执行 hook。
+- 报告四态：`NOT_CONFIGURED`、`PARTIALLY_ADOPTED`、`ADOPTED`、`ADOPTED_WITH_SUGGESTIONS`。
+- findings 分四类：`mandatory-gap`（必选缺口，阻断接入）、`satisfied`（已满足）、`optional-suggestion`（可选建议）、`not-applicable`（不适用）；每条带 `code`、`fieldPath`、`evidence` 与 `action`。
+- 建议边界：hook 缓存候选只提示 `cacheInputs` 必须由项目自己声明并证明完整，评估不代猜、不代写；hook 耗时只从描述匹配且生产者可信的 started/completed 事件对推导，`timeoutMs` 不是实际成本；任何建议都不改变接入状态。
+- 必选缺口存在时先修复并重跑 `setup --assess-adoption`，再进入发布流程。
+
+## publisher 字段与个人片段泄漏策略
+
+setup 生成的 `.release-skill/project.yaml` 中 `publisher` 是**已批准的公开发布身份**：它是人工确认的对外发布署名，属于公开面的一部分，而非需要隐藏的私有信息。
+
+若目标仓库用“个人片段”类泄漏策略扫描仓树，而该策略按片段匹配恰好覆盖到 `publisher` 字段，正确做法不是删除或改写策略，而是由贡献者在**本地、gitignore 的个人片段 overlay** 中为该规则声明位置豁免（如 `approvedPlacements`：限定 `publisher` 所在的确切文件路径与行键前缀）。豁免只放行已批准的放置位置，其余出现照常命中；overlay 不入库，个人片段本身不进 committed 策略。
+
+## 故障路由
+
+- `NEEDS_INPUT`：审阅紧凑摘要；有冲突先修正权威事实并重跑。
+- `LOCAL_ONLY_DETECTED`：只能建立本地配置，由用户决定是否创建远端渠道。
+- `ALREADY_CONFIGURED` / `CONFIG_EXISTS`：不覆盖，转 `release-assess`。
+- `SETUP_DIGEST_MISMATCH`：事实或 answers 已变化，重新只读发现与确认。
+- `SAFE_WRITE_UNAVAILABLE`：保留只读报告，不启用普通路径写入兜底。
+
+## 完成标准
+
+完整报告未进入 Agent 上下文；跨 shell 只靠显式会话路径续接；无冲突提案由机器机械提取；写入仅创建一次且摘要精确匹配；创建后状态和 assess 只输出紧凑结果；人工文件保持原字节。

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

@@ -0,0 +1,110 @@
+---
+name: release-verify
+description: Post-publish verification including remote state recheck, exact npm installation smoke, and consumer plugin install verification
+---
+
+> **Cursor 安装入口解析协议**：在调用 CLI 前，Agent 必须从宿主当前已加载技能的元数据中取得本 `SKILL.md` 的实际绝对路径，并将该字面量记为 `SKILL_FILE`。
+> `SKILL_FILE` 不是环境变量；禁止从工作目录、可执行搜索路径、源码仓库或 shell 调用上下文猜测。若宿主未提供该绝对路径，立即停止并报告安装定位失败。
+> 对 `SKILL_FILE` 执行 `realpath`，取其目录向上两级得到 `PLUGIN_ROOT`；校验真实技能路径匹配 `PLUGIN_ROOT/skills/*/SKILL.md` 且仍位于插件根内（路径包含检查）。
+> 校验 `PLUGIN_ROOT/.cursor-plugin/plugin.json` 是根内的普通文件，且名称为 `release-skill`；清单缺失或不一致时停止。Cursor 不保证注入插件根变量。
+> 令 `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/cursor/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/cursor/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/cursor/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/cursor/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/cursor/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 }
+      }
+    }
+  }
+}