用途
Specsfy Release CLI 用于将 Specsfy 的稳定版本从其单体仓库 promovaweb/specsfy 中正式发布。发布须在官方检出根目录执行，要求提供 X.Y.Z 格式的版本号、确认过的发布说明，并在推送前获得明确授权。
版本来源
仓库根目录的 VERSION 是唯一版本来源。skills 与 especialistas 直接沿用单体仓库标签的版本号，不保有自己的版本文件。Hub 与 website 不参与该版本号。
主要流程
1. 状态分类
通过 git remote get-url origin、git branch --show-current、gh auth status、npm whoami、git fetch、git status、git rev-parse、gh release view 等命令，确认远程地址为 https://github.com/promovaweb/specsfy、分支为 main、具备同一仓库访问权限、工作区干净、HEAD 与 origin/main 一致，且用于新发布的标签与 release 尚不存在。若处于部分完成状态，不重建 commit、tag 或版本，而是比对标签、提交、产物与 changelog 段落，仅补做缺失环节。
2. 准备版本
以 python3 -B 调用 release_changelog.py 的 prepare 子命令，传入 --cli cli --version X.Y.Z --date YYYY-MM-DD 与 --notes-file。随后进入 cli 目录执行 npm install --package-lock-only --ignore-scripts、npm ci、npm run build:executable、npm run typecheck、npm test、npm run build、node dist/main.js --help、./bin/specsfy --version、npm publish --dry-run；回到根目录执行 make ebook、make verify-ebook、make verify-version，再用 release_changelog.py extract 从 cli/CHANGELOG.md 提取指定版本说明。此阶段要求 X.Y.Z 出现在 VERSION、package.json、src/version.ts、package-lock.json、CLI 安装、二进制、bin/specsfy.build.json、ebook 与 ebook/build.json 中，changelog 将说明提升到 ## [X.Y.Z] - YYYY-MM-DD 标题下。
3. 审查与版本化
交付物包括 VERSION、cli/CHANGELOG.md、cli/package.json、cli/package-lock.json、cli/src/version.ts、cli/bin/specsfy、cli/bin/specsfy.build.json、ebook/build.json 及当期版产物、以及本次变更的文档、skills 与 especialistas。展示说明与 diff，确认后执行 make verify-version，并将上述文件加入 Git，提交信息为 chore(release): vX.Y.Z，创建注解标签 git tag -a vX.Y.Z -m "Specsfy CLI vX.Y.Z"，确认 HEAD 与标签提交哈希一致。该标签属于单体仓库。
4. 发布与验证
执行 git push --atomic origin main vX.Y.Z，使用 gh run watch 等待 Specsfy 工作流，再用 gh release create --verify-tag 创建 GitHub Release 并附带发布说明，通过 gh release view 导出已发布说明 JSON，运行 release_changelog.py verify 校验 changelog 与发布说明一致。随后用 git ls-remote 确认远程标签，用 gh run list 查看 CI 结果。确认远程标签、CI 与说明完全一致；若失败则保留状态并重新分类。标签任务会把 @promovaweb/specsfy 发布到 npm；仓库公开时会包含 provenance。禁止创建补偿性标签。
适用场景
适用于从 promovaweb/specsfy 单体仓库发布 Specsfy 稳定版本的维护人员，涵盖从版本准备、构建测试、changelog 与电子书生成，到 Git 推送、CI、GitHub Release 与 npm 发布的全流程。
限制
必须在官方检出根目录执行并具备相应远程、认证与 npm 权限；要求 X.Y.Z 版本号、确认的说明与显式推送授权；不支持为失败步骤创建补偿标签。Hub 与 website 不参与该版本号。