@haiyangbg/buildbeat 2.0.2 → 3.0.1

package/bin/buildbeat.js

@@ -1,5 +1,17 @@
 #!/usr/bin/env node
 
-import { run } from "../src/cli.js";
+// BuildBeat runtime CLI entry.
+//
+// Guard before loading any module: the kernel uses Node>=20 syntax, and on a
+// machine whose default node drifted older the raw SyntaxError stack hides
+// the actual problem (real incident: default node v14 during the meta pilot).
+const major = Number(process.versions.node.split(".")[0]);
+if (major < 20) {
+  console.error(
+    `buildbeat needs Node >= 20; this shell resolved v${process.versions.node}.\n` +
+      "Check `which node` / nvm default, then rerun (e.g. `nvm use 23`).",
+  );
+  process.exit(1);
+}
 
-process.exitCode = await run(process.argv.slice(2));
+import("../src/v2/cli/run.js");

package/docs/CAPABILITY-MATRIX.md

@@ -1,51 +1,20 @@
 # BuildBeat 能力矩阵 / Capability Matrix
 
-> 状态：BuildBeat `@haiyangbg/buildbeat@2.0.2`（dist-tag `latest`，2026-09-09；2.0.0 于 2026-09-05 首次把 v2 发到 `latest`）。本页按**产品层次**区分四个可用面：Skill-only 手工路径、v1 生命周期 CLI（`buildbeat`）、v2 运行时（`buildbeat-v2`）、Claude Code 插件；并保留 v1.21 分发合同的原始条目与 legacy npm v0 的边界。源码、registry artifact 与真实项目证据仍分别核验。
+> 状态：BuildBeat `@haiyangbg/buildbeat`（dist-tag `latest`；发布证据按版本归档在本目录的 `*-RELEASE-EVIDENCE-*.md`）。本页按**产品层次**区分三个可用面：Skill-only 手工路径、运行时 `buildbeat`、Claude Code 插件。源码、registry artifact 与真实项目证据仍分别核验。
 
-## 0. 四个可用面
+## 0. 三个可用面
 
 | 层 | 是什么 | 装在哪 | 权威文档 | 已验证到什么程度 |
 |---|---|---|---|---|
-| **Skill-only 手工路径** | 工件协议（Work 目录、intent/plan、决策台账、证据分级）由 AI 会话按 `SKILL.md` 手工维护 | Skill 本身（仓库 `SKILL.md` / 插件） | `SKILL.md` | 协议完整可用；**没有**自动闭环、隔离 worktree、digest 绑定批准校验、预算与恢复（`tests/skill-only.test.sh` 证明去掉 CLI 后 v1 文件总线仍可维护） |
-| **v1 生命周期 CLI `buildbeat`** | `doctor / init / adopt / upgrade / version`：v1 文件总线骨架的只读体检、受控写入与 schema 2 机械升级 | `@haiyangbg/buildbeat@latest`（2.0.0 起与 v2 同包；骨架版本仍 v1.21） | [`CLI.md`](CLI.md) | 1.21 发布证据 + 真实版本增量试点（§5）；2.0.0 未改其命令与边界 |
-| **v2 运行时 `buildbeat-v2`** | 隔离 worktree 内 Build→Verify→Review→Fix 自动闭环，停在人的合并决定；`accept / start / resume / status / inbox / overview / approve / reject / findings / doctor / preflight / gc / metrics / observe / watch` | 同上 | [`v2/guide/`](v2/guide/README.md)、RFC-0001/2/3、SPEC-0001 | 单元与 CLI 端到端测试（`tests/v2-*.test.js`，含脚本 worker 的模板首跑）；真实 AI worker 试点见 `docs/v2/M4-*`、迭代记录（`codex exec` 实证；其他工具"可通过命令接入"，未逐一验证） |
+| **Skill-only 手工路径** | 工件协议（Work 目录、intent/plan、决策台账、证据分级）由 AI 会话按 `SKILL.md` 手工维护 | Skill 本身（仓库 `SKILL.md` / 插件） | `SKILL.md` | 协议完整可用；**没有**自动闭环、隔离 worktree、digest 绑定批准校验、预算与恢复 |
+| **运行时 `buildbeat`** | 隔离 worktree 内 Build→Verify→Review→Fix 自动闭环，停在人的合并决定；`accept / start / resume / status / inbox / overview / approve / reject / findings / doctor / preflight / gc / metrics / observe / watch` | `npm install --global @haiyangbg/buildbeat@latest` | [`v2/guide/`](v2/guide/README.md)、RFC-0001/2/3、SPEC-0001 | 单元与 CLI 端到端测试（`tests/v2-*.test.js`，含脚本 worker 的模板首跑）与打包首跑（`tests/pack-firstrun.test.sh`）；真实 AI worker 试点见 `docs/v2/M4-*`、迭代记录（`codex exec` 实证；其他工具"可通过命令接入"，未逐一验证） |
 | **Claude Code 插件** | 把 Skill、模板、文档、lessons 装进 Claude Code；**不含**任何 CLI `bin/` | `claude plugin marketplace add HaiYangBG1/BuildBeat` + `claude plugin install buildbeat@buildbeat-plugins` | [`plugins/buildbeat/README.md`](../plugins/buildbeat/README.md) | `tests/plugin-marketplace.test.sh`（manifest 校验、隔离安装、缓存自包含）；装了插件不等于装了运行时，两者分别检查 |
 
-一句话：Skill 是入口（会话读它决定调什么），CLI 是引擎（`buildbeat-v2` 跑 Run、`buildbeat` 管 v1 骨架），项目文件是事实（Git 面 `delivery/` 与 `.buildbeat/`），插件只是把入口送进 Claude Code。
+一句话：Skill 是入口（会话读它决定调什么），`buildbeat` 是引擎（跑 Run、回读事实），项目文件是事实（Git 面 `delivery/` 与本机 `.buildbeat/`），插件只是把入口送进 Claude Code。
 
-## 1. 三组生命周期入口
+## 1. 运行时面：`buildbeat`
 
-WP4.2 所说的“CLI 三命令”按职责分成三组，不是把 `version` 或兼容别名算成新生命周期能力：
-
-| 组 | canonical 命令 | 机械责任 | 不承担 |
-|---|---|---|---|
-| 检查 | `buildbeat doctor` | 只读识别安装/布局/版本、关键文件、占位符、Hook 与本地依赖降级 | 不复制 `bus-check`，不判断业务正确、Gate 或线上健康 |
-| 建骨架 | `buildbeat init` / `buildbeat adopt` | 规划或受控写入默认/紧凑布局，填确定项，manifest 最后写 | 不猜项目语义，不安装 Hook，不初始化 Git，不跨人工 Gate |
-| 机械升级 | `buildbeat upgrade` | 对真实 schema 2 基线按 policy/hash 替换未改文件，冲突时 fail-closed | 不三方合并，不覆盖 project-owned，不猜 legacy 所有权，不自动删文件 |
-
-`buildbeat version` 是纯信息工具。`diff` 与 `uninstall` 仍只是返回 `command_not_available` 的保留名；`check/status/gate/adr/standards` 属于 Skill 与项目脚本，不进 CLI。`solobaton` 是 legacy 可执行兼容别名，不是第四组能力。
-
-## 2. v1 生命周期面：Skill-only / legacy v0 / `buildbeat`
-
-本节是 v1.21 分发合同的原始条目，2.0.0 未改变其中任何一行；v2 运行时的能力见 §2.5。
-
-| 能力 | Skill-only / 手工路径 | legacy `solobaton@1.16.3` | v1 生命周期 CLI（BuildBeat `@haiyangbg/buildbeat@1.21.0` 起，2.0.0 包内不变） | 权威与边界 |
-|---|---|---|---|---|
-| 理解新/存量项目，只问剩余问题 | 完整；读代码/配置后做 Bootstrap/Adopt | 不提供语义判断 | 不提供语义判断，只输出有界事实/问题 | Skill 与当前 AI 会话承担语义，CLI 不内置模型 |
-| 安装与能力体检 | 读文件并运行项目脚本 | `doctor` 只读可用 | `doctor` 只读可用 | `doctor` 是 CLI 体检；同步检查唯一权威仍是项目 `bus-check` |
-| 新项目 Bootstrap | 一屏确认后手动复制/渲染，完整可用 | `init --dry-run` 只规划；去掉 dry-run 拒绝写入 | `init --dry-run` 预览；无 blocker + 确认后受控 apply | 项目事实与剩余占位符必须回到 Skill 渲染 |
-| 存量项目 Adopt | 先摸底/划新旧边界/补最小验证，完整可用 | `adopt --dry-run` 只规划 | `adopt --dry-run` 预览；默认紧凑布局，确认后受控 apply | CLI 不决定绞杀者边界、危险区或 L3 充分性 |
-| 项目语义渲染 | 完整；填契约、看板、验证、部署与风险事实 | 不提供 | 只填项目名/日期/版本/布局等确定项 | CLI 的 `pendingPlaceholders` 是交接清单，不是完成声明 |
-| Gate、status、evidence、standards、ADR | 完整；由 Skill + 项目文件/脚本维护 | 不提供工作流命令 | 不提供工作流命令 | 人工 Gate 不能被 CLI/reviewer/绿测试代批 |
-| 同步/Gate/证据/多仓/STACK 检查 | 项目内 `bus-check --format=json --strict` 可独立运行 | 不复制脚本 finding | 不复制脚本 finding | `docs/CHECKS.md` + 项目脚本是唯一同步检查权威；覆盖不完必须显示 unverified |
-| schema 2 生命周期基线 | Skill-only 不需 manifest，也不手写伪造 | 只读识别历史 manifest | `init/adopt` 成功交易最后写入 | manifest 只是所有权/hash 基线，不是项目事实数据库 |
-| 拷出/legacy 项目升级 | 按 CHANGELOG 和 policy 手工语义合并 | `upgrade` 未开放 | 无真实 schema 2 基线必须 blocked | 不手写/复制/改名 manifest；见 `LEGACY-V1.16-MIGRATION.md` |
-| schema 2 机械升级 | Skill 处理机械冲突后的语义合并 | 未开放 | 已实现；同 major 按 hash，跨 major 需 `--major`，`--force` 不碰 project-owned | 真实版本增量试点与发布证据分别归档，不以模板测试代替 |
-| Git 初始化、Hook、commit/push/deploy/publish | 经明确授权后人/会话按项目边界执行 | 不执行 | 不执行 | 生命周期 CLI 不扩张任何外部权限；发布另走 `RELEASING.md` |
-
-## 2.5 v2 运行时面：`buildbeat-v2`（2.0.0）
-
-| 能力 | Skill-only / 手工路径 | v2 运行时 `buildbeat-v2` | 权威与边界 |
+| 能力 | Skill-only / 手工路径 | 运行时 `buildbeat` | 权威与边界 |
 |---|---|---|---|
 | 工件接受 | 会话记一行到 `decisions.jsonl` | `accept --artifact intent\|plan\|spec`：digest 绑定；改过即 `stale`，`doctor` / `overview` 报出 | 接受不是开工；policy 按 riskPreset 决定 build 前要求哪些工件已接受 |
 | 自动闭环 | 无 | `start --config <run-config> [--attempt new]`：隔离 worktree、builder→verify→review→fix 自动路由、停 `WAITING_HUMAN` | 一仓同时只有一个活动 Run；worker 是配置的任意命令，内核不内置模型 |
@@ -58,24 +27,13 @@ WP4.2 所说的“CLI 三命令”按职责分成三组，不是把 `version`
 | 生产体检 | 无 | `observe run / status / triage`：探针 → 分层 → Intent 草稿入队 | 草稿绝不自动执行 |
 | 通知 | 无 | `.buildbeat/notify.yaml`（钉钉 / webhook，URL 只能来自环境变量） | 通知不是审批通道 |
 | 环境合同 | 无 | `requires:`（command / probe）启动前 fail-closed；worker env 白名单，`env:` 点名注入，`inheritEnv` 显式打开 | 见 [安全边界](v2/guide/09-security-boundaries.md)：内核检测与移除的边界 vs 宿主沙箱 |
-| 首跑验证 | — | `tests/v2-templates-firstrun.test.js`：脚本 worker 从模板走到合并决定（含 verify 失败→fixer） | 证明路径与合同连得上，不证明真实模型能完成任务 |
-
-## 3. 双向互操作结论
-
-| 转换 | 结论 | 已验证 | 不可外推 |
-|---|---|---|---|
-| Skill-only → CLI `doctor` | 可保守识别；无 manifest 显式 `manifest.missing`，不猜所有权 | `tests/skill-only.test.sh` 自动回归 | 不因 doctor 可读就获得机械 upgrade |
-| CLI `init/adopt` → Skill-only | 项目仍是普通 Git 文件/脚本；屏蔽 Node/CLI 后可继续维护并 strict 检查 | 自动互操作回归 + WP2.8 本地真实目录试点 | 不证明业务测试、Gate 或线上状态 |
-| CLI `upgrade` → Skill-only | 升级后仍使用同一文件协议；冲突交给 Skill 语义合并 | disposable 升级沙箱 + BuildBeat 1.20 真实版本增量试点 | 不证明未观测的业务、线上或生产状态 |
-| legacy v1.16 → schema 2 | 默认继续手工维护；经批准才在专用分支重建基线 | 指南和静态契约已闭合 | 没有执行真实 legacy 迁移 |
+| 首跑验证 | — | `tests/v2-templates-firstrun.test.js`：脚本 worker 从模板走到合并决定（含 verify 失败→fixer）；`tests/pack-firstrun.test.sh` 从安装后的包再走一遍 | 证明路径与合同连得上，不证明真实模型能完成任务 |
 
-## 4. Distribution status / 分发状态
+## 2. Distribution status / 分发状态
 
-- **Skill-only:** first-class and complete for protocol semantics; it does not need a lifecycle manifest or a runtime CLI.
-- **Legacy npm v0:** `solobaton@latest` is frozen on `doctor`, `init/adopt --dry-run`, and version inspection, then deprecated toward the scoped package. Project writes and `upgrade` remain unavailable there.
-- **BuildBeat 2.0.x (current `latest` = 2.0.2):** since `@haiyangbg/buildbeat@2.0.0` (evidence: [`V2.0.0-RELEASE-EVIDENCE-2026-09-05.md`](V2.0.0-RELEASE-EVIDENCE-2026-09-05.md)) one package ships the unchanged v1 lifecycle CLI `buildbeat` and the v2 runtime `buildbeat-v2`; 2.0.1 fixed run-config `env:` passthrough and added `templates/v2/` (evidence: [`V2.0.1-RELEASE-EVIDENCE-2026-09-06.md`](V2.0.1-RELEASE-EVIDENCE-2026-09-06.md)); 2.0.2 only trims historical documents from the tarball. The managed v1 scaffold stays at `v1.21`.
-- **BuildBeat 1.21 (previous stable, 2026-08-25 → 2026-09-05):** `@haiyangbg/buildbeat@1.21.0` was the independently verified canonical scoped distribution before 2.0.0. It keeps the bounded `init/adopt` and schema-2-only mechanical `upgrade` surface established in 1.20, and adds the standard domain-response contract to Skill/scaffold handoffs. Registry availability, provenance, signatures, and exact artifact identity are archived in [`V1.21-RELEASE-EVIDENCE-2026-08-25.md`](V1.21-RELEASE-EVIDENCE-2026-08-25.md) and remain live-recheck requirements for future releases.
+- **Skill-only:** first-class and complete for protocol semantics; it does not need the runtime.
+- **Runtime:** `@haiyangbg/buildbeat@latest` ships one executable, `buildbeat`, with zero third-party runtime dependencies. Each published version is independently read back (registry identity, provenance, signatures, isolated install, packaged first run) before the tag moves; the dated evidence files in this directory are the record, [`RELEASING.md`](RELEASING.md) is the procedure.
 - **Claude Code plugin:** the local marketplace candidate distributes the canonical Skill/templates/docs, not the top-level npm CLI `bin/`; installation evidence does not authorize project writes or npm publication.
-- **Project runtime:** after scaffolding, the Git files and project-local scripts remain independently usable. BuildBeat has no account service, telemetry, remote project database, or hosted agents; the v2 runtime is a local process that orchestrates the commands you configure and never carries a model of its own.
+- **Project runtime:** the Git files remain independently usable without the runtime. BuildBeat has no account service, telemetry, remote project database, or hosted agents; the runtime is a local process that orchestrates the commands you configure and never carries a model of its own.
 
-The real version-increment and multi-repository evidence remains archived in [`PHASE4-V1.20-PILOT-2026-08-25.md`](PHASE4-V1.20-PILOT-2026-08-25.md); release readiness is tracked in [`PHASE4-STABILITY-AUDIT-2026-08-25.md`](PHASE4-STABILITY-AUDIT-2026-08-25.md), the first scoped publication in [`WP4.3-RELEASE-EVIDENCE-2026-08-25.md`](WP4.3-RELEASE-EVIDENCE-2026-08-25.md), and the current v1.21 distribution in [`V1.21-RELEASE-EVIDENCE-2026-08-25.md`](V1.21-RELEASE-EVIDENCE-2026-08-25.md). v1 lifecycle command details remain authoritative in [`CLI.md`](CLI.md); the v2 command surface is documented in [`v2/guide/`](v2/guide/README.md) with RFC-0003 as the workflow authority; legacy migration uses [`LEGACY-V1.16-MIGRATION.md`](LEGACY-V1.16-MIGRATION.md); moving a v1 file-bus project onto v2 uses [`v2/guide/08-migration-v1.md`](v2/guide/08-migration-v1.md).
+The command surface is documented in [`v2/guide/`](v2/guide/README.md) with RFC-0003 as the workflow authority. Removed generations (the file bus, its lifecycle CLI, and the pre-3.0 executable names) live only in the dated history under this directory and in [`CHANGELOG-v1.md`](../CHANGELOG-v1.md).

package/docs/README.md

@@ -1,26 +1,24 @@
 # docs/ 总入口
 
-> 这一页只回答"我该读哪份"。文件按**现行**与**历史**分开：现行文档描述今天的包（`@haiyangbg/buildbeat@latest`，v2 系列）并受 `tests/check_docs.py` 的时效检查约束；历史文档保存当时的事实与数字，只加状态说明、不改原文。
+> 这一页只回答"我该读哪份"。文件按**现行**与**历史**分开：现行文档描述今天的包（`@haiyangbg/buildbeat@latest`）并受 `tests/check_docs.py` 的时效检查约束；历史文档保存当时的事实与数字，只加状态说明、不改原文。
 
 ## 现行：用户读
 
 | 你要做什么 | 读 |
 |---|---|
-| 第一次用 v2，在 AI 会话里 | [`v2/guide/00-how-to-talk.md`](v2/guide/00-how-to-talk.md) → 会话读 [`SKILL.md`](../SKILL.md) §0.5 |
-| 第一次用 v2，自己敲命令核对 | [`v2/guide/01-quickstart.md`](v2/guide/01-quickstart.md) |
-| 十件套指南（日常 / 配置 / 迁移） | [`v2/guide/README.md`](v2/guide/README.md) |
+| 第一次用，在 AI 会话里 | [`v2/guide/00-how-to-talk.md`](v2/guide/00-how-to-talk.md) → 会话读 [`SKILL.md`](../SKILL.md) §0.5 |
+| 第一次用，自己敲命令核对 | [`v2/guide/01-quickstart.md`](v2/guide/01-quickstart.md) · [English](v2/guide/01-quickstart.en.md) |
+| 指南索引（日常 / 配置） | [`v2/guide/README.md`](v2/guide/README.md) |
 | 关闭旧会话后继续，或由其他成员/工具接手 | [`跨会话接续`](v2/guide/11-session-handoff.md) · [English](v2/guide/11-session-handoff.en.md) |
-| 四个可用面各能做什么（Skill-only / v1 CLI / v2 运行时 / 插件） | [`CAPABILITY-MATRIX.md`](CAPABILITY-MATRIX.md) |
-| v1 生命周期 CLI（`buildbeat doctor/init/adopt/upgrade`） | [`CLI.md`](CLI.md)、[`CHECKS.md`](CHECKS.md) |
-| 从 v1 文件总线迁到 v2 | [`v2/guide/08-migration-v1.md`](v2/guide/08-migration-v1.md) |
-| v1.16 拷出项目重建 schema 2 基线 | [`LEGACY-V1.16-MIGRATION.md`](LEGACY-V1.16-MIGRATION.md) |
+| 三个可用面各能做什么（Skill-only / 运行时 / 插件） | [`CAPABILITY-MATRIX.md`](CAPABILITY-MATRIX.md) |
 | 项目装载入口与信封模板 | [`../templates/v2/`](../templates/v2/AGENTS.md) |
+| 填好之后长什么样：一个 Work 跑到合并决定的快照 | [`../example/`](../example/README.md) |
 
 ## 现行：规范与维护
 
 | 内容 | 读 |
 |---|---|
-| v2 产品定位 / 域模型 / workflow 与 policy / 事件 schema | [`v2/RFC-0001`](v2/RFC-0001-product-definition.md) / [`RFC-0002`](v2/RFC-0002-domain-model.md) / [`RFC-0003`](v2/RFC-0003-workflow-policy.md) / [`SPEC-0001`](v2/SPEC-0001-events-v1.md)（`FINAL`；带日期的生效修订写在正文顶部） |
+| 产品定位 / 域模型 / workflow 与 policy / 事件 schema | [`v2/RFC-0001`](v2/RFC-0001-product-definition.md) / [`RFC-0002`](v2/RFC-0002-domain-model.md) / [`RFC-0003`](v2/RFC-0003-workflow-policy.md) / [`SPEC-0001`](v2/SPEC-0001-events-v1.md)（`FINAL`；带日期的生效修订写在正文顶部） |
 | 发布手册、通道、发布后同步清单 | [`RELEASING.md`](RELEASING.md) |
 | 分支策略、测试分层、文档权威分层 | [`../CONTRIBUTING.md`](../CONTRIBUTING.md)、[`../tests/README.md`](../tests/README.md) |
 | 每条机制背后的真实事故 | [`../lessons.md`](../lessons.md) |
@@ -29,11 +27,12 @@
 
 | 类别 | 文件 |
 |---|---|
-| 发布证据 | `V2.0.1-RELEASE-EVIDENCE-2026-09-06.md`（当前 `latest`）、`V2.0.0-RELEASE-EVIDENCE-2026-09-05.md`、`V2.0.0-BETA.1～5-RELEASE-EVIDENCE-*.md`、`V1.21-RELEASE-EVIDENCE-2026-08-25.md`、`WP4.3-RELEASE-EVIDENCE-2026-08-25.md` |
-| v2 规划与决策 | [`V2-PLAN.md`](V2-PLAN.md)（执行基线，已交付）、[`V2-PROPOSAL.md`](V2-PROPOSAL.md)、[`V2-DECISIONS.md`](V2-DECISIONS.md)、[`V2-D2-DECISION-CARD.md`](V2-D2-DECISION-CARD.md)、[《BuildBeat v2：AI 原生软件交付控制平面》](BuildBeat%20v2%EF%BC%9AAI%20%E5%8E%9F%E7%94%9F%E8%BD%AF%E4%BB%B6%E4%BA%A4%E4%BB%98%E6%8E%A7%E5%88%B6%E5%B9%B3%E9%9D%A2.md) |
-| v2 迭代与里程碑记录 | `V2-ITERATION-01～08.md`、[`v2/`](v2/) 下的 M1/M2/M4 验收与试点记录 |
-| v1 路线与阶段试点 | [`ROADMAP.md`](ROADMAP.md)、[`EXECUTION-PLAN.md`](EXECUTION-PLAN.md)、`PHASE1/2/4-*.md`、[`CLI-STRATEGY-2026-08.md`](CLI-STRATEGY-2026-08.md)、[`CLI-PILOT-2026-08-23.md`](CLI-PILOT-2026-08-23.md)、[`PHASE4-STABILITY-AUDIT-2026-08-25.md`](PHASE4-STABILITY-AUDIT-2026-08-25.md) |
+| 发布证据 | `V3.0.0-RELEASE-EVIDENCE-2026-09-09.md`（当前 `latest`）、`V2.0.2-RELEASE-EVIDENCE-2026-09-09.md`、`V2.0.1-RELEASE-EVIDENCE-2026-09-06.md`、`V2.0.0-RELEASE-EVIDENCE-2026-09-05.md`、`V2.0.0-BETA.1～5-RELEASE-EVIDENCE-*.md`、`V1.21-RELEASE-EVIDENCE-2026-08-25.md`、`WP4.3-RELEASE-EVIDENCE-2026-08-25.md` |
+| 规划与决策（2026-08） | [`V2-PLAN.md`](V2-PLAN.md)（执行基线，已交付）、[`V2-PROPOSAL.md`](V2-PROPOSAL.md)、[`V2-DECISIONS.md`](V2-DECISIONS.md)、[`V2-D2-DECISION-CARD.md`](V2-D2-DECISION-CARD.md)、[《BuildBeat v2：AI 原生软件交付控制平面》](BuildBeat%20v2%EF%BC%9AAI%20%E5%8E%9F%E7%94%9F%E8%BD%AF%E4%BB%B6%E4%BA%A4%E4%BB%98%E6%8E%A7%E5%88%B6%E5%B9%B3%E9%9D%A2.md) |
+| 迭代与里程碑记录 | `V2-ITERATION-01～08.md`、[`v2/`](v2/) 下的 M1/M2/M4 验收与试点记录 |
+| 早期版本史 | [`../CHANGELOG-v1.md`](../CHANGELOG-v1.md)（2026-06 ～ 2026-08 的条目原文；当前条目在根 [`CHANGELOG.md`](../CHANGELOG.md)） |
+| 早期路线与阶段试点（2026-08，已移除的文件总线时代） | [`ROADMAP.md`](ROADMAP.md)、[`EXECUTION-PLAN.md`](EXECUTION-PLAN.md)、`PHASE1/2/4-*.md`、[`CLI-STRATEGY-2026-08.md`](CLI-STRATEGY-2026-08.md)、[`CLI-PILOT-2026-08-23.md`](CLI-PILOT-2026-08-23.md)、[`PHASE4-STABILITY-AUDIT-2026-08-25.md`](PHASE4-STABILITY-AUDIT-2026-08-25.md) |
 
-历史文件里的版本号、通道与测试数字是它们日期当天的事实，出现"`latest` 留 v1"之类的旧策略是正常的；判断现状只看现行文档与 registry 回读（`npm view @haiyangbg/buildbeat dist-tags`）。
+历史文件里的版本号、通道与测试数字是它们日期当天的事实，出现已被移除的旧机制和旧通道策略是正常的；判断现状只看现行文档与 registry 回读（`npm view @haiyangbg/buildbeat dist-tags`）。
 
 历史文件只保存在 GitHub 仓库里，不随 npm 包分发（`package.json` 的 `files` 显式排除）；从安装目录点开现行文档里指向历史文件的链接会落空，到 [`HaiYangBG1/BuildBeat`](https://github.com/HaiYangBG1/BuildBeat/tree/main/docs) 看即可。现行文档全部随包分发，`tests/pack-firstrun.test.sh` 守着这两条边界。

package/docs/RELEASING.md

@@ -1,8 +1,8 @@
 # BuildBeat CLI package release runbook
 
-This runbook governs BuildBeat's public npm distribution. The canonical package is `@haiyangbg/buildbeat` in `HaiYangBG1/BuildBeat`; the canonical executable is `buildbeat`, while `solobaton` remains an executable alias. The old `solobaton` npm package is a frozen legacy distribution ID and must not receive the scoped write/upgrade command surface.
+This runbook governs BuildBeat's public npm distribution. The canonical package is `@haiyangbg/buildbeat` in `HaiYangBG1/BuildBeat`; the only executable is `buildbeat`. No other package name or executable alias receives publications.
 
-Release evidence at source package version `@haiyangbg/buildbeat@2.0.2`; latest independently verified BuildBeat npm distribution `@haiyangbg/buildbeat@2.0.1` (dist-tag `latest`; `next` stays `2.0.0-beta.5`), anchored by annotated tag `v2.0.1` at commit `4b2362f`, workflow run [34032278315](https://github.com/HaiYangBG1/BuildBeat/actions/runs/34032278315), and archived in [`V2.0.1-RELEASE-EVIDENCE-2026-09-06.md`](V2.0.1-RELEASE-EVIDENCE-2026-09-06.md). The 2.0.0 chain (`latest` from 2026-09-05 until 2.0.1 took over on 2026-09-06) stays archived in [`V2.0.0-RELEASE-EVIDENCE-2026-09-05.md`](V2.0.0-RELEASE-EVIDENCE-2026-09-05.md). The beta.5 chain stays archived in [`V2.0.0-BETA.5-RELEASE-EVIDENCE-2026-09-05.md`](V2.0.0-BETA.5-RELEASE-EVIDENCE-2026-09-05.md). The beta.4 chain stays archived in [`V2.0.0-BETA.4-RELEASE-EVIDENCE-2026-09-03.md`](V2.0.0-BETA.4-RELEASE-EVIDENCE-2026-09-03.md); the beta.3 chain in [`V2.0.0-BETA.3-RELEASE-EVIDENCE-2026-09-01.md`](V2.0.0-BETA.3-RELEASE-EVIDENCE-2026-09-01.md). The beta.2 chain stays archived in [`V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md`](V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md); the beta.1 chain stays archived in [`V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md`](V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md). The previous stable distribution, `@haiyangbg/buildbeat@1.21.0` (`latest` from 2026-08-25 until 2.0.0 took over on 2026-09-05), stays anchored by annotated tag `v1.21.0` at commit `ce69a05`, workflow run [32864438692](https://github.com/HaiYangBG1/BuildBeat/actions/runs/32864438692), and the matching [GitHub Release](https://github.com/HaiYangBG1/BuildBeat/releases/tag/v1.21.0). Its exact registry identity, provenance, signatures, isolated-install readback, Environment approval, and immutable-artifact boundary are archived in [`V1.21-RELEASE-EVIDENCE-2026-08-25.md`](V1.21-RELEASE-EVIDENCE-2026-08-25.md). First-scoped-release bootstrap behavior and legacy deprecation remain archived in [`WP4.3-RELEASE-EVIDENCE-2026-08-25.md`](WP4.3-RELEASE-EVIDENCE-2026-08-25.md). The legacy distribution remains `solobaton@1.16.3`; all three published legacy versions are retained and deprecated toward the scoped package.
+Release evidence at source package version `@haiyangbg/buildbeat@3.0.1`; latest independently verified BuildBeat npm distribution `@haiyangbg/buildbeat@3.0.0` (dist-tag `latest`; `next` stays `2.0.0-beta.5`), anchored by annotated tag `v3.0.0` at commit `0289415`, workflow run [34362068004](https://github.com/HaiYangBG1/BuildBeat/actions/runs/34362068004), and archived in [`V3.0.0-RELEASE-EVIDENCE-2026-09-09.md`](V3.0.0-RELEASE-EVIDENCE-2026-09-09.md). The 2.0.2 chain (`latest` from 2026-09-09 until 3.0.0 took over the same day; the last version carrying the removed generation) stays archived in [`V2.0.2-RELEASE-EVIDENCE-2026-09-09.md`](V2.0.2-RELEASE-EVIDENCE-2026-09-09.md). The 2.0.1 chain (`latest` from 2026-09-06 until 2.0.2 took over on 2026-09-09) stays archived in [`V2.0.1-RELEASE-EVIDENCE-2026-09-06.md`](V2.0.1-RELEASE-EVIDENCE-2026-09-06.md). The 2.0.0 chain (`latest` from 2026-09-05 until 2.0.1 took over on 2026-09-06) stays archived in [`V2.0.0-RELEASE-EVIDENCE-2026-09-05.md`](V2.0.0-RELEASE-EVIDENCE-2026-09-05.md). The beta.5 chain stays archived in [`V2.0.0-BETA.5-RELEASE-EVIDENCE-2026-09-05.md`](V2.0.0-BETA.5-RELEASE-EVIDENCE-2026-09-05.md). The beta.4 chain stays archived in [`V2.0.0-BETA.4-RELEASE-EVIDENCE-2026-09-03.md`](V2.0.0-BETA.4-RELEASE-EVIDENCE-2026-09-03.md); the beta.3 chain in [`V2.0.0-BETA.3-RELEASE-EVIDENCE-2026-09-01.md`](V2.0.0-BETA.3-RELEASE-EVIDENCE-2026-09-01.md). The beta.2 chain stays archived in [`V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md`](V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md); the beta.1 chain stays archived in [`V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md`](V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md). Earlier distributions and the retired legacy package name are archived in the dated evidence files under `docs/`.
 
 ## Channels and branches
 
@@ -16,7 +16,7 @@ Release evidence at source package version `@haiyangbg/buildbeat@2.0.2`; latest
 ## Release invariants
 
 1. One npm version maps to one immutable annotated Git tag and one exact source commit. Never move a published version's tag.
-2. `CLI_VERSION` comes from `package.json`; the scaffold version is the pinned `SCAFFOLD_VERSION` literal in `src/constants.js` and tracks the frozen v1 scaffold content bundle, not the CLI. Since the v2 package line it stays at `v1.21` until the scaffold surface itself changes — a package release never invents a scaffold upgrade.
+2. The runtime version comes from `package.json` (`buildbeat --version`). Project templates under `templates/v2/` are copied into projects by hand; a package release never rewrites a project's files.
 3. Publish only from a clean worktree whose `HEAD`, tag target, tested commit, and packed artifact all match.
 4. `publishConfig.registry` stays pinned to `https://registry.npmjs.org/`; a developer's mirror configuration must not redirect a public release.
 5. A successful `npm publish` response is not enough. Registry metadata, tarball contents, an isolated install, the executable version, and a read-only command must be checked independently.
@@ -24,7 +24,7 @@ Release evidence at source package version `@haiyangbg/buildbeat@2.0.2`; latest
 7. After a version is published, later `main` documentation changes carrying that same `package.json` version do not redefine its artifact and are not releasable candidates. The next publication requires a new package version, Changelog heading, and annotated tag.
 8. Canonical examples use `@haiyangbg/buildbeat@latest`, not a hard-coded release number. Reproducible consumers first resolve `npm view @haiyangbg/buildbeat@latest version`, record that exact version, and substitute it for `@latest`; exact release evidence remains in this runbook and the matching GitHub Release. One-off commands use `npx --yes --package=@haiyangbg/buildbeat@latest buildbeat ...`.
 9. The active repository ruleset `Protect release tags` must match `refs/tags/v*`, forbid tag updates and deletions, and grant no bypass actor. It deliberately does not forbid creation, so a reviewed new release tag can still be created once.
-10. The write-enabled first-screen command `npx --yes --package=@haiyangbg/buildbeat@latest buildbeat init my-project` is active because every scoped artifact that has held `latest` (1.21.0 on 2026-08-25, 2.0.0 on 2026-09-05) passed registry/provenance/signature/isolated-install/README readback before the tag moved. The old-name WP2.7 pilots remain historical compatibility evidence and do not redefine the scoped artifact.
+10. The README install line `npm install --global @haiyangbg/buildbeat@latest` is safe to advertise because every artifact that has held `latest` passed registry/provenance/signature/isolated-install/README readback before the tag moved.
 
 ## Candidate checks
 
@@ -85,11 +85,10 @@ release_probe="$(mktemp -d)"
 npm install --prefix "$release_probe" "@haiyangbg/buildbeat@$release_version" \
   --registry=https://registry.npmjs.org/ --ignore-scripts --no-audit --no-fund
 node "$release_probe/node_modules/@haiyangbg/buildbeat/bin/buildbeat.js" --version
-node "$release_probe/node_modules/@haiyangbg/buildbeat/bin/solobaton.js" --version
-node "$release_probe/node_modules/@haiyangbg/buildbeat/bin/buildbeat.js" doctor . --json
+node "$release_probe/node_modules/@haiyangbg/buildbeat/bin/buildbeat.js" >/dev/null
 ```
 
-The expected version is exact. `doctor` may correctly return exit 1 for a directory without an installed scaffold; the acceptance condition is valid bounded JSON and zero project writes, not a forced green diagnosis.
+The expected version is exact. The bare invocation prints usage and exits 0 without touching the current directory; the acceptance condition is zero project writes, not a forced green diagnosis.
 
 Only after this readback should the matching GitHub Release be published and documentation treat the npm version as independently verified.
 
@@ -119,11 +118,13 @@ gh workflow run publish.yml --ref main -f tag=vX.Y.Z
 gh run watch --exit-status
 ```
 
+npm now processes a publish asynchronously (`npm publish` prints "being processed and may take a few minutes"); the verify job waits up to ten minutes for the exact version, the dist-tag and the provenance to read back. If it still fails **only** on readback, wait for `npm view` to show the version and re-run the failed job (`gh run rerun <run-id> --failed`); never publish again. Real incident: 3.0.0 became readable about six minutes after `npm publish` returned.
+
 The workflow waits for exact registry-version readback, requires `dist.attestations` to expose an npm attestation URL with the SLSA v1 provenance predicate, installs the public package into a clean temporary prefix, checks its executable version, and runs `npm audit signatures`. The release operator must still repeat the isolated-install and read-only `doctor` check independently before publishing the matching GitHub Release. Never use `workflow_dispatch` to bypass the repository's human merge or tag Gate.
 
 Trusted Publishing removes the long-lived write token and automatically emits provenance for supported public GitHub repositories. Configure the exact owner, repository, workflow filename, allowed `npm publish` action, and the exact `npm-publish` environment on npmjs.com. A GitHub Environment without the matching npm-side environment binding is not sufficient evidence. See npm's [Trusted Publishing](https://docs.npmjs.com/trusted-publishers/) and [provenance](https://docs.npmjs.com/generating-provenance-statements/) documentation.
 
-The bootstrap `0.0.0` package is not retroactively provenance-backed and must remain on the non-default `bootstrap` tag. The existence of the workflow and trusted-publisher binding is configuration evidence only; npm validates the binding during the real publish. After the first OIDC release succeeds, set `npm access set mfa=publish @haiyangbg/buildbeat` and independently read back npm's most restrictive Publishing access option, currently labeled `Require two-factor authentication and disallow bypass 2fa tokens (recommended)`, while preserving the Trusted Publisher. Then deprecate every legacy `solobaton` version with a concise migration pointer to `@haiyangbg/buildbeat`; do not unpublish it, because existing read-only installations and redirects remain useful compatibility paths. Because package access, trust, tags, and deprecation are mutable registry state, future release operators must recheck them live.
+The bootstrap `0.0.0` package is not retroactively provenance-backed and must remain on the non-default `bootstrap` tag. The existence of the workflow and trusted-publisher binding is configuration evidence only; npm validates the binding during the real publish. After the first OIDC release succeeds, set `npm access set mfa=publish @haiyangbg/buildbeat` and independently read back npm's most restrictive Publishing access option, currently labeled `Require two-factor authentication and disallow bypass 2fa tokens (recommended)`, while preserving the Trusted Publisher. Because package access, trust, tags, and deprecation are mutable registry state, future release operators must recheck them live.
 
 ## Post-release synchronization checklist
 
@@ -132,7 +133,7 @@ Publishing the artifact is one surface. These are the others; each has drifted a
 - [ ] `CHANGELOG.md`: `## Unreleased` renamed to the version with date and the publication paragraph (run id, dist-tag, readback).
 - [ ] `docs/<VERSION>-RELEASE-EVIDENCE-<date>.md` archived; the current-state paragraph at the top of this runbook names the new version and the previous stable moves to a dated past tense — never two "current" versions in one runbook.
 - [ ] `README.md` / `README.en.md`: version and channel claims (`@latest` is what it says it is), no `@next` install line unless a pre-release is being announced as such.
-- [ ] `SKILL.md` §0.5 install line and `docs/v2/guide/01-quickstart.md` / `08-migration-v1.md` install lines: stable channel.
+- [ ] `SKILL.md` §0.5 install line and `docs/v2/guide/01-quickstart.md` install line: stable channel.
 - [ ] `docs/CLI.md` status line, `docs/CAPABILITY-MATRIX.md` status line and distribution section.
 - [ ] Active RFC / plan documents whose channel policy the release changed get a dated "生效修订" note; history keeps its original text.
 - [ ] GitHub repository About (description, topics, homepage) still describes the product that was just released — cannot be checked from the repository, do it by hand.

package/docs/v2/RFC-0001-product-definition.md

@@ -50,6 +50,8 @@ v1 的"Skill-only 完整等价"拆成两个承诺（[`V2-PLAN.md`](../V2-PLAN.md
 
 ## 6. v1 的地位
 
+> **生效修订（2026-09-09）**：3.0.0 起 v1 文件总线、生命周期命令（`buildbeat doctor/init/adopt/upgrade`）、`solobaton` 与 `buildbeat-v2` 可执行文件全部移除，`buildbeat` 即运行时；`v1-maintenance` 维护线结束，最后一个带 v1 的版本是 2.0.2。本节原文保留为决策记录。
+>
 > **生效修订（2026-09-05）**：下段"`latest` 留 v1"是 beta 期策略，已按计划结束——`@haiyangbg/buildbeat@2.0.0` 于 2026-09-05 发布到 `latest`（[`CHANGELOG.md`](../../CHANGELOG.md)、[发布证据](../V2.0.0-RELEASE-EVIDENCE-2026-09-05.md)）。此后 `latest` = v2 系列，`next` 仅用于后续预发布；v1 生命周期命令随同一个包分发，v1 骨架版本仍是 v1.21。原文保留为决策记录。
 
 v1 进入 `v1-maintenance` 维护线，只修安全与严重缺陷；npm `latest` 留 v1，`next` 发 v2 预发布；Beta 前 `latest` 不指向 v2。v1 迁移采用半天手工 runbook（装机量 N=1），`migrate-v1` importer 已裁掉（收尾修正三）。旧概念的保留/转换/删除逐项见 [`RFC-0002`](RFC-0002-domain-model.md) §8。

package/docs/v2/RFC-0003-workflow-policy.md

@@ -159,6 +159,8 @@ review 修复轮次：2
 | `controlled` | Intent、Plan、Merge、Release |
 | `legacy-four-gates` | v1 四 Gate 完整形态（迁移用） |
 
+> **生效修订（2026-09-09）**：`legacy-four-gates` 预设随 v1 于 3.0.0 移除；上行保留为原文。
+
 ## 8. observe 预设与 bands schema（随本 RFC 冻结，实现 M5）
 
 裁决 #6：**接口现在冻结，实现推后**。冻结内容为以下 schema 形状与语义；M5 前不实现，但 M1 起任何内核设计不得与之冲突（尤其：Evidence Provider 产出的记录必须能进入同一 Evidence Contract 与事件台账）。

package/docs/v2/guide/00-how-to-talk.md

@@ -1,6 +1,6 @@
 # 怎么和装了 BuildBeat 的会话说话（按项目阶段）
 
-> 这是给**用户**看的一页。你在任意一个 AI 编程会话里工作（哪家工具都可以，一个会话就够），会话装载了 BuildBeat Skill；你说人话，它去调 `buildbeat-v2`、读输出、按「已做 → 未做 → 下一步」回你。**你不需要记任何命令**。下面的例句就是平时的说法，照抄即可；同一格里的几句话意思相同，挑顺口的。
+> 这是给**用户**看的一页。你在任意一个 AI 编程会话里工作（哪家工具都可以，一个会话就够），会话装载了 BuildBeat Skill；你说人话，它去调 `buildbeat`、读输出、按「已做 → 未做 → 下一步」回你。**你不需要记任何命令**。下面的例句就是平时的说法，照抄即可；同一格里的几句话意思相同，挑顺口的。
 > 会话侧的对应规则在 `SKILL.md` §0.5；项目专属的路由与红线在各项目根的 `AGENTS.md`。
 
 准备换会话时说「把关键上下文落盘,我要关闭旧会话」;新会话说「读取项目入口,核对进度与待批,继续这个工作」。交给同事时说「同步项目记录与候选,让接手成员核对当前范围和原 Run 所在环境」。详细步骤与活动 Run 的保留范围见 [跨会话与团队接续](11-session-handoff.md)。
@@ -10,7 +10,7 @@
 | 阶段 | 你想干什么 | 你就这么说 | 会话背后做什么 | 你会得到什么 / 注意 |
 |---|---|---|---|---|
 | **0. 未开始** | 判断值不值得上 BuildBeat | 「这个项目适合用 BuildBeat 吗」 | 看仓库规模、周期、仓/部署单元/会话数 | 一句判断：多期迭代 / 多仓 / 多会话才值得；一周收尾的小活直接干 |
-| | 新项目搭骨架 | 「帮我用 BuildBeat 搭一下这个项目」「初始化协作骨架」 | 自查代码 → 少量提问（栈、仓、部署单元、有没有 UI）→ 一屏确认 → 生成 `AGENTS.md`（v2 模板）、`delivery/`、`.buildbeat/observe.yaml`、`.buildbeat/notify.yaml`、`scripts/bus-check.sh`、pre-commit | 一屏确认单，你说「可以」它才写；生成后给文件清单 |
+| | 新项目搭骨架 | 「帮我用 BuildBeat 搭一下这个项目」「初始化协作骨架」 | 自查代码 → 少量提问（栈、仓、部署单元、有没有 UI）→ 一屏确认 → 生成 `AGENTS.md`、`delivery/`（含信封）、`.buildbeat/observe.yaml`、`.buildbeat/notify.yaml`、gitleaks pre-commit | 一屏确认单，你说「可以」它才写；生成后给文件清单 |
 | | 接管老项目 | 「给这个老项目套上 BuildBeat」「接管这个仓」 | 摸底（测试、契约、部署事实）→ 划绞杀边界（新地盘 / 老地盘 / 只读）→ 第 0 期补最小验证 | 摸底报告 + 边界草案，你拍板边界；历史不回改 |
 | | 装上通知 | 「Run 停下来时通知我」 | 写 `.buildbeat/notify.yaml`（钉钉 / webhook） | 它告诉你要建什么机器人、`export` 哪个环境变量；URL 永远不进 Git |
 | **1. 立项 · 定方案** | 立一件事 | 「开个 Work：〔一句话目标〕」「把当前目标收成一个 Work」 | 写 `delivery/work/<ID>/intent.md`（为什么做、做到什么算完）+ `plan.md`（怎么做、分几步）+ `run-config.yaml` | 摘要 + 「看完说接受」；你说「接受」才 digest 绑定生效 |
@@ -31,7 +31,7 @@
 | | 停下来 | 「这次再不成功就停」「先停下来」 | 封顶轮数；`stop --reason` 记账，候选与证据保留 | 已做 / 未做 / 下一步，带 hash；之后由你决定改方案、手工修还是关掉 Work |
 | **4. 验收 · 合并** | 验收 | 「验收」「验 RUN-X 候选」 | 测试视角对精确 candidate 独立核验，报告落 Work 目录 | 通过 / 不通过 + 证据；写者的话不算证据 |
 | | 合并 | 「merge 吧」「授权 push」 | 人类动作由会话代执行（在 `AGENTS.md` 红线内），回读远端 | 报合并后 hash；`overview` 显示 MERGED |
-| **5. 上线** | 上线 | 「上线」「准备 Gate4」 | `release-readback` 预设 + `riskPreset: release`：先回读 → 停下来 | 「回读全绿，现在轮到你做〔动作〕；做完说一声」 |
+| **5. 上线** | 上线 | 「上线」「准备上线」 | `release-readback` 预设 + `riskPreset: release`：先回读 → 停下来 | 「回读全绿，现在轮到你做〔动作〕；做完说一声」 |
 | | 我做完了 | 「做完了」「做到一半了，你核一下」 | 批准 apply-readback → 回读 + 观察 → 停关窗 | 差什么逐条说；任一步失败即停 |
 | | 拍上线卡 | 「批准上线」「先不上线」 | 按决策卡执行 / 不执行 | 生产动作永远是你的；它只回读和记账 |
 | | 生产报警 | 「生产有报警」「体检一下」 | `observe run` → 草稿入队 | 草稿一句 + 「fix_now / schedule / dismiss 你选」 |

package/docs/v2/guide/01-quickstart.en.md

@@ -0,0 +1,163 @@
+# Quickstart: your first Run
+
+[简体中文](01-quickstart.md) | **English**
+
+Goal: in a real Git repository, let the Runner drive Build → Verify → Review to completion and **stop at the merge decision**, which you make with the evidence in front of you. The order is fixed: install → prepare the Work → write the run config → accept the plan → doctor → start → read the evidence and decide. Every step says what success looks like. How long it takes depends on your workers and the task; this page promises no numbers.
+
+> People who use BuildBeat inside an AI session never type these commands: `SKILL.md` §0.5 is the driving manual the session reads, and you just say "start", "where are we", "approve". This page shows what runs behind the session so you can check it.
+
+## 0. Install
+
+```bash
+npm install --global @haiyangbg/buildbeat@latest
+buildbeat | head -3    # printing "BuildBeat runtime" plus the usage means the install worked
+```
+
+Stable releases live on `@latest`; there is exactly one executable, `buildbeat` (the runtime this page uses). `@next` is only for pre-releases. Requirements: Node ≥ 20, Git, bash, zero runtime dependencies.
+
+> Before continuing, confirm that `$(npm root -g)/@haiyangbg/buildbeat/templates/v2/envelope/` exists. If it does not, reinstall with `npm install --global @haiyangbg/buildbeat@latest`.
+
+## 1. Prepare the Work (Git plane)
+
+In the target repository, create the Work directory and write the intent and the plan (their digests get bound into the approval subject), copy the official workflow preset next to the Work (copy, do not reference the install directory: the workflow file's digest is recorded in the Run and travels with the project in Git), then copy the envelope templates (worker wrapper script plus three prompts) into the repository-level `delivery/envelope/`:
+
+```bash
+BB="$(npm root -g)/@haiyangbg/buildbeat"
+mkdir -p delivery/work/WORK-DEMO-1
+printf "# Intent\nAdd date filtering to the CSV export.\nStop-loss: at most 3 Runs, 4 review rounds.\n" > delivery/work/WORK-DEMO-1/intent.md
+printf "# Plan\n1. Add from/to parameters in src/export.js; 2. add boundary cases under tests/.\n" > delivery/work/WORK-DEMO-1/plan.md
+cp "$BB/src/v2/presets/software-delivery.yaml" delivery/work/WORK-DEMO-1/workflow.yaml
+cp -R "$BB/templates/v2/envelope" delivery/envelope
+git add delivery && git commit -qm "buildbeat: work WORK-DEMO-1 + envelope"
+```
+
+The envelope must be committed: workers run in an isolated worktree and only see committed files. `delivery/envelope/worker.sh <role> -- <tool command…>` takes care of "exit 75 when the tool is not on PATH, append the prompt as the last argument, commit mechanically after a writing step, capture stdout as the envelope for a read-only step"; the three prompts only need the project's environment facts added ([Worker contract](05-worker-contract.md), Chinese).
+
+## 2. Write the run config
+
+`delivery/work/WORK-DEMO-1/run-config.yaml`. Paths resolve relative to **this file**; the YAML is a strict subset: block lists and block maps only, no inline `[]` / `{}`, no anchors, comments on their own line. The config below parses as-is (machine-checked by `tests/v2-templates-firstrun.test.js`); the full sample and the envelope templates are in [`templates/v2/`](../../../templates/v2/run-config.example.yaml).
+
+```yaml
+repo: ../../..
+work: WORK-DEMO-1
+run: RUN-DEMO
+workflow: workflow.yaml
+riskPreset: standard
+entry: build
+allowedPaths:
+  - src
+  - tests
+reviewTriage: required
+envelope:
+  prompts: ../../envelope/prompts
+workers:
+  builder:
+    command: bash
+    args:
+      - delivery/envelope/worker.sh
+      - builder
+      - --
+      - codex
+      - exec
+      - -s
+      - workspace-write
+  verifier:
+    command: bash
+    args:
+      - -lc
+      - npm test
+  reviewer:
+    command: bash
+    args:
+      - delivery/envelope/worker.sh
+      - reviewer
+      - --
+      - codex
+      - exec
+      - -s
+      - read-only
+  fixer:
+    command: bash
+    args:
+      - delivery/envelope/worker.sh
+      - fixer
+      - --
+      - codex
+      - exec
+      - -s
+      - workspace-write
+```
+
+- `workers.<role>` is any CLI: to switch tools, change only what follows `--` (`claude -p`, any script), see the [Adapter guide](04-adapter-guide.md) (Chinese); the reviewer's output format is in the [Worker contract](05-worker-contract.md) (Chinese) and already spelled out in the prompt template.
+- **`fixer` is not optional**: without it, a failed verify or a blocking review stops the Run at `WAITING_HUMAN` (reason `no adapter configured for worker fixer`) waiting for you to fix by hand; nothing gets fixed automatically.
+- Worker subprocesses receive only `PATH HOME LANG LC_ALL TMPDIR TERM USER SHELL` by default; inject anything else by name with `env:` ([Adapter guide](04-adapter-guide.md), Chinese).
+- `reviewTriage: required` routes P0/P1 findings through you before a fixer is dispatched; delete the line if you do not want that.
+
+## 3. Accept the plan
+
+The `standard` preset requires the plan to be an accepted artifact before build (`controlled` also requires the intent). Acceptance is digest-bound: edit the plan after accepting it and the acceptance expires on its own; `doctor` reports `stale`.
+
+```bash
+buildbeat accept --repo . --work WORK-DEMO-1 --artifact plan --by <your name>
+```
+
+Success: it prints `accepted plan as A-WORK-DEMO-1-<n>` and `digest: sha256:…`.
+
+## 4. doctor: read what start will read, before starting
+
+```bash
+buildbeat doctor --config delivery/work/WORK-DEMO-1/run-config.yaml
+```
+
+Check section by section: declared versus actual enforcement for each entry under `policies`; whether each worker under `worker isolation` is `env allowlist` or `WARNING inherit`; `push protection`; the per-step budgets; under `work artifacts`, whether intent and plan exist, are accepted, are stale, and the preview of where `start` will stop. A `WARNING` does not mean you cannot run, but you should know what it means; exit code 0 does not mean everything is ready.
+
+## 5. Start the Run; it stops for a human
+
+```bash
+buildbeat start --config delivery/work/WORK-DEMO-1/run-config.yaml --attempt new
+```
+
+`--attempt new` numbers the run automatically (`RUN-DEMO-01/02…`) and supersedes older Runs of the same Work that are still waiting for a human. The Runner will: open an isolated worktree (branch `run/RUN-DEMO-01`, pushing to the configured remote is blocked) → the builder produces a commit and the candidate is pinned → the verifier really runs the tests (the exit code is read back as evidence) → the reviewer produces structured findings read-only → the Run reaches `WAITING_HUMAN`.
+
+When starting from inside an AI session, detach the process (`nohup` / `setsid`); otherwise the host session's timeout kills the Run.
+
+**What success looks like**: the output ends with `status: WAITING_HUMAN`, and `waiting on human:` is followed by `enter-wait-merge` (the merge decision) or `enter-fix` (triage). **Stopping with `infra` is an environment problem, not a code problem**: timeouts, crashes, non-JSON envelopes and exit code 75 all count; fix the worker or the environment, then `approve --transition resume-<step>` to continue. No budget is consumed.
+
+## 6. Read the evidence, decide
+
+```bash
+buildbeat overview --repo .                       # where each Work is, whose move is next, what it has cost
+buildbeat inbox --repo .                          # Runs waiting for you, each with the copyable next command
+buildbeat status --repo . --run RUN-DEMO-01       # steps, durations, evidence, findings, the reason it waits
+```
+
+Before approving, look at: the candidate SHA, the verify exit code and log, every review finding. Then run the line `inbox` gives you, usually:
+
+```bash
+buildbeat approve --repo . --run RUN-DEMO-01 --transition enter-wait-merge --by <your name> --config delivery/work/WORK-DEMO-1/run-config.yaml
+```
+
+**Be clear about which step you are approving** ([Approval guide](07-approval-guide.en.md)): `enter-wait-merge` is the merge decision; the Run reaches the terminal state `SUCCEEDED`, meaning the candidate is fit to merge. The actual merge, push and release are always your actions outside the Runner. `enter-fix` / `resume-<step>` are non-terminal transitions: after approving them, `resume --config …` lets the Run continue. When findings block, the Run routes fix → verify → review on its own; when the budget is exhausted or a failure fingerprint repeats, it stops and hands back to you ([Recovery](10-recovery.en.md)).
+
+## 7. Walk the failure branch once
+
+To see the automatic repair loop, commit a failing test case under `tests/` and `start --attempt new` again: verify fails → the fixer repairs with the failure summary → verify reruns → review. `status` shows `step fix: SUCCEEDED` and a second `verify`. To route findings through your hands first: `reviewTriage: required` together with `findings list` / `findings adjudicate` adjudicates fingerprint by fingerprint; a dismissed fingerprint no longer blocks.
+
+## 8. Recovery, notifications, cleanup
+
+- Process killed / machine rebooted: `resume --config <run-config.yaml>`, see [Recovery](10-recovery.en.md).
+- You fixed the problem yourself in the worktree and committed it: `resume --config … --adopt <sha> --by <name>` skips the fixer and continues from verify.
+- Not watching the screen: configure one DingTalk / webhook channel in `.buildbeat/notify.yaml` (the URL comes only from an environment variable) and the Run finds you when it stops ([Approval guide](07-approval-guide.en.md)).
+- Worktrees left by terminal Runs: `gc --repo .` prints the plan first, `--apply true` cleans.
+- To dry-run a single step before a real Run: `preflight --step <id>` (main checkout, minute-scale, produces no evidence); declare the envelope's environment dependencies with `requires:` so they are checked fail-closed before start ([Workflow guide](02-workflow-guide.md), Chinese).
+
+## 9. observe: let the system watch production (v0)
+
+```bash
+cp "$(npm root -g)/@haiyangbg/buildbeat/src/v2/presets/observe.yaml" .buildbeat/observe.yaml   # replace with the project's real probes
+buildbeat observe run --config .buildbeat/observe.yaml            # one invocation = one cycle; leave scheduling to cron
+buildbeat observe status --repo .
+buildbeat observe triage --repo . --intent delivery/observe/intents/INTENT-<fp>.md --action fix_now --by <you>
+```
+
+A probe fails or cannot collect → evidence `failed` / `unverified` → bands escalate (record → read-only diagnosis → Intent draft queued). Drafts are **never executed automatically**; `dismiss` feeds the threshold back so the same fingerprint stays quiet until its severity rises. Details in the [Evidence guide](06-evidence-guide.en.md) §observe.

package/docs/v2/guide/01-quickstart.md

@@ -1,5 +1,7 @@
 # 快速开始：第一个 Run
 
+**简体中文** | [English](01-quickstart.en.md)
+
 目标：在一个真实 Git 仓库里，让 v2 Runner 驱动 Build→Verify→Review 自动跑完，**停在合并决定**，由你带着证据拍板。下面的顺序是固定的：安装 → 准备工作项 → 写 run 配置 → 接受计划 → doctor → start → 看证据、拍板。每一步都写了"成功是什么样"。耗时取决于你的 worker 与任务，本文不给承诺数字。
 
 > 在 AI 会话里用 BuildBeat 的人不需要手敲这些命令：`SKILL.md` §0.5 是给会话读的驾驶手册，你说「开工 / 当前进度 / 批准」即可。本文给的是会话背后跑的东西，方便你核对。
@@ -8,12 +10,12 @@
 
 ```bash
 npm install --global @haiyangbg/buildbeat@latest
-buildbeat-v2 | head -3    # 打印 "BuildBeat v2 runtime" 与用法即安装成功
+buildbeat | head -3    # 打印 "BuildBeat runtime" 与用法即安装成功
 ```
 
-2.0.0 起 `@latest` 就是 v2；同一个包同时给出 `buildbeat`（v1 生命周期命令：doctor / init / adopt / upgrade）和 `buildbeat-v2`（本文用的运行时）。预发布才用 `@next`。要求 Node ≥ 20、Git、bash，零运行时依赖。
+稳定版走 `@latest`，可执行文件只有一个：`buildbeat`（本文用的运行时）。预发布才用 `@next`。要求 Node ≥ 20、Git、bash，零运行时依赖。
 
-> 下文用到的 `templates/v2/envelope/` 与 run 配置 `env:` 透传修复自 2.0.1 起随包分发。装好后确认 `$(npm root -g)/@haiyangbg/buildbeat/templates/v2/envelope/` 存在再继续；不存在说明装到的是 2.0.0，先 `npm install --global @haiyangbg/buildbeat@latest` 更新。
+> 继续之前确认 `$(npm root -g)/@haiyangbg/buildbeat/templates/v2/envelope/` 存在；不存在就重新 `npm install --global @haiyangbg/buildbeat@latest`。
 
 ## 1. 准备工作项（Git 面）
 
@@ -96,7 +98,7 @@ workers:
 `standard` 预设在 build 前要求 plan 是已接受工件（`controlled` 还要求 intent）。接受是 digest 绑定的：接受后改了 plan，接受自动过期，`doctor` 会报 `stale`。
 
 ```bash
-buildbeat-v2 accept --repo . --work WORK-DEMO-1 --artifact plan --by <你的名字>
+buildbeat accept --repo . --work WORK-DEMO-1 --artifact plan --by <你的名字>
 ```
 
 成功：打印 `accepted plan as A-WORK-DEMO-1-<n>` 与 `digest: sha256:…`。
@@ -104,7 +106,7 @@ buildbeat-v2 accept --repo . --work WORK-DEMO-1 --artifact plan --by <你的名
 ## 4. doctor：起跑前把 start 会读的事实读一遍
 
 ```bash
-buildbeat-v2 doctor --config delivery/work/WORK-DEMO-1/run-config.yaml
+buildbeat doctor --config delivery/work/WORK-DEMO-1/run-config.yaml
 ```
 
 逐段核对：`policies` 每条的 declared 与 actual 强制等级；`worker isolation` 每个 worker 是 `env allowlist` 还是 `WARNING inherit`；`push protection`；每步预算；`work artifacts` 里 intent / plan 是否存在、是否已接受、是否 stale，以及"start 会停在哪一步"的预告。有 `WARNING` 不代表不能跑，但要知道它意味着什么；退出码 0 不等于全部就绪。
@@ -112,7 +114,7 @@ buildbeat-v2 doctor --config delivery/work/WORK-DEMO-1/run-config.yaml
 ## 5. 起 Run，停在人批
 
 ```bash
-buildbeat-v2 start --config delivery/work/WORK-DEMO-1/run-config.yaml --attempt new
+buildbeat start --config delivery/work/WORK-DEMO-1/run-config.yaml --attempt new
 ```
 
 `--attempt new` 自动编号 `RUN-DEMO-01/02…`，并作废同一 Work 下仍在等人的旧 Run。Runner 会：开隔离 worktree（分支 `run/RUN-DEMO-01`，对配置 remote 的 push 已被封禁）→ builder 产出提交并固定 candidate → verifier 真实跑测试（退出码回读为证据）→ reviewer 只读出结构化 findings → 到达 `WAITING_HUMAN`。
@@ -124,15 +126,15 @@ buildbeat-v2 start --config delivery/work/WORK-DEMO-1/run-config.yaml --attempt
 ## 6. 看证据、拍板
 
 ```bash
-buildbeat-v2 overview --repo .                       # 每个 Work 走到哪、下一步该谁、花了多少
-buildbeat-v2 inbox --repo .                          # 等你批的 Run，每条附可复制的下一句命令
-buildbeat-v2 status --repo . --run RUN-DEMO-01       # 步、耗时、证据、findings、待批理由
+buildbeat overview --repo .                       # 每个 Work 走到哪、下一步该谁、花了多少
+buildbeat inbox --repo .                          # 等你批的 Run，每条附可复制的下一句命令
+buildbeat status --repo . --run RUN-DEMO-01       # 步、耗时、证据、findings、待批理由
 ```
 
 批之前先看：候选 SHA、verify 的退出码与日志、review 的每条 finding。然后按 `inbox` 给出的那一句执行，通常是：
 
 ```bash
-buildbeat-v2 approve --repo . --run RUN-DEMO-01 --transition enter-wait-merge --by <你的名字> --config delivery/work/WORK-DEMO-1/run-config.yaml
+buildbeat approve --repo . --run RUN-DEMO-01 --transition enter-wait-merge --by <你的名字> --config delivery/work/WORK-DEMO-1/run-config.yaml
 ```
 
 **批的是哪一步要分清**（[Approval 指南](07-approval-guide.md)）：`enter-wait-merge` 是合并决定，Run 进终态 `SUCCEEDED`，表示候选具备合并条件——真正的合并、push、发布永远是你在 Runner 之外的动作；`enter-fix` / `resume-<step>` 是非终态转换，批准后要 `resume --config …` 让它续跑。被 findings 阻断时会自动路由 fix→verify→review 重走，超预算或失败指纹重复则停下交还给你（[Recovery](10-recovery.md)）。
@@ -153,9 +155,9 @@ buildbeat-v2 approve --repo . --run RUN-DEMO-01 --transition enter-wait-merge --
 
 ```bash
 cp "$(npm root -g)/@haiyangbg/buildbeat/src/v2/presets/observe.yaml" .buildbeat/observe.yaml   # 改成项目真实探针
-buildbeat-v2 observe run --config .buildbeat/observe.yaml            # 一次=一个周期；周期化交给 cron
-buildbeat-v2 observe status --repo .
-buildbeat-v2 observe triage --repo . --intent delivery/observe/intents/INTENT-<fp>.md --action fix_now --by <你>
+buildbeat observe run --config .buildbeat/observe.yaml            # 一次=一个周期；周期化交给 cron
+buildbeat observe status --repo .
+buildbeat observe triage --repo . --intent delivery/observe/intents/INTENT-<fp>.md --action fix_now --by <你>
 ```
 
 探针失败/采不到 → 证据 `failed`/`unverified` → bands 分层（记录→只读诊断→Intent 草稿入队）。草稿**绝不自动执行**；`dismiss` 会回调阈值，同指纹在严重度升级前不再打扰。详见 [Evidence 指南](06-evidence-guide.md) §observe。

package/docs/v2/guide/03-policy-guide.md

@@ -50,4 +50,4 @@ rule:
 
 ## 接入
 
-run 配置 `policies:` 列表引用文件路径；risk 预设（`fast`/`standard`/`controlled`/`legacy-four-gates`）自带一组策略与停点，`riskPreset:` 一行即可启用，再叠加项目自定义策略。
+run 配置 `policies:` 列表引用文件路径；risk 预设（`fast`/`standard`/`controlled`/`release`）自带一组策略与停点，`riskPreset:` 一行即可启用，再叠加项目自定义策略。