@haiyangbg/buildbeat 1.20.0 → 2.0.0-beta.1

package/CHANGELOG.md

@@ -2,24 +2,46 @@
 
 > 本项目吃自己的狗粮(红线④:必更 CHANGELOG)。格式循 Keep a Changelog,倒序。
 
-## Unreleased
+## v2.0.0-beta.1 — 未发布（beta-ready，等待所有者发布授权）
+
+> 主题：BuildBeat v2 首个 Beta——确定性内核 + Agent Loop Runtime。事件溯源台账（hash 链、损坏截断、终态压实进 Git 面）、Policy 门（8 算子三值逻辑、`UNVERIFIED` 永不当 PASS）、隔离 Workspace（push 物理封禁、`allowedPaths` 越界即停、Reviewer 只读快照强制）、Shell Adapter 厂商中立接任意 CLI Agent（codex 实证）、digest 绑定人批与 `APPROVAL_STALE`。MVP 承诺兑现：Build–Verify–Fix–Review 自动闭环，停在合并决定，带证据交人。
+> **发布口径**：`dist-tag: next`；`latest` 仍指向 v1.21.0，v1 CLI 与文件原样冻结随包分发。v2 入口为独立 bin `buildbeat-v2`。
+> **试点证据**：self-host（RUN-SELF-001）+ 两个外部真实项目（ruoyi-ai RUN-CLI-DW-01 全自动 5.2 分钟到合并决定；chickAI 看板积压含完整 reviewer 阻断→fixer 修复闭环），六退出指标全达标；见 `docs/v2/M4-*.md`。
+
+- **observe v0**（RFC-0003 §8 冻结契约的实现）：drift-check/live-status 类探针接为 Evidence Provider（采不到即 `unverified`，同一 Evidence Contract 与链校验台账）；bands log→只读诊断→Intent 草稿三层分层响应；草稿只入队 Git 面绝不自动执行；`observe triage` 人分诊，`dismiss` 回调阈值防告警疲劳；分诊记忆活在 Git 面，runtime 可删（不变量 23 有测试）
+- **文档十件套**（`docs/v2/guide/`）：快速开始 / Workflow / Policy / Adapter / Worker 合同 / Evidence / Approval / v1 迁移半天手工 runbook / 安全边界 / 故障恢复
+- **`buildbeat-v2 metrics`**：本地只读六指标；行为 evals 九场景卡进 `npm test` 单入口
+- **v1 迁移**：半天手工 runbook（不猜旧状态、单向迁移、禁止双写）；`legacy-four-gates` 风险预设保留 v1 四 Gate 完整形态
+- **v1 冻结的两处诚实修正**（prepublish 门抓出）：manifest `cliVersion` 校验接受 prerelease（否则 v1 CLI 装在 beta 包里自坏）；`SCAFFOLD_VERSION` 钉死 `v1.21` 字面量、与包版本解耦——脚手架内容束未变，存量安装不应看到虚构的跨大版本升级
+- **发布道**：publish workflow 增加 prerelease 通道（prerelease tag 只能从其发布分支的 origin tip 发、强制 dist-tag `next`、verify 回读 dist-tag 路由；stable 通道 main-only 原样），配对契约进 `tests/publish-workflow.test.js` 永久回归
+
+## v1.21.0 — 2026-08-25
+
+> 主题：统一各域的收口回复，让人一眼看清做成了什么、证据在哪、还有什么没做，以及下一棒或真实求助。
+> **拷出项目升级**:在根 `AGENTS.md` 的任务包规则后补入「域回复格式」;未改过的 `指挥台.md` 可随后续版本机械替换。历史 status、看板和证据不回改,`pm/status/**` 持久口径不变。
+> **发布状态**：`@haiyangbg/buildbeat@1.21.0` 已通过 GitHub Actions OIDC / Trusted Publishing 发布；官方 registry exact artifact、SLSA provenance、签名、attestation、隔离安装、README 与 GitHub Release 均已独立回读。关闭证据见 [`docs/V1.21-RELEASE-EVIDENCE-2026-08-25.md`](docs/V1.21-RELEASE-EVIDENCE-2026-08-25.md)。
+
+- **域回复契约**:产品/全栈/测试等 AI 视角面向人收口时统一按「已做 → 未做 → 下一步」输出;已做只写功能/业务结果,证据紧跟对应事项,未做必须写原因,下一步明确交棒对象或真实求助
+- **发挥边界**:回复契约只约束收口/交接,不要求中间进展和探索讨论套模板;本域仍能安全推进时继续做,不伪造求助或固定域流水线
+- **多入口同步**:`SKILL.md`、`templates/AGENTS.md`、`指挥台.md`、中英 README、教学沙盘与文档回归检查同步新口径;Claude Code 插件版本升至 `0.2.1` 以刷新缓存;`lessons.md` 新增「域回复各说各话」失败模式
+- **Node 23 macOS 测试兼容**:符号链接安全回归用 `unlinkSync` 删除符号链接,避免 `fs.rmSync` 在 Node 23.6 上误报 `ERR_FS_EISDIR`;不改运行时写入逻辑
 
 ## v1.20.0 — 2026-08-25
 
-> 主题：把 Phase 0–3 合并为 BuildBeat 首个 scoped 正式候选，canonical 分发迁移到 `@haiyangbg/buildbeat` 与 `HaiYangBG1/BuildBeat`；旧 `solobaton` 包冻结为只读兼容入口。
+> 主题：把 Phase 0–3 合并为 BuildBeat 首个 scoped 正式版本，canonical 分发迁移到 `@haiyangbg/buildbeat` 与 `HaiYangBG1/BuildBeat`；旧 `solobaton` 包冻结为只读兼容入口。
 > **拷出项目升级**：真实 schema 2 v1.16 安装可先运行 `buildbeat upgrade --dry-run`，无 blocker 后再机械升级到 v1.20；legacy/无 manifest 项目继续走手工迁移指南。`--force` 不覆盖 project-owned，项目 uninstall 仍不开放。
-> **发布状态**：本条随不可变候选进入 tag；只有官方 registry 的 scoped artifact、SLSA provenance、签名、隔离安装、README 与 GitHub Release 全部回读后，才能补记为已验证发布。
+> **发布状态**：`@haiyangbg/buildbeat@1.20.0` 已通过 GitHub Actions OIDC / Trusted Publishing 发布；官方 registry exact artifact、SLSA provenance、签名、attestation、隔离安装、README 与 GitHub Release 均已独立回读。关闭证据见 [`docs/WP4.3-RELEASE-EVIDENCE-2026-08-25.md`](docs/WP4.3-RELEASE-EVIDENCE-2026-08-25.md)。
 
 - **WP4.3 scoped 分发决策**：用户拍板立即迁移到 `@haiyangbg/buildbeat` 和 `HaiYangBG1/BuildBeat`；不冒用已被占用的 unscoped `buildbeat`。canonical executable 保持 `buildbeat`，`solobaton` 只保留包内兼容别名
 - **版本序列合并**：未对外发布的 v1.17/v1.18/v1.19 不伪造成中间 artifact；当前 Phase 0–3 统一进入 `1.20.0`，scaffold version 从 v1.16 形成真实增量到 v1.20
-- **legacy 包退场策略**：新 scoped artifact 与迁移回读全绿后，`solobaton@*` 只做 deprecation 提示，不 unpublish、不获得写入/upgrade 能力，避免破坏既有只读安装
+- **legacy 包退场完成**：`solobaton@1.16.1`、`1.16.2`、`1.16.3` 已逐版本读回指向 `@haiyangbg/buildbeat` 的 deprecation 提示；未 unpublish，旧包不获得写入/upgrade 能力
 - **Claude plugin 迁移**：仓库入口更新为 `HaiYangBG1/BuildBeat`，插件版本升至 `0.2.0` 以刷新分发缓存；npm CLI `bin/` 仍不进入插件包
 - **真实 v1.20 升级试点**：在专用分支将真实 schema 2 项目从 scaffold `v1.16` / CLI `1.16.3` 升至 `v1.20` / `1.20.0`；默认 dry-run 对四个改写文件零写阻断，force 后人工回灌项目事实，project-owned 零 diff，doctor 0/0、strict exit 0、提交后 dry-run up-to-date，目标仓 clean 且无 remote
 - **真实多仓刷新与兼容修复**：当前检查器在真实四子仓协调层投影中发现 legacy prose 根内 `../` 误判；现只对 scoped prose 允许 realpath 留在根内的 source-relative link，canonical Gate/evidence 仍禁 traversal，根外逃逸回归继续阻断。Shell 回归增至 `222/222`；最终刷新精确保留业务仓真实 `lessons.md` 断链、未登记 map 与适配器/远端/live unverified，不冒充全绿
 - **Linux CI 可移植性**：JSON renderer 的 awk quote 正则改为 BSD awk / mawk 共通写法，避免 Linux stderr warning 污染机器 JSON；同时展开旧式 `A && B || C` Shell 断言并兼容 ShellCheck 0.9/0.11，macOS 与 Ubuntu 共用同一语义
 - **品牌正式定名 BuildBeat**：2026-08-25 用户拍板产品名为 BuildBeat；canonical CLI/Skill/Claude plugin 标识统一为 `buildbeat` / `buildbeat@buildbeat-plugins`，新骨架入口改为 `BUILDBEAT.md`
 - **canonical namespace 迁移**：新写入只生成 `.buildbeat/manifest.json`、BuildBeat `.gitignore` marker 与 `buildbeat-stack-baseline:v1`；doctor/bus-check 继续读取旧 `SOLOBATON.md`、`.solobaton/manifest.json`、marker 与 STACK 基线，双 manifest 或混合安装 fail-closed
-- **legacy 分发兼容**：已发布 npm 包 `solobaton` 保留为 BuildBeat 的 legacy read-only distribution ID，并同时暴露 canonical `buildbeat` 与兼容 `solobaton` executable；未加 scope 的 `buildbeat` 包名已被其他项目占用，用户已批准迁移 scoped package 和新仓库名，远端完成状态仍逐项回读
+- **legacy 分发兼容**：已发布 npm 包 `solobaton` 保留为 BuildBeat 的 legacy read-only distribution ID；新 scoped 包同时暴露 canonical `buildbeat` 与兼容 `solobaton` executable。未加 scope 的 `buildbeat` 包名已被其他项目占用，canonical package/repository 已迁移并完成远端回读
 - **改名证据边界**：WP2.7 三条真实目录试点及其 hash 保持为 legacy namespace 历史证据；WP2.8 已用全新的隔离目录完成 BuildBeat canonical init/adopt/Skill-only 回归，二者不混写、不互相外推
 - **新版方向与执行基线入库**：新增 `docs/ROADMAP.md`、`docs/EXECUTION-PLAN.md` 与官方来源可复核的 CLI 策略对照；产品方向由路线图承载，当前交付范围与依赖顺序由执行计划 v3 承载
 - **CLI 选择性解冻决策**：未来只开放 `init/adopt` 哑脚手架写入与 manifest/hash 驱动的机械 `upgrade`；三方合并、项目 uninstall 引擎、`gate/adr/standards/check` 命令扩张继续冻结，语义渲染和冲突合并归 AI 会话/Skill
@@ -42,7 +64,7 @@
 - **仓库安全基线**：新增 npm/GitHub Actions Dependabot 周检、JavaScript/TypeScript CodeQL、SECURITY/贡献/行为规范、CODEOWNERS、Issue/PR 模板；CI 中第三方 Action 改为不可变完整 commit SHA
 - **发布引用保护**：GitHub 服务端 `Protect release tags` ruleset 覆盖 `refs/tags/v*`，禁止更新和删除已创建的发布 tag，且无绕过角色；发布 runbook 增加回读步骤
 - **CLI v0 真实试点**：使用官方 npm registry 的 `solobaton@1.16.3` 对三个存量项目运行只读 `doctor` 和 `adopt --dry-run`；Git 可见状态前后一致，并正确区分未安装、旧版已安装和部分安装状态
-- **当前能力边界不冒进**：已独立验证的 npm `solobaton@1.16.3` 仍对所有项目写入 fail-closed；scoped `1.20.0` 源码候选已完成真实旧 schema 2 → 新 bundle 试点，但源码/项目证据不替代 registry artifact、provenance、签名、隔离安装与 GitHub Release 回读
+- **真实 scoped 发布验收**：`@haiyangbg/buildbeat@1.20.0` 已由 `v1.20.0@5aaa9e8` 和 workflow run `32826832379` 保全；registry `latest=1.20.0`、exact integrity、SLSA v1 provenance、registry signature、attestation、隔离安装及 GitHub Release 全绿。legacy `solobaton@1.16.3` 仍对所有项目写入 fail-closed
 - **产品扩张边界**：多人账号/权限/组织管理和遥测/效能评分/指标仪表盘明确为当前非目标；CLI 不采集或上传项目使用数据，未来若扩展须独立立项并审查数据口径、隐私和权限治理
 - **不变量与输出合同落地**：`docs/CHECKS.md` 冻结八条文件总线不变量、Gate/证据令牌、五级结论、finding code 命名空间、JSON 外形和严格模式退出语义；`bus-check --format=json` 已由同一 finding 集合渲染，默认人类报告保持 exit 0，strict 只拦 `conflict/error`
 - **Phase 1 执行同步**：`SKILL.md` 与 AGENTS/status 模板固化开工 7 步、执行中 5 守则、收工 7 步；看板模板和教学沙盘新增四行 canonical Gate 状态与完成工作包 `**证据**:` 令牌
@@ -72,7 +94,7 @@
 - **端到端 Builder 模型对齐**：`SKILL.md`、模板、示例和中英 README 统一为“按需求/功能工作包并行，单个 Builder 端到端负责产品判断、实现、测试与交付证据”；产品/全栈/测试保留为 AI 专业视角，不建人类角色接力或团队管理层
 - **Phase 0 回归地基**：新增健康/坏指针项目夹具和 `expected-findings.json` 过渡合同，并增加无 Node、无 CLI manifest 的 Skill-only 脚手架回归；两条 Shell 套件纳入 `prepublishOnly`，但未授权 v1.17 tag、GitHub Release 或 npm 发布
 
-> **拷出项目升级（当前 Unreleased 候选，尚未发布）**：
+> **拷出项目升级（v1.20 已验证发布）**：
 > 1. 若 `scripts/bus-check.sh` 未被项目修改，可整文件替换；紧凑布局替换 `pm/scripts/bus-check.sh`。
 > 2. `verify-status.sh` 属 project-owned：保留现有 `SUITES`，仅人工合并 `--format=machine` 与 L3 新鲜度逻辑，不整文件覆盖。
 > 3. 旧看板人工补 Gate1–Gate4 四行；每个 `✅完成` 工作包补恰好一行 `**证据**:`；NOW/看板的新机器引用改用仓库根相对路径（不用 `../`），并按需把开工/收工核对措辞合入 AGENTS/status 约定。

package/README.en.md

@@ -79,7 +79,7 @@ npm uninstall --global @haiyangbg/buildbeat       # remove only the global CLI p
 
 Package-manager install, update, and removal operations manage only the **CLI package and executables**; they never create, upgrade, or delete a project's scaffold. `doctor` is read-only. `init/adopt` show the complete plan and write only after clean-Git, collision, blocker, and confirmation checks. `upgrade` accepts only a canonical schema 2 baseline and performs manifest/hash-based mechanical changes with zero writes on unresolved conflict. `diff/uninstall` and workflow-command expansion remain frozen. `buildbeat` is canonical; the `solobaton` executable remains only as a compatibility alias. See [`docs/CLI.md`](docs/CLI.md) for the complete contract.
 
-`1.20.0` is the merged Phase 0–3 version: bounded Wave 1 `init/adopt` writes, schema-2-only `upgrade`, stronger Gate/evidence joins, multi-repository drift, and scan-boundary reporting. `--force` still cannot overwrite project-owned content or unsafe paths, and a major transition separately requires `--major`. A source checkout, Git tag, and npm artifact remain different evidence surfaces; use [`docs/RELEASING.md`](docs/RELEASING.md) plus the matching GitHub Release and registry readback for release and pilot status.
+`1.21.0` is now independently verified and adds a standard domain-response format on top of the `1.20.0` lifecycle: close out with Done → Not done → Next, and keep evidence directly under the completed outcome it supports. CLI commands and safety boundaries do not expand. `--force` still cannot overwrite project-owned content or unsafe paths, and a major transition separately requires `--major`. A source checkout, Git tag, and npm artifact remain different evidence surfaces; exact release evidence is archived in [`docs/V1.21-RELEASE-EVIDENCE-2026-08-25.md`](docs/V1.21-RELEASE-EVIDENCE-2026-08-25.md).
 
 Copied v1.16 legacy projects must not hand-author, copy, or rename a manifest to fabricate schema 2 ownership. Continue with manual CHANGELOG-based maintenance by default; if mechanical upgrades are genuinely required, use the [v1.16 legacy migration guide](docs/LEGACY-V1.16-MIGRATION.md) to rebuild the baseline under review on a dedicated Git branch.
 
@@ -128,6 +128,8 @@ You are the Fullstack perspective for the current work package. Own implementati
 You are the Testing perspective for the current work package. Own black-box acceptance, E2E, and evidence. Verify the current candidate.
 ```
 
+Every perspective closes its user-facing response as **Done → Not done → Next**. Done contains only functional or business outcomes, and evidence stays directly under the completed outcome it supports. Not done names the remaining outcome and its reason. A completed perspective says who takes the next baton and what they own; an incomplete perspective says who must provide or confirm what. If it can continue safely on its own, it keeps working instead of inventing a handoff or help request. See [`templates/指挥台.md`](templates/%E6%8C%87%E6%8C%A5%E5%8F%B0.md) for the full template.
+
 At the start of every session, synchronize the repository and run the guardrail:
 
 ```bash
@@ -236,9 +238,9 @@ The compact brownfield layout moves the scripts, operator card, and version mark
 | Production-config drift | `jq`, a SHA tool, project `live-config.sh` | Explicitly skipped; no production-state conclusion |
 | Live-version query | project `live-status.sh` and platform CLI | Explicitly unconfigured; documentation is not treated as live truth |
 | L3 test evidence | real `SUITES` in project `verify-status.sh` | Reports unconfigured; cannot claim automation is green |
-| CLI inspection/scaffolding/mechanical upgrade | Node.js 20+, the npm registry, or this source checkout | Legacy npm v0 remains read-only; scoped BuildBeat 1.20 has completed a genuine schema 2 version-increment pilot, while registry-artifact availability still requires independent readback; project uninstall remains frozen, and the Skill/manual equivalent stays supported |
+| CLI inspection/scaffolding/mechanical upgrade | Node.js 20+, the npm registry, or this source checkout | Legacy npm v0 remains read-only; scoped BuildBeat 1.21 is independently verified, while the genuine schema 2 version-increment pilot remains the v1.20 real-project evidence; project uninstall remains frozen, and the Skill/manual equivalent stays supported |
 
-Skill-only, legacy npm v0, and scoped BuildBeat 1.20 are distinct availability surfaces; the source checkout, registry artifact, and real project must also be verified separately. `doctor`, `init/adopt`, and `upgrade` own different responsibilities. See the bilingual [BuildBeat capability matrix](docs/CAPABILITY-MATRIX.md) and the [v1.20 real-project pilot](docs/PHASE4-V1.20-PILOT-2026-08-25.md).
+Skill-only, legacy npm v0, and scoped BuildBeat 1.21 are distinct availability surfaces; the source checkout, registry artifact, and real project must also be verified separately. `doctor`, `init/adopt`, and `upgrade` own different responsibilities. See the bilingual [BuildBeat capability matrix](docs/CAPABILITY-MATRIX.md) and the [v1.20 real-project pilot](docs/PHASE4-V1.20-PILOT-2026-08-25.md).
 
 ## Continue reading
 
@@ -250,7 +252,7 @@ Skill-only, legacy npm v0, and scoped BuildBeat 1.20 are distinct availability s
 - [`docs/CLI-STRATEGY-2026-08.md`](docs/CLI-STRATEGY-2026-08.md): the official-source CLI comparison and its evidence limits;
 - [`docs/CHECKS.md`](docs/CHECKS.md): file-bus invariants, Gate/evidence tokens, finding codes, and strict-mode semantics;
 - [`docs/CLI.md`](docs/CLI.md): command boundaries, file ownership, manifest, mechanical upgrade, and manual-removal contract;
-- [`docs/CAPABILITY-MATRIX.md`](docs/CAPABILITY-MATRIX.md): bilingual capability and interoperability mapping across Skill-only, legacy npm v0, and scoped BuildBeat 1.20;
+- [`docs/CAPABILITY-MATRIX.md`](docs/CAPABILITY-MATRIX.md): bilingual capability and interoperability mapping across Skill-only, legacy npm v0, and scoped BuildBeat 1.21;
 - [`docs/LEGACY-V1.16-MIGRATION.md`](docs/LEGACY-V1.16-MIGRATION.md): safe paths for a copied v1.16 project to remain manually managed or rebuild a schema 2 baseline under review (Chinese);
 - [`docs/CLI-PILOT-2026-08-23.md`](docs/CLI-PILOT-2026-08-23.md): read-only CLI v0 evidence from three real brownfield projects and the write-boundary decision;
 - [`docs/PHASE1-PILOT-2026-08-24.md`](docs/PHASE1-PILOT-2026-08-24.md): the read-only Phase 1 file-bus pilot across the example, an active multi-repo projection, and a real single-repo code tree;

package/README.md

@@ -77,7 +77,7 @@ npm uninstall --global @haiyangbg/buildbeat       # 只移除全局 CLI 包
 
 包管理器的安装、更新、移除只管理 **CLI 包和可执行文件**，不会创建、升级或删除项目里的协作骨架。`doctor` 只读检查；`init/adopt` 必须先看完整计划，并在无 blocker、干净 Git 和明确确认后才写入；`upgrade` 只接受 canonical schema 2 基线，按 manifest/hash 做机械升级，冲突时零写。`diff/uninstall` 与工作流命令扩张继续冻结。canonical 命令是 `buildbeat`；`solobaton` executable 只保留兼容别名。完整契约见 [`docs/CLI.md`](docs/CLI.md)。
 
-`1.20.0` 是 Phase 0–3 的合并版本：包含 Wave 1 `init/adopt` 受控写入、schema-2-only `upgrade`、Gate/证据强关联、多仓漂移与扫描边界报告。`--force` 也永不覆盖 project-owned 内容或不安全路径；跨 major 另需 `--major`。源码 checkout、Git tag 和 npm artifact 仍是不同证据面，发布状态与真实试点边界必须以 [`docs/RELEASING.md`](docs/RELEASING.md) 和对应 GitHub Release/registry 回读为准。
+`1.21.0` 已独立验证发布，并在 `1.20.0` 生命周期上新增统一域回复格式：收口时按「已做 → 未做 → 下一步」输出，证据紧跟对应的已做事项；CLI 命令和安全边界不扩张。`--force` 仍永不覆盖 project-owned 内容或不安全路径，跨 major 另需 `--major`。源码 checkout、Git tag 和 npm artifact 是不同证据面，精确发布证据见 [`docs/V1.21-RELEASE-EVIDENCE-2026-08-25.md`](docs/V1.21-RELEASE-EVIDENCE-2026-08-25.md)。
 
 已拷出的 v1.16 legacy 项目不得手写、复制或重命名 manifest 来伪造 schema 2 所有权。默认继续按 CHANGELOG 手工维护；如果确需进入机械升级，按 [v1.16 legacy 迁移指南](docs/LEGACY-V1.16-MIGRATION.md) 在专用 Git 分支受控重建基线。
 
@@ -126,6 +126,8 @@ chmod +x .git/hooks/pre-commit
 你是当前工作包的测试视角，负责黑盒验收、E2E 和证据。验收当前候选。
 ```
 
+每个视角面向人收口时统一按「已做 → 未做 → 下一步」回复:`已做`只写功能/业务结果,证据紧跟对应的已做事项;`未做`写清事项和原因;本域完成就说下一棒是谁、接什么,未完成就说需要谁提供或确认什么。自己能继续就不交棒、不伪求助。完整模板见 [`templates/指挥台.md`](templates/%E6%8C%87%E6%8C%A5%E5%8F%B0.md)。
+
 每个会话开工先同步代码，再运行护栏：
 
 ```bash
@@ -234,9 +236,9 @@ flowchart LR
 | 生产配置漂移 | `jq`、SHA 工具、项目 `live-config.sh` | 明确跳过，不能外推生产状态 |
 | 线上版本查询 | 项目 `live-status.sh` 和平台 CLI | 明确未配置，不引用文档版本冒充线上事实 |
 | L3 测试证据 | 项目填写 `verify-status.sh` 的 `SUITES` | 只能报告未配置，不能声称自动化测试已绿 |
-| CLI 检查/脚手架/机械升级 | Node.js 20+、npm registry 或本仓库源码 | legacy npm v0 仍只读；scoped BuildBeat 1.20 已完成真实 schema 2 版本增量试点，registry artifact 是否可用仍须独立回读；项目 uninstall 继续冻结，Skill/手动等价路径始终保留 |
+| CLI 检查/脚手架/机械升级 | Node.js 20+、npm registry 或本仓库源码 | legacy npm v0 仍只读；scoped BuildBeat 1.21 已独立验证，真实 schema 2 版本增量试点仍由 v1.20 证据支撑；项目 uninstall 继续冻结，Skill/手动等价路径始终保留 |
 
-Skill-only、legacy npm v0 和 scoped BuildBeat 1.20 是三个不同可用面；源码 checkout、registry artifact 与真实项目也必须分别核验。`doctor`、`init/adopt`、`upgrade` 不承担相同责任。完整对照见 [BuildBeat 能力矩阵](docs/CAPABILITY-MATRIX.md)，真实版本增量证据见 [v1.20 试点记录](docs/PHASE4-V1.20-PILOT-2026-08-25.md)。
+Skill-only、legacy npm v0 和 scoped BuildBeat 1.21 是三个不同可用面；源码 checkout、registry artifact 与真实项目也必须分别核验。`doctor`、`init/adopt`、`upgrade` 不承担相同责任。完整对照见 [BuildBeat 能力矩阵](docs/CAPABILITY-MATRIX.md)，真实版本增量证据见 [v1.20 试点记录](docs/PHASE4-V1.20-PILOT-2026-08-25.md)。
 
 ## 继续阅读
 
@@ -248,7 +250,7 @@ Skill-only、legacy npm v0 和 scoped BuildBeat 1.20 是三个不同可用面；
 - [`docs/CLI-STRATEGY-2026-08.md`](docs/CLI-STRATEGY-2026-08.md)：基于官方来源的 CLI 策略对照与证据边界；
 - [`docs/CHECKS.md`](docs/CHECKS.md)：文件总线不变量、Gate/证据令牌、finding code 与严格模式规格；
 - [`docs/CLI.md`](docs/CLI.md)：CLI 命令边界、文件所有权、manifest、机械升级和手动移除合同；
-- [`docs/CAPABILITY-MATRIX.md`](docs/CAPABILITY-MATRIX.md)：Skill-only、legacy npm v0 与 scoped BuildBeat 1.20 的双语能力/互操作对照；
+- [`docs/CAPABILITY-MATRIX.md`](docs/CAPABILITY-MATRIX.md)：Skill-only、legacy npm v0 与 scoped BuildBeat 1.21 的双语能力/互操作对照；
 - [`docs/LEGACY-V1.16-MIGRATION.md`](docs/LEGACY-V1.16-MIGRATION.md)：v1.16 拷出项目继续手工维护或受控重建 schema 2 基线的安全路径；
 - [`docs/CLI-PILOT-2026-08-23.md`](docs/CLI-PILOT-2026-08-23.md)：三个真实存量项目的 CLI v0 只读试点与写入边界决策；
 - [`docs/PHASE1-PILOT-2026-08-24.md`](docs/PHASE1-PILOT-2026-08-24.md)：Phase 1 文件总线在 example、活跃多仓投影和真实单仓代码树上的只读试点；

package/SKILL.md

@@ -154,7 +154,38 @@ Gate1 规格(人批) → Gate2 设计(人对着真渲染原型批) → 实现+
 6. 确认各仓工作树与 staged 范围;他人 WIP、散落临时文件或计划中的 candidate 修改未收敛时,不声称 review-ready。
 7. 一屏收尾:交付结果、证据、未验证边界、挂账/真实阻塞、是否命中下一道人工 Gate。
 
-### 6.4 检查结果怎么读
+### 6.4 域回复格式
+
+每个 AI 视角面向用户收口、交接或回复明确检查点时,统一按「已做 → 未做 → 下一步」输出。这个格式只约束收口事实,不要求中间进展或探索讨论套模板。
+
+```md
+## 〔当前域〕｜✅ 已完成 / 🔄 未完成
+
+### 已做
+
+1. 〔功能或业务结果〕
+   - 证据：〔commit、测试结果或报告〕
+
+### 未做
+
+1. 〔还没完成或没验证什么〕
+   - 原因：〔具体原因〕
+
+### 下一步
+
+- **本域已完成：** 下一棒是〔哪个域 / AI 视角〕，负责〔业务级目标〕。
+- **本域未完成：** 需要〔谁〕提供或确认〔什么〕。
+- **无需协助：** 我继续做，暂不交棒。
+```
+
+口径:
+
+- `已做`只写功能或业务级结果,不罗列文件和实现细节;证据紧跟它所支持的事项。多项共用同一份证据时,改在列表末尾写一次「共同证据」。
+- `未做`必须同时写原因;未验证范围也放这里。没有就写「无」,不把局部验证外推为整体完成。
+- `下一步`只保留符合当前状态的一项。下一棒按剩余目标决定,不是固定的产品 → 全栈 → 测试流水线;整个工作包已完成就写「下一棒:无」。
+- 本域未完成但仍能在已批范围内安全推进时,不向用户伪求助;继续做。只有真实阻塞或用户明确要检查点时,才用「需要帮助」或「我继续做,暂不交棒」收口。
+
+### 6.5 检查结果怎么读
 
 先按级别处理,不要只看退出码。`bus-check --strict` 只让 `conflict/error` 非零退出；`warning/unverified` 不阻断,但仍必须写进本次证据边界。需要给自动化消费时用 `--format=json --strict`,同时看 `summary`、`coverage.complete` 和 `strict.blocked`。
 
@@ -196,7 +227,7 @@ Gate1 规格(人批) → Gate2 设计(人对着真渲染原型批) → 实现+
 > 🔴 收到「搭骨架 / 用 BuildBeat 起项目」类请求时,流程 = **先自查代码 → 只问查不到的 → 一屏确认 → 生成**;不许直接拷模板留 `<占位符>` 让用户手改,也**不许把看代码就能搞清的事拿去问用户**。
 > **提问三原则:① 能从代码/配置查到的不问;② 问就问不懂技术的人也能答的话**(话术不出现"仓/部署单元/契约/CLI"这类词,能给选项就不开放问);**③ 合并一次问完(常规 3 问,查到有 UI 时 +1),不连环追问**。有 AskUserQuestion 类工具就用,没有就在对话里问;用户说「你定 / 随便」就取默认值,并在收尾报告标注。
 >
-> **CLI 是确定性机械层,不是 Bootstrap 替身。** 旧 npm 包 `solobaton` 已发布的 v0 仍只读；当前未发布源码候选可先运行 `node bin/buildbeat.js init <项目根> --dry-run --json`,存量项目改用 `adopt ... --dry-run --json`。旧 `bin/solobaton.js` 只作为迁移别名保留。把仓/部署标记/UI/测试/碰撞结果作为自查证据,随后仍要读代码、只问剩余问题并做一屏确认。只有同一屏已获用户确认且 dry-run 无 blocker,才可用源码候选去掉 `--dry-run` 交互写入；非交互时 `--yes` 只复用这次确认,不能绕过碰撞/脏 Git/路径检查。CLI 只填确定项,必须继续按输出的 `pendingPlaceholders` 完成语义渲染；不得声称它已初始化 Git、安装 Hook、跨 Gate 或发布 npm。
+> **CLI 是确定性机械层,不是 Bootstrap 替身。** Canonical npm 入口已发布为 `@haiyangbg/buildbeat@latest`；先运行 `npx --yes --package=@haiyangbg/buildbeat@latest buildbeat init <项目根> --dry-run --json`,存量项目改用 `adopt ... --dry-run --json`。旧 npm 包 `solobaton` 已 deprecate 且仍只读；新包内的 `solobaton` executable 只作为迁移别名保留。把仓/部署标记/UI/测试/碰撞结果作为自查证据,随后仍要读代码、只问剩余问题并做一屏确认。只有同一屏已获用户确认且 dry-run 无 blocker,才可去掉 `--dry-run` 交互写入；非交互时 `--yes` 只复用这次确认,不能绕过碰撞/脏 Git/路径检查。CLI 只填确定项,必须继续按输出的 `pendingPlaceholders` 完成语义渲染；不得声称它已初始化 Git、安装 Hook、跨 Gate 或替业务项目批准发布。
 
 ### 8.1 先自查,后提问
 

package/bin/buildbeat-v2.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+// v2 runtime CLI entry. The v1 `buildbeat` bin stays frozen on src/cli.js;
+// v2 ships as a separate entry until it takes over `latest`.
+
+import "../src/v2/cli/run.js";