@haiyangbg/buildbeat 2.0.0 → 2.0.1

package/README.md

@@ -2,306 +2,165 @@
 
 **简体中文** | [English](README.en.md)
 
-**让人和 AI 会话围绕同一组项目事实完成交付。**
+**会话随时换，项目接着干。**
+上下文存进文件，协作围绕 Git，工作持续推进。
 
-BuildBeat（旧称 Solobaton）是一套面向人和 AI 会话的、**file-first、human-gated 工程交付协议与脚手架**。它通过 Git 中的文件总线、人工 Gate 和可验证证据，让项目在长期迭代、多个仓库和多个 AI 上下文之间保持同步、可控、可核验。它不负责创建 Agent、管理模型、建模团队岗位或提供运行时编排。
+BuildBeat 是以 Git 和项目文件为基础的 AI 交付工作流，面向人和 AI 会话。目标、计划、决定与交付记录保存在项目里，换模型、换工具、换会话，或换一个人接手，都有继续工作的依据。Loop 推进实现、验证、审查与修复；进度和证据由内核从 Git 与真实命令回读，不靠会话自述；关键决定由人掌握。
 
-> **信息走文件，不走人嘴。完成必须有证据。规格、设计、合并和上线由人拍板。**
+[使用指南](docs/v2/guide/README.md) · [跨会话接续](docs/v2/guide/11-session-handoff.md) · [npm](https://www.npmjs.com/package/@haiyangbg/buildbeat) · [CI](https://github.com/HaiYangBG1/BuildBeat/actions/workflows/ci.yml) · [MIT](LICENSE)
 
-需求、看板、契约、决策、状态和验证证据都落在 Git 管理的文件中。会话可以关闭或替换，项目上下文不会跟着聊天窗口消失。
+## 告别祖传上下文
 
-BuildBeat 最初蒸馏自一个人指挥 4 个 AI 会话、持续多期交付复杂产品的实践；这说明了方法的来源，不限定使用人数。一个 Builder 可以使用，多个 Builder 也可以共享同一 Git 项目并按需求/工作包分别闭环。
+不用再抱着一个越来越长的“祖传会话”不放。上下文满了，开个新会话；想换模型或工具，从项目记录接着做；今天交给同事，接手的人也能从文件了解进度和下一步。目标、约束、计划、决定和交付记录都应落在文件系统中，新会话不必依赖旧聊天历史来判断下一步。
 
-**当前主线是 v2**（`@haiyangbg/buildbeat@latest`，2.0.0）：在 v1 的文件总线与人工 Gate 之上加了一个由 AI 会话调用的交付运行时 `buildbeat-v2`——隔离 worktree 内 Build → Verify → Review → Fix 自动闭环、停在合并决定，`overview` / `inbox` / `status` 回答「到哪了、谁批、卡没卡」。见下文 [v2 运行时](#v2-运行时buildbeat-v2当前主线) 与 [`docs/v2/guide/`](docs/v2/guide/README.md)。自 2.0.0 起 `@latest` 就是 v2：v1 的 `buildbeat` 生命周期命令原样保留，`buildbeat-v2` 是同一个包里的第二个可执行文件；`@next` 用于后续预发布。
+下面是已配置项目的**使用情景示意**，不是一次实测运行记录：
 
-## 解决什么问题
+| 时刻 | 你说什么 | 会话做什么 |
+|---|---|---|
+| 会话 A：开始 | “给导出功能加日期筛选，先定计划。” | 读取项目约束，把目标与计划写入 Work；接受后启动执行 |
+| 准备离开 | “把决定和未完成事项落盘，我要关闭这个会话。” | 补齐项目记录，核对运行状态与未提交改动，说明下一步 |
+| 新会话接手 | “读取项目的 BuildBeat 入口，接着做日期筛选。” | 读取 Work、Git 与运行台账，查清已完成、未验证、待批和阻塞 |
+| 继续推进 | “按当前已接受的计划继续。” | 根据实况继续执行、处理恢复或等待决定，带证据停在合并决定前 |
 
-当一个项目同时打开多个 AI Coding 会话，最容易失控的不是代码生成，而是交付状态：
+新会话可以由自己打开，也可以交给另一位有项目权限的人；换人或换机器时，同步记录与候选，并核对原 Run 的执行环境。
 
-- A 会话不知道 B 已经改了接口，继续基于旧上下文工作；
-- 人在会话之间复制粘贴，自己变成消息总线；
-- Agent 声称“完成”，却没有测试、commit 或线上证据；
-- 一个子文档或 commit 完成后，会话过早停下等人说“继续”；
-- 草案中的每个小选择都打断人，真正的阶段 Gate 被确认噪音淹没；
-- 当前进度、线上版本和决策被重复写进多个文档，逐渐互相矛盾。
+**关键上下文落盘后，旧聊天可以关闭或删除。** 未保存的讨论不会自动变成项目记忆；删除聊天时应保留项目、候选分支和所需运行文件。具体步骤见 [跨会话接续](docs/v2/guide/11-session-handoff.md)。
 
-BuildBeat 把这些问题收敛成四个支柱：
+## 上下文就在项目里
 
-1. **端到端工作包**：一个 Builder 对一个需求/功能工作包的产品判断、实现、测试、合并与发布证据负责；产品、全栈、测试是可调用的 AI 专业视角，不是人类岗位接力。
-2. **文件总线**：`NOW → 看板 → contracts → status`，交接不依赖聊天记忆。
-3. **人在 Gate**：规格、设计、合并、上线四个关键决策不允许自动跨过。
-4. **证据制完成**：完成必须带 commit hash 和可核验证据；无证据，不算完成。
+Git 管理需要长期保留的项目事实；本机文件保存运行中的状态。BuildBeat 读取这些事实来回答“做到哪了”，而不是让每个会话重新写一份进度猜测。
 
-## 5 分钟开始
+| 文件与目录 | 保存什么 | 怎样使用 |
+|---|---|---|
+| `AGENTS.md`、项目规范与契约 | 项目入口、约束、角色和写入边界 | 新会话从入口读取，按任务深入相关文件 |
+| `delivery/work/<ID>/` | 目标、计划、配置、决定、审查裁决与终态运行记录 | 纳入 Git，作为同一项工作的接续依据 |
+| `.buildbeat/runtime/` | 在途事件、检查点、锁与原始日志 | 留在本机，不进 Git；恢复活动 Run 时需要 |
+| `.buildbeat/worktrees/` | Run 的隔离工作树 | 保留候选代码与现场，不作为聊天缓存清理 |
 
-### 推荐：引导式 Bootstrap
+落在文件系统不等于每个文件都应该提交到 Git。秘密留在受保护的本地环境中；终态记录保存证据摘要和引用，原始日志需要按项目要求另行保留。详见 [证据指南](docs/v2/guide/06-evidence-guide.md)。
 
-把本仓库放到本机任意稳定位置，或放进 AI Coding 工具当前支持的本地 skill 目录。然后让会话读取 [`SKILL.md`](SKILL.md)，并说：
+## 换个方式，继续同一项工作
 
-> 用 BuildBeat 给我的项目搭协作骨架。
+继续工作所需的上下文由项目文件承载。装载了 BuildBeat 的新会话可以读取同一份目标、决定和当前状态；负责执行的 Worker 通过命令接入，模型选择与鉴权由所用 AI 工具处理。
 
-它会先自己检查代码和配置，识别仓库数量、部署单元、UI 和契约边界；只问 3–4 个无法从项目中查到的简单问题；给出一屏确认后，再生成已经填好项目事实的骨架并运行自检。
+- **跨会话**：关闭旧聊天，用干净上下文接续同一个 Work。
+- **跨工具与模型**：按目标工具的方式加载 Skill、配置执行命令和输出合同，复用项目记录。
+- **跨人接手**：有项目访问权限的人，同步上下文、候选与必要证据后，可以在职责和授权范围内继续；有效的既有决定继续保留。
+- **跨时间与地点**：同步已提交的项目文件后，可在准备好环境的另一台机器重新接手；活动 Run 的运行状态和工作树不会随普通 Git clone 自动迁移。
 
-> 已经存在大量代码的项目不要直接套新项目模板。使用 `SKILL.md` §8.5 的**存量接管仪式**：先摸底、划新旧边界、补最小验证能力，再采用 `pm/scripts/` 紧凑布局，避免撞上原项目自己的 `scripts/`。
+**随时随地接手的基础，是记录可达、环境可用、权限明确。** 自己继续或交给别人，都从项目文件开始，无需携带旧聊天全文。Git 提供协作与版本管理，访问权限沿用仓库托管和执行平台的设置。
 
-### Claude Code 插件：BuildBeat 仓库
+协议可由不同工具读写；具体工具能否直接执行 Loop，要看适配、权限和环境。现有真实 Worker 证据覆盖 `codex exec`，脚本 Worker 有确定性测试；其他工具不能仅因有 CLI 就算已验证。见 [能力矩阵](docs/CAPABILITY-MATRIX.md) 与 [Adapter 指南](docs/v2/guide/04-adapter-guide.md)。
 
-本仓提供独立的 Claude Code marketplace 包，安装后以 `/buildbeat:buildbeat` 路由同一份 canonical [`SKILL.md`](SKILL.md)。可从本地 checkout 隔离安装：
+## 多个角色，共同推进一项工作
 
-```text
-/plugin marketplace add /absolute/path/to/BuildBeat
-/plugin install buildbeat@buildbeat-plugins
-/buildbeat:buildbeat
-```
+**端到端工作包**是协作单元。一个 Builder 对一个用户级结果负责，按需要调用产品、全栈、测试三个 AI 视角；多个 Builder 可以分别拥有不同工作包，也可以交接同一工作包；交接时写清当前负责推进的人、已完成事项和下一步，避免重复执行。
 
-从 GitHub 安装时使用 `/plugin marketplace add HaiYangBG1/BuildBeat`。插件只携带 Skill、模板、示例和参考文档，不把 npm CLI 的顶层 `bin/` 暴露进 Claude Code；是否对项目执行写入仍受 CLI 版本、确认屏和人工 Gate 约束。完整打包边界见 [`plugins/buildbeat/README.md`](plugins/buildbeat/README.md)。
+| 会话视角 | 接手时读取什么 | 产出什么 |
+|---|---|---|
+| 产品 | 目标、约束与既有决定 | 可接受的范围、计划与验收条件 |
+| 全栈（含运维） | 已接受计划、契约与环境事实 | 候选代码与实现记录 |
+| 测试 | 验收条件与候选 | 实际测试结果、覆盖范围与缺口 |
 
-### CLI：scoped BuildBeat 包承载完整有界生命周期
+这些是可调用的专业视角，不是人类岗位接力的固定流程，也不要求固定开三个会话。审查不是会话视角：它是 Run 内置的只读 reviewer，见下一节。一个人或多个人都可以按需要调用这些视角。共同事实通过项目文件传递，各视角遵守自己的写入边界。当前单仓活动 Run 锁在本地生效；多角色或多个 Git 副本不等于有跨机器的运行协调。同一工作包交接前应核对原执行环境，避免双方重复启动。
 
-canonical npm 分发标识是 `@haiyangbg/buildbeat`；未加 scope 的 `buildbeat` 已被其他项目占用，本仓不会冒用。使用前先从官方 registry 回读 `@latest` 的精确版本；需要复现时，把后续命令中的 `@latest` 换成已记录版本：
+## 让工作进入 Loop
 
-```bash
-npm view @haiyangbg/buildbeat@latest version
-npx --yes --package=@haiyangbg/buildbeat@latest buildbeat doctor /path/to/project
-npx --yes --package=@haiyangbg/buildbeat@latest buildbeat init /path/to/project --dry-run
-npx --yes --package=@haiyangbg/buildbeat@latest buildbeat adopt /path/to/project --dry-run --json
-npx --yes --package=@haiyangbg/buildbeat@latest buildbeat upgrade /path/to/project --dry-run --json
-```
-
-需要长期使用时，可以显式管理全局 CLI：
+接受所需计划后，`buildbeat-v2` 在隔离 Git worktree 中调用配置好的 Worker，推进实现、验证、审查与修复。审查由一个不带上下文、只读的 reviewer worker 执行，任何工作树写入都会被前后快照比对捕获并按失败落账。
 
-```bash
-npm install --global @haiyangbg/buildbeat@latest
-buildbeat doctor /path/to/project
-npm install --global @haiyangbg/buildbeat@latest  # 更新 CLI 包
-npm uninstall --global @haiyangbg/buildbeat       # 只移除全局 CLI 包
+```mermaid
+flowchart LR
+    P[接受计划] --> B[实现]
+    B --> V[验证]
+    V -->|通过| R[审查]
+    V -->|失败| F[修复]
+    R -->|阻断性发现| F
+    F --> V
+    R -->|通过| H[等待人的合并决定]
 ```
 
-包管理器的安装、更新、移除只管理 **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.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 分支受控重建基线。
+- **完成有证据**：候选提交由 Git 回读，测试结论来自实际命令；AI 的“已完成”不能代替验证。
+- **批准有对象**：批准绑定具体候选、计划与证据；对象变了，旧批准会失效。
+- **中断有去向**：Runner 可按台账恢复；中断步骤可能重跑，脏工作树会先请求处理。
+- **循环有止损**：预算、重复失败与基础设施故障形成明确的待处理事项；可配置通知。
 
-旧 `solobaton@latest` 固定在 legacy v0 只读能力，并迁移提示到本 scoped package；它不会获得新的项目写入或升级能力。写入式首屏命令必须使用 `@haiyangbg/buildbeat`，并且仍先展示计划、受 Git/碰撞/所有权检查约束，不能跨人工 Gate。
+合并决定表示候选具备合并条件。合并、推送和部署由人或另行授权的工具在 Runner 之外执行；上线后可用 `release-readback` 保存回读与观察记录。执行检查与宿主隔离各有范围，见 [安全与权限边界](docs/v2/guide/09-security-boundaries.md)。
 
-### v2 运行时：`buildbeat-v2`（当前主线）
+## 开始你的第一次接力
 
-v2 把「一个工作包怎么从接受走到合并、上线」做成了机器可核验的 Run：`delivery/work/<ID>/` 里的 intent / plan 被 digest 绑定接受后，`buildbeat-v2 start` 在隔离 git worktree 里按官方预设跑 Build → Verify → Review → Fix，候选由 git 回读而不是 worker 自述，只读 reviewer 由机器强制，超预算、同指纹重复失败、worker 基础设施故障都停下来等人；合并、push、部署永远是人批之后的人类动作（内核没有这些调用路径）。上线用 `release-readback` 车道把「做之前回读 → 人做 → 做之后回读 → 观察 → 人关窗」记成 L4 证据；`observe` 做生产只读体检；`gc` 打扫；`.buildbeat/notify.yaml` 把等待推到钉钉或 webhook。
+需要 Node.js ≥ 20、Git、Bash，以及已安装并完成鉴权的 AI 编程工具。
 
-它不创建 Agent、不管理模型：worker 是你在 run 配置里写的任意命令（Codex / Claude Code / 一段脚本都行），内核只负责台账、隔离、证据和门。
+**1. 安装运行时。** 稳定发布包使用 `@latest`，同包包含 `buildbeat-v2` 运行时与 `buildbeat` v1 生命周期命令。
 
 ```bash
-npm install --global @haiyangbg/buildbeat@latest # 2.0.0 起 latest 即 v2；预发布用 @next
-buildbeat-v2 overview --repo .                     # 每个 Work 走到哪、花了多少、下一步该谁
-buildbeat-v2 inbox --repo .                        # 谁在等你批，下一句该说什么
-buildbeat-v2 start --config delivery/work/WORK-X/run-config.yaml --attempt new
-buildbeat-v2 status --repo . --run RUN-X-01        # 在跑第几步、跑了多久、历史通常多久、卡没卡
+npm view @haiyangbg/buildbeat@latest version
+npm install --global @haiyangbg/buildbeat@latest
 ```
 
-在 AI 会话里用的人不需要记这些命令：[`SKILL.md`](SKILL.md) §0.5 是给会话读的驾驶手册，用户说「当前进度 / 开工 / 怎么样了 / 批准 / 上线 / 打扫卫生」即可。用户视角的一页在 [`docs/v2/guide/00-how-to-talk.md`](docs/v2/guide/00-how-to-talk.md)，十件套指南索引在 [`docs/v2/guide/README.md`](docs/v2/guide/README.md)，从 v1 文件总线迁移见 [`docs/v2/guide/08-migration-v1.md`](docs/v2/guide/08-migration-v1.md)。每个 beta 的内容与发布证据见 [`CHANGELOG.md`](CHANGELOG.md) 与 `docs/V2.0.0-BETA.*-RELEASE-EVIDENCE-*.md`；每条机制背后的真实事故在 [`lessons.md`](lessons.md)。
-
-### 手动安装
-
-只建议在你已经理解模板含义时使用：
-
-```bash
-git clone https://github.com/HaiYangBG1/BuildBeat.git
-rsync -a --exclude '/standards/' --exclude '/pm/adr/' "BuildBeat/templates/" /path/to/new-project/
-cd /path/to/new-project
-```
+> 快速开始用到的信封模板（`templates/v2/envelope/`）自 2.0.1 起随包分发；版本与内容对照见 [CHANGELOG](CHANGELOG.md)。
 
-上面的默认路径保留隐藏 `.claude/`，但不生成可选的 `standards/` 与 `pm/adr/`。它们仍作为 project-owned 模板随源仓提供：只有在 Bootstrap 一屏确认中明确启用相应规范，或真实决定命中 ADR 判据时，才单独复制并按项目事实填写；缺失是合法状态。
+**2. 让会话加载入口。** 下载或检出本仓，让你的 AI 工具读取其中的 [`SKILL.md`](SKILL.md)，然后在目标项目中说：
 
-接着必须：
+> 用 BuildBeat 接管这个项目。先检查代码和现有约束，为第一项工作准备 v2 上下文与运行配置。
 
-1. 逐文件替换所有 `<占位符>`；
-2. 将 `gitignore.template` 的规则合并进项目 `.gitignore`；
-3. 为 `verify-status.sh` 配置真实测试命令；
-4. 运行 `bash scripts/bus-check.sh`，确认骨架指针和能力边界；
-5. 在 meta 仓和每个代码子仓分别安装 pre-commit 护栏：
+会话先检查项目，补齐目标、计划、验证命令和执行配置；你接受后再启动。完整步骤见 [快速开始](docs/v2/guide/01-quickstart.md)，已有 v1 项目见 [迁移指南](docs/v2/guide/08-migration-v1.md)。
 
-```bash
-cp scripts/pre-commit.sh .git/hooks/pre-commit
-chmod +x .git/hooks/pre-commit
-```
+**3. 试一次接力。** 在工作记录落盘后关闭旧会话，打开一个没有旧聊天历史的新会话；也可以同步记录与候选，让另一位有权限的成员用自己的工具接手：
 
-强烈建议同时安装 [`gitleaks`](https://github.com/gitleaks/gitleaks)。未安装时，pre-commit 仍会运行其它检查，但 Secret 扫描会降级成警告而不是阻断。Git hooks 不进入普通 Git 历史，新 clone 后需要重新安装，或显式配置版本化的 `core.hooksPath`。
+> 读取项目的 BuildBeat 入口，查看当前进度和待批事项，告诉我下一步，然后在已有授权范围内继续。
 
-## 日常怎么运行
+核对它读出的目标、候选、验证结果和下一步，再继续。见 [跨会话接续指南](docs/v2/guide/11-session-handoff.md)。
 
-先从看板认领一个可独立验收的工作包；同一个 Builder 对它端到端负责。需要并行专业视角时，可以打开产品、全栈、测试会话，但它们是该工作包内的 AI 视角，不是三个人类岗位的强制交接。多个 Builder 协作时，各自认领不同工作包并通过 Git 共享最终事实。
+<details>
+<summary>Claude Code 插件安装</summary>
 
-```text
-你是当前工作包的产品视角，负责澄清需求、看板和决策事实。开工。
-```
+插件负责加载 Skill 与参考资料，运行时需要另行安装。
 
 ```text
-你是当前工作包的全栈视角，负责实现、契约和部署候选。开工。
-```
-
-```text
-你是当前工作包的测试视角，负责黑盒验收、E2E 和证据。验收当前候选。
+/plugin marketplace add HaiYangBG1/BuildBeat
+/plugin install buildbeat@buildbeat-plugins
+/buildbeat:buildbeat
 ```
 
-每个视角面向人收口时统一按「已做 → 未做 → 下一步」回复:`已做`只写功能/业务结果,证据紧跟对应的已做事项;`未做`写清事项和原因;本域完成就说下一棒是谁、接什么,未完成就说需要谁提供或确认什么。自己能继续就不交棒、不伪求助。完整模板见 [`templates/指挥台.md`](templates/%E6%8C%87%E6%8C%A5%E5%8F%B0.md)。
+本地源码安装可把 marketplace 地址换成本仓绝对路径。缓存与安装检查见 [插件说明](plugins/buildbeat/README.md)。
 
-每个会话开工先同步代码，再运行护栏：
-
-```bash
-git pull
-bash scripts/bus-check.sh
-```
+</details>
 
-多仓项目要在各子仓分别同步。修改契约、执行 migration、部署等不可逆动作前，再运行一次 `bus-check.sh`。
+<details>
+<summary>v1 生命周期与旧名称</summary>
 
-常用命令：
+`buildbeat doctor` 检查 v1 骨架，`init/adopt/upgrade` 管理其生命周期；它们不会生成或迁移完整的 v2 Work。
 
 ```bash
-bash scripts/bus-check.sh --format=json  # 输出 schema 1 JSON；warning/unverified 不会被吞掉
-bash scripts/bus-check.sh --strict       # 任一 conflict/error finding 会非零退出
-bash scripts/verify-status.sh --run       # 跑项目配置的真实测试套件并记录最近全绿
-bash scripts/design-preview.sh 1          # 有 UI 时，Gate2 前打开真实可点原型
-```
-
-## 核心机制
-
-- **工作包**：按一个可验收的用户级结果持续推进，不因单个文件、commit 或 reviewer 返回而提前结束。
-- **三级审批**：`STOP_NOW` 处理越权、冻结语义和不可逆动作；`BATCH_AT_GATE` 集中可逆取舍；`NO_APPROVAL` 自主完成派生工作。
-- **三轨制**：快轨、标准轨、重轨按风险选择流程重量，小事不上全套仪式。
-- **单点事实**：`NOW.md` 只做薄指针，契约、决策、状态和线上查询各有唯一入口。
-- **review-ready 核查门**：候选稳定、工作树干净、L3 证据已绿且没有已知待修项后，才启动一次独立 milestone reviewer。
-- **机器护栏**：`bus-check --strict`、pre-commit、gitleaks 和项目测试把确定性规则变成可执行检查。
-- **多仓漂移**：多仓项目在契约入口显式绑定各子仓 CHANGELOG、契约版本来源和本地部署基线 app；确定不一致才阻塞，缺仓或缺来源保持 unverified，不猜自然语言。
-- **可选规范与 ADR**：STACK/CODE/REVIEW/DESIGN 默认不生成；存在时检查三行声明、Rule ID 和 Draft/Confirmed 状态。Confirmed STACK 还只读比对显式基线与 Node、lockfile、Docker FROM 事实，无法覆盖时保持 unverified。长期难回退决定才建 ADR，并校验 Status 与 Superseded 链。
-- **生产状态证据**：项目接入 `live-status.sh` / `live-config.sh` 后，可检查部署平台配置与基线的漂移；它不自动证明运行中容器已经加载最新配置。
-- **存量接管**：先建立系统边界和最小验证能力，再把新地盘纳入完整总线，避免直接重写未知遗留行为。
-
-完整规则、Bootstrap 和接管流程见 [`SKILL.md`](SKILL.md)；真实失败模式和设计理由见 [`lessons.md`](lessons.md)。
-
-## 运转模型
-
-```mermaid
-flowchart LR
-    Views["AI 专业视角<br/>产品 · 全栈 · 测试"] --> WPA["Builder / 工作包 A<br/>判断 → 实现 → 测试 → 合并/发布证据"]
-    Views --> WPB["Builder / 工作包 B<br/>判断 → 实现 → 测试 → 合并/发布证据"]
-    Human["人工 Gate<br/>规格 · 设计 · 合并 · 上线"] --> WPA
-    Human --> WPB
-    WPA --> Bus["Git 文件总线<br/>NOW · 契约 · 决策 · 状态 · 证据"]
-    WPB --> Bus
+npx --yes --package=@haiyangbg/buildbeat@latest buildbeat doctor /path/to/project
 ```
 
-每个工作包都纵向闭环，不按人类职能切成产品→研发→测试流水线。人不负责在会话之间搬运上下文，只负责不能委托的判断；普通事实、归档、状态回写和已授权范围内的可逆实现继续自动推进。
-
-## 适用边界
-
-推荐用于：
-
-- 至少 2 个仓库或部署单元；
-- 会持续迭代数周或更久；
-- 一个或多个 Builder 需要分别驾驭多个 AI 上下文，并按工作包端到端闭环；
-- 多个 AI Coding 会话需要稳定交接；
-- 项目重视可核验记录，但不希望引入复杂 Agent Runtime。
-
-不建议用于：
-
-- 单仓小任务；
-- 一次性脚本；
-- 一周内即可收尾的工作；
-- 没有验证能力、又不准备先补最小测试的项目。
+完整合同见 [CLI 参考](docs/CLI.md)。BuildBeat 旧称 Solobaton，`solobaton` 可执行文件保留兼容别名；历史示例在 [example/](example/README.md)。
 
-已知边界：人仍是最终决策者；流程提高“按已定目标正确交付”的可信度，不保证产品方向本身正确。自动加载规则和 skill 目录也因 AI Coding 工具而异，正式宣称兼容前应以对应工具的当前文档和实测为准。
+</details>
 
-当前非目标：多人账号、角色/权限和组织管理后台；遥测采集、团队效能评分或指标仪表盘。BuildBeat CLI 不采集或上传项目使用数据。这些不是未完成的维护项；若未来立项，必须单独定义需求、数据口径、隐私/权限治理和验收 Gate。
+## 日常使用与适用范围
 
-## 安装后的项目结构
+完成配置后，直接在会话里说：
 
-```text
-<项目根>/
-├── AGENTS.md                       # 会话路由、总线规则和红线
-├── CLAUDE.md                       # 兼容指针，不复制规则正文
-├── ARCHITECTURE.md                 # 系统事实和子项目索引
-├── contracts/PROTOCOL.md           # 跨边界契约入口
-├── pm/
-│   ├── NOW.md                      # 当前期薄指针
-│   ├── <期>-看板.md
-│   ├── decisions.md
-│   ├── status/
-│   ├── changes/
-│   ├── adr/                         # 可选；长期技术决定与替代链
-│   └── archive/<期>/evidence/
-├── standards/                      # 可选；STACK/CODE/REVIEW，UI 项目可加 DESIGN
-├── scripts/
-│   ├── bus-check.sh
-│   ├── verify-status.sh
-│   ├── drift-check.sh
-│   ├── design-preview.sh
-│   └── pre-commit.sh
-├── .claude/agents/reviewer.md      # 只读 milestone / risk-delta / closure 核查
-├── 指挥台.md                        # 给人的一页操作卡
-└── BUILDBEAT.md                    # 所用 BuildBeat 版本与升级记录
-```
+| 你想做什么 | 可以怎么说 |
+|---|---|
+| 新会话或新成员接手 | “同步项目记录，读取入口，继续这个工作。” |
+| 查进度 | “已经做了什么，还差什么，下一步该谁？” |
+| 处理决定 | “有什么需要我拍板？把证据一起给我。” |
+| 排查中断 | “这次运行卡住了吗？核对现场后处理恢复。” |
+| 准备换会话 | “把关键上下文落盘，核对哪些工作还在运行。” |
 
-存量项目的紧凑布局会把脚本、指挥台和版本标记放进 `pm/`。`standards/` 与 `pm/adr/` 两个可选目录不属于默认骨架；具体规则见 `SKILL.md` §3/§8。
+BuildBeat 适合持续迭代、经常切换 AI 上下文、需要多角色协作与可核验交付记录的项目。个人可以连续推进自己的工作，团队也可以通过共享记录接力。一次性脚本和很小的修改通常无需完整工作流。项目应有真实验证命令，或先建立最小验证能力。
 
-## 能力与依赖
-
-| 能力 | 依赖 | 缺失时 |
-|---|---|---|
-| 文件总线和基础检查 | Git、Bash | 无法使用核心流程 |
-| 真渲染设计预览 | Python 3 | 不能使用自带预览脚本 |
-| Secret 提交阻断 | gitleaks | 降级为警告，不能声称 Secret gate 已建立 |
-| 生产配置漂移 | `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.21 已独立验证，真实 schema 2 版本增量试点仍由 v1.20 证据支撑；项目 uninstall 继续冻结，Skill/手动等价路径始终保留 |
-
-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)。
-
-## 继续阅读
-
-- [`SKILL.md`](SKILL.md)：方法论与 Bootstrap 的唯一完整入口，§0.5 是 v2 驾驶手册；
-- [`docs/v2/guide/README.md`](docs/v2/guide/README.md)：v2 运行时十件套指南（怎么和会话说话、快速开始、workflow / policy / adapter / worker 合同 / 证据 / 审批 / 从 v1 迁移 / 安全边界 / 恢复）；
-- [`example/`](example/)：虚构「简账」项目一期收尾的协议教学快照（可执行脚本仍引用模板 SSOT）；
-- [`lessons.md`](lessons.md)：真实反模式、根因与解法；
-- [`docs/ROADMAP.md`](docs/ROADMAP.md)：新版产品方向、设计原则与 2026-08-24 生效的 CLI 执行修订；
-- [`docs/EXECUTION-PLAN.md`](docs/EXECUTION-PLAN.md)：当前分阶段工作包、依赖、验收和冻结边界；
-- [`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.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、活跃多仓投影和真实单仓代码树上的只读试点；
-- [`docs/PHASE2-PILOT-2026-08-25.md`](docs/PHASE2-PILOT-2026-08-25.md)：Wave 1 三条真实目录写路径、Tide 保护摘要、UI 探测反馈与最终本地 Git/Hook/hash 证据；
-- [`docs/PHASE2-BUILDBEAT-PILOT-2026-08-25.md`](docs/PHASE2-BUILDBEAT-PILOT-2026-08-25.md)：BuildBeat canonical namespace 的新真实目录回归、Tide 保护复核与 Gate3 关闭证据；
-- [`docs/PHASE4-V1.20-PILOT-2026-08-25.md`](docs/PHASE4-V1.20-PILOT-2026-08-25.md)：schema 2 真实版本增量升级、项目所有权保护与真实多仓只读刷新证据；
-- [`docs/PHASE4-STABILITY-AUDIT-2026-08-25.md`](docs/PHASE4-STABILITY-AUDIT-2026-08-25.md)：演进书 §15 的 12 条硬门槛现状、证据边界与未关闭发布阻塞；
-- [`docs/RELEASING.md`](docs/RELEASING.md)：npm 发布 Gate、验证与 Trusted Publishing 迁移；
-- [`CONTRIBUTING.md`](CONTRIBUTING.md)：贡献、验证和 PR 边界；
-- [`SECURITY.md`](SECURITY.md)：支持版本与私密漏洞报告通道；
-- [`CHANGELOG.md`](CHANGELOG.md)：版本历史和拷出项目升级说明。
-
-## 贡献
-
-欢迎 Issue 和 Pull Request。完整提交规则见 [`CONTRIBUTING.md`](CONTRIBUTING.md)；未公开漏洞请勿发公开 Issue，按 [`SECURITY.md`](SECURITY.md) 私密报告。修改流程语义时，请同时更新 `SKILL.md`、相关模板、中文/英文 README、示例和 CHANGELOG，并说明：
-
-1. 解决了哪个真实失败模式；
-2. 如何复现；
-3. 哪些自动化检查证明没有回归。
-
-提交前至少运行：
-
-```bash
-bash -n templates/scripts/*.sh tests/*.sh
-npm test
-npm run test:scripts
-npm run test:skill-only
-npm run check:docs
-npm run pack:check
-git diff --check
-```
+团队协作使用共享 Git 仓库与项目约定。BuildBeat 不提供独立的多人账号、角色/权限管理；不采集或上传项目使用数据，没有遥测采集。你配置的 AI 工具和通知服务有各自的数据处理方式。更完整的日常话术见 [用户指南](docs/v2/guide/00-how-to-talk.md)。
 
-## License
+## 深入了解与贡献
 
-[MIT](LICENSE) © 2026 HaiYangBG
+- [文档总入口](docs/README.md)：当前指南、规范与历史记录。
+- [能力矩阵](docs/CAPABILITY-MATRIX.md)：手工协议、v1 CLI、v2 运行时与插件的能力和验证范围。
+- [跨会话接续](docs/v2/guide/11-session-handoff.md) · [运行恢复](docs/v2/guide/10-recovery.md) · [批准与分诊](docs/v2/guide/07-approval-guide.md)。
+- [Skill](SKILL.md)：会话如何使用 BuildBeat；[lessons](lessons.md)：机制背后的真实事故。
+- [CHANGELOG](CHANGELOG.md) · [贡献指南](CONTRIBUTING.md) · [MIT 许可](LICENSE)。