release-skill 0.9.15 → 0.9.16

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 只保留发布计划到宿主更新输入的领域映射。