feat: update manage-release

skills/manage-release/SKILL.md

@@ -1,13 +1,12 @@
 ---
 name: manage-release
 description: >-
-  管理 Git 项目从开发版本到发布的完整生命周期：发现并遵循项目分支与版本策略，
-  创建或复用隔离 worktree 和版本分支，确定并同步版本号，推送并创建、检查或合并
-  PR/MR，在合并后的准确提交上创建并推送 release tag，并按需创建 Forge Release、
-  恢复中断流程或安全清理。用户要求开始发布相关的新版本、为发布开 worktree 或分支、
-  升版本、提交或合并发布 PR/MR、打 release tag、完成发版、处理 hotfix 或继续未完成
-  发布时使用。只做普通编码、普通 worktree 或 PR/MR 操作、代码审查、构建或上传
-  DEB/Docker 等产物、管理仓库权限时不使用。
+  管理 Git 项目从已准备 commit 到版本发布的生命周期：发现并遵循项目版本与发布策略，
+  优先为远端已验证 commit 生成更新说明并创建 annotated release tag，按需创建 Forge
+  Release；只有必须修改版本文件或仓库内发布说明时，才创建或复用版本分支、worktree
+  和 PR/MR。也支持恢复中断流程与安全清理。用户要求发布版本、打 release tag、创建
+  平台 Release、准备版本变更、处理 hotfix 或继续未完成发布时使用。只做普通编码、普通
+  worktree 或 PR/MR 操作、代码审查、构建或上传 DEB/Docker 等产物、管理仓库权限时不使用。
 ---
 
 # Manage Release
@@ -40,9 +39,11 @@ description: >-
 项目策略只描述仓库期望的做法，不能替用户授予 push、创建或合并 PR/MR、推送 tag、
 创建 Forge Release、删除分支等外部写权限。
 
-“完整处理并发布 v1.2.3”可以授权从准备到验证远端 tag 的流程，不要在每一步重复询问；
-它不自动包含 Forge Release 或分支清理。若版本、base、tag、远端或合并方式是推断所得，
-或者执行中目标发生变化，在第一次远端写操作前展示准确目标并获得确认。
+“发布 v1.2.3”允许为已经准备好的远端 commit 生成更新说明、创建并推送 annotated tag，
+再验证远端 tag 的 commit 和说明。“完整处理并发布 v1.2.3”还允许在仓库内容必须修改时
+走版本分支、PR/MR 和合并流程。两者都不自动包含 Forge Release 或分支清理。若版本、
+base、目标 commit、tag、远端或合并方式是推断所得，或者执行中目标发生变化，在第一次
+远端写操作前展示准确目标和更新说明并获得确认。
 
 ## 工作流
 
@@ -70,25 +71,47 @@ description: >-
 
 在修改前确定并展示：
 
-- base 分支及其远端 commit。
-- 当前版本、规范化后的目标版本、渲染出的分支名和 tag，以及升级依据。
-- 分支名与 worktree 路径。
+- base 分支、远端 commit，以及本次 tag 将指向的准确目标 commit。
+- 当前版本、规范化后的目标版本、tag，以及升级依据；需要准备仓库修改时再渲染分支名。
+- 从上一个稳定 tag 到目标 commit 的更新说明范围、来源和拟发布内容。
+- 是否需要修改仓库内容；若需要，再列出分支名与 worktree 路径。
 - 需要执行的本地验证和远端检查。
 - 合并方式、tag、是否创建 Forge Release。
 - 用户已授权的最远阶段和清理范围。
 
-项目没有约定时，单一协调版本使用 SemVer、`release/v<version>` 分支、
-`v<version>` annotated tag。仓库只启用一种合并方式时使用该方式；存在多种方式且没有
-项目规则时默认 squash。默认不删除远端分支，不自动创建 Forge Release。
+项目没有约定时，单一协调版本使用 SemVer 和 `v<version>` annotated tag。只有发布前
+必须修改仓库内容时才使用 `release/v<version>` 分支；仓库只启用一种合并方式时使用该
+方式，存在多种方式且没有项目规则时默认 squash。默认不删除远端分支，不自动创建
+Forge Release。
 
 把用户输入拆成“规范版本”和“展示名称”：默认 SemVer 的规范版本是无 `v` 前缀的
 `1.6.0`，版本文件和 `{version}` 都使用该值；分支与 tag 再分别按 pattern 渲染为
 `release/v1.6.0` 和 `v1.6.0`。用户输入 `v1.6.0` 时先规范化，不要产生双前缀。
 
-### 3. 创建或复用隔离 worktree
+### 3. 选择直接发布或准备版本
 
-优先使用当前环境提供的 worktree 管理器；项目仓库中的管理脚本只有在可信 base 已声明
-且经过检查时才能使用，没有时使用原生 Git。创建前验证：
+先计算发布所需的仓库内容差异，不要为了遵循固定模板而创建分支或 worktree。满足以下
+条件时走直接发布路径，跳过第 4 至 7 节：
+
+- 目标 commit 已作为准确远端引用读取，并可从计划的 base 或项目允许的维护分支到达。
+- 项目权威版本文件若存在，目标 commit 中已经是目标版本；或项目明确以 tag 作为版本来源。
+- 项目不要求把本次 CHANGELOG 或发布说明提交回仓库。
+- 项目要求的构建、测试和发布检查已经通过。
+
+直接发布不 checkout 目标 commit，不创建分支、worktree、版本提交或 PR/MR。更新说明是
+tag object 和可选 Forge Release 的内容，不因生成说明本身进入仓库修改路径。
+
+只要版本文件、生成元数据或仓库内 CHANGELOG 必须修改，就进入准备版本路径。优先复用
+身份准确、未被占用且适合本次发布的现有分支；没有时才创建版本分支。优先复用安全且
+干净的现有 worktree；当前目录承载用户工作、目标分支已在别处使用或需要隔离时，才创建
+linked worktree。用户只授权了直接发布时，在展示必要差异后停止，不要擅自扩大到修改、
+分支或 PR/MR 流程。
+
+### 4. 创建或复用准备版本的分支和 worktree
+
+仅在第 3 节判定需要准备仓库修改时执行本节。优先使用当前环境提供的 worktree 管理器；
+项目仓库中的管理脚本只有在可信 base 已声明且经过检查时才能使用，没有时使用原生 Git。
+创建前验证：
 
 - 目标分支和目录未被其他 worktree 占用。
 - 目标目录不是 `/`、用户主目录、仓库根目录或已有非空目录。
@@ -105,7 +128,7 @@ worktree 占用的分支。
 相对计划 base 的提交，确认是同一次发布后用 `git worktree add <path> <branch>` 挂载；
 身份不匹配或来源不明时停止，不要用 `-b` 覆盖或另建同名分支。
 
-### 4. 开发并同步版本
+### 5. 修改并同步版本
 
 在目标 worktree 内完成用户要求的修改。根据项目规则更新所有权威版本来源和
 CHANGELOG 或发布说明，保证它们进入同一个 PR/MR。运行项目声明的格式化、测试、构建
@@ -119,7 +142,7 @@ CHANGELOG 或发布说明，保证它们进入同一个 PR/MR。运行项目声
 提交前重新读取 HEAD 和完整工作区状态，只提交本次范围内的文件。不要在未合并分支上
 创建正式 release tag。
 
-### 5. 推送并创建 PR/MR
+### 6. 推送并创建 PR/MR
 
 执行远端写操作前再次确认 remote、base、head、版本、活动账号和授权范围，并重新读取
 唯一 fetch/push URL。Git 分支与 tag 通过已确认的 remote 读写；创建或操作 PR/MR 时使用
@@ -130,7 +153,7 @@ CHANGELOG 或发布说明，保证它们进入同一个 PR/MR。运行项目声
 PR/MR 内容至少说明目标版本、变更摘要、验证命令和结果、发布后续动作。用户只要求开
 PR/MR 时，停在这里并返回 URL、head/base、当前检查状态和阻塞项。
 
-### 6. 检查并合并
+### 7. 检查并合并
 
 从托管平台重新读取 PR/MR 状态。仅在下列条件全部满足时合并：
 
@@ -143,29 +166,40 @@ PR/MR 时，停在这里并返回 URL、head/base、当前检查状态和阻塞
 不要使用管理员绕过、直接推送受保护 base，或为通过检查而修改保护规则。合并后获取
 平台确认的 merged commit，更新远端 base，并验证该 commit 可从远端 base 到达。
 
-### 7. 创建并发布 tag
+### 8. 创建并发布带更新说明的 tag
 
-在 merged commit 上核对目标版本后，再查询一次远端同名 tag。tag 不存在时创建
-annotated tag；项目要求签名时，必须先确认签名工具和密钥可用，创建 signed tag，并在
-本地验证签名成功后才允许 push。签名不可用或验证失败时停止，不得降级为 unsigned tag。
-显式指定 merged commit，并只推送这个 tag。
+准备版本路径使用平台确认且可从远端 base 到达的 merged commit；直接发布路径使用计划
+中锁定且重新验证过的远端目标 commit。两者统一记为 release commit。核对目标版本后，
+再查询一次远端同名 tag。
+
+创建 tag 前，根据上一个稳定 tag 到 release commit 的实际差异生成更新说明；首次发布则
+使用项目声明的发布基线，没有声明时核对完整可达历史并明确标记首次发布。说明概括实际
+存在的新增、变更、修复、维护或文档变化；存在破坏性变化、迁移步骤或已知限制时必须明确
+列出。每项内容都应能追溯到本次提交、PR/MR 或项目 CHANGELOG。空说明、只重复版本号、
+模板占位文字或无法由实际变化支持的内容都不能发布。
+
+tag 不存在时，使用完整更新说明创建 annotated tag；项目要求签名时，必须先确认签名
+工具和密钥可用，创建 signed annotated tag，并在本地验证签名成功后才允许 push。使用
+文件输入完整的多行说明，显式指定 release commit，并只推送这个 tag。禁止创建 lightweight
+release tag。签名不可用或验证失败时停止，不得降级为 unsigned tag。
 
 同名远端 tag 已存在且指向其他 commit 时立即停止。不要覆盖、删除或移动已经发布的
-tag。推送后读取远端 tag，并将 annotated tag 解引用到 commit，确认它与 merged commit
-完全相同。
+tag。同名 tag 即使指向 release commit，只要它是 lightweight tag、缺少更新说明或说明与
+计划不一致，也视为身份不匹配并停止。推送后读取远端 tag object，确认它是 annotated
+tag，将它解引用到 commit 并核对完整更新说明；commit 和说明必须都与发布计划完全一致。
 
 仅当用户本次请求明确要求时创建 Forge Release；项目策略只能说明创建方式，不能授予
 外部写权限。必须引用已经存在并验证过的 tag，禁止让平台从默认分支隐式创建 tag。
-发布说明中的每项变化都应能追溯到本次 PR/MR、提交或项目 CHANGELOG。
+Forge Release 正文复用 tag 中经过验证的更新说明，不维护第二份相互独立的发布内容。
 
-### 8. 验证、恢复和清理
+### 9. 验证、恢复和清理
 
 分别报告以下状态，不要用“发布成功”掩盖其中某一步未完成：
 
 - 版本文件和本地验证。
 - PR/MR URL、合并状态和 merged commit。
-- 远端 tag 及其解引用后的 commit。
-- Forge Release URL 和可见性，若本次要求创建。
+- 远端 tag 的对象类型、完整更新说明及其解引用后的 commit。
+- Forge Release URL、可见性及正文一致性，若本次要求创建。
 - worktree、本地分支和远端分支是否保留。
 
 清理时只移除干净且已确认不再使用的 linked worktree，不使用强制删除。删除本地或远端
@@ -176,12 +210,15 @@ tag。推送后读取远端 tag，并将 annotated tag 解引用到 commit，确
 遇到以下任一情况时停止相应写操作并说明恢复路径：
 
 - base、目标版本、版本来源、remote，或请求阶段所需的托管平台无法唯一确定。
+- 直接发布的目标 commit 无法从计划远端分支到达，或项目要求的发布检查未通过。
 - 项目策略包含未知字段、错误类型、仓库外路径或不安全 ref。
 - 多个权威版本来源不一致。
 - 目标分支、worktree、PR/MR、tag 或 release 已存在但身份不匹配。
 - required checks、review 或冲突状态不满足合并规则。
 - 合并结果的准确 commit 无法从平台确认，或无法从远端 base 到达。
 - 远端 tag 已指向其他 commit。
+- 更新说明为空、只有版本号、包含占位内容、无法追溯到实际变化，或远端 tag 不是包含
+  计划说明的 annotated tag。
 - 请求的 PR/MR、合并或 Forge Release 阶段所需的平台 CLI 缺失、未认证或无法读取状态。
 - 项目要求 tag 签名，但签名能力不可用或本地签名验证失败。
 - 操作需要 force push、管理员绕过、移动已发布 tag 或覆盖用户工作。
@@ -192,7 +229,9 @@ tag。推送后读取远端 tag，并将 annotated tag 解引用到 commit，确
 
 ## 完成标准
 
-只分析时，给出当前状态、建议版本、依据和下一步。开始版本时，给出 worktree 路径、
-分支和基线 commit。创建 PR/MR 时，给出 URL 与检查状态。合并时，给出 merged commit。
-发布 tag 时，证明远端 tag 解引用到该 commit。创建 Forge Release 时，再给出 release URL
-与可见性。任何部分未完成都要标明阻塞阶段和可恢复动作。
+只分析时，给出当前状态、建议版本、依据和下一步。直接发布时，给出目标 commit 和更新
+说明，不得虚构 worktree 或分支步骤。开始准备版本时，给出所用 worktree、分支和基线
+commit；未新建 worktree 时明确说明复用了哪个安全工作区。创建 PR/MR 时，给出 URL 与
+检查状态。合并时，给出 merged commit。发布 tag 时，证明远端 tag 是包含计划更新说明的
+annotated tag，并解引用到 release commit。创建 Forge Release 时，再给出 release URL、
+可见性与正文一致性。任何部分未完成都要标明阻塞阶段和可恢复动作。