release-skill 0.9.17 → 0.9.19

package/skills/release-help/SKILL.md

@@ -7,140 +7,84 @@ description: "Discoverable entry point for release-skill: dependency and environ
 
 ## 触发
 
-用户询问如何使用 release-skill、发布流程是什么、或请求只读诊断和 dry-run 安全检查。
+询问 release-skill 的用法、发布流程、依赖、环境、只读诊断或 dry-run 时使用。本入口只做能力说明和分诊；专用工作流交给对应 Skill。
 
-## 职责
+## 只读边界
 
-- 依赖和环境检查：Node.js >= 22、Git 决定本地准备就绪度；npm/gh 另行决定生产依赖就绪度
-- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；日常生产发布优先使用可恢复的 `ship`，兼容的分阶段闭环仍是 `prepare --online --production → approve → publish → verify`。冻结计划批准是正常发布级流程的唯一批准门；声明 `requiresApproval: true` 的 postPublish hook 仍须等待独立 checkpoint 批准。若计划声明 `postVerify` hook，可用 `postverify` 直接执行独立收尾 run，也可由 `ship` 编排该阶段；本机收尾必须等待完成的 postVerify run，不能把仅有 `VERIFIED` 的 verify run 当作本机收尾授权。核心发布流程跨平台，WorkBuddy 本机收尾仅支持 macOS
-- 最小示例：展示从 release-help 到 release-assess 的最短路径
-- 只读诊断：运行 dry-run 检查，不修改任何文件
-- 故障引导：根据错误码指向对应的修复 Skill
+`help` 不联网、不检查认证、不改文件、不生成计划，也不执行 Git、宿主安装或外部发布写入。它只根据当前环境报告准备度并给出下一步。优先调用插件自带入口；不可用时才回退到源码入口。
 
-## 0.9.17 候选边界
+核心流程跨平台；WorkBuddy 本机收尾仅支持 macOS。Node.js >= 22 和 Git 决定本地准备度。npm、gh 只影响生产发布依赖；pnpm 缺失只进入建议。
 
-当前源码候选允许多发布单元项目在计划冻结前显式选择本轮范围。`prepare` 和新建的 `ship` 状态支持重复传入 `--unit <id>`；未传时继续选择全部配置单元。成功选择会列出选中与延期单元。延期单元不进入本轮计划，也不获得发布状态。
+本地阶段通过须同时满足 `status: "READY"` 和 exit code 0。读取 `readiness.localPreparation.status` 与 `missingRequired`。生产另读 `readiness.productionPublish`：缺 npm/gh 为 `NOT_READY`，已安装也只是 `AUTH_CHECK_REQUIRED`，不代表认证、权限或发布授权已经成立。
 
-选择只影响按单元绑定的检查与动作。完整配置、生成物新鲜度和顶层 Hook 仍覆盖整个项目。`publicSourceAuthorityReceipt` 涉及的 coordinator 和 subjects 必须作为完整闭包共同选择，系统不会自动扩选。计划冻结后，`plan.units` 是唯一范围权威；publish、reconcile、verify 和 distribute 不接受 `--unit`。
+## 0.9.19 候选边界
 
-0.9.3 引入的四项工作流保护、Hook cache v2 和稳定隔离安装树记录在后续版本继续保留。当前 0.9.17 候选精确消费 Foundation 0.17.0 的公开包根 API。Hook cache 只复用绝对路径或经真实 cwd 校验的 cwd-relative executable identity；裸 PATH、PATHEXT、Windows 和观察不可用时，Hook 仍冷执行，缓存复用失败关闭且不写入 v2 cache。缓存没有 TTL。
+当前 0.9.19 候选精确消费 Foundation 0.21.0 的公开包根 API。0.9.19 仍是源码候选，不能从本说明推断已批准、发布或验证。
 
-稳定隔离安装树记录只在宿主命令退出、目录已隔离且扫描期间没有并发写入时执行；宿主附加链接只记录、不跟随，声明载荷中的 symlink 失败关闭，legacy 全树语义保持不变。0.9.17 仍是源码候选，不能从本说明推断已批准、发布或验证。
+冻结前，`prepare` 或新建 `ship` 状态可重复传入 `--unit <id>`；不传则选择全部单元。延期单元不进入计划，也不获得发布状态。完整配置、生成物新鲜度和顶层 Hook 仍覆盖全项目；`publicSourceAuthorityReceipt` 的 coordinator 与 subjects 必须共同选择。冻结后以 `plan.units` 为唯一范围，publish、reconcile、verify、distribute 不再接受 `--unit`。
 
-**阶段通过规则**: `status` 与 `readiness.localPreparation.status` 只判断本地 help/assess/prepare；其充要条件是 `READY` 且 exit code 为 0。`missingRequired` 列出缺失的 Node/Git。生产发布必须另外读取 `readiness.productionPublish`：缺少 npm/gh 时为 `NOT_READY`，依赖存在时仍是 `AUTH_CHECK_REQUIRED`，因为 help 不访问网络、不验证认证。Agent 无权把本地就绪解释为生产就绪。
+每个单元都要声明 `previousPublicBaseline`：确认没有前序版本才用 `none`，否则使用带 repo/ref/commit 的 `bound`。`none` 不绕过 publish 的唯一性预检。
 
-**边界**: help 不修改文件系统、不执行外部写操作、不生成发布计划。优先探测 PATH 上的全局安装命令 `release-skill`，不可用时回退到源码路径。每个 unit 必须配置 `previousPublicBaseline`：首次发布且确认无前序版本用 none，已有版本用 bound + repo/ref/commit；none 不是绕过 publish 唯一性预检的开关。v0.1.1 已完成 GitHub/npm 真实生产发布、冻结 Git ref 的 Claude/Codex 消费者安装、精确 npm 安装 smoke 与最终 VERIFIED；生产等价本地协议套件继续覆盖 fake gh/npm/Claude/Codex 和本地 bare Git。测试未做 OS 级禁网，且一次成功发布不能证明其他项目的认证、权限、限流或最终一致性行为；每个项目的首次生产发布仍应作为受监控 canary。
+Hook cache v2 只复用绝对路径，或已用真实 cwd 核验的 cwd-relative executable identity；裸 PATH、PATHEXT、Windows 或观察不可用时冷执行，并失败关闭。稳定隔离安装树只在宿主命令退出、目录隔离且扫描期间无并发写入时记录；附加链接只记录、不跟随，声明载荷中的 symlink 失败关闭。
 
-## 正向执行路径
+## 最短路径
 
-1. 使用插件根相对路径运行 CLI：`node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" help --json`
-2. 检查 `readiness.localPreparation`；需要生产发布时再检查 `readiness.productionPublish`
-3. 若环境就绪且缺少 `.release-skill/project.yaml`，先路由 `release-setup`；配置已存在才运行 `release-assess`
-4. 默认在审阅本地计划和快照后停止；只有用户明确要求且完成摘要审批时才进入 `release-publish`。已持有合法批准的 production plan 时，publish 自行完成权威校验，不把 route 当作授权门
-
-## 确定性脚本调用
+1. 从插件根运行 `help --json`，检查本地准备度；生产发布再检查生产准备度。
+2. 缺少 `.release-skill/project.yaml` 时进入 `release-setup`；已有配置时进入 `release-assess`。
+3. 本地评估使用 `release-assess` 和 `prepare --offline`。默认在审阅计划与快照后停止。
+4. 生产发布优先使用可恢复的 `ship`；也可走 `prepare --online --production → approve → publish → verify`。
 
 ```bash
-# 从插件根运行（自包含 bundle，无需 node_modules）
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" help --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root <path> --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offline --json
-# 日常发布快速路径：发布前确认可读计划摘要，状态文件可恢复。
-# 受限 postPublish hook 的 checkpoint 批准与计划批准分开。
-node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> --target-version <version> --json
-# 多发布单元项目显式选择本轮范围；未传 --unit 时仍为全部单元
-node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> \
-  --target-version <version> --unit <unit-a> --unit <unit-b> --json
-# 对已经 VERIFIED 的计划独立执行 postVerify hook；不读取或写入 ship state
-node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" postverify --root <path> \
-  --plan <plan-path> --approval <approval-path> --run <verified-run-path> \
-  --hook-approval <immutable-hook-approval-path> --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
-# 发布文档刷新：默认只读演练
-node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> --json
-# 摘要确认后的本地写入（三项绑定缺一不可）
-node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> \
-  --write --confirm-refresh <refreshDigest> --ack-local-document-write --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" route --root <path> --target-version <version> --json
 ```
 
-## 发布文档刷新（docs refresh）
+`route` 只做分类和推荐，不是授权门。分类为 docs、config、marketplace、code 或 mixed；存在 `PARTIAL` 时先进入 reconcile，不能确定时按更安全的完整路径处理。
 
-发布单元配置 `releaseDocuments` 后，一份结构化双语说明源可确定性刷新 README 受管区域、唯一版本标记的机器值和 CHANGELOG 当前版本受管条目。核心 CLI 不联网、不调用大模型、不自动翻译；只改写声明过的受管区域、版本标记机器值和当前受管条目，区域外字节逐字保留。`prepare` 只检查新鲜度，不写工作树。
+## 生产发布与恢复边界
 
-- **配置**：`releaseDocuments.notesSource`（说明源路径，只允许 `{version}` 占位符与 `.yaml`/`.yml`/`.json` 后缀）、`locales`（如 `[en, zh-CN]`）、`changelogs`（path + locale）、`readmes`（path + locale + `regions` 受管区域 id + `versionMarkers` 版本标记模式）。版本标记模式必须与 README 现有唯一标记精确匹配，`{version}` 代表机器版本值，刷新只替换该值；零次或多次匹配失败关闭。
-- **说明源**：`version` 必须与单元版本精确一致，`date` 为 `YYYY-MM-DD`，每个配置语种恰好出现一次且 `summary`、变更项非空，`security`/`breaking`/`added`/`changed`/`deprecated`/`removed`/`fixed` 至少一个类别含条目。YAML alias、重复键、未知字段和语种回退都失败关闭。
-- **只读演练**：`docs refresh --unit <id> --json` 输出逐文件相对路径、locale、新旧摘要、`version`、`locales`、`inputDigest`、`refreshDigest` 和 `nextCommand.argv`；候选无变化时 `status: "clean"`。
-- **确认写入**：必须同时提供 `--write`、精确 `--confirm-refresh <refreshDigest>` 和 `--ack-local-document-write`，全部目标作为一个事务提交；成功后立即复演必须为 `clean`。
+只有用户明确要求生产发布，且冻结计划摘要已经人工审阅，才进入 `release-publish`。冻结计划批准是发布级唯一批准门；publish 会自行核对 plan、approval、digest、目标版本、远端冲突和允许动作。route、help、`READY`、历史成功或 `VERIFIED` 都不能替代批准。
 
-**授权边界**：本地发布文档写入授权只覆盖声明的本地文档目标，不是 Git 提交、push、publish 或安装的授权。hook/gate 由对应命令调用直接授权——在 project.yaml 配置 hook 即完成授权（配置时刻即授权契约，FM-16 处置 A）：hook 是任意本地进程、无文件系统/网络隔离、触发前无确认点，配置者须对其内容负责；恢复触发前强制确认门为后续加固项。写入后必须审阅、提交，再重新 prepare。
+`requiresApproval: true` 的 postPublish hook 还需要独立 checkpoint 批准。项目配置中的其他 hook 是任意本地进程，没有文件系统或网络隔离；执行相应命令即授权运行，help 不替用户作出该授权。
 
-## 故障路由
+外部写入按 checkpoint 停止；部分成功进入 `PARTIAL`。不得自动删除远端标签、覆盖 Release、unpublish npm 或从头重跑。使用 `release-reconcile` 查询远端实际状态，只重试安全且未完成的动作；冲突交回人工决定。
 
-| 场景 | 处理 |
-|---|---|
-| Node.js 版本不足 | `status: "NOT_READY"`, `missingRequired` 含 `"node>=22"`；提示升级至 >= 22 |
-| Git 未安装 | `status: "NOT_READY"`, `missingRequired` 含 `"git"`；提示安装 Git |
-| pnpm 未安装 | 不影响本地准备；仅出现在 recommendations 中 |
-| npm/gh 未安装 | 本地准备仍可就绪，但 `readiness.productionPublish.status` 为 `NOT_READY` |
-| npm/gh 已安装 | 生产状态仍为 `AUTH_CHECK_REQUIRED`；发布前验证 `gh auth`、Git HTTPS credential 和 npm auth |
-| CLI 入口不存在 | 确认 `${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs` 存在；不存在时重新安装插件 |
-| 项目配置不存在 | 路由 `release-setup`，默认只读；不得直接生成或覆盖 README/配置 |
-| assess 失败 | 运行 `node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --offline --json` 获取详情 |
-| 请求生产发布 | 已有公开版本先调用 `release-prepare --online --production` 观察 bound 基线；人工审阅后直接调用 `release-publish`，由 publish 自行完成计划、approval、digest、远端冲突和 `PARTIAL` 校验 |
-| RELEASE_DOCS_INVALID | 配置或说明源语义非法（重复键、alias、未知字段、版本漂移等）；修正配置或说明源后重新演练 |
-| RELEASE_DOCS_TRANSLATION_MISSING | 配置语种缺失或多余；补齐说明源语种，与 `releaseDocuments.locales` 完全一致，不得回退 |
+## VERIFIED 后收尾
 
-## Routing Suggestions (§4.3 Quickstart Routing)
+声明的 `postVerify` hook 可由 `postverify` 独立执行或由 `ship` 编排。计划声明该 hook 时，本机收尾必须等待完成的 postVerify run；没有声明时使用同一计划的 `VERIFIED` verify run。
 
-对于不清楚如何开始的用户，推荐使用 `release-skill route` 命令进行自动化工作流选择：
+随后进入 `release-finish`，通过公共入口编排宿主更新、加载确认、已配置 setup 和源码分支检查：
 
 ```bash
-# 快速分类变更并推荐工作流；已知目标版本时显式传入，未知时省略
-node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" route --root <path> --json
-node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" route --root <path> \
-  --target-version <version> --json
-
-# JSON 输出包含 classification 和 recommendation 字段
-{
-  "classification": {
-    "code": [],
-    "docs": ["README.md"],
-    "config": [],
-    "marketplace": [],
-    "mixed": false
-  },
-  "recommendation": {
-    "workflowKind": "docs-only",
-    "reason": "Pure documentation changes detected...",
-    "firstCommand": "release-docs"
-  }
-}
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs" \
+  --root <project-root> --plan <plan-path> --run <verify-or-postverify-run-path> \
+  --finish --json
 ```
 
-**可用工作流**:
-- `docs-only`: 纯文档变更（跳过代码类门限）
-- `config-only`: 纯配置变更（schema 验证 + 决策分支）
-- `marketplace-only`: 纯 marketplace 索引变更（条目更新 + snapshot 同步）
-- `full-happy-end`: 混合变更或无法确定（fail-closed 到最安全路径）
-- `reconcile`: 存在 PARTIAL 运行时需先恢复
-- `help`: 无变更且未指定目标版本
+首次结果可能请求用户选择分支和本机宿主，或返回需要智能体实际加载并调用 setup 的请求。将绑定反馈写入文件后，以同一入口增加 `--finish-feedback <feedback-path>` 再次汇总。完整参数、反馈合同、宿主限制和 macOS Cursor 安装见 `release-finish`。仅有 `VERIFIED` 不构成本机写入、插件更新、分支合并或 setup 写入授权；收尾结果也不改写发布状态。
+
+## 专用工作流路由
+
+- 消费项目的 Cursor 场景配置、受控可执行目录、用户状态目录、结果不确定时的现场保留与复验，见 `release-verify`。
+- README、CHANGELOG 和双语说明的 `docs refresh` 演练、摘要确认与受管写入，见 `release-docs`。
+- VERIFIED 后的分支决定、宿主更新、加载反馈、setup 和源码检查，见 `release-finish`。
+- 纯配置变更，见 `release-config`。
+- 纯 marketplace 索引与快照变更，见 `release-marketplace`。
+
+这些入口保留各自的参数、确认和失败关闭规则；help 不复制或放宽它们。
 
-参考文档：
-- [`release-docs`](../release-docs/SKILL.md) - 文档工作流详解
-- [`release-config`](../release-config/SKILL.md) - 配置工作流详解
-- [`release-marketplace`](../release-marketplace/SKILL.md) - Marketplace 工作流详解
+## 故障分诊
 
-| RELEASE_DOCS_CONFLICT | 目标含非受管同版本条目、受管标记损坏或人工冲突；人工修复目标并保留人工修改后重新演练 |
-| RELEASE_DOCS_REFRESH_STALE | 确认绑定后候选已变化；重新演练取得新 `refreshDigest` 再确认写入 |
-| RELEASE_DOCS_STALE | prepare 检测到文档未刷新；按 `docs refresh` → 审阅 → 提交 → 重新 prepare 恢复 |
+- Node.js 或 Git 缺失：读取 `missingRequired`，补齐依赖后重跑 help。
+- npm/gh 缺失或未认证：本地准备仍可继续；生产发布前另行完成 gh、Git HTTPS credential 与 npm auth 检查。
+- CLI 入口缺失：确认 `${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs` 存在；缺失时重新安装插件。
+- 项目配置缺失：进入 `release-setup` 的只读发现，不直接生成或覆盖 README/配置。
+- assess 失败：运行 `release-assess` 的离线诊断并按错误码处理。
+- `PARTIAL` 或远端冲突：进入 `release-reconcile`，保留已经成功的 checkpoint。
+- 文档、Cursor、宿主更新或本机收尾失败：转到上节对应专用 Skill，不在 help 中猜测恢复步骤。
 
 ## 后续引导
 
-本地准备就绪后下一步运行 `release-assess`：`node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess`。生产发布还要求 npm、gh 可用，并在发布前另行完成认证检查。
+本地就绪后运行 `release-assess`；需要生产发布时，再确认 npm、gh、认证、冻结计划和有效批准。

package/skills/release-verify/SKILL.md

@@ -50,7 +50,7 @@ ship state；hook approval 缺失、错误或过期时，在 hook 执行前失
 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`。随后按清单主动询问分支合并和本机宿主插件更新；发布策略已包含分支动作时略过合并询问
+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`。随后执行返回的 `post-release --finish` 命令，按 `nextActions` 补齐分支决定、宿主加载与真实 setup 结果；发布策略已包含分支动作时略过合并询问
 
 ## 确定性脚本调用
 
@@ -77,7 +77,7 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" postverify --root <path> \
 
 ## 发布后收尾
 
-`VERIFIED` 不代表要自动修改开发分支或本机宿主。进入 `release-finish` 后，只有用户明确同意，才执行对应的本地动作。本机插件更新失败不会改变发布终态。
+`VERIFIED` 不代表要自动修改开发分支或本机宿主。进入 `release-finish` 后，只有用户明确同意，才执行对应的本地动作。`post-release --finish` 退出 0 需要所有适用步骤完成或明确跳过；单纯的宿主 `UPDATED` 不代表新入口已加载，也不代表 setup 已执行。本机插件更新失败不会改变发布终态。
 核心 prepare、publish、verify 流程跨平台；WorkBuddy 的本机收尾探测和更新仅支持 macOS。
 
 ## 烟雾测试

package/skills-src/release-finish/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: release-finish
-description: 发布达到 VERIFIED 后处理发布收尾：确认 postVerify 提案送达边界，按发布分支策略决定是否询问合并，并在用户确认后更新本机 Claude、Codex、Kimi、CodeBuddy/WorkBuddy、Qoder 插件
+description: 发布达到 VERIFIED 后编排完整收尾：处理分支决定和本机宿主更新，确认实际加载，调用已配置的 setup，检查源码分支并汇总剩余工作
 ---
 
 # release-finish
@@ -15,7 +15,7 @@ description: 发布达到 VERIFIED 后处理发布收尾：确认 postVerify 提
 
 默认只读取冻结计划和 verify 或 postVerify run。没有用户明确同意，不合并分支，不更新插件。用户显式选择 Kimi 更新后，只有标准初始目录信任界面和插件信任界面中的冻结身份都通过核对，才确认当前项目并安装。用户显式选择 Qoder 且冻结计划声明该宿主后，才执行计划绑定的 Hub 更新。
 
-## 先生成收尾清单
+## 进入完整收尾
 
 从插件根执行：
 
@@ -24,18 +24,22 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs" \
   --root <project-root> \
   --plan <plan-path> \
   --run <verify-or-postverify-run-path> \
+  --finish \
   --json
 ```
 
 脚本只接受与冻结计划一致的显式运行证据：计划未声明 `postVerify` hook 时，传入同计划的 `VERIFIED` verify run；计划声明了 `postVerify` hook 时，必须传入同计划、沿同一 `VERIFIED` verify run 继承谱系且所有 hook checkpoint 均为 `succeeded` 或 `NO_CHANGE` 的 `DISTRIBUTED` postVerify run。postVerify 尚未完成时，不能直接运行本机收尾；应先完成所需 checkpoint approval，再通过 `ship` 完成 postVerify，并使用结果中的 postVerify run 路径。
 
+`--finish` 每次都返回 `merge`、`host-update`、`host-load`、`setup` 和 `source-branch` 五个步骤。`COMPLETE` 表示本次收尾没有待办，`PENDING` 以退出码 2 要求当前智能体续接，`FAILED` 以退出码 1 保留确定失败。脚本观察标为 `script-observed`；宿主加载与 setup 结果标为 `agent-reported`。两种来源都不改写 `VERIFIED`。
+
 ## 主动询问
 
-读取返回的 `merge` 和 `localHostUpdate`：
+读取 `finish.steps` 和 `finish.nextActions`：
 
 1. `merge.promptRequired=false` 时，发布工作流已经推进或初始化目标分支，不再询问合并。
 2. `merge.promptRequired=true` 时，向用户说明尚未覆盖的发布分支，并询问是否需要合并。用户同意后，先只读核对源分支、目标分支、工作区状态和项目既有合并方式，再用明确的分支名执行；本脚本不猜分支，也不自动推送。
-3. `localHostUpdate.promptRequired=true` 时，列出计划覆盖的宿主，询问是否更新本机插件。Hub-backed 目标必须显示其声明的 Hub、插件和宿主。Qoder 是其中唯一可执行的 Hub-backed 目标；Claude/Codex 使用现有 marketplace 管理入口，Kimi 使用冻结 GitHub Release 和现有人工确认路径，CodeBuddy/WorkBuddy 明确人工处理且不能固定 Hub ref。后续“用户同意更新”段适用于 `available=true` 的 executable externalActions 目标和 Qoder Hub 目标，其余 Hub-backed 目标仍为人工入口。两个问题可以一次问完。
+3. `choose-local-hosts` 出现时，列出计划覆盖的宿主，询问是否更新本机插件。Hub-backed 目标必须显示其声明的 Hub、插件和宿主。Qoder 是其中唯一可执行的 Hub-backed 目标；Claude/Codex 使用现有 marketplace 管理入口，Kimi 使用冻结 GitHub Release 和现有人工确认路径，CodeBuddy/WorkBuddy 明确人工处理且不能固定 Hub ref。后续“用户同意更新”段适用于 `available=true` 的 executable externalActions 目标和 Qoder Hub 目标，其余 Hub-backed 目标仍为人工入口。分支决定和宿主选择可以一次问完。
+4. 用户明确不处理本机宿主时，向同一命令加入 `--skip-local-hosts`。该选择会显示地跳过宿主更新、加载和 setup，不得与 `--hosts` 或 `--update-local-hosts` 同时使用。
 
 ## postVerify 提案送达边界
 
@@ -54,23 +58,58 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs" \
   --root <project-root> \
   --plan <plan-path> \
   --run <verify-or-postverify-run-path> \
+  --finish \
   --update-local-hosts \
   --hosts claude,codex,kimi,codebuddy,workbuddy,qoder \
   --confirm-plan <planDigest> \
   --json
 ```
 
-只传用户选择且计划声明的宿主。宿主 CLI 不存在时返回 `SKIPPED_NOT_INSTALLED`。各宿主按以下规则处理：
+只传用户选择且计划声明的宿主。Cursor 选择方式见下节；其他宿主 CLI 不存在时返回 `SKIPPED_NOT_INSTALLED`。各宿主按以下规则处理：
 
 - Claude 或 Codex 只有在市场需要重绑时，才会在该宿主第一条写命令之前只读查询冻结的市场仓库、引用和提交。远端不可达、引用缺失或提交不一致时返回 `MANUAL_REQUIRED`，该宿主不执行市场或插件写入；其他已选宿主继续处理。精确当前安装仍核对真实载荷，但不强制联网。
-- Kimi 的精确当前安装会在返回 `ALREADY_CURRENT` 前核对真实载荷；发生安装或迁移时，只在操作完成后核对结果。配置根依次取显式 `kimiHome`、`KIMI_CODE_HOME`、用户主目录下的 `.kimi-code`，TUI 与安装后观察使用同一根。release-finish 当前只采用并验证 Kimi Code 的受控终端交互界面（TUI）路径，并把 TUI 工作目录固定为 `--root` 指定的当前发布项目。用户已确认冻结计划、显式选择更新且 `--hosts` 包含 `kimi` 时，流程只在初始标准 `Trust this folder?` 界面确认目录：先核对当前选中 `No, exit` 和目标 `Trust this folder`，移动并重新核对目标选中项，确认后等待已知命令提示符。插件命令发出后再次出现目录信任、界面或选中项未知、移动后无法确认、超时或提前退出时，该宿主失败并停止后续安装步骤。插件信任仍先清理 ANSI/OSC 控制序列和软换行，再分别核对冻结仓库与标签；只有选中 `Trust and install` 才提交并重新加载。包名、版本、发布标签、已安装修订号和受管安装根必须与冻结计划一致；`.git` 只提供附加诊断，不是通过条件。旧的本地路径安装会在同一 TUI 会话中先移除，再按发布标签安装。
+- Kimi 的精确当前安装会在返回 `ALREADY_CURRENT` 前核对真实载荷；发生安装或迁移时，只在操作完成后核对结果。配置根依次取显式 `kimiHome`、`KIMI_CODE_HOME`、用户主目录下的 `.kimi-code`，TUI 与安装后观察使用同一根。release-finish 当前只采用并验证 Kimi Code 的受控终端交互界面（TUI）路径，并把 TUI 工作目录固定为 `--root` 指定的当前发布项目。用户已确认冻结计划、显式选择更新且 `--hosts` 包含 `kimi` 时，流程读取完整的初始 `Trust this folder?` 对话框，要求其中只有一个正向项 `Trust this folder` 和一个选中项。正向项已经选中时不发送方向键，直接确认；已知拒绝项选中时，按它与正向项的相对位置移动一次，重新读取完整对话框并确认正向项已选中，然后才提交。插件命令发出后再次出现目录信任、界面或选中项未知、正向项缺失或重复、移动后无法确认、超时或提前退出时，该宿主失败并停止后续安装步骤。若后续 Kimi 版本出现新的可复现界面差异，先记录 Kimi 版本、可见选项、选中项及选项关系；这些事实足以唯一确认当前目录、正向信任项和选择结果时，在最近测试补回归与兼容并继续，目录身份或选项语义不明时仍停止并交回主会话。插件信任仍先清理 ANSI/OSC 控制序列和软换行，再分别核对冻结仓库与标签；只有选中 `Trust and install` 才提交并重新加载。包名、版本、发布标签、已安装修订号和受管安装根必须与冻结计划一致；`.git` 只提供附加诊断，不是通过条件。旧的本地路径安装会在同一 TUI 会话中先移除，再按发布标签安装。
 - CodeBuddy/WorkBuddy 只处理同一 bundled-family 插件和市场。CodeBuddy 仅探测全局 `codebuddy`/`cbc`，由收尾脚本把 `CODEBUDDY_CONFIG_DIR` 固定为有效 `HOME`（环境未提供时取操作系统用户主目录）下名为 `.codebuddy` 的目录；WorkBuddy 仅在 macOS 探测 WorkBuddy 应用内嵌 CLI，由收尾脚本把 `CODEBUDDY_CONFIG_DIR` 与 `WORKBUDDY_CONFIG_DIR` 同时固定为有效 `HOME` 下名为 `.workbuddy` 的目录，绝不把两者互作回退。只有冻结标签与计划声明的可变分支都从同一远端解析到冻结提交时，才调用正式市场更新和插件更新命令；完成后重新读取安装列表，并精确核对唯一条目的市场、版本和修订号。目标未安装、来源不符、远端不可访问或身份不一致时返回 `MANUAL_REQUIRED`，不修改宿主。非 macOS 的 WorkBuddy 返回 `SKIPPED_UNSUPPORTED_PLATFORM`。
 - Qoder 先用 `qoder plugins marketplace list --json` 核对计划声明的 Hub 名称、仓库、分支和本机 checkout，再用 `qoder plugins list --json` 核对唯一插件条目的市场、`scope=user`、版本与 `installPath`。目标市场或插件未安装时返回 `MANUAL_REQUIRED`，不添加市场，也不执行首次安装。旧版已安装时，只运行 `qoder plugins marketplace update <name>` 和 `qoder plugins update <plugin@marketplace> --scope user`。市场刷新后、插件更新前，必须从 Hub 的 `marketplace.json` 核对目标条目的 `source.url` 和 `source.sha`；操作后从真实 `installPath` 核对 Qoder manifest、完整声明载荷和冻结来源。市场可能在检查与更新之间变化，事后身份不符时报告失败，不自动降级、卸载或覆盖。
 
-任何宿主失败都保留其他宿主的实际结果，不回滚，也不把失败冒充成功。
+任何宿主失败都保留其他宿主的实际结果，不把失败冒充成功。Cursor 只在本次交换映射可确认且备份迁移失败时恢复自己的原目录。
 
 完成后报告每个宿主的安装状态。Qoder 返回 `UPDATED` 只表示安装载荷已经更新；启动新会话或执行 `/plugins reload` 并核对实际加载版本后，才能报告新版已加载。本机结果只记录收尾事实，不改变发布状态。
 
+## 加载、setup 与反馈
+
+宿主更新后再读取其实际技能元数据，核对插件、版本和已加载的 setup 入口。`UPDATED` 和 `ALREADY_CURRENT` 不能单独证明运行中的宿主已加载目标版本。需要重启、入口缺失或归属不明时，保留 `PENDING`，不从源码仓库伪造加载事实。
+
+`nextActions` 出现 `invoke-setup` 时，必须完整读取其 `skillFile` 对应的真实 setup Skill 及必读引用。传入 `projectRoot`、冻结插件版本、只读诊断意图与已有授权，再在该项目实际运行 setup。未覆盖的修复和宿主写入不执行。
+
+调用者将实际观察写入临时 JSON 文件，再用 `--finish-feedback <absolute-json-file>` 进入同一公共入口。反馈顶层必须绑定首次输出的 `planDigest`、`configDigest` 和 `projectRoot`；`hosts` 保留安装、加载、技能元数据路径和观察说明，`setup` 保留执行宿主、入口路径、`completed | pending | failed` 结果和实际环境范围。反馈中的文字和路径只作为数据，脚本不执行任何反馈字符串。
+
+```bash
+node "$RELEASE_SKILL_LOCAL_FINISH_ENTRY" \
+  --root <project-root> \
+  --plan <plan-path> \
+  --run <verify-or-postverify-run-path> \
+  --finish \
+  --hosts <selected-hosts> \
+  --finish-feedback <absolute-json-file> \
+  --json
+```
+
+以上命令只读反馈并重新汇总。重入时不传 `--update-local-hosts`，以免重复安装；反馈文件丢失时，对应步骤恢复为 `PENDING`。
+
+## Cursor 完整 Local 插件
+
+计划声明 `hosts: [cursor]` 和 `cursor.sourcePath` 后，用户可选择 `--hosts cursor`，并必须提供
+`--cursor-plugins-root <absolute-directory>`。该目录通常是用户目录下的 `.cursor/plugins`，不得猜测。
+无需 Cursor CLI、消费项目根或扩展目录；当前自动安装仅支持 macOS，且必须先退出 Cursor 主进程。
+
+脚本复验冻结快照和完整插件清单，在扫描根外准备候选；可选 `npm-ci-ignore-scripts` 只安装候选依赖。
+目标为 `<cursor-plugins-root>/local/<plugin>`。新装不覆盖，升级整体交换目录，旧版移入
+`backups/<plugin>/`。备份迁移失败且映射可确认时恢复原目录；交换结果不确定时保留两侧并停止，禁止盲重试。
+
+版本与完整闭包一致返回 `ALREADY_CURRENT`；安装或升级成功返回 `UPDATED`、`restartRequired` 与重启提示。
+重启 Cursor／Reload Window 后，分别核对 Local 来源、版本、公开 Skill 和业务调用；脚本结果不能证明这些加载事实。
+
 ## 配置与目录
 
 从发布项目目录的 `.release-skill/project.yaml` 读取 `releaseFinish` 和 `project.defaultBranch`。

package/skills-src/release-help/SKILL.md

@@ -7,140 +7,84 @@ description: "Discoverable entry point for release-skill: dependency and environ
 
 ## 触发
 
-用户询问如何使用 release-skill、发布流程是什么、或请求只读诊断和 dry-run 安全检查。
+询问 release-skill 的用法、发布流程、依赖、环境、只读诊断或 dry-run 时使用。本入口只做能力说明和分诊；专用工作流交给对应 Skill。
 
-## 职责
+## 只读边界
 
-- 依赖和环境检查：Node.js >= 22、Git 决定本地准备就绪度；npm/gh 另行决定生产依赖就绪度
-- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；日常生产发布优先使用可恢复的 `ship`，兼容的分阶段闭环仍是 `prepare --online --production → approve → publish → verify`。冻结计划批准是正常发布级流程的唯一批准门；声明 `requiresApproval: true` 的 postPublish hook 仍须等待独立 checkpoint 批准。若计划声明 `postVerify` hook，可用 `postverify` 直接执行独立收尾 run，也可由 `ship` 编排该阶段；本机收尾必须等待完成的 postVerify run，不能把仅有 `VERIFIED` 的 verify run 当作本机收尾授权。核心发布流程跨平台，WorkBuddy 本机收尾仅支持 macOS
-- 最小示例：展示从 release-help 到 release-assess 的最短路径
-- 只读诊断：运行 dry-run 检查，不修改任何文件
-- 故障引导：根据错误码指向对应的修复 Skill
+`help` 不联网、不检查认证、不改文件、不生成计划，也不执行 Git、宿主安装或外部发布写入。它只根据当前环境报告准备度并给出下一步。优先调用插件自带入口；不可用时才回退到源码入口。
 
-## 0.9.17 候选边界
+核心流程跨平台；WorkBuddy 本机收尾仅支持 macOS。Node.js >= 22 和 Git 决定本地准备度。npm、gh 只影响生产发布依赖；pnpm 缺失只进入建议。
 
-当前源码候选允许多发布单元项目在计划冻结前显式选择本轮范围。`prepare` 和新建的 `ship` 状态支持重复传入 `--unit <id>`；未传时继续选择全部配置单元。成功选择会列出选中与延期单元。延期单元不进入本轮计划，也不获得发布状态。
+本地阶段通过须同时满足 `status: "READY"` 和 exit code 0。读取 `readiness.localPreparation.status` 与 `missingRequired`。生产另读 `readiness.productionPublish`：缺 npm/gh 为 `NOT_READY`，已安装也只是 `AUTH_CHECK_REQUIRED`，不代表认证、权限或发布授权已经成立。
 
-选择只影响按单元绑定的检查与动作。完整配置、生成物新鲜度和顶层 Hook 仍覆盖整个项目。`publicSourceAuthorityReceipt` 涉及的 coordinator 和 subjects 必须作为完整闭包共同选择，系统不会自动扩选。计划冻结后，`plan.units` 是唯一范围权威；publish、reconcile、verify 和 distribute 不接受 `--unit`。
+## 0.9.19 候选边界
 
-0.9.3 引入的四项工作流保护、Hook cache v2 和稳定隔离安装树记录在后续版本继续保留。当前 0.9.17 候选精确消费 Foundation 0.17.0 的公开包根 API。Hook cache 只复用绝对路径或经真实 cwd 校验的 cwd-relative executable identity；裸 PATH、PATHEXT、Windows 和观察不可用时，Hook 仍冷执行，缓存复用失败关闭且不写入 v2 cache。缓存没有 TTL。
+当前 0.9.19 候选精确消费 Foundation 0.21.0 的公开包根 API。0.9.19 仍是源码候选，不能从本说明推断已批准、发布或验证。
 
-稳定隔离安装树记录只在宿主命令退出、目录已隔离且扫描期间没有并发写入时执行；宿主附加链接只记录、不跟随，声明载荷中的 symlink 失败关闭，legacy 全树语义保持不变。0.9.17 仍是源码候选，不能从本说明推断已批准、发布或验证。
+冻结前，`prepare` 或新建 `ship` 状态可重复传入 `--unit <id>`；不传则选择全部单元。延期单元不进入计划，也不获得发布状态。完整配置、生成物新鲜度和顶层 Hook 仍覆盖全项目；`publicSourceAuthorityReceipt` 的 coordinator 与 subjects 必须共同选择。冻结后以 `plan.units` 为唯一范围，publish、reconcile、verify、distribute 不再接受 `--unit`。
 
-**阶段通过规则**: `status` 与 `readiness.localPreparation.status` 只判断本地 help/assess/prepare；其充要条件是 `READY` 且 exit code 为 0。`missingRequired` 列出缺失的 Node/Git。生产发布必须另外读取 `readiness.productionPublish`：缺少 npm/gh 时为 `NOT_READY`，依赖存在时仍是 `AUTH_CHECK_REQUIRED`，因为 help 不访问网络、不验证认证。Agent 无权把本地就绪解释为生产就绪。
+每个单元都要声明 `previousPublicBaseline`：确认没有前序版本才用 `none`，否则使用带 repo/ref/commit 的 `bound`。`none` 不绕过 publish 的唯一性预检。
 
-**边界**: help 不修改文件系统、不执行外部写操作、不生成发布计划。优先探测 PATH 上的全局安装命令 `release-skill`，不可用时回退到源码路径。每个 unit 必须配置 `previousPublicBaseline`：首次发布且确认无前序版本用 none，已有版本用 bound + repo/ref/commit；none 不是绕过 publish 唯一性预检的开关。v0.1.1 已完成 GitHub/npm 真实生产发布、冻结 Git ref 的 Claude/Codex 消费者安装、精确 npm 安装 smoke 与最终 VERIFIED；生产等价本地协议套件继续覆盖 fake gh/npm/Claude/Codex 和本地 bare Git。测试未做 OS 级禁网，且一次成功发布不能证明其他项目的认证、权限、限流或最终一致性行为；每个项目的首次生产发布仍应作为受监控 canary。
+Hook cache v2 只复用绝对路径，或已用真实 cwd 核验的 cwd-relative executable identity；裸 PATH、PATHEXT、Windows 或观察不可用时冷执行，并失败关闭。稳定隔离安装树只在宿主命令退出、目录隔离且扫描期间无并发写入时记录；附加链接只记录、不跟随，声明载荷中的 symlink 失败关闭。
 
-## 正向执行路径
+## 最短路径
 
-1. 使用插件根相对路径运行 CLI：`node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" help --json`
-2. 检查 `readiness.localPreparation`；需要生产发布时再检查 `readiness.productionPublish`
-3. 若环境就绪且缺少 `.release-skill/project.yaml`，先路由 `release-setup`；配置已存在才运行 `release-assess`
-4. 默认在审阅本地计划和快照后停止；只有用户明确要求且完成摘要审批时才进入 `release-publish`。已持有合法批准的 production plan 时，publish 自行完成权威校验，不把 route 当作授权门
-
-## 确定性脚本调用
+1. 从插件根运行 `help --json`，检查本地准备度；生产发布再检查生产准备度。
+2. 缺少 `.release-skill/project.yaml` 时进入 `release-setup`；已有配置时进入 `release-assess`。
+3. 本地评估使用 `release-assess` 和 `prepare --offline`。默认在审阅计划与快照后停止。
+4. 生产发布优先使用可恢复的 `ship`；也可走 `prepare --online --production → approve → publish → verify`。
 
 ```bash
-# 从插件根运行（自包含 bundle，无需 node_modules）
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" help --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root <path> --json
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offline --json
-# 日常发布快速路径：发布前确认可读计划摘要，状态文件可恢复。
-# 受限 postPublish hook 的 checkpoint 批准与计划批准分开。
-node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> --target-version <version> --json
-# 多发布单元项目显式选择本轮范围；未传 --unit 时仍为全部单元
-node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> \
-  --target-version <version> --unit <unit-a> --unit <unit-b> --json
-# 对已经 VERIFIED 的计划独立执行 postVerify hook；不读取或写入 ship state
-node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" postverify --root <path> \
-  --plan <plan-path> --approval <approval-path> --run <verified-run-path> \
-  --hook-approval <immutable-hook-approval-path> --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
-# 发布文档刷新：默认只读演练
-node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> --json
-# 摘要确认后的本地写入（三项绑定缺一不可）
-node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> \
-  --write --confirm-refresh <refreshDigest> --ack-local-document-write --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" route --root <path> --target-version <version> --json
 ```
 
-## 发布文档刷新（docs refresh）
+`route` 只做分类和推荐，不是授权门。分类为 docs、config、marketplace、code 或 mixed；存在 `PARTIAL` 时先进入 reconcile，不能确定时按更安全的完整路径处理。
 
-发布单元配置 `releaseDocuments` 后，一份结构化双语说明源可确定性刷新 README 受管区域、唯一版本标记的机器值和 CHANGELOG 当前版本受管条目。核心 CLI 不联网、不调用大模型、不自动翻译；只改写声明过的受管区域、版本标记机器值和当前受管条目，区域外字节逐字保留。`prepare` 只检查新鲜度，不写工作树。
+## 生产发布与恢复边界
 
-- **配置**：`releaseDocuments.notesSource`（说明源路径，只允许 `{version}` 占位符与 `.yaml`/`.yml`/`.json` 后缀）、`locales`（如 `[en, zh-CN]`）、`changelogs`（path + locale）、`readmes`（path + locale + `regions` 受管区域 id + `versionMarkers` 版本标记模式）。版本标记模式必须与 README 现有唯一标记精确匹配，`{version}` 代表机器版本值，刷新只替换该值；零次或多次匹配失败关闭。
-- **说明源**：`version` 必须与单元版本精确一致，`date` 为 `YYYY-MM-DD`，每个配置语种恰好出现一次且 `summary`、变更项非空，`security`/`breaking`/`added`/`changed`/`deprecated`/`removed`/`fixed` 至少一个类别含条目。YAML alias、重复键、未知字段和语种回退都失败关闭。
-- **只读演练**：`docs refresh --unit <id> --json` 输出逐文件相对路径、locale、新旧摘要、`version`、`locales`、`inputDigest`、`refreshDigest` 和 `nextCommand.argv`；候选无变化时 `status: "clean"`。
-- **确认写入**：必须同时提供 `--write`、精确 `--confirm-refresh <refreshDigest>` 和 `--ack-local-document-write`，全部目标作为一个事务提交；成功后立即复演必须为 `clean`。
+只有用户明确要求生产发布，且冻结计划摘要已经人工审阅，才进入 `release-publish`。冻结计划批准是发布级唯一批准门；publish 会自行核对 plan、approval、digest、目标版本、远端冲突和允许动作。route、help、`READY`、历史成功或 `VERIFIED` 都不能替代批准。
 
-**授权边界**：本地发布文档写入授权只覆盖声明的本地文档目标，不是 Git 提交、push、publish 或安装的授权。hook/gate 由对应命令调用直接授权——在 project.yaml 配置 hook 即完成授权（配置时刻即授权契约，FM-16 处置 A）：hook 是任意本地进程、无文件系统/网络隔离、触发前无确认点，配置者须对其内容负责；恢复触发前强制确认门为后续加固项。写入后必须审阅、提交，再重新 prepare。
+`requiresApproval: true` 的 postPublish hook 还需要独立 checkpoint 批准。项目配置中的其他 hook 是任意本地进程，没有文件系统或网络隔离；执行相应命令即授权运行，help 不替用户作出该授权。
 
-## 故障路由
+外部写入按 checkpoint 停止；部分成功进入 `PARTIAL`。不得自动删除远端标签、覆盖 Release、unpublish npm 或从头重跑。使用 `release-reconcile` 查询远端实际状态，只重试安全且未完成的动作；冲突交回人工决定。
 
-| 场景 | 处理 |
-|---|---|
-| Node.js 版本不足 | `status: "NOT_READY"`, `missingRequired` 含 `"node>=22"`；提示升级至 >= 22 |
-| Git 未安装 | `status: "NOT_READY"`, `missingRequired` 含 `"git"`；提示安装 Git |
-| pnpm 未安装 | 不影响本地准备；仅出现在 recommendations 中 |
-| npm/gh 未安装 | 本地准备仍可就绪，但 `readiness.productionPublish.status` 为 `NOT_READY` |
-| npm/gh 已安装 | 生产状态仍为 `AUTH_CHECK_REQUIRED`；发布前验证 `gh auth`、Git HTTPS credential 和 npm auth |
-| CLI 入口不存在 | 确认 `${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs` 存在；不存在时重新安装插件 |
-| 项目配置不存在 | 路由 `release-setup`，默认只读；不得直接生成或覆盖 README/配置 |
-| assess 失败 | 运行 `node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --offline --json` 获取详情 |
-| 请求生产发布 | 已有公开版本先调用 `release-prepare --online --production` 观察 bound 基线；人工审阅后直接调用 `release-publish`，由 publish 自行完成计划、approval、digest、远端冲突和 `PARTIAL` 校验 |
-| RELEASE_DOCS_INVALID | 配置或说明源语义非法（重复键、alias、未知字段、版本漂移等）；修正配置或说明源后重新演练 |
-| RELEASE_DOCS_TRANSLATION_MISSING | 配置语种缺失或多余；补齐说明源语种，与 `releaseDocuments.locales` 完全一致，不得回退 |
+## VERIFIED 后收尾
 
-## Routing Suggestions (§4.3 Quickstart Routing)
+声明的 `postVerify` hook 可由 `postverify` 独立执行或由 `ship` 编排。计划声明该 hook 时，本机收尾必须等待完成的 postVerify run；没有声明时使用同一计划的 `VERIFIED` verify run。
 
-对于不清楚如何开始的用户，推荐使用 `release-skill route` 命令进行自动化工作流选择：
+随后进入 `release-finish`，通过公共入口编排宿主更新、加载确认、已配置 setup 和源码分支检查：
 
 ```bash
-# 快速分类变更并推荐工作流；已知目标版本时显式传入，未知时省略
-node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" route --root <path> --json
-node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" route --root <path> \
-  --target-version <version> --json
-
-# JSON 输出包含 classification 和 recommendation 字段
-{
-  "classification": {
-    "code": [],
-    "docs": ["README.md"],
-    "config": [],
-    "marketplace": [],
-    "mixed": false
-  },
-  "recommendation": {
-    "workflowKind": "docs-only",
-    "reason": "Pure documentation changes detected...",
-    "firstCommand": "release-docs"
-  }
-}
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs" \
+  --root <project-root> --plan <plan-path> --run <verify-or-postverify-run-path> \
+  --finish --json
 ```
 
-**可用工作流**:
-- `docs-only`: 纯文档变更（跳过代码类门限）
-- `config-only`: 纯配置变更（schema 验证 + 决策分支）
-- `marketplace-only`: 纯 marketplace 索引变更（条目更新 + snapshot 同步）
-- `full-happy-end`: 混合变更或无法确定（fail-closed 到最安全路径）
-- `reconcile`: 存在 PARTIAL 运行时需先恢复
-- `help`: 无变更且未指定目标版本
+首次结果可能请求用户选择分支和本机宿主，或返回需要智能体实际加载并调用 setup 的请求。将绑定反馈写入文件后，以同一入口增加 `--finish-feedback <feedback-path>` 再次汇总。完整参数、反馈合同、宿主限制和 macOS Cursor 安装见 `release-finish`。仅有 `VERIFIED` 不构成本机写入、插件更新、分支合并或 setup 写入授权；收尾结果也不改写发布状态。
+
+## 专用工作流路由
+
+- 消费项目的 Cursor 场景配置、受控可执行目录、用户状态目录、结果不确定时的现场保留与复验，见 `release-verify`。
+- README、CHANGELOG 和双语说明的 `docs refresh` 演练、摘要确认与受管写入，见 `release-docs`。
+- VERIFIED 后的分支决定、宿主更新、加载反馈、setup 和源码检查，见 `release-finish`。
+- 纯配置变更，见 `release-config`。
+- 纯 marketplace 索引与快照变更，见 `release-marketplace`。
+
+这些入口保留各自的参数、确认和失败关闭规则；help 不复制或放宽它们。
 
-参考文档：
-- [`release-docs`](../release-docs/SKILL.md) - 文档工作流详解
-- [`release-config`](../release-config/SKILL.md) - 配置工作流详解
-- [`release-marketplace`](../release-marketplace/SKILL.md) - Marketplace 工作流详解
+## 故障分诊
 
-| RELEASE_DOCS_CONFLICT | 目标含非受管同版本条目、受管标记损坏或人工冲突；人工修复目标并保留人工修改后重新演练 |
-| RELEASE_DOCS_REFRESH_STALE | 确认绑定后候选已变化；重新演练取得新 `refreshDigest` 再确认写入 |
-| RELEASE_DOCS_STALE | prepare 检测到文档未刷新；按 `docs refresh` → 审阅 → 提交 → 重新 prepare 恢复 |
+- Node.js 或 Git 缺失：读取 `missingRequired`，补齐依赖后重跑 help。
+- npm/gh 缺失或未认证：本地准备仍可继续；生产发布前另行完成 gh、Git HTTPS credential 与 npm auth 检查。
+- CLI 入口缺失：确认 `${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs` 存在；缺失时重新安装插件。
+- 项目配置缺失：进入 `release-setup` 的只读发现，不直接生成或覆盖 README/配置。
+- assess 失败：运行 `release-assess` 的离线诊断并按错误码处理。
+- `PARTIAL` 或远端冲突：进入 `release-reconcile`，保留已经成功的 checkpoint。
+- 文档、Cursor、宿主更新或本机收尾失败：转到上节对应专用 Skill，不在 help 中猜测恢复步骤。
 
 ## 后续引导
 
-本地准备就绪后下一步运行 `release-assess`：`node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess`。生产发布还要求 npm、gh 可用，并在发布前另行完成认证检查。
+本地就绪后运行 `release-assess`；需要生产发布时，再确认 npm、gh、认证、冻结计划和有效批准。

package/skills-src/release-verify/SKILL.md

@@ -50,7 +50,7 @@ ship state；hook approval 缺失、错误或过期时，在 hook 执行前失
 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`。随后按清单主动询问分支合并和本机宿主插件更新；发布策略已包含分支动作时略过合并询问
+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`。随后执行返回的 `post-release --finish` 命令，按 `nextActions` 补齐分支决定、宿主加载与真实 setup 结果；发布策略已包含分支动作时略过合并询问
 
 ## 确定性脚本调用
 
@@ -77,7 +77,7 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" postverify --root <path> \
 
 ## 发布后收尾
 
-`VERIFIED` 不代表要自动修改开发分支或本机宿主。进入 `release-finish` 后，只有用户明确同意，才执行对应的本地动作。本机插件更新失败不会改变发布终态。
+`VERIFIED` 不代表要自动修改开发分支或本机宿主。进入 `release-finish` 后，只有用户明确同意，才执行对应的本地动作。`post-release --finish` 退出 0 需要所有适用步骤完成或明确跳过；单纯的宿主 `UPDATED` 不代表新入口已加载，也不代表 setup 已执行。本机插件更新失败不会改变发布终态。
 核心 prepare、publish、verify 流程跨平台；WorkBuddy 的本机收尾探测和更新仅支持 macOS。
 
 ## 烟雾测试

package/src/adapters/contract.mjs

@@ -64,6 +64,7 @@ export const ActionType = Object.freeze({
   CODEX_MARKETPLACE_INSTALL: 'codex-marketplace-install',
   KIMI_MARKETPLACE_INSTALL: 'kimi-marketplace-install',
   CODEBUDDY_MARKETPLACE_INSTALL: 'codebuddy-marketplace-install',
+  QODER_MARKETPLACE_INSTALL: 'qoder-marketplace-install',
 
   // default branch management
   SET_DEFAULT_BRANCH: 'set-default-branch',