release-skill 0.9.18 → 0.9.19

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

@@ -1,6 +1,6 @@
 ---
 name: release-finish
-description: 发布达到 VERIFIED 后处理发布收尾：确认 postVerify 提案送达边界，按发布分支策略决定是否询问合并，并在用户确认后更新本机 Claude、Codex、Kimi、CodeBuddy/WorkBuddy、Qoder、Cursor 插件
+description: 发布达到 VERIFIED 后编排完整收尾：处理分支决定和本机宿主更新，确认实际加载，调用已配置的 setup，检查源码分支并汇总剩余工作
 ---
 
 # release-finish
@@ -15,7 +15,7 @@ description: 发布达到 VERIFIED 后处理发布收尾：确认 postVerify 提
 
 默认只读取冻结计划和 verify 或 postVerify run。没有用户明确同意，不合并分支，不更新插件。用户显式选择 Kimi 更新后，只有标准初始目录信任界面和插件信任界面中的冻结身份都通过核对，才确认当前项目并安装。用户显式选择 Qoder 且冻结计划声明该宿主后，才执行计划绑定的 Hub 更新。
 
-## 先生成收尾清单
+## 进入完整收尾
 
 从插件根执行：
 
@@ -24,18 +24,22 @@ node "${CODEBUDDY_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,6 +58,7 @@ node "${CODEBUDDY_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> \
@@ -71,6 +76,27 @@ node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs" \
 
 完成后报告每个宿主的安装状态。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`，并必须提供

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

@@ -7,141 +7,84 @@ description: "Discoverable entry point for release-skill: dependency and environ
 
 ## 触发
 
-询问用法、发布流程、只读诊断或 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` 独立执行或由 `ship` 编排；本机收尾须等待完成的 postVerify run，仅有 `VERIFIED` 不构成授权。核心流程跨平台，WorkBuddy 本机收尾仅支持 macOS
-- 示例与诊断：引导至 `release-assess`；dry-run 不改文件，失败按错误码路由
+`help` 不联网、不检查认证、不改文件、不生成计划，也不执行 Git、宿主安装或外部发布写入。它只根据当前环境报告准备度并给出下一步。优先调用插件自带入口；不可用时才回退到源码入口。
 
-## 0.9.18 候选边界
+核心流程跨平台；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.18 候选精确消费 Foundation 0.21.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.18 仍是源码候选，不能从本说明推断已批准、发布或验证。
+冻结前，`prepare` 或新建 `ship` 状态可重复传入 `--unit <id>`；不传则选择全部单元。延期单元不进入计划，也不获得发布状态。完整配置、生成物新鲜度和顶层 Hook 仍覆盖全项目；`publicSourceAuthorityReceipt` 的 coordinator 与 subjects 必须共同选择。冻结后以 `plan.units` 为唯一范围，publish、reconcile、verify、distribute 不再接受 `--unit`。
 
-**阶段通过规则**：本地 help/assess/prepare 通过须同时满足 `READY` 和 exit code 0；读取 `status`、`readiness.localPreparation.status`，缺失 Node/Git 见 `missingRequired`。生产另看 `readiness.productionPublish`：缺 npm/gh 为 `NOT_READY`，存在也只到 `AUTH_CHECK_REQUIRED`。help 不联网、不检查认证，本地就绪不等于生产就绪。
+每个单元都要声明 `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 失败关闭。
 
-## Cursor 消费项目验证
+## 最短路径
 
-消费项目的 `cursor-plugin` 必填 `entrySkill` 和 `hostVerification`。场景含 UTF-8 `workloadDocument`、非空 `fixtureFiles` 与 `protectedWorkspaceFiles`、JSON 对象 `platformManifest`、提示词 `effectivePrompt` 和预期字符串 `expectedResult`。文件格式为 `{path, content}`；路径须安全、相对，不得重复、互为父子或指向 `.cursor`。场景进入公开冻结计划，禁止含凭证。`timeoutMs` 限制验证时长，默认 300000 毫秒。
-
-`prepare` 冻结到 `hostVerificationContract.scenario`；`verify` 复验冻结单 Skill 载荷后，由 Foundation 0.21.0 准备并执行 Cursor 调用。仅当宿主成功且 `result` 严格等于 `expectedResult` 时自动通过；不证明完整插件安装或团队市场分发。
-
-每次运行 `verify` 或通过 `ship` 进入验证阶段，都须传入以下两个绝对目录：
-
-- `--cursor-executable-root <absolute-directory>`：包含 `cursor-agent` 的受控目录。
-- `--cursor-user-state-root <absolute-directory>`：本次获准使用的现有 Cursor 用户状态目录。
-
-目录不写入计划、ship 状态或公开收据，恢复时须重传，不从 `PATH`/`HOME` 推断。须有用户状态使用权限；宿主可能刷新该状态。
-
-成功、失败或拒绝后读取证据并清理临时目录；结果不确定则保留现场，返回 `CONSUMER_VERIFICATION_DEFERRED` 和临时目录名 `sceneId`。人工检查进程与现场后才重试，并用新目录；不确定结果不构成 Cursor 发布检查点或 `PARTIAL`。
-
-## 正向执行路径
-
-1. 从插件根运行下节的 `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 "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" help --json
 node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root <path> --json
 node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offline --json
-# 日常发布快速路径：发布前确认可读计划摘要，状态文件可恢复。
-# 受限 postPublish hook 的 checkpoint 批准与计划批准分开。
-node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> --target-version <version> --json
-# 对已经 VERIFIED 的计划独立执行 postVerify hook；不读取或写入 ship state
-node "${CODEBUDDY_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 "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" hooks validate --root <path> --json
-# 仅旧冻结计划兼容：记录历史 Kimi/CodeBuddy 人工证明
-# （本地自声明收据，证明力弱：--actor 仅非空字符串校验、无外部签名核验；新计划不适用）
-node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" attest --root <path> \
-  --platform <kimi|codebuddy> --plugin <id> --result <passed|failed> --actor <person> --json
-# 发布文档刷新：默认只读演练
-node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> --json
-# 摘要确认后的本地写入（三项绑定缺一不可）
-node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> \
-  --write --confirm-refresh <refreshDigest> --ack-local-document-write --json
+node "${CODEBUDDY_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` 声明语种；`changelogs` 声明 path + locale；`readmes` 另含 `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 入口不存在 | 确认 `${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs` 存在；不存在时重新安装插件 |
-| 项目配置不存在 | 路由 `release-setup`，默认只读；不得直接生成或覆盖 README/配置 |
-| assess 失败 | 运行 `node "${CODEBUDDY_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 "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" route --root <path> \
-  --target-version <version> --json
-
+node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs" \
+  --root <project-root> --plan <plan-path> --run <verify-or-postverify-run-path> \
+  --finish --json
 ```
 
-输出 `classification` 区分 code/docs/config/marketplace 和 mixed，`recommendation` 给出 workflowKind、reason、firstCommand。
-
-**可用工作流**：
+首次结果可能请求用户选择分支和本机宿主，或返回需要智能体实际加载并调用 setup 的请求。将绑定反馈写入文件后，以同一入口增加 `--finish-feedback <feedback-path>` 再次汇总。完整参数、反馈合同、宿主限制和 macOS Cursor 安装见 `release-finish`。仅有 `VERIFIED` 不构成本机写入、插件更新、分支合并或 setup 写入授权；收尾结果也不改写发布状态。
 
-- `docs-only`: 纯文档变更（跳过代码类门限）
-- `config-only`: 纯配置变更（schema 验证 + 决策分支）
-- `marketplace-only`: 纯 marketplace 索引变更（条目更新 + snapshot 同步）
-- `full-happy-end`: 混合变更或无法确定（fail-closed 到最安全路径）
-- `reconcile`: 存在 PARTIAL 运行时需先恢复
-- `help`: 无变更且未指定目标版本
+## 专用工作流路由
 
-参考文档：
-- [`release-docs`](../release-docs/SKILL.md) - 文档工作流详解
-- [`release-config`](../release-config/SKILL.md) - 配置工作流详解
-- [`release-marketplace`](../release-marketplace/SKILL.md) - Marketplace 工作流详解
+- 消费项目的 Cursor 场景配置、受控可执行目录、用户状态目录、结果不确定时的现场保留与复验，见 `release-verify`。
+- README、CHANGELOG 和双语说明的 `docs refresh` 演练、摘要确认与受管写入，见 `release-docs`。
+- VERIFIED 后的分支决定、宿主更新、加载反馈、setup 和源码检查，见 `release-finish`。
+- 纯配置变更，见 `release-config`。
+- 纯 marketplace 索引与快照变更，见 `release-marketplace`。
 
-| RELEASE_DOCS_CONFLICT | 目标含非受管同版本条目、受管标记损坏或人工冲突；人工修复目标并保留人工修改后重新演练 |
-| RELEASE_DOCS_REFRESH_STALE | 确认绑定后候选已变化；重新演练取得新 `refreshDigest` 再确认写入 |
-| RELEASE_DOCS_STALE | prepare 检测到文档未刷新；按 `docs refresh` → 审阅 → 提交 → 重新 prepare 恢复 |
+这些入口保留各自的参数、确认和失败关闭规则；help 不复制或放宽它们。
 
-## Cursor 本地安装
+## 故障分诊
 
-完整 `adapters/cursor/` 插件的首次安装和升级见 `release-finish`；macOS 需退出 Cursor 并传入 `--cursor-plugins-root`。安装与加载分别验收。
+- Node.js 或 Git 缺失：读取 `missingRequired`，补齐依赖后重跑 help。
+- npm/gh 缺失或未认证：本地准备仍可继续；生产发布前另行完成 gh、Git HTTPS credential 与 npm auth 检查。
+- CLI 入口缺失：确认 `${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs` 存在；缺失时重新安装插件。
+- 项目配置缺失：进入 `release-setup` 的只读发现，不直接生成或覆盖 README/配置。
+- assess 失败：运行 `release-assess` 的离线诊断并按错误码处理。
+- `PARTIAL` 或远端冲突：进入 `release-reconcile`，保留已经成功的 checkpoint。
+- 文档、Cursor、宿主更新或本机收尾失败：转到上节对应专用 Skill，不在 help 中猜测恢复步骤。
 
 ## 后续引导
 
-本地就绪后运行 `release-assess`；生产发布另需 npm、gh 和认证检查。
+本地就绪后运行 `release-assess`；需要生产发布时，再确认 npm、gh、认证、冻结计划和有效批准。

package/adapters/workbuddy/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 "${CODEBUDDY_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/bin/release-skill-cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { readFile } from 'node:fs/promises';
-import { basename, dirname, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, normalize, resolve } from 'node:path';
 import { execFile as execFileCb } from 'node:child_process';
 import { promisify } from 'node:util';
 import { parseNodeMajor, meetsMinimum, computeReadinessStatus } from '../src/core/node-version.mjs';
@@ -432,6 +432,9 @@ Options:
   --hosts <ids>     Comma-separated local hosts for post-release update: claude,codex,kimi,codebuddy,workbuddy,qoder,cursor. No local host is updated unless --hosts contains at least one id
   --cursor-plugins-root <absolute-directory> Required for Cursor Local installation/update; quit Cursor before running
   --confirm-plan <digest> Confirm the exact VERIFIED plan before local host mutation
+  --finish         Run the complete post-release finish orchestration and return COMPLETE/PENDING/FAILED
+  --finish-feedback <absolute-json-file> Read bound agent-reported host loading and setup results
+  --skip-local-hosts Explicitly skip host update, loading, and setup for this finish run
   --no-hook-cache  Force every prepare hook to run in full; neither read nor write the hook cache
   --json           Output results as JSON
   --version        Show version and exit
@@ -1144,9 +1147,9 @@ if (command === 'ship') {
         const localHostUpdate = result.postRelease.localHostUpdate;
         if (localHostUpdate?.promptRequired === true) {
           console.log(`Post-release: ask whether to update local host plugins (${result.postRelease.localHostUpdate.hosts.join(', ')}).`);
-          if (localHostUpdate.available === true && typeof localHostUpdate.runPath === 'string') {
-            console.log(`Post-release command: release-skill post-release --plan ${result.planPath} --run ${localHostUpdate.runPath}`);
-            console.log('Choose --hosts before adding --update-local-hosts to perform a local update.');
+          if (result.postRelease.finishCommand) {
+            console.log(`Post-release finish command: ${result.postRelease.finishCommand.argv.join(' ')}`);
+            console.log('Choose --hosts before adding --update-local-hosts, or use --skip-local-hosts.');
           }
           printHubManualTargets(localHostUpdate.targets);
         } else {
@@ -1539,6 +1542,48 @@ if (command === 'post-release') {
   };
   const planPath = value('--plan') ? resolve(value('--plan')) : undefined;
   const runPath = value('--run') ? resolve(value('--run')) : undefined;
+  const finishRequested = args.includes('--finish');
+  const skipLocalHosts = args.includes('--skip-local-hosts');
+  const feedbackValue = value('--finish-feedback');
+  if (finishRequested || skipLocalHosts || args.includes('--finish-feedback')) {
+    const valued = new Set([
+      '--root', '--plan', '--run', '--confirm-plan', '--hosts',
+      '--cursor-plugins-root', '--finish-feedback',
+    ]);
+    const booleans = new Set(['--finish', '--skip-local-hosts', '--update-local-hosts', '--json']);
+    const seen = new Set();
+    let parameterError;
+    for (let index = 1; index < args.length; index += 1) {
+      const token = args[index];
+      if (valued.has(token)) {
+        if (seen.has(token)) parameterError ??= `post-release finish does not accept duplicate ${token}`;
+        seen.add(token);
+        const next = args[index + 1];
+        if (!next || next.startsWith('-')) parameterError ??= `post-release finish requires a value for ${token}`;
+        else index += 1;
+        continue;
+      }
+      if (booleans.has(token)) {
+        if (seen.has(token)) parameterError ??= `post-release finish does not accept duplicate ${token}`;
+        seen.add(token);
+        continue;
+      }
+      parameterError ??= `post-release finish does not accept ${token}`;
+    }
+    const rawHosts = value('--hosts');
+    if (!finishRequested) parameterError ??= '--skip-local-hosts and --finish-feedback require --finish';
+    if (skipLocalHosts && (args.includes('--update-local-hosts') || (typeof rawHosts === 'string' && rawHosts.trim().length > 0))) {
+      parameterError ??= '--skip-local-hosts conflicts with --update-local-hosts and --hosts';
+    }
+    if (feedbackValue && (!isAbsolute(feedbackValue) || normalize(feedbackValue) !== feedbackValue)) {
+      parameterError ??= '--finish-feedback requires a normalized absolute JSON file path';
+    }
+    if (parameterError) {
+      if (hasJson) console.log(JSON.stringify({ error: 'POST_RELEASE_FINISH_INVALID', message: parameterError, exitCode: 1 }));
+      else console.error(`Error: ${parameterError}`);
+      await exitAfterFlush(1);
+    }
+  }
   if (!planPath || !runPath) {
     const message = 'post-release requires --plan <path> and --run <verify-or-postverify-run-path>';
     if (hasJson) console.log(JSON.stringify({ error: 'MISSING_PARAMETERS', message, exitCode: 1 }));
@@ -1563,7 +1608,7 @@ if (command === 'post-release') {
       requireDigest: true,
       authorityPlanPath: planPath,
     });
-    if (!updateRequested) {
+    if (!updateRequested || finishRequested) {
       const { assertLocalFinishRun } = await import('../src/commands/post-release-local.mjs');
       await assertLocalFinishRun({
         plan,
@@ -1584,11 +1629,28 @@ if (command === 'post-release') {
       .split(',')
       .map((host) => host.trim())
       .filter(Boolean);
-    const result = updateRequested
+    const root = resolve(value('--root') ?? process.cwd());
+    const result = finishRequested
+      ? await (async () => {
+        const { runPostReleaseFinish } = await import('../src/commands/post-release-finish.mjs');
+        return runPostReleaseFinish({
+          root,
+          plan,
+          planPath,
+          runPath: resolvedRunPath,
+          selectedHosts,
+          updateRequested,
+          skipLocalHosts,
+          confirmPlanDigest: value('--confirm-plan'),
+          cursorPluginsRoot: value('--cursor-plugins-root'),
+          feedbackPath: feedbackValue,
+        });
+      })()
+      : updateRequested
       ? await updateLocalHostPlugins({
         planPath,
         runPath: resolvedRunPath,
-        root: resolve(value('--root') ?? process.cwd()),
+        root,
         confirmPlanDigest: value('--confirm-plan'),
         selectedHosts,
         cursorPluginsRoot: value('--cursor-plugins-root'),
@@ -1603,6 +1665,14 @@ if (command === 'post-release') {
 
     if (hasJson) {
       console.log(JSON.stringify(result, null, 2));
+    } else if (finishRequested) {
+      console.log(`Post-release finish: ${result.finish.status}`);
+      for (const [name, outcome] of Object.entries(result.finish.steps)) {
+        console.log(`  ${name}: ${outcome.status} - ${outcome.summary}`);
+      }
+      for (const action of result.finish.nextActions) {
+        console.log(`Next [${action.type}] ${JSON.stringify(action)}`);
+      }
     } else if (!updateRequested) {
       console.log(`Post-release status: ${result.status}`);
       if (result.merge.promptRequired) console.log('Ask whether the user wants to merge the remaining branch.');
@@ -1626,6 +1696,9 @@ if (command === 'post-release') {
       }
       console.log('The release remains VERIFIED; restart updated hosts before using the new plugin bytes.');
     }
+    if (finishRequested) {
+      await exitAfterFlush(result.finish.status === 'COMPLETE' ? 0 : result.finish.status === 'PENDING' ? 2 : 1);
+    }
     const success = !updateRequested || ['UPDATED', 'ALREADY_CURRENT', 'NO_APPLICABLE_HOSTS'].includes(result.status);
     await exitAfterFlush(success ? 0 : 1);
   } catch (err) {
@@ -1705,7 +1778,9 @@ if (command === 'verify') {
       } = await import('../src/commands/post-release-local.mjs');
       const plan = JSON.parse(await readFile(planPath, 'utf8'));
       try {
-        result.postRelease = derivePostReleaseChecklist(plan, { root, runPath: result.runPath });
+        result.postRelease = derivePostReleaseChecklist(plan, {
+          root, planPath, runPath: result.runPath,
+        });
       } catch (error) {
         result.postRelease = unavailablePostReleaseChecklist(plan, error);
       }
@@ -1733,9 +1808,9 @@ if (command === 'verify') {
       }
       if (result.postRelease?.localHostUpdate?.promptRequired === true) {
         console.log(`Post-release: ask whether to update local host plugins (${result.postRelease.localHostUpdate.hosts.join(', ')}).`);
-        if (result.postRelease.localHostUpdate.available === true && typeof result.postRelease.localHostUpdate.runPath === 'string') {
-          console.log(`Post-release command: release-skill post-release --plan ${planPath} --run ${result.postRelease.localHostUpdate.runPath}`);
-          console.log('Choose --hosts before adding --update-local-hosts to perform a local update.');
+        if (result.postRelease.finishCommand) {
+          console.log(`Post-release finish command: ${result.postRelease.finishCommand.argv.join(' ')}`);
+          console.log('Choose --hosts before adding --update-local-hosts, or use --skip-local-hosts.');
         }
         printHubManualTargets(result.postRelease.localHostUpdate.targets);
       } else {
@@ -1863,6 +1938,7 @@ This command creates an independent postVerify run and never reads or writes shi
         plan = JSON.parse(await readFile(resolve(planPath), 'utf8'));
         result.postRelease = derivePostReleaseChecklist(plan, {
           root,
+          planPath: resolve(planPath),
           runPath: result.runPath,
           postVerifyComplete: true,
         });
@@ -1884,9 +1960,9 @@ This command creates an independent postVerify run and never reads or writes shi
       } else if (result.postRelease?.localHostUpdate?.promptRequired === true) {
         const localHostUpdate = result.postRelease.localHostUpdate;
         console.log(`Post-release: ask whether to update local host plugins (${localHostUpdate.hosts.join(', ')}).`);
-        if (localHostUpdate.available === true && typeof localHostUpdate.runPath === 'string') {
-          console.log(`Post-release command: release-skill post-release --plan ${resolve(planPath)} --run ${localHostUpdate.runPath}`);
-          console.log('Choose --hosts before adding --update-local-hosts to perform a local update.');
+        if (result.postRelease.finishCommand) {
+          console.log(`Post-release finish command: ${result.postRelease.finishCommand.argv.join(' ')}`);
+          console.log('Choose --hosts before adding --update-local-hosts, or use --skip-local-hosts.');
         }
         printHubManualTargets(localHostUpdate.targets);
       }