release-skill 0.9.14 → 0.9.16

package/references/02-project-config.md

@@ -27,6 +27,10 @@ project:
   defaultBranch: <string>        # workspace 远端默认分支，必填；不限定为 main
   sourceRepository: <owner/repo> # workspace 源仓库；生产发布必填
 
+releaseFinish:                   # 可选；仅控制本地发布收尾
+  sourceBranchCheck: remind      # remind（缺省）或 skip
+  setupSkill: <plugin:skill>     # 可选；已加载目标插件提供的 setup 入口
+
 publicSourceAuthorityReceipt:    # 可选；把源码坐标与多个 npm tarball 绑定为公开 Release asset
   coordinatorUnitId: <release-unit-id>
   subjectUnitIds: [<release-unit-id>]
@@ -113,6 +117,18 @@ policy:                     # 可选，安全策略
 ```
 
 `distributions: []` 表示该发布单元不生成 npm 或插件市场动作，不表示跳过公开发布。
+
+### 2.1 本地发布收尾
+
+`releaseFinish` 只控制 `release-finish` 的本地收尾，不改写冻结计划、发布状态或宿主范围。
+`sourceBranchCheck` 缺省为 `remind`。该值要求收尾时读取当前分支和工作区摘要；设为 `skip`
+时关闭这项提醒。`setupSkill` 可省略；填写时必须是技能入口名，例如 `release-setup` 或
+`skill-family-docs:skill-family-docs-setup`。它只用于匹配已安装并加载的目标插件入口，不能作为
+shell 命令执行。
+
+`releaseFinish` 保持闭合。未知字段、`sourceBranchCheck` 的其他值，以及空值、路径、带参数或
+shell 语法的 `setupSkill` 都是配置错误。两个字段彼此独立：关闭分支提醒不会关闭已配置的 setup。
+
 生产模式的 `prepare` 仍会冻结 GitHub 快照，并生成 `push-snapshot`、`create-tag` 和
 `github-release`。该单元的 `postPublish` 声明保持独立生效，其中 phase 为
 `postVerify` 的 hook 也不受影响。因此纯插件可以先验证公开 GitHub Release，再向中央

package/schemas/release-project.schema.json

@@ -44,6 +44,24 @@
         }
       }
     },
+    "releaseFinish": {
+      "type": "object",
+      "description": "Optional local post-release finish settings. Omitted sourceBranchCheck defaults to remind.",
+      "additionalProperties": false,
+      "properties": {
+        "sourceBranchCheck": {
+          "type": "string",
+          "enum": [
+            "remind",
+            "skip"
+          ]
+        },
+        "setupSkill": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*(?::[a-z0-9][a-z0-9-]*)?$"
+        }
+      }
+    },
     "publicSourceAuthorityReceipt": {
       "type": "object",
       "description": "Optional public source-authority receipt uploaded to one coordinator GitHub Release after all subject npm tarballs are frozen.",

package/skills/release-finish/SKILL.md

@@ -70,6 +70,64 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs" \
 
 完成后报告每个宿主的状态，并提醒用户重启已更新的宿主。本机结果只记录收尾事实，不改变发布状态。
 
+## 配置与目录
+
+从发布项目目录的 `.release-skill/project.yaml` 读取 `releaseFinish` 和 `project.defaultBranch`。
+文件缺失或无法解析时，报告具体配置问题，不猜默认分支或 setup，也不得把文件缺失当作字段合法缺省；
+已经取得的发布结果仍保留。只有配置文件有效时，整个 `releaseFinish` 或其中字段缺省才按各自合同默认。
+
+发布项目目录用于读取配置和执行源码 Git 检查。setup 使用用户明确指定的消费项目目录或已明确的使用
+上下文。只有用户明确把发布源码仓库作为消费项目时，才能在那里执行 setup；同时提供两个目录时不得混用。
+
+## 更新后 setup
+
+完成现有清单及已授权的宿主处理后，读取发布项目 `.release-skill/project.yaml` 的
+`releaseFinish.setupSkill`。未配置时不增加 setup 提示。配置的技能名只用于匹配入口，不作为 shell 命令执行，
+也不授权安装同名插件。
+
+只有本次所选宿主已经成功更新，或现有检查确认它已是目标版本时，才衔接 setup。通过宿主实际技能
+元数据核对目标插件身份、版本和入口；不能从开发仓库、旧会话缓存或同名技能推断新版已加载。当前宿主
+不满足时，可以使用同次更新中另一个已安装并加载目标版本和入口的宿主。
+
+目标目录来自用户本次明确指定的消费项目或已明确的使用上下文。目录不明确、宿主需要重启、当前环境
+不能调用可用宿主、入口不存在或归属有歧义时，标为“待执行”，并给出插件与版本、技能名、目标目录和
+已有授权的续接提示。发出提示不代表 setup 已完成。
+
+对同一插件版本、同一项目目录和相同共享运行环境，项目级依赖、项目配置和 Git hooks 由一个已加载
+新版插件的宿主检查一次。其余宿主分别核对自身安装、加载和宿主专属配置。不同运行环境不得无条件
+复用项目就绪结论；按目标 setup 的实际合同补查差异。release-finish 不保存去重键、收据或新的状态。
+
+调用 setup 前完整读取目标技能及其必读引用，并传入目标项目、插件版本、只读检查意图和已有授权范围。
+已有具体修复授权应传递给 setup；未覆盖的写入不能执行。只读检查、安装结果和配置修复结果分别报告。
+最终自然语言回复列出执行宿主、插件版本、消费项目路径、实际结果和未完成项。任何 setup 结果都不改变
+`VERIFIED`，也不影响其他宿主已经完成的结果。
+
+## 源码分支检查
+
+宿主更新和 setup 不影响本项检查。读取 `releaseFinish.sourceBranchCheck`；字段或整个
+`releaseFinish` 缺省时按 `remind` 处理。配置为 `skip` 时不运行 Git 命令，只说明项目已关闭
+源码分支检查。
+
+`remind` 时，在发布项目目录依次运行两条只读命令：
+
+```bash
+git branch --show-current
+git status --short --branch
+```
+
+第一条命令取得当前分支。第二条命令读取工作区改动和现有上游跟踪摘要；不得增加会写入或访问网络的
+参数。当前分支等于 `project.defaultBranch` 且没有文件改动时，说明本地已位于目标分支；输出含
+ahead 或 behind 等跟踪信息时，仍原样概括。分支不一致时说明两个准确名称，并询问用户是否需要处理。
+第一条命令输出为空时，说明处于 detached HEAD，不猜测目标操作。工作区存在改动时说明不建议直接
+切换或清理。任一命令失败时，报告命令、退出结果和无法完成检查的事实。
+
+最终自然语言回复至少列出提醒策略、目标分支、当前分支或无法取得的事实、工作区是否有改动、Git
+上游跟踪摘要，以及是否需要用户决定下一步。没有上游信息时，明确说明命令输出未显示上游信息。
+
+本项检查不从宿主更新推导出 Git 写入授权，不自动执行 fetch、switch、checkout、merge、rebase、stash、
+reset、clean 或 push。用户跳过宿主更新仍执行默认分支检查。用户已经明确授权同一仓库、分支和操作时，
+按项目 Git 纪律继续，不重复询问相同授权；检查本身不改变 `VERIFIED`，不保存结果，也不产生新的 run。
+
 ## 临时归属
 
 本能力目前只服务发布后的本机收尾，因此保留在 release-skill。第二个技能族需要复用宿主更新或 TUI 驱动，或 Foundation 发布等价公共入口时，再把通用机制上收 Foundation并删除这里的通用部分。release-skill 只保留发布计划到宿主更新输入的领域映射。

package/skills/release-prepare/SKILL.md

@@ -25,17 +25,45 @@ description: Freeze an immutable release plan with local configuration, document
 
 **不确定性停止**: 遇到无法确定的配置项或版本冲突时，Agent 必须停止并上报用户。
 
+**候选与授权边界**: 先确认本轮操作的是未冻结工作树，还是已经冻结并取得验收的候选。候选已经冻结时，未经授权不得运行会改写候选的生成命令或 Hook。保留原候选时，原有验收继续绑定原候选。若要生成新候选，先说明哪些计划、批准和验收需要重新绑定；禁止把旧候选的验收用于新候选。
+
+**项目事实来源**: 依赖关系、生成入口、聚焦检查和环境前提只能来自用户请求、项目权威指引、配置及现有脚本。Skill 必须在授权范围内实际执行已确认的入口，不能只建议主会话“统一刷新”。现有事实不足以证明顺序或副作用时，报告缺少的具体事实并停止，不创建通用依赖图、前提检查脚本或配置迁移。
+
 **发布文档新鲜度门**: 配置了 `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`；用户已明确选择范围时，为每个单元追加一个 `--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 批准
+1. 使用插件根相对路径运行 CLI：`CLI="node ${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs"`。读取用户请求、项目权威指引和 `.release-skill/project.yaml`，固定目标版本、单元范围、候选状态和本轮写入授权。
+2. 配置首次接入或本轮发生变化时，运行只读评估 `${CLI} assess --root <path> --offline --json`；配置未变且已有对应检查证据时不重复评估。读取 `status` 和 `gaps[]` 并逐项分类，不能把整体 `ASSESSED` 当作生成前置，也不能只凭退出码宣布发布条件齐备：
+   - `CONFIG_INVALID` 必须先按结构化错误定位字段。只有已知合法值和本轮授权同时具备时才修复，随后复跑 assess；在此之前不得生成或运行完整测试，也不得放宽 schema 或猜值。
+   - 明确发布范围内的 missing/stale gap，如果能由项目已有且获授权的生成入口或发布文档协议解决，保留原 gap 并进入后续刷新链。配置本身未变时，使用刷新和聚焦检查的新证据继续，不为形式完整重复 assess。
+   - gap 需要用户输入，或缺少写入授权、权威入口或必要项目事实时，停在 `NEEDS_INPUT`，报告缺少的具体条件。
+   - 按发布单元保留 gap 归属。延期单元的问题不能证明已选单元通过，也不能据此自动增删范围。assess 的整体状态也不能单独阻断已选范围；最终结果由正式 prepare 的完整配置、新鲜度和 Hook 门禁裁决。
+3. 配置含 `releaseDocuments` 时，运行只读演练 `${CLI} docs refresh --unit <id> --json`。`status: "changes"` 时展示逐文件路径、语种、版本和 `refreshDigest`；取得“本地发布文档写入”明确授权后才执行 `nextCommand.argv`。审阅并提交刷新结果后再继续；`status: "clean"` 时进入下一步。
+4. 根据项目权威指引列出从配置到最终派生物的完整依赖链，并确认唯一生成责任。此时只选择现有入口，不开始生成：
+   - 项目已有外部完整生成入口时，记录该入口及对应聚焦检查。后续 build Hook 不得重复生成同一批输出。
+   - 可达的 `hooks.build` 已承担完整生成流程时，不在 prepare 外重复生成。必须从现有 Hook 命令确认它会刷新完整依赖链并执行所需聚焦检查；前置新鲜度门会先阻断时，不能期待 build Hook 修复输入。
+   - `releaseDocuments` 仍按上一步的专用刷新协议处理，不能改由 build Hook 绕过。
+5. 在首次生成、写候选或完整验证之前，核对项目合同中已知的环境前提。`envAllowlist` 只转发调用环境中已经存在的同名变量，不会生成值或证明值正确：
+   - 项目已有廉价前提检查时，先在当前环境原样运行同一入口。检查失败后保留原始错误，且不得开始生成、Hook 或昂贵测试。
+   - 只有项目合同给出合法值且本轮已经授权修正时，才修正后续命令环境；随后复跑同一廉价检查。没有值或授权时停在 `NEEDS_INPUT`。
+   - 项目没有廉价入口时，说明尚未验证的前提，再由正式 Hook 的实际结果裁决。不得临时编写检查脚本或把 assess 当成环境值检查。
+6. 外部生成入口承担责任时，在授权写集内运行一次该入口，再运行一次项目指定的聚焦检查。build Hook 承担责任时跳过本步，留给 prepare 执行；不得先手工调用同一生成流程。
+7. 普通路径不额外运行手动完整测试或 `hooks validate`。直接运行 `${CLI} prepare --root <path> --offline --json`，由 prepare 执行已声明 Hook 和完整验证；用户已明确选择范围时，为每个单元追加一个 `--unit <id>`。用户明确要求独立完整验收时保留该要求，即使正式 prepare 会再次运行完整 Hook。
+8. 检查 CLI exit code 0 和结构化状态 `PREPARED`。读取返回的不可变 `planPath=plans/<planDigest>.json`，再从该文件读取 `status`、`units` 和 `externalActions`。build Hook 承担生成时，还要从 Hook 输出及 evidence 确认完整依赖链和聚焦检查各执行一次。聚焦检查通过、Hook 通过和 `PREPARED` 是不同结果，不得互相代替。
+9. 向用户展示可读的 `approvalSummary`：版本、公开仓库、分支策略、branch/tag、npm 与 GitHub Release 目标、全部外部动作、例外，以及需要独立 checkpoint 批准的 postPublish hook。`planDigest` 仅作为内部绑定字段，不要求用户复制或确认。后续 approve/publish 只能使用该 immutable planPath，等待确认后再 approve。计划批准不包含受限 postPublish hook 的 checkpoint 批准。
+
+报告调用次数时，以本轮请求开始到取得结果或停止为计数窗口。分别列出生成命令、聚焦检查、正式 Hook 前提检查和昂贵测试。`prepare` 不是生成命令；一次 Hook 启动也不能证明昂贵测试已经进入测试体。优先使用工具转录、项目夹具输出和 CLI evidence，不能用模型自报替代实际记录。
+
+## 修复与重试
+
+一次失败后，集中核对该失败及其直接依赖。统一完成已授权修复，再运行现有聚焦检查；修复收敛后才重新尝试 prepare，不用完整门禁逐项寻找下一项问题。
+
+命令、目录、参数或环境错误由当前职责修正。环境改变后重新验证受影响的廉价入口和正式入口，过去的手动成功不能证明新环境。需要单独诊断 Hook 时可以使用 `hooks validate`，但须说明它会执行全部已声明 Hook，并可能写文件或访问网络。它不是每次 prepare 的固定前置步骤；缺少有效 cache 时，随后 prepare 会再次执行 Hook。
+
+同类产品失败连续两次时停止原样重试，检查依赖和入口是否选错。保留原始错误和输出；新诊断替换旧猜测，但不得覆盖已有日志或另建整改状态。
 
 若用户明确要求 GitHub+npm 生产发布，加入 `--production`。该模式还会封存独立
 Git commit/tree 和 npm tarball，并把路径、SHA/integrity、branch/tag 写入计划。
@@ -93,9 +121,7 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --onlin
 | RELEASE_DOCS_STALE | 文档相对说明源已陈旧；按详情运行只读演练，展示文件/语种/版本/摘要，经用户授权“本地发布文档写入”后执行写入，审阅提交再重新 prepare |
 | RELEASE_DOCS_INVALID / TRANSLATION_MISSING / CONFLICT / REFRESH_STALE | 修复配置/说明源/目标或重新演练取得新 `refreshDigest`；不得扩大写入范围绕过 |
 | SECRET_DETECTED | 移除密钥并更新 allowlist |
-| CONFIG_INVALID | 检查 version.source、package.json，以及 `--unit` 是否为空、重复或不在 `releaseUnits[]` 中 |
-
-重试时只保留最新结构化错误码和失败门，不沿用早期猜测；重跑确定性命令获得新证据。
+| CONFIG_INVALID | 先用 assess 定位结构化配置错误；检查 version.source、package.json、环境白名单是否为合法大写名称，以及 `--unit` 是否为空、重复或不在 `releaseUnits[]` 中。修复须使用已知合法值和明确写入授权 |
 
 ## 后续引导
 

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

@@ -70,6 +70,64 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs" \
 
 完成后报告每个宿主的状态，并提醒用户重启已更新的宿主。本机结果只记录收尾事实，不改变发布状态。
 
+## 配置与目录
+
+从发布项目目录的 `.release-skill/project.yaml` 读取 `releaseFinish` 和 `project.defaultBranch`。
+文件缺失或无法解析时，报告具体配置问题，不猜默认分支或 setup，也不得把文件缺失当作字段合法缺省；
+已经取得的发布结果仍保留。只有配置文件有效时，整个 `releaseFinish` 或其中字段缺省才按各自合同默认。
+
+发布项目目录用于读取配置和执行源码 Git 检查。setup 使用用户明确指定的消费项目目录或已明确的使用
+上下文。只有用户明确把发布源码仓库作为消费项目时，才能在那里执行 setup；同时提供两个目录时不得混用。
+
+## 更新后 setup
+
+完成现有清单及已授权的宿主处理后，读取发布项目 `.release-skill/project.yaml` 的
+`releaseFinish.setupSkill`。未配置时不增加 setup 提示。配置的技能名只用于匹配入口，不作为 shell 命令执行，
+也不授权安装同名插件。
+
+只有本次所选宿主已经成功更新，或现有检查确认它已是目标版本时，才衔接 setup。通过宿主实际技能
+元数据核对目标插件身份、版本和入口；不能从开发仓库、旧会话缓存或同名技能推断新版已加载。当前宿主
+不满足时，可以使用同次更新中另一个已安装并加载目标版本和入口的宿主。
+
+目标目录来自用户本次明确指定的消费项目或已明确的使用上下文。目录不明确、宿主需要重启、当前环境
+不能调用可用宿主、入口不存在或归属有歧义时，标为“待执行”，并给出插件与版本、技能名、目标目录和
+已有授权的续接提示。发出提示不代表 setup 已完成。
+
+对同一插件版本、同一项目目录和相同共享运行环境，项目级依赖、项目配置和 Git hooks 由一个已加载
+新版插件的宿主检查一次。其余宿主分别核对自身安装、加载和宿主专属配置。不同运行环境不得无条件
+复用项目就绪结论；按目标 setup 的实际合同补查差异。release-finish 不保存去重键、收据或新的状态。
+
+调用 setup 前完整读取目标技能及其必读引用，并传入目标项目、插件版本、只读检查意图和已有授权范围。
+已有具体修复授权应传递给 setup；未覆盖的写入不能执行。只读检查、安装结果和配置修复结果分别报告。
+最终自然语言回复列出执行宿主、插件版本、消费项目路径、实际结果和未完成项。任何 setup 结果都不改变
+`VERIFIED`，也不影响其他宿主已经完成的结果。
+
+## 源码分支检查
+
+宿主更新和 setup 不影响本项检查。读取 `releaseFinish.sourceBranchCheck`；字段或整个
+`releaseFinish` 缺省时按 `remind` 处理。配置为 `skip` 时不运行 Git 命令，只说明项目已关闭
+源码分支检查。
+
+`remind` 时，在发布项目目录依次运行两条只读命令：
+
+```bash
+git branch --show-current
+git status --short --branch
+```
+
+第一条命令取得当前分支。第二条命令读取工作区改动和现有上游跟踪摘要；不得增加会写入或访问网络的
+参数。当前分支等于 `project.defaultBranch` 且没有文件改动时，说明本地已位于目标分支；输出含
+ahead 或 behind 等跟踪信息时，仍原样概括。分支不一致时说明两个准确名称，并询问用户是否需要处理。
+第一条命令输出为空时，说明处于 detached HEAD，不猜测目标操作。工作区存在改动时说明不建议直接
+切换或清理。任一命令失败时，报告命令、退出结果和无法完成检查的事实。
+
+最终自然语言回复至少列出提醒策略、目标分支、当前分支或无法取得的事实、工作区是否有改动、Git
+上游跟踪摘要，以及是否需要用户决定下一步。没有上游信息时，明确说明命令输出未显示上游信息。
+
+本项检查不从宿主更新推导出 Git 写入授权，不自动执行 fetch、switch、checkout、merge、rebase、stash、
+reset、clean 或 push。用户跳过宿主更新仍执行默认分支检查。用户已经明确授权同一仓库、分支和操作时，
+按项目 Git 纪律继续，不重复询问相同授权；检查本身不改变 `VERIFIED`，不保存结果，也不产生新的 run。
+
 ## 临时归属
 
 本能力目前只服务发布后的本机收尾，因此保留在 release-skill。第二个技能族需要复用宿主更新或 TUI 驱动，或 Foundation 发布等价公共入口时，再把通用机制上收 Foundation并删除这里的通用部分。release-skill 只保留发布计划到宿主更新输入的领域映射。

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

@@ -25,17 +25,45 @@ description: Freeze an immutable release plan with local configuration, document
 
 **不确定性停止**: 遇到无法确定的配置项或版本冲突时，Agent 必须停止并上报用户。
 
+**候选与授权边界**: 先确认本轮操作的是未冻结工作树，还是已经冻结并取得验收的候选。候选已经冻结时，未经授权不得运行会改写候选的生成命令或 Hook。保留原候选时，原有验收继续绑定原候选。若要生成新候选，先说明哪些计划、批准和验收需要重新绑定；禁止把旧候选的验收用于新候选。
+
+**项目事实来源**: 依赖关系、生成入口、聚焦检查和环境前提只能来自用户请求、项目权威指引、配置及现有脚本。Skill 必须在授权范围内实际执行已确认的入口，不能只建议主会话“统一刷新”。现有事实不足以证明顺序或副作用时，报告缺少的具体事实并停止，不创建通用依赖图、前提检查脚本或配置迁移。
+
 **发布文档新鲜度门**: 配置了 `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`；用户已明确选择范围时，为每个单元追加一个 `--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 批准
+1. 使用插件根相对路径运行 CLI：`CLI="node ${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs"`。读取用户请求、项目权威指引和 `.release-skill/project.yaml`，固定目标版本、单元范围、候选状态和本轮写入授权。
+2. 配置首次接入或本轮发生变化时，运行只读评估 `${CLI} assess --root <path> --offline --json`；配置未变且已有对应检查证据时不重复评估。读取 `status` 和 `gaps[]` 并逐项分类，不能把整体 `ASSESSED` 当作生成前置，也不能只凭退出码宣布发布条件齐备：
+   - `CONFIG_INVALID` 必须先按结构化错误定位字段。只有已知合法值和本轮授权同时具备时才修复，随后复跑 assess；在此之前不得生成或运行完整测试，也不得放宽 schema 或猜值。
+   - 明确发布范围内的 missing/stale gap，如果能由项目已有且获授权的生成入口或发布文档协议解决，保留原 gap 并进入后续刷新链。配置本身未变时，使用刷新和聚焦检查的新证据继续，不为形式完整重复 assess。
+   - gap 需要用户输入，或缺少写入授权、权威入口或必要项目事实时，停在 `NEEDS_INPUT`，报告缺少的具体条件。
+   - 按发布单元保留 gap 归属。延期单元的问题不能证明已选单元通过，也不能据此自动增删范围。assess 的整体状态也不能单独阻断已选范围；最终结果由正式 prepare 的完整配置、新鲜度和 Hook 门禁裁决。
+3. 配置含 `releaseDocuments` 时，运行只读演练 `${CLI} docs refresh --unit <id> --json`。`status: "changes"` 时展示逐文件路径、语种、版本和 `refreshDigest`；取得“本地发布文档写入”明确授权后才执行 `nextCommand.argv`。审阅并提交刷新结果后再继续；`status: "clean"` 时进入下一步。
+4. 根据项目权威指引列出从配置到最终派生物的完整依赖链，并确认唯一生成责任。此时只选择现有入口，不开始生成：
+   - 项目已有外部完整生成入口时，记录该入口及对应聚焦检查。后续 build Hook 不得重复生成同一批输出。
+   - 可达的 `hooks.build` 已承担完整生成流程时，不在 prepare 外重复生成。必须从现有 Hook 命令确认它会刷新完整依赖链并执行所需聚焦检查；前置新鲜度门会先阻断时，不能期待 build Hook 修复输入。
+   - `releaseDocuments` 仍按上一步的专用刷新协议处理，不能改由 build Hook 绕过。
+5. 在首次生成、写候选或完整验证之前，核对项目合同中已知的环境前提。`envAllowlist` 只转发调用环境中已经存在的同名变量，不会生成值或证明值正确：
+   - 项目已有廉价前提检查时，先在当前环境原样运行同一入口。检查失败后保留原始错误，且不得开始生成、Hook 或昂贵测试。
+   - 只有项目合同给出合法值且本轮已经授权修正时，才修正后续命令环境；随后复跑同一廉价检查。没有值或授权时停在 `NEEDS_INPUT`。
+   - 项目没有廉价入口时，说明尚未验证的前提，再由正式 Hook 的实际结果裁决。不得临时编写检查脚本或把 assess 当成环境值检查。
+6. 外部生成入口承担责任时，在授权写集内运行一次该入口，再运行一次项目指定的聚焦检查。build Hook 承担责任时跳过本步，留给 prepare 执行；不得先手工调用同一生成流程。
+7. 普通路径不额外运行手动完整测试或 `hooks validate`。直接运行 `${CLI} prepare --root <path> --offline --json`，由 prepare 执行已声明 Hook 和完整验证；用户已明确选择范围时，为每个单元追加一个 `--unit <id>`。用户明确要求独立完整验收时保留该要求，即使正式 prepare 会再次运行完整 Hook。
+8. 检查 CLI exit code 0 和结构化状态 `PREPARED`。读取返回的不可变 `planPath=plans/<planDigest>.json`，再从该文件读取 `status`、`units` 和 `externalActions`。build Hook 承担生成时，还要从 Hook 输出及 evidence 确认完整依赖链和聚焦检查各执行一次。聚焦检查通过、Hook 通过和 `PREPARED` 是不同结果，不得互相代替。
+9. 向用户展示可读的 `approvalSummary`：版本、公开仓库、分支策略、branch/tag、npm 与 GitHub Release 目标、全部外部动作、例外，以及需要独立 checkpoint 批准的 postPublish hook。`planDigest` 仅作为内部绑定字段，不要求用户复制或确认。后续 approve/publish 只能使用该 immutable planPath，等待确认后再 approve。计划批准不包含受限 postPublish hook 的 checkpoint 批准。
+
+报告调用次数时，以本轮请求开始到取得结果或停止为计数窗口。分别列出生成命令、聚焦检查、正式 Hook 前提检查和昂贵测试。`prepare` 不是生成命令；一次 Hook 启动也不能证明昂贵测试已经进入测试体。优先使用工具转录、项目夹具输出和 CLI evidence，不能用模型自报替代实际记录。
+
+## 修复与重试
+
+一次失败后，集中核对该失败及其直接依赖。统一完成已授权修复，再运行现有聚焦检查；修复收敛后才重新尝试 prepare，不用完整门禁逐项寻找下一项问题。
+
+命令、目录、参数或环境错误由当前职责修正。环境改变后重新验证受影响的廉价入口和正式入口，过去的手动成功不能证明新环境。需要单独诊断 Hook 时可以使用 `hooks validate`，但须说明它会执行全部已声明 Hook，并可能写文件或访问网络。它不是每次 prepare 的固定前置步骤；缺少有效 cache 时，随后 prepare 会再次执行 Hook。
+
+同类产品失败连续两次时停止原样重试，检查依赖和入口是否选错。保留原始错误和输出；新诊断替换旧猜测，但不得覆盖已有日志或另建整改状态。
 
 若用户明确要求 GitHub+npm 生产发布，加入 `--production`。该模式还会封存独立
 Git commit/tree 和 npm tarball，并把路径、SHA/integrity、branch/tag 写入计划。
@@ -93,9 +121,7 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --onlin
 | RELEASE_DOCS_STALE | 文档相对说明源已陈旧；按详情运行只读演练，展示文件/语种/版本/摘要，经用户授权“本地发布文档写入”后执行写入，审阅提交再重新 prepare |
 | RELEASE_DOCS_INVALID / TRANSLATION_MISSING / CONFLICT / REFRESH_STALE | 修复配置/说明源/目标或重新演练取得新 `refreshDigest`；不得扩大写入范围绕过 |
 | SECRET_DETECTED | 移除密钥并更新 allowlist |
-| CONFIG_INVALID | 检查 version.source、package.json，以及 `--unit` 是否为空、重复或不在 `releaseUnits[]` 中 |
-
-重试时只保留最新结构化错误码和失败门，不沿用早期猜测；重跑确定性命令获得新证据。
+| CONFIG_INVALID | 先用 assess 定位结构化配置错误；检查 version.source、package.json、环境白名单是否为合法大写名称，以及 `--unit` 是否为空、重复或不在 `releaseUnits[]` 中。修复须使用已知合法值和明确写入授权 |
 
 ## 后续引导