cut-release

Cut Release

严格按顺序通过各道关卡，准备并发布一个版本。为下面的每个步骤创建一个待办事项，并按顺序执行。

**停止规则：**任何步骤失败都意味着停止——准确报告失败内容和剩余事项，并保持仓库未发布。不得部分发布：构建未通过不得打标签，不得为不存在的制品编写说明，也不得“先打标签，之后再修复”。

终止拒绝与停止规则：停止规则触发后，只询问一次用户是否发出明确的终止拒绝。是 → 必须使用 record-verdict 子技能，判定结果为 release-reject，设置 Boundary-Type: release，并在正文中提供持久证据；保持仓库未发布。否 / 沉默 / “之后再修复” → 不记录决策（仅机械性停止不构成终止判定）。用户在版本或标签审批阶段拒绝时，同样适用 release-reject 写入交接规则。停止规则的约束不变：不得部分发布。

从 docs/agents/project.md 读取仓库的命令（验证命令、发布步骤、冒烟测试命令）。如果文件缺失，请说明这一点，建议使用 configure-repo，并在继续之前向用户询问这些命令。

a. 声明验证关卡

按顺序运行所有验证命令——typecheck、lint、unit、e2e——以及仅针对文档的 audit-trace 检查（必需子技能：使用 audit-trace）。所有检查都必须在当前重新运行并通过；之前通过的运行不算。audit-trace 检查必须在文档完整性方面干净（例如，无未知任务引用、无重复定义等）——它不会在测试中搜索需求 ID。

**完成条件：**每条命令都已重新运行并通过，且你已阅读其输出。

b. 发布范围，然后编写变更日志

在起草说明或提出版本号之前进行分类。对 HEAD 打标签会发布该范围内每个已合并功能的代码——如果其 Status: 仍写着 Approved 或 In-progress，那就是虚构。本步骤本身就是拦截关卡，不是步骤 i。

操作步骤——运行并阅读：

1. last=$(git describe --tags --abbrev=0 2>/dev/null) — 如果没有标签，范围就是整个历史；请说明这一点。
2. git diff --name-only ${last:+$last..}HEAD 和 git log ${last:+$last..}HEAD --oneline。
3. 将变更路径映射到 docs/specs/INDEX.md 中的功能（规格目录前缀或 **Files:** 归属关系）。该列表就是范围集合。
4. 对于每项功能，从其 requirements.md 读取 Status:（如果文件中没有该行，则读取 INDEX 行）。划分如下：
   • Implemented → 本次发布（此次发布将纳入该功能，之后更新状态）
   • Shipped → 已发布（如果范围涉及，则在变更日志中以补充项说明；不要更新状态）
   • Approved、In-progress、Draft 或缺失 → 阻塞项

如果存在任何阻塞项：本步骤失败。停止。列出每个阻塞项及其 Status:。不要提出版本号。不要打标签。不要调用 realign-spec。说明每个阻塞项都必须先达到 Implemented（对该单项功能使用 realign-spec——如果它们仍在落地中，则使用 land-branch 的 forget-net），然后重新运行 /cut-release。SHELL/BILLING 与本次发布集合中的其他功能一并等待。

如果没有阻塞项：根据本次发布集合（以及已发布功能的补充项）起草变更日志。引用 requirements.md 中现有的需求原文，可选择在括号中注明 CODE。将剩余提交主题归入 Misc。不要要求或解析 Implements: / Guards: trailers。

**完成条件：**要么已向用户列出停止项，要么已起草并展示本次发布集合的变更日志。

c. 提议版本升级

根据变更日志按 semver 规则判断：移除或更改公共行为 → major；发布新需求 → minor；仅包含修复和保护措施 → patch。说明判断依据并提出版本号。由用户批准具体版本号——用户未回复时不得继续。

**完成条件：**用户已批准一个确切的版本字符串。

d. 更新版本文件和变更日志

将已批准的版本写入项目的版本文件（清单文件、生态系统要求时的锁定文件，以及任何硬编码的版本常量），并将变更日志条目添加到变更日志文件的开头（如果仓库中没有该文件，则创建 CHANGELOG.md）。将这些更改一并提交。

**完成条件：**切版提交已存在，且 git status 干净。

e. 构建

严格按顺序执行 docs/agents/project.md 中的发布步骤。不得自行增添标志或替换命令；根据停止规则，步骤不明确即视为失败。

**可选的部署说明：**为 docs/ops/deployment.md 遵循 skills/project/define-system-doc/consult-recipe.md — 仅限说明文字。不得替代或覆盖 docs/agents/project.md 中可执行的发布命令。如有实质意义，可建议一次； 不得自动调用。

**完成条件：**所有发布步骤均已成功运行，且产物已生成。

f. 对产物进行冒烟测试

测试构建产物，而不是源代码树：如果项目配置了冒烟测试命令，就运行该命令；否则与用户一起进行简短的手动检查清单（安装／启动产物，体验核心流程），并取得用户的明确确认。

**完成条件：**冒烟测试命令已通过，或用户已确认检查清单。

g. 打标签并推送

仅在用户明确批准后执行（此批准即为切版的成功最终裁定）：

1. 必须的子技能：使用 record-verdict，裁定为 release-approve，并提供 Boundary-Type: release、Accountable 深度输入，以及涵盖版本／构建／冒烟测试／标签批准的证据行（整个切版只记录一次，不得针对各个中间批准分别记录）。创建标签前必须先发布。
2. 发布失败时：不得创建或推送标签；报告该裁定未生效。
3. 成功后：创建标签（git tag <version>），推送切版提交和标签，然后将以下内容追加到记录封套中： Execution-Outcome: tag <ref-name>@<object-id> pushed <UTC>。

**完成条件：**远程仓库中存在该标签，且切版决策记录引用了该标签（或者切版已被明确拒绝／停止，且未创建标签）。

h. 起草发布说明

将变更日志条目转换为跟踪器的格式（例如 gh cut-release create --draft，或用于手动发布的说明文件）。保留按需求分组的结构。除非用户要求发布，否则将切版保留为草稿。

**完成条件：**草稿说明已生成，且其 URL 或路径已告知用户。

i. 更新规格状态

范围组是步骤 b 中记录的“已实现”列表 — 集合保持不变，不得重新发现。对范围组中的每项功能，在相应的 requirements.md 和 docs/specs/INDEX.md 对应行中写入 Status: Shipped。一次提交。

不得调用 realign-spec。此技能负责将范围组从 Implemented 更新为 Shipped。realign-spec 用于重新对齐一个已偏离的三元组；它不会标记发布。

“始终运行 realign-spec，以免遗漏”、“跳过规格文档”、“没人看 INDEX”以及“标签才是正事”都不能作为跳过此步骤的理由，也不能成为将此状态更新交给 realign-spec 的理由。

然后处理范围组的工单（前提是 docs/agents/issue-tracker.md 指定了跟踪器）。如果某个 PR 在该范围内合并且关闭了工单，则该工单属于此次切版范围：范围内的合并提交和 PR 正文会使用关闭关键词（Closes #N）标明工单。对每个此类工单，使用跟踪器的操作规范，将其状态角色替换为 shipped（docs/agents/triage-labels.md），并评论 Shipped in v<version>。三个基准切版均标记为 v0.5.0，却让已关闭工单 #23 保持 status:in-review，因此看板无法区分已合并和已发布。

**完成条件：**范围组中的每项功能在文件和 INDEX 中均为 Shipped，且范围内关闭的每个工单状态均为 shipped（或者步骤 b 已停止此次切版）。

红线 — 绝不可做

• 只要有任何范围集功能的状态为 Approved、In-progress、Draft，或缺少 Status:，就不要打标签
• 不要从此技能调用 realign-spec
• 不要将阻塞项（Approved/In-progress/Draft）改为 Shipped
• 不要因为标签已存在或负责人说状态可以之后再处理，就跳过步骤 i
• 不要在变更日志中将 Approved 或 In-progress 状态的工作宣称为已发布的行为

想法	事实
“AUTH 只有 Approved 状态——我会在打标签后把它作为步骤 i 对齐”	太迟了。代码已经在标签里了。步骤 b 要在版本/标签操作之前完成。
“代码已经合入 main，所以它们都已发布”	合入 main 是落地。本技能会为一组 Implemented 规格打标签。
“必需的子技能 realign-spec 就是把状态改成 Shipped 的方法”	已不再如此。步骤 i 是对 Status/INDEX 的编辑。realign-spec 用于单个功能，防止规格腐化。
“总是运行 realign-spec，这样就不会忘记”	这和总是润色如出一辙。干净的 Implemented 规格集合 → 机械地改状态。
“跳过规格文书工作 / 没人看 INDEX / 我们已经完成了”	步骤 i 是一道关卡。打标签不是整个流程的终点。
“五分钟后就要站会——直接切出版本，把所有状态都改了”	时间紧迫和负责人都不能成为跳过步骤 b 阻塞项清单的理由。
“把 AUTH 从 Approved 改为 Shipped；切出版本就是证据”	Shipped 要求先达到 Implemented。阻塞项仍然是阻塞项。