release-skill 0.8.1 → 0.9.1

package/adapters/codex/bin/rules.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "kind": "skill-family.contracts.rules",
-  "contractsVersion": "1.13.0",
+  "contractsVersion": "1.14.0",
   "budget": {
     "firstVersionMax": 20,
     "absoluteMax": 30,

package/adapters/codex/bin/schemas/consumer-contract-vector.schema.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/consumer-contract-vector.json",
+  "title": "ConsumerContractVector",
+  "description": "A public, version-bound input and expected-observation vector for a Foundation consumer contract.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "vectorId", "vectorSetId", "capabilityId", "foundationVersion", "contractId", "caseClass", "strategy", "request", "expected"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "skill-family.consumer-contract-vector" },
+    "vectorId": { "type": "string", "minLength": 1 },
+    "vectorSetId": { "type": "string", "minLength": 1 },
+    "capabilityId": { "type": "string", "minLength": 1 },
+    "foundationVersion": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "contractId": { "type": "string", "minLength": 1 },
+    "caseClass": { "enum": ["positive", "negative", "indeterminate"] },
+    "strategy": { "enum": ["real-pure", "official-fake"] },
+    "request": { "type": "object" },
+    "expected": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["outcome", "valueRelation"],
+          "properties": {
+            "outcome": { "const": "return" },
+            "valueRelation": { "const": "atomic-write-contained-absolute-target" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["outcome", "value"],
+          "properties": {
+            "outcome": { "const": "return" },
+            "value": {}
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["outcome", "errorCode"],
+          "properties": {
+            "outcome": { "const": "throw" },
+            "errorCode": { "type": "string", "pattern": "^SFC[0-9]{4}$" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["outcome", "errorCode", "errorKind"],
+          "properties": {
+            "outcome": { "const": "throw" },
+            "errorCode": { "type": "string", "pattern": "^SFC[0-9]{4}$" },
+            "errorKind": { "const": "path-traversal" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["outcome", "allowedStates", "failClosed"],
+          "properties": {
+            "outcome": { "const": "indeterminate" },
+            "allowedStates": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "enum": ["return", "throw", "indeterminate"] },
+              "uniqueItems": true
+            },
+            "failClosed": { "const": true }
+          }
+        }
+      ]
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "capabilityId": { "const": "foundation.harness.atomic-write" } },
+        "required": ["capabilityId"]
+      },
+      "then": {
+        "properties": {
+          "request": {
+            "type": "object",
+            "required": ["root"],
+            "properties": { "root": { "$ref": "#/$defs/atomicRoot" } }
+          }
+        }
+      },
+      "else": {
+        "properties": {
+          "request": {
+            "type": "object",
+            "properties": {
+              "root": {
+                "not": {
+                  "type": "object",
+                  "required": ["runtimeBinding"],
+                  "properties": { "runtimeBinding": { "const": "atomic-write-canonical-root" } }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "capabilityId": { "const": "foundation.harness.atomic-write" },
+          "caseClass": { "const": "negative" }
+        },
+        "required": ["capabilityId", "caseClass"]
+      },
+      "then": {
+        "properties": {
+          "expected": {
+            "type": "object",
+            "required": ["errorKind"],
+            "properties": { "errorKind": { "const": "path-traversal" } }
+          }
+        }
+      },
+      "else": {
+        "properties": {
+          "expected": {
+            "type": "object",
+            "not": {
+              "required": ["errorKind"],
+              "properties": { "errorKind": true }
+            }
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "atomicRoot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runtimeBinding"],
+      "properties": {
+        "runtimeBinding": { "const": "atomic-write-canonical-root" }
+      }
+    }
+  }
+}

package/adapters/codex/schemas/release-plan.schema.json

@@ -17,9 +17,10 @@
       "type": "integer",
       "enum": [
         1,
-        2
+        2,
+        3
       ],
-      "description": "Plan format and digest-scoping version. 1: legacy (every field except the top-level digest binds; commitTimestamp must equal createdAt). 2: T1.2 digest layering (record-layer fields status/createdAt/baseline/per-action status are excluded from the plan digest; commitTimestamp is derived from the HEAD commit committer date)."
+      "description": "Plan format and digest-scoping version. 1: legacy (every field except the top-level digest binds; commitTimestamp must equal createdAt). 2: T1.2 digest layering (record-layer fields status/createdAt/baseline/per-action status are excluded from the plan digest; commitTimestamp is derived from the HEAD commit committer date). 3: multi-release-unit postPublish v3 (postPublish is a declaration ARRAY, one entry per declaring unit in plan.units order, possibly empty; v3 inherits the v2 record-layer semantics and only changes the postPublish shape)."
     },
     "status": {
       "type": "string",
@@ -1121,7 +1122,11 @@
       }
     },
     "postPublish": {
-      "$ref": "#/definitions/planPostPublish"
+      "type": [
+        "object",
+        "array"
+      ],
+      "description": "Frozen post-release distribution block. planVersion 1/2: a single declaration object, or absent (normalized to the empty array view at runtime). planVersion 3: a declaration ARRAY, one entry per declaring unit in plan.units order, possibly empty — never a single object, never absent. The exact allowed shape is enforced conditionally on planVersion (root allOf); readers must never guess the shape from the field value."
     },
     "digest": {
       "type": "string",
@@ -1844,6 +1849,38 @@
     }
   },
   "allOf": [
+    {
+      "if": {
+        "properties": {
+          "planVersion": {
+            "const": 3
+          }
+        },
+        "required": [
+          "planVersion"
+        ]
+      },
+      "then": {
+        "properties": {
+          "postPublish": {
+            "type": "array",
+            "items": {
+              "$ref": "#/definitions/planPostPublish"
+            }
+          }
+        },
+        "required": [
+          "postPublish"
+        ]
+      },
+      "else": {
+        "properties": {
+          "postPublish": {
+            "$ref": "#/definitions/planPostPublish"
+          }
+        }
+      }
+    },
     {
       "if": {
         "properties": {

package/adapters/codex/skills/release-finish/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: release-finish
+description: 发布达到 VERIFIED 后处理可选的本地收尾：按发布分支策略决定是否询问合并，并在用户确认后更新本机 Claude、Codex、Kimi、CodeBuddy/WorkBuddy 插件
+---
+
+> **Codex 安装入口解析协议**：在调用 CLI 前，Agent 必须从宿主当前已加载技能的元数据中取得本 `SKILL.md` 的实际绝对路径，并将该字面量记为 `SKILL_FILE`。
+> `SKILL_FILE` 不是环境变量；禁止从工作目录、可执行搜索路径、源码仓库或 shell 调用上下文猜测。若宿主未提供该绝对路径，立即停止并报告安装定位失败。
+> 对 `SKILL_FILE` 执行 `realpath`，取其目录向上两级得到 `PLUGIN_ROOT`；校验真实技能路径匹配 `PLUGIN_ROOT/skills/*/SKILL.md` 且仍位于插件根内（路径包含检查）。
+> 令 `RELEASE_SKILL_LOCAL_FINISH_ENTRY=PLUGIN_ROOT/bin/release-skill-local-finish.mjs`，对入口执行 `realpath` containment、`lstat` 非符号链接且为普通文件校验。
+> 每一次 shell 工具调用都必须在同一个调用中用上述已验证绝对值设置 `RELEASE_SKILL_LOCAL_FINISH_ENTRY`，然后执行 `node "$RELEASE_SKILL_LOCAL_FINISH_ENTRY" ...`；不得依赖前一次 shell 的变量。
+>
+
+# release-finish
+
+## 触发
+
+发布刚达到 `VERIFIED`（已完成发布后验证），或用户要求处理发布后的分支合并、本机宿主插件更新。
+
+## 边界
+
+这是发布后的独立收尾，不属于 `prepare → approve → publish → verify` 状态机。它不能把本机更新结果写成新的发布状态，也不能因为本机更新失败而降低 `VERIFIED`。
+
+默认只读取冻结计划和 verify run。没有用户明确同意，不合并分支，不更新插件，不接受 Kimi 的安装信任提示。
+
+## 先生成收尾清单
+
+从插件根执行：
+
+```bash
+node "$RELEASE_SKILL_LOCAL_FINISH_ENTRY" \
+  --plan <plan-path> \
+  --run <verified-run-path> \
+  --json
+```
+
+脚本只接受状态为 `VERIFIED`、且 `planDigest` 与冻结计划一致的 verify run。
+
+## 主动询问
+
+读取返回的 `merge` 和 `localHostUpdate`：
+
+1. `merge.promptRequired=false` 时，发布工作流已经推进或初始化目标分支，不再询问合并。
+2. `merge.promptRequired=true` 时，向用户说明尚未覆盖的发布分支，并询问是否需要合并。用户同意后，先只读核对源分支、目标分支、工作区状态和项目既有合并方式，再用明确的分支名执行；本脚本不猜分支，也不自动推送。
+3. `localHostUpdate.promptRequired=true` 时，列出计划覆盖的宿主，询问是否更新本机插件。两个问题可以一次问完。
+
+## 用户同意更新本机宿主
+
+把用户选择的宿主和清单返回的精确 `planDigest` 传回脚本：
+
+```bash
+node "$RELEASE_SKILL_LOCAL_FINISH_ENTRY" \
+  --plan <plan-path> \
+  --run <verified-run-path> \
+  --update-local-hosts \
+  --hosts claude,codex,kimi,codebuddy,workbuddy \
+  --confirm-plan <planDigest> \
+  --json
+```
+
+只传用户选择且计划声明的宿主。宿主 CLI 不存在时返回 `SKIPPED_NOT_INSTALLED`。各宿主按以下规则处理：
+
+- Claude 先重新绑定冻结市场，再重新观察安装状态；旧插件若仍存在，才调用正式更新命令。Codex 继续按正式市场协议移除并安装冻结的 Git 引用。两者都在安装后核对插件、市场、版本和市场检出提交。
+- Kimi 的精确当前安装会在返回 `ALREADY_CURRENT` 前核对真实载荷；发生安装或迁移时，只在操作完成后核对结果。包名、版本、发布标签、已安装修订号和受管安装根必须与冻结计划一致；`.git` 只提供附加诊断，不是通过条件。旧的本地路径安装会在同一个受控终端交互界面（TUI）会话中先移除，再按发布标签安装、确认信任并重新加载。
+- CodeBuddy/WorkBuddy 只处理同一 bundled-family 插件和市场。只有冻结标签与计划声明的可变分支都从同一远端解析到冻结提交时，才调用正式市场更新和插件更新命令；完成后重新读取安装列表，并精确核对唯一条目的市场、版本和修订号。目标未安装、来源不符、远端不可访问或身份不一致时返回 `MANUAL_REQUIRED`，不修改宿主。
+
+任何宿主失败都保留其他宿主的实际结果，不回滚，也不把失败冒充成功。
+
+完成后报告每个宿主的状态，并提醒用户重启已更新的宿主。本机结果只记录收尾事实，不改变发布状态。
+
+## 临时归属
+
+本能力目前只服务发布后的本机收尾，因此保留在 release-skill。第二个技能族需要复用宿主更新或 TUI 驱动，或 Foundation 发布等价公共入口时，再把通用机制上收 Foundation并删除这里的通用部分。release-skill 只保留发布计划到宿主更新输入的领域映射。

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

@@ -19,7 +19,7 @@ description: "Discoverable entry point for release-skill: dependency and environ
 ## 职责
 
 - 依赖和环境检查：Node.js >= 22、Git 决定本地准备就绪度；npm/gh 另行决定生产依赖就绪度
-- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；日常生产发布优先使用可恢复的 `ship`，兼容的分阶段闭环仍是 `prepare --online --production → approve → publish → verify`
+- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；日常生产发布优先使用可恢复的 `ship`，兼容的分阶段闭环仍是 `prepare --online --production → approve → publish → verify`。冻结计划批准是正常发布级流程的唯一批准门；声明 `requiresApproval: true` 的 postPublish hook 仍须等待独立 checkpoint 批准
 - 最小示例：展示从 release-help 到 release-assess 的最短路径
 - 只读诊断：运行 dry-run 检查，不修改任何文件
 - 故障引导：根据错误码指向对应的修复 Skill
@@ -42,7 +42,8 @@ description: "Discoverable entry point for release-skill: dependency and environ
 node "$RELEASE_SKILL_ENTRY" help --json
 node "$RELEASE_SKILL_ENTRY" setup --root <path> --json
 node "$RELEASE_SKILL_ENTRY" assess --root <path> --offline --json
-# 日常发布快速路径：仅在发布前确认一次可读计划摘要，状态文件可恢复
+# 日常发布快速路径：发布前确认可读计划摘要，状态文件可恢复。
+# 受限 postPublish hook 的 checkpoint 批准与计划批准分开。
 node "$RELEASE_SKILL_ENTRY" ship --root <path> --target-version <version> --json
 # 开发阶段执行声明 hooks 并生成 prepare 可复用的内容绑定收据
 # 配置时刻即授权（FM-16 处置 A）：hook 是任意本地进程、无隔离、触发前无确认点，

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

@@ -36,7 +36,7 @@ description: Freeze an immutable release plan with local configuration, document
 2. 配置含 `releaseDocuments` 时，先运行只读演练 `${CLI} docs refresh --unit <id> --json`；`status: "changes"` 时展示逐文件路径/语种/版本/`refreshDigest`，取得"本地发布文档写入"明确授权后才执行 `nextCommand.argv` 写入，审阅并提交刷新结果后再继续；`status: "clean"` 时直接进入 prepare
 3. 运行 `${CLI} prepare --root <path> --offline --json`
 4. 检查 exit code 0，读取 JSON 返回的 immutable `planPath=plans/<planDigest>.json`，再从该文件读取 `status`、`units`、`externalActions`
-5. 向用户展示可读的 `approvalSummary`（版本、仓库/包、branch/tag、外部动作和例外）；`planDigest` 仅作为内部绑定字段，不要求用户复制或确认。后续 approve/publish 只能使用该 immutable planPath，等待确认后再 approve
+5. 向用户展示可读的 `approvalSummary`：版本、公开仓库、分支策略、branch/tag、npm 与 GitHub Release 目标、全部外部动作、例外，以及需要独立 checkpoint 批准的 postPublish hook。`planDigest` 仅作为内部绑定字段，不要求用户复制或确认。后续 approve/publish 只能使用该 immutable planPath，等待确认后再 approve。计划批准不包含受限 postPublish hook 的 checkpoint 批准
 
 若用户明确要求 GitHub+npm 生产发布，加入 `--production`。该模式还会封存独立
 Git commit/tree 和 npm tarball，并把路径、SHA/integrity、branch/tag 写入计划。
@@ -96,4 +96,4 @@ node "$RELEASE_SKILL_ENTRY" prepare --root <path> --online --production --json
 
 ## 后续引导
 
-计划冻结后，读取命令返回的 immutable `planPath` 和 `approvalSummary` 展示给用户，等待确认后再 approve。`planDigest` 由系统自动计算和绑定，不作为人工交互口令。`release-plan.json` 等 latest alias 只用于浏览，不得作为生产 authority 传递。
+计划冻结后，读取命令返回的 immutable `planPath` 和 `approvalSummary` 展示给用户，等待确认后再 approve。`planDigest` 由系统自动计算和绑定，不作为人工交互口令。`release-plan.json` 等 latest alias 只用于浏览，不得作为生产 authority 传递。冻结计划批准是正常发布级流程的唯一批准门；有效 `requiresApproval: true` 的 postPublish hook 仍须使用绑定 `(planDigest, hookId)` 且最长有效 24 小时的独立 checkpoint 批准。

package/adapters/codex/skills/release-publish/SKILL.md

@@ -51,10 +51,12 @@ description: "从已批准的生产计划发布冻结 Git branch/tag、npm tarba
 
 ## 授权门
 
-1. 展示可读的 `approvalSummary`：版本、仓库/包名、branch/tag、全部 actions 和例外。
+1. 展示可读的 `approvalSummary`：版本、公开仓库、分支策略、branch/tag、npm 与 GitHub Release 目标、全部 actions、例外，以及需要独立 checkpoint 批准的 postPublish hook。
 2. 必须存在未过期且由系统绑定同一内部 digest 的 approval record；批准后不再要求用户复制摘要做二次确认。
 3. 只有 CLI exit code 0 且结构化状态为 `PUBLISHED` 才算外写阶段通过；随后必须运行 verify，只有 `VERIFIED` 才是完整终态。
 
+冻结计划批准是正常发布级流程的唯一批准门。它包含计划内的外部动作和验证门禁，不包含有效 `requiresApproval: true` 的 postPublish checkpoint。这类 hook 仍须使用绑定 `(planDigest, hookId)` 且最长有效 24 小时的独立批准记录。
+
 ## 确定性执行
 
 ```bash

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

@@ -49,7 +49,8 @@ verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再
 1. 确认有 `--run` 路径（必需），且源 run 状态为 PUBLISHED
 2. 使用插件根相对路径运行 CLI；命令调用本身即授权执行已配置的 verification gate 和 smoke process
 3. 检查 exit code 和结构化状态：`VERIFIED`（全部通过）/ 失败（具体错误）
-4. 只有 `VERIFIED` 才是 happy end
+4. 只有 `VERIFIED` 才是发布 happy end
+5. 达到 `VERIFIED` 后立即路由 `release-finish`：先生成只读收尾清单，再按清单主动询问分支合并和本机宿主插件更新；发布策略已包含分支动作时略过合并询问
 
 ## 确定性脚本调用
 
@@ -67,6 +68,10 @@ node "$RELEASE_SKILL_ENTRY" verify --root <path> --plan <plan-path> --run <run-p
 5. 对 Claude/Codex marketplace distribution 执行全新隔离消费者安装验证；收集 Kimi/CodeBuddy 的非阻塞 `manualFollowUps`
 6. 全部通过 → `VERIFIED`
 
+## 发布后收尾
+
+`VERIFIED` 不代表要自动修改开发分支或本机宿主。进入 `release-finish` 后，只有用户明确同意，才执行对应的本地动作。本机插件更新失败不会改变发布终态。
+
 ## 烟雾测试
 
 - 在 `os.tmpdir()` 创建隔离目录