| name | hf-release |
| description | 适用于把多个已 closed 的 feature/iteration 汇总成 vX.Y.Z 工程级发版（版本切片 + 全量回归 + 发布文档聚合）。当用户表达"切版本/出 release/打 tag/发版本号"时使用。不适用于单 feature closeout（→ hf-finalize）、上线/部署/监控/回滚（不在本 skill 范围；由项目自身的 ops 流程承担）。 |
HF Release
把若干个已 workflow-closeout 的 feature 汇总成一次 vX.Y.Z engineer-level release。负责锁范围、做版本级回归、聚合发布文档、产出 tag-ready pack。不做部署 / staged rollout / 监控 / 回滚——这些不在本 skill 范围，由项目自身的 ops 流程承担。
When to Use
适用：
- 用户表达 "切 vX.Y.Z" / "出 release" / "发版本号" / "打 tag" 意图（含
/release [version] 命令）
- 仓库累积 ≥ 1 个
workflow-closeout 的 feature，且需要切版本号
- 要做 release-wide full regression（不是单 feature 的 impact-based 回归）
- 要聚合多 feature 的 release notes / CHANGELOG / migration / known limitations
- 要产 release scope ADR（仿 ADR-001/002/003 风格的版本范围决策）
不适用：
- 单 feature closeout（task-closeout 或 workflow-closeout） →
hf-finalize
- 实际部署 / feature flag rollout / 监控配置 / 回滚演练 → 不在本 skill 范围；由项目自身的 ops 流程承担
- 需要新实现或补 fresh evidence → 上游
hf-test-driven-dev / 各 gate；本 skill 不写新代码
- 候选 feature 还没
workflow-closeout → 先回到 hf-finalize 把它们 close 掉
- 阶段不清 / 用户意图不是切版本 →
using-hf-workflow → 由 entry shell 重新分流
边界：本 skill 与 hf-workflow-router 完全解耦——不进 router transition map，不修改主链 FSM，不依赖 hf-finalize / hf-regression-gate / hf-doc-freshness-gate 在同一 session 跑过。它只读磁盘工件（feature 的 closeout.md / progress.md / 既有 review / verification 记录）做版本级判断。
Hard Gates
- 任一候选 feature 的
closeout.md 不是 Closeout Type: workflow-closeout → 拒入（task-closeout / blocked 都不算）
- candidate feature 的
completion / regression 记录缺失或与 closeout 结论矛盾 → 拒入
- release-wide regression 缺失或不 fresh（与本次 release scope 不匹配）→ 拒出
- CHANGELOG
[vX.Y.Z] 段未落盘 → 拒出
- release scope ADR 草稿未落盘 → 拒出
interactive 模式下 Final Confirmation 未通过 → 不写 Next Action: null- 不得承诺部署 / 监控 / 回滚演练 / SLO / health check / staged rollout / feature flag——这些不在本 skill 范围
- 不得自动执行
git tag / git push --tags——本 skill 只产 readiness pack，tag 操作交给项目维护者
- 不得自动删除 worktree——只能记录 disposition
- 不得让 release scope ADR 由作者自我批准——
docs/principles/soul.md 立场：HF 不替用户验收自己；建议由独立人/会话评审 ADR draft 后再 commit
Object Contract
- Primary Object:
Release Pack——版本级工件聚合（scope 决策 + evidence matrix + docs sync 记录 + tag readiness）
- Frontend Input Object: 候选 feature 的
closeout.md（type=workflow-closeout）+ 各 feature 的 verification / reviews 记录 + 项目级版本号约定（若有）
- Backend Output Object:
features/release-vX.Y.Z/release-pack.md + 仓库根 CHANGELOG.md 的 [vX.Y.Z] 段 + docs/decisions/ADR-NNN-release-scope-vX.Y.Z.md + docs/release-notes/vX.Y.Z.md（按存在）+ ADR 状态批量翻转（proposed → accepted）
- Object Transformation: 输入是 N 份
workflow-closeout 的 closeout pack；输出是 1 份 release pack + 配套发布文档；中间步骤是 scope 决策 + release-wide regression + docs aggregation
- Object Boundaries: 不修改既有
features/<feature-id>/closeout.md（只读消费）；不修改 spec/design/tasks 等已批准工件；不替代 hf-finalize 写单 feature closeout
- Object Invariants: 所有候选 feature 的 closeout 状态在
hf-release 执行前后一致；release pack 一旦写入，scope 已定，再要扩范围必须显式回到 §3 重做 scope 决策
Methodology
| 方法 | 来源 | 落到哪一步 |
|---|
| Release Scope ADR | HF 自身 ADR-001/002/003 实践 | §3 |
| SemVer 2.0.0 + Pre-release Marker | semver.org / ADR-001 D6 / ADR-002 D6 / ADR-003 D5 | §4 |
| Cross-feature Regression（impact-based 的版本级扩展） | Regression Testing Best Practice | §6 |
| Cross-feature Traceability Aggregation | Zigzag Validation（向上延伸到版本范围） | §7 |
| Sync-on-Presence (release tier) | 同 hf-doc-freshness-gate（协议内联，不引用该 skill） | §8 |
| Release Readiness Review | PMBOK release readiness | §9 |
| Handoff Pack Pattern | 同 hf-finalize（结构同源，scope 不同） | §10 |
| Standalone / No-Router Coupling | 本 skill 自包含运行原则（ADR-004 D3） | 全流程 |
| Author / Reviewer Separation (Fagan) | scope ADR 建议由独立人/会话评审 | §3 末尾 advisory |
Workflow
1. Entry vs Recovery（自给自足，不依赖 router）
读 features/release-vX.Y.Z/release-pack.md：
- 不存在 → 新建 release，进 §2
- 存在但 Final Confirmation 字段为空或
Status: in-progress → 续 release，跳到上次中断的步骤
- 存在且
Status: released 或 Final Confirmation: confirmed → 已收口，告知用户后退出（不重做）
vX.Y.Z 版本号优先级：用户传入 hint > 项目级版本号约定 > 默认按 SemVer 推断（见 §4）。
2. 候选 Feature 盘点
- Object: 候选 feature 集合
- Method: 扫
features/*/closeout.md，筛 Closeout Type: workflow-closeout
- Input: 仓库
features/ 目录
- Output: 候选清单（feature-id + closeout 路径 + 关闭日期 + affected modules 摘要）
- Stop / continue: 候选数 = 0 → 抛回用户"无可入版的 closed feature，建议先
hf-finalize"；候选数 ≥ 1 → 继续
不要把 task-closeout / blocked 当成候选——这两类未真正完成单 feature workflow。
3. Release Scope ADR 起草
- Object: scope ADR 草稿
- Method: 仿 ADR-001/002/003 模板（背景 / Decisions / Tradeoffs / Consequences / v0.X+ Roadmap / Implementation R1–RN / Notes），见
references/release-scope-adr-template.md
- Input: §2 候选清单 + 用户口径（必入 / 显式 defer / 限制说明）
- Output:
docs/decisions/ADR-NNN-release-scope-vX.Y.Z.md（草稿）+ scope decision 摘要写入 release pack 的 ## Scope Summary
- Stop / continue: scope 与候选清单不一致（含未列入的、含未在候选中的）→ 停下问用户；一致 → 继续
Author/Reviewer separation (advisory)：建议在 commit ADR draft 前，由独立人/会话评审一遍（HF Fagan 立场）。本 skill 不强制 hard gate——保持 standalone 性质，由项目自己决定评审节奏。
4. SemVer + Pre-release 判定
- Object: 版本号 + pre-release 标记
- Method: SemVer 2.0.0 决策表
- 含任一 breaking change → major bump
- 仅含 backward-compatible 新功能 → minor bump
- 仅含 backward-compatible bug fix → patch bump
- 主链覆盖未达 100% / 客户端面无质变 / 用户场景未稳定 → 仍勾 pre-release（沿用 ADR-001 D6 / ADR-002 D6 / ADR-003 D5 默认）
- Input: §3 scope ADR + 既有版本号
- Output: vX.Y.Z + pre-release: yes/no
- Stop / continue: 项目级约定（CalVer / 自定义）覆盖默认时遵循项目约定
5. Worktree / 分支盘点
- Object: 各候选 feature 的 worktree disposition
- Method: 读
features/<feature-id>/closeout.md 的 Worktree Disposition 字段；对仍是 kept-for-pr 的 feature，确认对应 PR 已合并到 release base branch
- Input: §2 候选清单
- Output: worktree disposition 清单写入 release pack
- Stop / continue: 任一候选 feature 的 PR 仍 open → 抛回用户决定（要么先合并 PR，要么把该 feature 移出本次 scope）；不擅自删除 worktree
6. Release-wide Regression（协议内联）
- Object: 版本级回归 evidence
- Method: 内联 fresh-evidence 协议
- Scope =
union(各候选 feature 的 affected modules)
- Profile-aware rigor：full / standard 必须跑 union 全集；lightweight 至少跑 critical path 子集
- Fresh evidence：执行点必须晚于所有候选 feature 最晚一次 closeout 时间
- 失败 = 拒出，不允许把单 feature 历史 regression 记录拼贴当成 release-wide 通过
- Input: §5 scope + 项目测试入口（项目级约定优先；默认尝试
npm test / pytest / make test / 项目 CI 入口）
- Output:
features/release-vX.Y.Z/verification/release-regression.md（含 scope / 执行命令 / 时间戳 / 通过/失败结论 / 失败时的 reroute 指向）
- Stop / continue: 失败 → 抛回用户 + 标记需修复哪个 feature；通过 → 继续
如果项目无统一测试入口或测试基础设施缺失，不降级回归——而是停下来抛回"项目缺乏 release-wide regression 入口，建议先建立"，让用户决定是延后发版还是临时降级；不替用户拍板降低门禁。
7. Cross-feature Traceability 摘要
- Object: 跨 feature 的 spec ↔ design ↔ tasks ↔ code ↔ tests 链聚合摘要
- Method: 不重做单 feature traceability（那是
hf-traceability-review 在 closeout 前已经做过的事）；只做版本级聚合——把各 feature 的 traceability verdict 汇总
- Input: 各候选 feature 的
reviews/traceability-*.md / closeout.md Evidence Matrix 段
- Output:
features/release-vX.Y.Z/verification/release-traceability.md（含每个 feature 的 traceability verdict + 跨 feature 风险（如有 API 变化跨多个 feature））
- Stop / continue: 任一候选 feature 缺 traceability verdict 且 profile 要求 → 抛回用户；profile 跳过的写
N/A（按 profile 跳过）
8. Pre-Release Engineering Checklist
按 references/pre-release-engineering-checklist.md，分小节核对（仅工程级 hygiene；显式不含 ops 项）：
Code & Evidence
Documentation Sync（sync-on-presence 协议内联）
Versioning Hygiene
Worktree / Branch State
Out of Scope（显式列出本 skill 不做的事）
- 部署到 production / staging / canary
- Feature flag 0% → 5% → 100% 的 staged rollout
- 监控仪表盘 / 错误上报 / SLO 配置
- 回滚 procedure / 回滚演练
- Health check / CDN / DNS / SSL / Rate limiting
- 上线后的观察窗口
以上不在本 skill 范围；如项目需要这些能力，由项目自身的 ops 流程承担——不写进本 skill 的 evidence。
9. 形成 Evidence Matrix
每条 release 证据写出：
- artifact name
- record path
- 是否适用于当前 profile
- 不适用时写
N/A（按 profile 跳过）
写入 release pack 的 ## Evidence Matrix 段。
10. 产出 Release Pack
按 references/release-pack-template.md 写入 features/release-vX.Y.Z/release-pack.md。至少包含：
- Release Summary（version / pre-release flag / scope ADR 路径 / included features / deferred features）
- Evidence Matrix
- Docs Sync 实际同步路径
- Tag Readiness（建议 tag 名 / 建议 commit / 分支 / PR 状态）
- Worktree Disposition
- Final Confirmation（interactive only）
- Limits / Open Notes（明确告知部署 / 监控 / 回滚等上线侧能力不在本 skill 范围，由项目自身 ops 流程承担）
11. Final Confirmation（interactive only）
hf-release 完成后会让 release scope 正式锁定（ADR 状态翻转 / CHANGELOG 段固化 / tag readiness pack 就位）；这是项目的对外承诺面变化，不能由 skill 自行决定。
interactive：先展示 Release Summary + Evidence Matrix + Docs Sync 实际路径 + Tag Readiness，等真人确认 "正式锁定 vX.Y.Z 范围"；auto：先写完 release pack（Status: ready-for-tag），把 Next Action 写成 null（实际 git tag 由项目维护者执行），不替用户最终拍板。
如果用户不同意锁定，回到 §3（scope 改动）或 §6（regression 失败）按需重做对应步骤。
Output Contract
工件目录布局：
features/release-vX.Y.Z/
release-pack.md # 主工件（必出）
scope-decision.md # 反向引用 docs/decisions/ADR-NNN-release-scope-vX.Y.Z.md（按需）
progress.md # 复用 feature progress schema（按需，记录 §1–§11 推进状态）
verification/
release-regression.md # §6（必出）
release-traceability.md # §7（必出）
pre-release-checklist.md # §8（必出，含勾选状态）
docs/decisions/
ADR-NNN-release-scope-vX.Y.Z.md # §3（必出）
CHANGELOG.md # 必出 [vX.Y.Z] 段
docs/release-notes/
vX.Y.Z.md # 仅档 2 启用时
release-pack.md 必备字段见 references/release-pack-template.md。
Next Action 规则：
- Final Confirmation 通过 / Status: released：
Next Action Or Recommended Skill: null（tag 操作由项目维护者执行；本 skill 不自动打 tag）
- 未通过 / 阻塞：
Next Action Or Recommended Skill: <具体阻塞点描述>，例如"§6 release-wide regression failed on module X，先回 hf-test-driven-dev 修复对应 feature 的回归"
- scope 还未锁定：
Next Action Or Recommended Skill: hf-release §3（同 skill 内回退）
不写回 hf-workflow-router（本 skill 与 router 解耦，没有"交回 router"的语义）。
Red Flags
- 把单 feature 的 release notes 直接当成 vX.Y.Z 整包发布说明
- 用 commit messages dump 充当 release notes
- 跳过 §6 release-wide regression，仅复用各 feature 的 impact-based 历史回归记录
- 候选 feature 的 ADR 仍是
proposed 就声称 release ready
- 在 release pack 中混入 ops 动作（feature flag / 监控 / 回滚演练）
- 把 release-pack 写到
features/<某 feature-id>/closeout.md（应在独立目录 features/release-vX.Y.Z/）
- 自动执行
git tag 或 git push --tags（本 skill 范围之外）
- 自动删除 worktree（只能记录 disposition）
- 一次发版同时纳入 breaking change + new feature + bug fix 而不分版本号语义（应按 SemVer 拆分或承认 major bump）
- 因为没有项目级 release-wide 测试入口就把 §6 写成
N/A 蒙混过关
- release scope ADR 由 skill 作者一手批准（违反 Fagan 分离 advisory）
- 把"用户当前在用什么客户端"作为 release 决策的输入（HF release 是 client-agnostic）
- 假设存在一个"现成的部署/上线 skill"可以承接被本 skill 拒绝的 ops 动作；out-of-scope 能力应直接说"由项目自身 ops 流程承担"，不要把读者推到一个虚构或未交付的 skill
Common Rationalizations
| 借口 | 反驳 / Hard rule |
|---|
| "/release 之后顺便 git tag + push 一下" | Hard Gates: 本 skill 只产 readiness pack；tag 是项目维护者动作，不在 skill 范围 |
| "复用各 feature 的 regression 记录就够了，不用再跑一次" | Hard Gates + §6: release-wide regression scope = union(features)，必须 fresh；拼贴 = 不通过 |
| "scope ADR 我自己拍就行了，多评审一轮浪费时间" | Author/Reviewer Separation 是 advisory 不是 hard gate，但 Red Flags 指出"作者一手批准"；与 docs/principles/soul.md "HF 不替用户验收自己" 立场冲突 |
| "这次 release 顺便配置一下 staged rollout / 监控 / 回滚" | Hard Gates: 本 skill 不承诺部署 / 监控 / 回滚；这些不在本 skill 范围，由项目自身的 ops 流程承担 |
| "router 应该把我派过来" / "我应该 handoff 回 router" | When to Use 边界 + ADR-004 D3: hf-release 与 router 完全解耦；不进 transition map，不交回 router |
| "项目没有统一的测试入口，§6 就标 N/A 跳过" | Hard Gates + §6 stop rule: 不替用户拍板降低门禁；缺入口要抛回用户决定（延后发版或临时降级），不能自己跳过 |
| "task-closeout 的 feature 也算入版吧，反正快做完了" | Hard Gates: 候选必须是 workflow-closeout；task-closeout 还有剩余任务未完成 |
| "writeonce demo 顺便也 release 一下" | When to Use + ADR-004 D9: writeonce demo 不走 release-tier；强加是空洞同步 |
Reference Guide
| 文件 | 用途 |
|---|
references/release-scope-adr-template.md | release scope ADR 起草模板（仿 ADR-001/002/003 结构） |
references/pre-release-engineering-checklist.md | §8 详细 checklist（仅工程级 hygiene；不含 ops 项） |
references/release-pack-template.md | release pack 主工件模板（schema 与 hf-finalize closeout pack 同源） |
hf-finalize/SKILL.md | 单 feature closeout（前置依赖：候选 feature 必须先经此 skill 写出 workflow-closeout 的 closeout pack） |
hf-test-driven-dev/references/worktree-isolation.md | worktree disposition 收尾语义（不擅自删除；只记录 kept-for-pr / cleaned-per-project-rule / in-place） |
docs/decisions/ADR-001-release-scope-v0.1.0.md 等 | HF 自身 release scope ADR 实践，可作 scope ADR 起草参考 |
Verification
