release-skill 0.9.3 → 0.9.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"
@@ -79,9 +79,9 @@
     "ajv-formats": "3.0.1",
     "libnpmpublish": "11.2.0",
     "npm-registry-fetch": "18.0.2",
-    "skill-family-contracts": "0.15.0",
-    "skill-family-engineering-kit": "0.15.0",
-    "skill-family-harness-node": "0.15.0",
+    "skill-family-contracts": "0.16.0",
+    "skill-family-engineering-kit": "0.16.0",
+    "skill-family-harness-node": "0.16.0",
     "yaml": "2.9.0"
   },
   "devDependencies": {

package/platform-manifest.json

@@ -2,11 +2,11 @@
   "schemaVersion": "1.0.0",
   "platformId": "release-skill",
   "platformName": "release-skill Plugin Platform",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "logicalRoot": "skills-src/",
-  "logicalRootDigest": "be294a1ed865d99841b78b60039136ab28b13ceaedf28570b2fbd91febd1ef65",
-  "projectionDigest": "fbd95e66fe7183c9cfd34eb83fa084e259a00806b3f129734cf866de632723cf",
-  "projectionId": "release-skill:platform:0.9.3",
+  "logicalRootDigest": "673e640c5e6b017bacc31649886805c879ac244b1b79b9917d2515f88f09e8ca",
+  "projectionDigest": "582e662d6f288725ffa09cd83034a339b8e05ec5c44a4989c16bf4e6a774e3c4",
+  "projectionId": "release-skill:platform:0.9.4",
   "manifestRequired": true,
   "projectionSources": {
     "skills-src-root": {

package/references/.render-manifest.json

@@ -6,12 +6,12 @@
       "bytes": 6335
     },
     "01-state-machine.md": {
-      "digest": "5afc8e9c29c0d5fb0de0db8b248bbb812fc715af185ac594a172fe68d9a24fed",
-      "bytes": 12617
+      "digest": "85e20f4ba60a833325516b9ced9351f9e324cd7b386460d3fb108b79b8875265",
+      "bytes": 14857
     },
     "02-project-config.md": {
-      "digest": "09e3c470dea54fe9437528620cc169596e75b5162e137683923347c9cb3702a6",
-      "bytes": 23167
+      "digest": "50f9b775a4864270642b752d040546f6c365f0b49bf1bfe8a3aacefe88eae702",
+      "bytes": 26033
     },
     "03-readme-quality.md": {
       "digest": "d74e41052592443ebbd450d0ace5f9b9b19c7a94db50f952b17c1c5a4c5dc230",

package/references/01-state-machine.md

@@ -84,6 +84,24 @@ postPublish hooks 分两个阶段，各自对应独立的 distribute run：
 - **postVerify 阶段**（`phase: postVerify`）：主 run VERIFIED 后由 ship/verify 路由触发，产出独立的 distribute run（复用现有 run 记录与 checkpoint 机制）；失败即该 run PARTIAL、reconcile 可续。主 run 的 VERIFIED 不回退，但 postVerify run 的失败必须以证据显著记录，绝不静默。
 - **checkpoint 级批准**：`requiresApproval: true` 的 hook 执行前需要绑定 `(planDigest, hookId)` 的独立批准记录（24h 过期、5 分钟时钟偏移容忍）。批准未获时：尚无外部 checkpoint 成功 → checkpoint 标记 `AWAITING_APPROVAL`、run 进 NEEDS_INPUT；已有外部 checkpoint 成功 → run 保持 PARTIAL。
 
+### 2.3 发布范围与延期单元（v0.9.4）
+
+多发布单元项目可以在首次计划冻结前显式选择本轮发布范围。`prepare` 和新建的
+`ship` 状态接受可重复的 `--unit <id>`；未传该参数时，范围仍是配置中的全部发布单元。
+
+显式选择不会增加生命周期状态。未选中的单元只显示为延期单元，不进入本轮
+`plan.units`，也不获得 PREPARED、APPROVED、PUBLISHED 或 VERIFIED 含义。完整项目配置、
+生成物新鲜度和顶层 hooks 仍按项目级规则检查；按单元绑定的版本、文档、快照、分发和
+验证门只处理选中单元。
+
+计划冻结后，`plan.units` 是唯一发布范围权威。批准必须绑定计划内的全部动作，
+`publish`、`reconcile`、`verify` 和 `distribute` 必须完整处理该计划，不接受单元选择参数。
+`ship` 可以沿用首次保存的显式范围恢复，但不得在同一状态上改变范围。旧状态没有保存
+显式范围时按全范围处理，不能在原状态上追加 `--unit`。
+
+外部写入开始后不得缩小范围。任一检查点成功后出现失败，仍进入 PARTIAL，并由
+`reconcile` 在原冻结计划内向前恢复；延期单元需要另行 prepare、审阅和批准。
+
 ---
 
 ## 3. 禁止转换

package/references/02-project-config.md

@@ -126,6 +126,26 @@ unit 恰好声明一个 npm distribution。prepare 等所有 subject tarball 冻
 重新下载远端字节并核对 SHA-256。离线消费者只需该文件和其中 subjects 对应的精确 tarball，便可
 核对包名、版本、文件名、tarball SHA-256、源码仓库与源码基线提交。
 
+### 2.1 显式发布范围（v0.9.4）
+
+发布范围不增加配置字段。`releaseUnits[]` 继续声明项目可发布的全部单元；操作者可以在
+`prepare` 或新建 `ship` 状态时重复传入 `--unit <id>`，从中选择本轮范围。未传参数时
+选择全部单元。显式参数至少包含一个已声明的唯一 ID，计划顺序始终按
+`releaseUnits[]` 的声明顺序确定，不受命令行顺序影响。
+
+选择只裁剪按单元绑定的工作，包括版本与发布文档检查、公开文件快照、分发合同、
+`verificationGates[].scope.unit` 对应的验证门和发布后声明。配置 Schema、单元 ID
+唯一性、生成物新鲜度和顶层 `hooks` 仍覆盖完整项目。顶层 Hook 没有单元作用域，
+不得根据命令、路径或输出猜测归属。
+
+`publicSourceAuthorityReceipt` 是现有的附加依赖闭包。显式范围只要包含 coordinator
+或任一 subject，就必须同时包含该收据声明涉及的全部单元。prepare 不会自动扩大范围；
+范围不完整时会在 Hook、快照和计划写入前停止，并返回缺少的单元和精确重试参数。
+
+冻结计划只包含选中单元及其派生门、动作和发布后声明。`plan.units` 是冻结后的唯一
+发布范围权威，完整配置摘要仍进入计划绑定。延期单元不写回项目配置，也不形成状态、
+豁免或待办记录。`publish`、`reconcile`、`verify` 和 `distribute` 不接受单元选择参数。
+
 `postPublish` 只能位于某个 `releaseUnits[]` 条目内。下面的完整结构样例会由 schema 契约测试直接读取并校验，避免文档层级再次漂移：
 
 ```yaml

package/skills/release-help/SKILL.md

@@ -17,11 +17,15 @@ description: "Discoverable entry point for release-skill: dependency and environ
 - 只读诊断：运行 dry-run 检查，不修改任何文件
 - 故障引导：根据错误码指向对应的修复 Skill
 
-## 0.9.3 候选边界
+## 0.9.4 候选边界
 
-当前源码候选已接入四项工作流保护、Hook cache v2 和稳定隔离安装树记录。三项 Foundation 依赖精确使用 0.15.0 的公开包根 API。Hook cache 只复用绝对路径或经真实 cwd 校验的 cwd-relative executable identity；裸 PATH、PATHEXT、Windows 和观察不可用时，Hook 仍冷执行，缓存复用失败关闭且不写入 v2 cache。缓存没有 TTL。
+当前源码候选允许多发布单元项目在计划冻结前显式选择本轮范围。`prepare` 和新建的 `ship` 状态支持重复传入 `--unit <id>`；未传时继续选择全部配置单元。成功选择会列出选中与延期单元。延期单元不进入本轮计划，也不获得发布状态。
 
-稳定隔离安装树记录只在宿主命令退出、目录已隔离且扫描期间没有并发写入时执行；宿主附加链接只记录、不跟随，声明载荷中的 symlink 失败关闭，legacy 全树语义保持不变。0.9.3 仍是源码候选，不能从本说明推断已批准、发布或验证。
+选择只影响按单元绑定的检查与动作。完整配置、生成物新鲜度和顶层 Hook 仍覆盖整个项目。`publicSourceAuthorityReceipt` 涉及的 coordinator 和 subjects 必须作为完整闭包共同选择，系统不会自动扩选。计划冻结后，`plan.units` 是唯一范围权威；publish、reconcile、verify 和 distribute 不接受 `--unit`。
+
+0.9.3 引入的四项工作流保护、Hook cache v2 和稳定隔离安装树记录在 0.9.4 继续保留。0.9.4 精确消费 Foundation 0.16.0 的公开包根 API。Hook cache 只复用绝对路径或经真实 cwd 校验的 cwd-relative executable identity；裸 PATH、PATHEXT、Windows 和观察不可用时，Hook 仍冷执行，缓存复用失败关闭且不写入 v2 cache。缓存没有 TTL。
+
+稳定隔离安装树记录只在宿主命令退出、目录已隔离且扫描期间没有并发写入时执行；宿主附加链接只记录、不跟随，声明载荷中的 symlink 失败关闭，legacy 全树语义保持不变。0.9.4 仍是源码候选，不能从本说明推断已批准、发布或验证。
 
 **阶段通过规则**: `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 无权把本地就绪解释为生产就绪。
 
@@ -44,6 +48,9 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offlin
 # 日常发布快速路径：发布前确认可读计划摘要，状态文件可恢复。
 # 受限 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
 # 开发阶段执行声明 hooks 并生成 prepare 可复用的内容绑定收据
 # 配置时刻即授权（FM-16 处置 A）：hook 是任意本地进程、无隔离、触发前无确认点，
 # 命令调用本身即授权执行配置中的 hooks

package/skills/release-prepare/SKILL.md

@@ -13,7 +13,9 @@ description: Freeze an immutable release plan with local configuration, document
 
 运行项目构建/测试 hook，生成公开快照并扫描泄漏，冻结不可变发布计划。prepare 自身不调用发布 adapter，但会执行用户配置的 hook。
 
-0.9.3 候选的 Hook cache v2 只复用有完整身份和输入证据的成功 Hook 结果。裸 PATH、PATHEXT、Windows、TTL、损坏记录或 Foundation 观察不可用时，缓存保持失败关闭，Hook 仍按完整路径冷执行；该机制不改变 prepare 的计划、批准和发布权威。
+0.9.4 候选允许多发布单元项目在冻结前显式选择本轮范围。`--unit <id>` 可以重复传入；未传时仍选择全部单元。显式选择只跳过延期单元的单元级工作，完整配置校验、生成物新鲜度和顶层 Hook 仍全部执行。计划冻结后以 `plan.units` 为唯一范围权威，publish、reconcile、verify 和 distribute 不接受单元选择。
+
+0.9.3 引入的 Hook cache v2 继续只复用有完整身份和输入证据的成功 Hook 结果。裸 PATH、PATHEXT、Windows、TTL、损坏记录或 Foundation 观察不可用时，缓存保持失败关闭，Hook 仍按完整路径冷执行；该机制不改变 prepare 的计划、批准和发布权威。
 
 **Hook 授权契约（配置时刻即授权，FM-16 处置 A）**: hook 是任意本地进程——在 `.release-skill/project.yaml` 中配置 hook 命令即完成授权，构成「配置时刻即授权」的显式契约。hook 不提供沙箱、无文件系统/网络隔离、触发前无确认点，命令调用本身即授权执行已配置的 hook 和 gate，不再设置额外人工授权环节；hook 可能产生项目目录外的副作用或远端写入，配置者须对其内容负责。旧参数 `--acknowledge-hook-side-effects` 和 `--acknowledge-gate-side-effects` 仍可解析，但只作为无效果的兼容输入，不能改变授权或执行语义。恢复「触发前强制确认门」属于后续加固项（属设计变更，需随新版本引入），当前版本不提供该确认门。
 
@@ -25,11 +27,13 @@ description: Freeze an immutable release plan with local configuration, document
 
 **发布文档新鲜度门**: 配置了 `releaseDocuments` 的单元在 hook 授权门前先执行同一只读规划器：`clean` 继续；`changes` 抛 `RELEASE_DOCS_STALE`，详情列出相对路径、语种、`refreshDigest` 和精确演练/写入参数数组。prepare 只检查、不写工作树。正式 prepare 前先运行只读演练；有变化时向用户展示文件/语种/版本/`refreshDigest`，只有在用户明确授权"本地发布文档写入"后，才执行带 `--write --confirm-refresh <refreshDigest> --ack-local-document-write` 三项绑定的写入，随后运行聚焦校验，要求维护者审阅并提交刷新结果，再重新 prepare。该授权不扩展为 hook、提交、push 或 publish 授权。
 
+**显式发布范围**: 只有用户已经指出本轮要发布哪些单元时，才把这些 ID 逐个传给 `--unit`。release-skill 不根据失败自动排除单元。选择命中 `publicSourceAuthorityReceipt` 的 coordinator 或 subject 时，必须包含收据声明的完整单元闭包；缺少单元时按命令返回的精确 argv 重新选择，不自动扩选。成功后展示 `releaseScope.selectedUnitIds`、`releaseScope.deferredUnitIds` 和批准摘要。延期仅表示没有进入本轮计划，不表示通过或失败。
+
 ## 正向执行路径
 
 1. 使用插件根相对路径运行 CLI：`CLI="node ${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs"`
 2. 配置含 `releaseDocuments` 时，先运行只读演练 `${CLI} docs refresh --unit <id> --json`；`status: "changes"` 时展示逐文件路径/语种/版本/`refreshDigest`，取得"本地发布文档写入"明确授权后才执行 `nextCommand.argv` 写入，审阅并提交刷新结果后再继续；`status: "clean"` 时直接进入 prepare
-3. 运行 `${CLI} prepare --root <path> --offline --json`
+3. 运行 `${CLI} prepare --root <path> --offline --json`；用户已明确选择范围时，为每个单元追加一个 `--unit <id>`
 4. 检查 exit code 0，读取 JSON 返回的 immutable `planPath=plans/<planDigest>.json`，再从该文件读取 `status`、`units`、`externalActions`
 5. 向用户展示可读的 `approvalSummary`：版本、公开仓库、分支策略、branch/tag、npm 与 GitHub Release 目标、全部外部动作、例外，以及需要独立 checkpoint 批准的 postPublish hook。`planDigest` 仅作为内部绑定字段，不要求用户复制或确认。后续 approve/publish 只能使用该 immutable planPath，等待确认后再 approve。计划批准不包含受限 postPublish hook 的 checkpoint 批准
 
@@ -64,6 +68,9 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> --js
 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" prepare --root <path> --offline --json
+# 显式选择发布范围；未传 --unit 时仍准备全部配置单元
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offline \
+  --unit <unit-a> --unit <unit-b> --json
 # 生产 happy end：bound 基线必须 online；远端目标唯一性仍由 publish 全局预检
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --online --production --json
 ```
@@ -81,11 +88,12 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --onlin
 | GATE_FAILED (bound + offline) | 改用 `--online --production`，不得把 unobserved-offline plan 交给 publish |
 | GATE_FAILED (前序基线漂移) | 先取得并比较实际远端内容；人工选择 merge/adopt/reject。merge/adopt 都必须把接受内容落回 human-owned 权威源，并把 `previousPublicBaseline` 更新为接受状态的精确 repo/ref/commit 后重新 online production prepare；reject 停止调查，禁止改 `mode: none` 绕过 |
 | GATE_FAILED (`npm-entry-closure`) | 修复打包内容或入口声明后重新 prepare；不得用 `requiredPublicFiles`/`smokeBin` 缺省绕过 |
+| GATE_FAILED（发布范围依赖闭包不完整） | 按详情补齐 `publicSourceAuthorityReceipt` 声明涉及的 coordinator 和全部 subjects，再重新 prepare；不得自动扩选或忽略收据 |
 | GATE_FAILED (其他) | 修复门失败原因后重试；以 CLI exit code 为准 |
 | RELEASE_DOCS_STALE | 文档相对说明源已陈旧；按详情运行只读演练，展示文件/语种/版本/摘要，经用户授权“本地发布文档写入”后执行写入，审阅提交再重新 prepare |
 | RELEASE_DOCS_INVALID / TRANSLATION_MISSING / CONFLICT / REFRESH_STALE | 修复配置/说明源/目标或重新演练取得新 `refreshDigest`；不得扩大写入范围绕过 |
 | SECRET_DETECTED | 移除密钥并更新 allowlist |
-| CONFIG_INVALID | 检查 version.source 和 package.json |
+| CONFIG_INVALID | 检查 version.source、package.json，以及 `--unit` 是否为空、重复或不在 `releaseUnits[]` 中 |
 
 重试时只保留最新结构化错误码和失败门，不沿用早期猜测；重跑确定性命令获得新证据。
 

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

@@ -17,11 +17,15 @@ description: "Discoverable entry point for release-skill: dependency and environ
 - 只读诊断：运行 dry-run 检查，不修改任何文件
 - 故障引导：根据错误码指向对应的修复 Skill
 
-## 0.9.3 候选边界
+## 0.9.4 候选边界
 
-当前源码候选已接入四项工作流保护、Hook cache v2 和稳定隔离安装树记录。三项 Foundation 依赖精确使用 0.15.0 的公开包根 API。Hook cache 只复用绝对路径或经真实 cwd 校验的 cwd-relative executable identity；裸 PATH、PATHEXT、Windows 和观察不可用时，Hook 仍冷执行，缓存复用失败关闭且不写入 v2 cache。缓存没有 TTL。
+当前源码候选允许多发布单元项目在计划冻结前显式选择本轮范围。`prepare` 和新建的 `ship` 状态支持重复传入 `--unit <id>`；未传时继续选择全部配置单元。成功选择会列出选中与延期单元。延期单元不进入本轮计划，也不获得发布状态。
 
-稳定隔离安装树记录只在宿主命令退出、目录已隔离且扫描期间没有并发写入时执行；宿主附加链接只记录、不跟随，声明载荷中的 symlink 失败关闭，legacy 全树语义保持不变。0.9.3 仍是源码候选，不能从本说明推断已批准、发布或验证。
+选择只影响按单元绑定的检查与动作。完整配置、生成物新鲜度和顶层 Hook 仍覆盖整个项目。`publicSourceAuthorityReceipt` 涉及的 coordinator 和 subjects 必须作为完整闭包共同选择，系统不会自动扩选。计划冻结后，`plan.units` 是唯一范围权威；publish、reconcile、verify 和 distribute 不接受 `--unit`。
+
+0.9.3 引入的四项工作流保护、Hook cache v2 和稳定隔离安装树记录在 0.9.4 继续保留。0.9.4 精确消费 Foundation 0.16.0 的公开包根 API。Hook cache 只复用绝对路径或经真实 cwd 校验的 cwd-relative executable identity；裸 PATH、PATHEXT、Windows 和观察不可用时，Hook 仍冷执行，缓存复用失败关闭且不写入 v2 cache。缓存没有 TTL。
+
+稳定隔离安装树记录只在宿主命令退出、目录已隔离且扫描期间没有并发写入时执行；宿主附加链接只记录、不跟随，声明载荷中的 symlink 失败关闭，legacy 全树语义保持不变。0.9.4 仍是源码候选，不能从本说明推断已批准、发布或验证。
 
 **阶段通过规则**: `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 无权把本地就绪解释为生产就绪。
 
@@ -44,6 +48,9 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offlin
 # 日常发布快速路径：发布前确认可读计划摘要，状态文件可恢复。
 # 受限 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
 # 开发阶段执行声明 hooks 并生成 prepare 可复用的内容绑定收据
 # 配置时刻即授权（FM-16 处置 A）：hook 是任意本地进程、无隔离、触发前无确认点，
 # 命令调用本身即授权执行配置中的 hooks

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

@@ -13,7 +13,9 @@ description: Freeze an immutable release plan with local configuration, document
 
 运行项目构建/测试 hook，生成公开快照并扫描泄漏，冻结不可变发布计划。prepare 自身不调用发布 adapter，但会执行用户配置的 hook。
 
-0.9.3 候选的 Hook cache v2 只复用有完整身份和输入证据的成功 Hook 结果。裸 PATH、PATHEXT、Windows、TTL、损坏记录或 Foundation 观察不可用时，缓存保持失败关闭，Hook 仍按完整路径冷执行；该机制不改变 prepare 的计划、批准和发布权威。
+0.9.4 候选允许多发布单元项目在冻结前显式选择本轮范围。`--unit <id>` 可以重复传入；未传时仍选择全部单元。显式选择只跳过延期单元的单元级工作，完整配置校验、生成物新鲜度和顶层 Hook 仍全部执行。计划冻结后以 `plan.units` 为唯一范围权威，publish、reconcile、verify 和 distribute 不接受单元选择。
+
+0.9.3 引入的 Hook cache v2 继续只复用有完整身份和输入证据的成功 Hook 结果。裸 PATH、PATHEXT、Windows、TTL、损坏记录或 Foundation 观察不可用时，缓存保持失败关闭，Hook 仍按完整路径冷执行；该机制不改变 prepare 的计划、批准和发布权威。
 
 **Hook 授权契约（配置时刻即授权，FM-16 处置 A）**: hook 是任意本地进程——在 `.release-skill/project.yaml` 中配置 hook 命令即完成授权，构成「配置时刻即授权」的显式契约。hook 不提供沙箱、无文件系统/网络隔离、触发前无确认点，命令调用本身即授权执行已配置的 hook 和 gate，不再设置额外人工授权环节；hook 可能产生项目目录外的副作用或远端写入，配置者须对其内容负责。旧参数 `--acknowledge-hook-side-effects` 和 `--acknowledge-gate-side-effects` 仍可解析，但只作为无效果的兼容输入，不能改变授权或执行语义。恢复「触发前强制确认门」属于后续加固项（属设计变更，需随新版本引入），当前版本不提供该确认门。
 
@@ -25,11 +27,13 @@ description: Freeze an immutable release plan with local configuration, document
 
 **发布文档新鲜度门**: 配置了 `releaseDocuments` 的单元在 hook 授权门前先执行同一只读规划器：`clean` 继续；`changes` 抛 `RELEASE_DOCS_STALE`，详情列出相对路径、语种、`refreshDigest` 和精确演练/写入参数数组。prepare 只检查、不写工作树。正式 prepare 前先运行只读演练；有变化时向用户展示文件/语种/版本/`refreshDigest`，只有在用户明确授权"本地发布文档写入"后，才执行带 `--write --confirm-refresh <refreshDigest> --ack-local-document-write` 三项绑定的写入，随后运行聚焦校验，要求维护者审阅并提交刷新结果，再重新 prepare。该授权不扩展为 hook、提交、push 或 publish 授权。
 
+**显式发布范围**: 只有用户已经指出本轮要发布哪些单元时，才把这些 ID 逐个传给 `--unit`。release-skill 不根据失败自动排除单元。选择命中 `publicSourceAuthorityReceipt` 的 coordinator 或 subject 时，必须包含收据声明的完整单元闭包；缺少单元时按命令返回的精确 argv 重新选择，不自动扩选。成功后展示 `releaseScope.selectedUnitIds`、`releaseScope.deferredUnitIds` 和批准摘要。延期仅表示没有进入本轮计划，不表示通过或失败。
+
 ## 正向执行路径
 
 1. 使用插件根相对路径运行 CLI：`CLI="node ${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs"`
 2. 配置含 `releaseDocuments` 时，先运行只读演练 `${CLI} docs refresh --unit <id> --json`；`status: "changes"` 时展示逐文件路径/语种/版本/`refreshDigest`，取得"本地发布文档写入"明确授权后才执行 `nextCommand.argv` 写入，审阅并提交刷新结果后再继续；`status: "clean"` 时直接进入 prepare
-3. 运行 `${CLI} prepare --root <path> --offline --json`
+3. 运行 `${CLI} prepare --root <path> --offline --json`；用户已明确选择范围时，为每个单元追加一个 `--unit <id>`
 4. 检查 exit code 0，读取 JSON 返回的 immutable `planPath=plans/<planDigest>.json`，再从该文件读取 `status`、`units`、`externalActions`
 5. 向用户展示可读的 `approvalSummary`：版本、公开仓库、分支策略、branch/tag、npm 与 GitHub Release 目标、全部外部动作、例外，以及需要独立 checkpoint 批准的 postPublish hook。`planDigest` 仅作为内部绑定字段，不要求用户复制或确认。后续 approve/publish 只能使用该 immutable planPath，等待确认后再 approve。计划批准不包含受限 postPublish hook 的 checkpoint 批准
 
@@ -64,6 +68,9 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" docs refresh --unit <id> --js
 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" prepare --root <path> --offline --json
+# 显式选择发布范围；未传 --unit 时仍准备全部配置单元
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offline \
+  --unit <unit-a> --unit <unit-b> --json
 # 生产 happy end：bound 基线必须 online；远端目标唯一性仍由 publish 全局预检
 node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --online --production --json
 ```
@@ -81,11 +88,12 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --onlin
 | GATE_FAILED (bound + offline) | 改用 `--online --production`，不得把 unobserved-offline plan 交给 publish |
 | GATE_FAILED (前序基线漂移) | 先取得并比较实际远端内容；人工选择 merge/adopt/reject。merge/adopt 都必须把接受内容落回 human-owned 权威源，并把 `previousPublicBaseline` 更新为接受状态的精确 repo/ref/commit 后重新 online production prepare；reject 停止调查，禁止改 `mode: none` 绕过 |
 | GATE_FAILED (`npm-entry-closure`) | 修复打包内容或入口声明后重新 prepare；不得用 `requiredPublicFiles`/`smokeBin` 缺省绕过 |
+| GATE_FAILED（发布范围依赖闭包不完整） | 按详情补齐 `publicSourceAuthorityReceipt` 声明涉及的 coordinator 和全部 subjects，再重新 prepare；不得自动扩选或忽略收据 |
 | GATE_FAILED (其他) | 修复门失败原因后重试；以 CLI exit code 为准 |
 | RELEASE_DOCS_STALE | 文档相对说明源已陈旧；按详情运行只读演练，展示文件/语种/版本/摘要，经用户授权“本地发布文档写入”后执行写入，审阅提交再重新 prepare |
 | RELEASE_DOCS_INVALID / TRANSLATION_MISSING / CONFLICT / REFRESH_STALE | 修复配置/说明源/目标或重新演练取得新 `refreshDigest`；不得扩大写入范围绕过 |
 | SECRET_DETECTED | 移除密钥并更新 allowlist |
-| CONFIG_INVALID | 检查 version.source 和 package.json |
+| CONFIG_INVALID | 检查 version.source、package.json，以及 `--unit` 是否为空、重复或不在 `releaseUnits[]` 中 |
 
 重试时只保留最新结构化错误码和失败门，不沿用早期猜测；重跑确定性命令获得新证据。
 

package/src/commands/post-release-local.mjs

@@ -35,6 +35,16 @@ const SAFE_ENV_KEYS = Object.freeze([
   'SSL_CERT_FILE', 'SSL_CERT_DIR', 'NODE_EXTRA_CA_CERTS',
   'CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'KIMI_CONFIG_DIR',
 ]);
+const CODEBUDDY_PLUGIN_LIST_ARGS = Object.freeze(['plugin', 'list', '--json']);
+const CODEBUDDY_MARKETPLACE_LIST_ARGS = Object.freeze(['plugin', 'marketplace', 'list']);
+
+function attachFoundationFailure(error, { envelope, stdout }) {
+  Object.defineProperties(error, {
+    foundationEnvelope: { value: envelope, enumerable: false },
+    foundationStdout: { value: stdout, enumerable: false },
+  });
+  return error;
+}
 
 function actionTarget(plan, action, host) {
   const parameters = action.parameters ?? {};
@@ -259,7 +269,7 @@ async function defaultRun(command, args, options = {}) {
         watchdogReason: envelope.watchdogReason,
         ...(envelope.evidence?.spawnError ? { spawnError: envelope.evidence.spawnError } : {}),
       };
-      throw error;
+      throw attachFoundationFailure(error, { envelope, stdout });
     }
     return { stdout, stderr };
   }, { prefix: 'release-skill-host-command-' });
@@ -303,6 +313,96 @@ function parseJson(stdout, label) {
   }
 }
 
+function foundationEnvelopeFromError(error) {
+  return error?.foundationEnvelope ?? null;
+}
+
+function foundationStdoutFromError(error) {
+  return error?.foundationStdout ?? null;
+}
+
+function isCodeBuddyResidualEnvelope(error) {
+  const envelope = foundationEnvelopeFromError(error);
+  const evidence = envelope?.evidence;
+  const signals = evidence?.signalSequence;
+  const signal = signals?.[0];
+  return envelope?.ok === false
+    && envelope.exitStatus === 124
+    && envelope.processStatus === 'TERMINATED'
+    && envelope.terminationReason === 'child_exit'
+    && envelope.watchdogReason === 'residual_process_group'
+    && evidence?.childExitCode === 0
+    && (evidence.childSignal === null || evidence.childSignal === undefined)
+    && evidence.residualGroupCleanupCompleted === true
+    && evidence.forcedKill === false
+    && evidence.outputLimitExceeded === null
+    && Array.isArray(signals)
+    && signals.length === 1
+    && signal?.signal === 'SIGTERM'
+    && signal.requestedMode === 'process_group'
+    && signal.successfulMode === 'process_group';
+}
+
+function isCodeBuddyReadCommand(target, command, args) {
+  return target.host === 'codebuddy'
+    && (command === 'codebuddy' || command === 'cbc' || command === CODEBUDDY_MACOS_PATH)
+    && Array.isArray(args)
+    && (
+      args.every((value, index) => value === CODEBUDDY_PLUGIN_LIST_ARGS[index])
+      && args.length === CODEBUDDY_PLUGIN_LIST_ARGS.length
+      || args.every((value, index) => value === CODEBUDDY_MARKETPLACE_LIST_ARGS[index])
+      && args.length === CODEBUDDY_MARKETPLACE_LIST_ARGS.length
+    );
+}
+
+function isCodeBuddyWriteCommand(target, command, args, kind) {
+  if (target.host !== 'codebuddy' || !['codebuddy', 'cbc', CODEBUDDY_MACOS_PATH].includes(command)) return false;
+  const expected = kind === 'marketplace-update'
+    ? ['plugin', 'marketplace', 'update', target.marketplace]
+    : ['plugin', 'update', `${target.plugin}@${target.marketplace}`, '--scope', 'user'];
+  return Array.isArray(args) && args.length === expected.length && args.every((value, index) => value === expected[index]);
+}
+
+async function runCodeBuddyRead(target, command, args, label, env, run) {
+  try {
+    return { output: await run(command, [...args], { env }), recovered: false };
+  } catch (error) {
+    if (!isCodeBuddyReadCommand(target, command, args) || !isCodeBuddyResidualEnvelope(error)) throw error;
+    const residualStdout = foundationStdoutFromError(error);
+    if (typeof residualStdout !== 'string') throw error;
+    parseJson(residualStdout, label);
+    return {
+      output: { stdout: residualStdout, stderr: '' },
+      recovered: true,
+    };
+  }
+}
+
+function exactCodeBuddyMarketplaceObservation(target, stdout) {
+  const parsed = parseJson(stdout, `${target.host} marketplace list`);
+  if (!Array.isArray(parsed)) throw new Error(`${target.host} marketplace list did not return an array`);
+  const matches = parsed.filter((entry) => entry?.name === target.marketplace);
+  if (matches.length !== 1) {
+    throw new Error(`${target.host} marketplace list did not contain exactly one ${target.marketplace}`);
+  }
+  if (matches[0].type !== 'git') {
+    throw new Error(`${target.host} marketplace ${target.marketplace} is not a git marketplace`);
+  }
+  return { installed: true, exact: true, found: matches[0] };
+}
+
+async function observeCodeBuddyMarketplaceAfterResidual(target, command, env, run) {
+  const observed = await runCodeBuddyRead(
+    target,
+    command,
+    CODEBUDDY_MARKETPLACE_LIST_ARGS,
+    `${target.host} marketplace list`,
+    env,
+    run,
+  );
+  return exactCodeBuddyMarketplaceObservation(target, observed.output.stdout);
+}
+
 function exactPluginObservation(target, stdout) {
   const selector = `${target.plugin}@${target.marketplace}`;
   const parsed = parseJson(stdout, `${target.host} plugin list`);
@@ -433,7 +533,10 @@ async function runStructuredUpdate(target, detected, run, {
 }) {
   if (target.host === 'codebuddy' || target.host === 'workbuddy') {
     const env = hostEnvironment(target.host);
-    const listed = await run(detected.command, ['plugin', 'list', '--json'], { env });
+    const listedObservation = target.host === 'codebuddy'
+      ? await runCodeBuddyRead(target, detected.command, CODEBUDDY_PLUGIN_LIST_ARGS, `${target.host} plugin list`, env, run)
+      : { output: await run(detected.command, [...CODEBUDDY_PLUGIN_LIST_ARGS], { env }), recovered: false };
+    const listed = listedObservation.output;
     const observed = exactPluginObservation(target, listed.stdout);
     if (
       target.sourceForm !== 'bundled-family'
@@ -445,7 +548,13 @@ async function runStructuredUpdate(target, detected, run, {
         reason: `${target.host} source identity is not eligible for a frozen bundled-family update`,
       };
     }
-    if (observed.exact) return { status: 'ALREADY_CURRENT', version: target.version };
+    if (observed.exact) {
+      return {
+        status: 'ALREADY_CURRENT',
+        version: target.version,
+        ...(listedObservation.recovered ? { residualRecovery: true } : {}),
+      };
+    }
     if (!observed.installed) {
       return {
         status: 'MANUAL_REQUIRED',
@@ -471,14 +580,51 @@ async function runStructuredUpdate(target, detected, run, {
         reason: `${target.host} frozen tag and mutable ref do not both resolve to ${target.pluginCommit}`,
       };
     }
-    await run(detected.command, ['plugin', 'marketplace', 'update', target.marketplace], { env });
-    await run(detected.command, [
-      'plugin', 'update', `${target.plugin}@${target.marketplace}`, '--scope', 'user',
-    ], { env });
-    const afterList = await run(detected.command, ['plugin', 'list', '--json'], { env });
-    const after = exactPluginObservation(target, afterList.stdout);
+    let marketplaceRecovered = false;
+    try {
+      await run(detected.command, ['plugin', 'marketplace', 'update', target.marketplace], { env });
+    } catch (error) {
+      if (!isCodeBuddyWriteCommand(target, detected.command, ['plugin', 'marketplace', 'update', target.marketplace], 'marketplace-update')
+        || !isCodeBuddyResidualEnvelope(error)) throw error;
+      await observeCodeBuddyMarketplaceAfterResidual(target, detected.command, env, run);
+      marketplaceRecovered = true;
+    }
+    let after;
+    let pluginRecovered = false;
+    try {
+      await run(detected.command, [
+        'plugin', 'update', `${target.plugin}@${target.marketplace}`, '--scope', 'user',
+      ], { env });
+    } catch (error) {
+      if (!isCodeBuddyWriteCommand(target, detected.command, [
+        'plugin', 'update', `${target.plugin}@${target.marketplace}`, '--scope', 'user',
+      ], 'plugin-update') || !isCodeBuddyResidualEnvelope(error)) throw error;
+      const afterList = await runCodeBuddyRead(
+        target,
+        detected.command,
+        CODEBUDDY_PLUGIN_LIST_ARGS,
+        `${target.host} plugin list`,
+        env,
+        run,
+      );
+      after = exactPluginObservation(target, afterList.output.stdout);
+      pluginRecovered = true;
+    }
+    if (!pluginRecovered) {
+      const afterList = target.host === 'codebuddy'
+        ? await runCodeBuddyRead(target, detected.command, CODEBUDDY_PLUGIN_LIST_ARGS, `${target.host} plugin list`, env, run)
+        : { output: await run(detected.command, [...CODEBUDDY_PLUGIN_LIST_ARGS], { env }), recovered: false };
+      after = exactPluginObservation(target, afterList.output.stdout);
+    }
     if (!after.exact) throw new Error(`${target.host} did not update to the frozen plugin identity`);
-    return { status: 'UPDATED', version: target.version, restartRequired: true };
+    return {
+      status: 'UPDATED',
+      version: target.version,
+      restartRequired: true,
+      ...(marketplaceRecovered || listedObservation.recovered || pluginRecovered
+        ? { residualRecovery: true }
+        : {}),
+    };
   }
 
   const command = detected.command;
@@ -566,9 +712,9 @@ expect {
       timeout { exit 95 }
       eof { exit 96 }
     }
-    expect -re {> $}
+    expect -re $promptPattern
   }
-  -re {> $} {}
+  -re $promptPattern {}
   timeout { exit 93 }
   eof { exit 94 }
 }
@@ -581,8 +727,9 @@ foreach variable {RELEASE_SKILL_KIMI_COMMAND RELEASE_SKILL_KIMI_INSTALL_URL RELE
 set kimiCommand $env(RELEASE_SKILL_KIMI_COMMAND)
 set installUrl $env(RELEASE_SKILL_KIMI_INSTALL_URL)
 set removePlugin $env(RELEASE_SKILL_KIMI_REMOVE_PLUGIN)
+set promptPattern {(?:(?:^|\\r|\\n)> |(?:^|\\r|\\n)(?:\\033\\[[0-9;?]*[ -/]*[@-~])*│[ \\t]*>[ \\t]*│(?:\\033\\[[0-9;?]*[ -/]*[@-~])*)(?![^\\n]|\\n)}
 spawn $kimiCommand
-expect -re {> $}
+expect -re $promptPattern
 ${removeCommand}send -- "/plugins install $installUrl\\r"
 expect {
   -nocase -re {trust and install} {
@@ -595,9 +742,9 @@ expect {
   timeout { exit 91 }
   eof { exit 92 }
 }
-expect -re {> $}
+expect -re $promptPattern
 send -- "/reload\\r"
-expect -re {> $}
+expect -re $promptPattern
 send -- "/exit\\r"
 expect eof
 `;
@@ -730,6 +877,12 @@ function aggregateStatus(results) {
 
 function failedHostResult(target, error) {
   const message = error?.message ?? String(error);
+  const details = error?.details;
+  const publicDetails = details && typeof details === 'object' && !Array.isArray(details)
+    ? Object.fromEntries(Object.entries(details).filter(([key]) => (
+      key !== 'foundationEnvelope' && key !== 'foundationStdout' && key !== 'foundationStderr'
+    )))
+    : details;
   return {
     host: target.host,
     unitId: target.unitId,
@@ -737,7 +890,7 @@ function failedHostResult(target, error) {
     error: message,
     reason: typeof error?.reason === 'string' ? error.reason : message,
     ...(error?.code !== undefined ? { code: error.code } : {}),
-    ...(error?.details !== undefined ? { details: error.details } : {}),
+    ...(publicDetails !== undefined ? { details: publicDetails } : {}),
   };
 }