@haiyangbg/buildbeat 2.0.0-beta.5 → 2.0.1

package/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: buildbeat
-description: BuildBeat（旧称 Solobaton）—— 面向人和 AI 会话的工程交付协议:帮助一个或多个端到端 Builder 通过 Git 文件总线、四个人工 Gate 和可验证证据闭环需求/功能工作包;产品/全栈/测试是可调用的 AI 专业视角,不是人类岗位流水线。包含会话路由/文件总线/三轨/任务包/审批分层/核查门/决策台账/换期压缩仪式/开工护栏脚本/机器闸 pre-commit:gitleaks+bus-check --strict/引导式 Bootstrap:自查代码+少量提问/接管存量项目仪式/已发布 legacy CLI v0 只读证据与源码候选 init/adopt 受控写入、schema 2 机械 upgrade/证据分级 L0-L4。**v2 运行时**(`buildbeat-v2`,由会话调用而非用户手敲):Work 目录 intent/plan digest 绑定接受、隔离 worktree 内 Build→Verify→Review→Fix 自动闭环停在合并决定、overview/inbox/status 回答"到哪了/谁批/卡没卡"、发现分诊与锚定审查、verify 复用、信封与 attempt 自动编号、release-readback 上线回读车道、observe 生产体检、通知出站、gc 打扫。当用户在 AI 会话里说"当前进度/开工/怎么样了/批准/上线/打扫卫生",或要为新的中大型项目搭多会话协作架构、**要给已有的存量老项目套上协作流程(接管)**、提到"BuildBeat/Solobaton/协作总线/Builder/人在回路/多 session 协作/AI 团队流程/项目骨架 bootstrap",或抱怨"多个 AI 会话信息不同步、任务过早结束、审批打断过多、review 过于频繁、验收漏验、文档腐烂、返工螺旋"时使用。
+description: BuildBeat(旧称 Solobaton)—— 面向人和 AI 会话的工程交付工作流,上下文落在项目文件、Git 管理长期事实,支持跨模型、跨工具、跨会话和跨人接续;帮助一个或多个端到端 Builder 用可验证证据闭环需求/功能工作包。**v2 运行时**(`buildbeat-v2`,由会话调用而非用户手敲):Work 目录 intent/plan digest 绑定接受;隔离 worktree 内 Build→Verify→Review→Fix 自动闭环,停在人的合并决定;overview/inbox/status 回答"到哪了/谁批/卡没卡";发现分诊、预算与成本、infra 故障停人、release-readback 上线回读、observe 生产体检、通知出站、gc 打扫。产品/全栈/测试是可调用的 AI 专业视角,不是人类岗位流水线。v1 文件总线/四 Gate/`buildbeat init|adopt|upgrade`(schema 2 机械 upgrade)生命周期命令作为兼容面保留。当用户说"换会话/删旧会话/继续项目/跨工具接手/同事接手/团队接力",或在 AI 会话里说"当前进度/开工/怎么样了/批准/上线/打扫卫生",或要为新项目搭多会话协作架构、给存量老项目套上协作流程(接管),提到"BuildBeat/Solobaton/Builder/人在回路/多 session 协作/AI 团队流程",或抱怨"多个 AI 会话信息不同步、任务过早结束、审批打断过多、review 过于频繁、验收漏验、返工螺旋"时使用。
 ---
 
 # BuildBeat —— 面向人和 AI 会话的工程交付协议
 
 > 蒸馏自一个真实跑了多期迭代的实践:一个人协调 4 个并行 AI 会话,把一个含前端/BFF/多个后端服务/网关/审计的内部产品持续交付。这个案例说明来源,不限定人数;一个 Builder 可用,多个 Builder 也可共享 Git 后按工作包分别闭环。方法论与项目解耦,模板可直接拷贝。
 
+> **会话随时换,项目接着干。** 继续工作所需的上下文落在项目文件中;会话按入口读取同一份目标、决定与证据,由 Loop 推进执行。关闭聊天前补齐未落盘事实;保留活动 Run 的台账与工作树。团队成员按已有权限同步项目文件与候选后可接手,有效的既有决定继续保留;新机器无活动项不代表原机器无 Run。跨成员、跨会话、跨工具和跨机器的具体边界见 [接续指南](docs/v2/guide/11-session-handoff.md)。
+
 ## 0. 何时用 / 不用
 
 - **用**:项目要跑多期迭代,或存在多个仓/部署单元/AI 上下文;一个或多个 Builder 需要让需求、契约、状态、Gate 与证据长期同步。
@@ -15,7 +17,7 @@ description: BuildBeat（旧称 Solobaton）—— 面向人和 AI 会话的工
 ## 0.5 v2 驾驶手册 —— Skill 是入口,CLI 是它调用的引擎
 
 > 绝大多数人在 Claude Code / Codex / Cursor 这类 AI 会话里使用 BuildBeat,而不是亲手敲 `buildbeat-v2`。所以**这一节是给会话读的**:用户说一句人话,会话按下表调命令、读输出、按格式收口。用户不需要知道任何命令;会话不得把命令名当成对用户的要求。§1–§10 是方法论正文,v1 文件总线(`pm/NOW.md`、看板、`pm/status/*`)在 v2 项目里已冻结只读,**禁止双写**。
-> 装载方式不变:项目根 `AGENTS.md`(v2 模板 [templates/v2/AGENTS.md](templates/v2/AGENTS.md))被任意会话自动装载,`CLAUDE.md` 只是一行指针。运行时 `npm i -g @haiyangbg/buildbeat@next`,Node ≥ 20;没装 CLI 时本节的"会话背后调什么"一列改为会话手工维护同名文件(`delivery/work/<ID>/` 与 `decisions.jsonl`),方法论不因此失效。
+> 装载方式:项目根 `AGENTS.md`(v2 模板 [templates/v2/AGENTS.md](templates/v2/AGENTS.md))按所用工具的方式装载——多数 AI 编程工具自动读根目录 `AGENTS.md` 或 `CLAUDE.md`(后者只是一行指针);不自动读的工具由用户开场贴给会话。运行时 `npm install --global @haiyangbg/buildbeat@latest`(2.0.0 起 `latest` 即 v2,预发布才用 `@next`),Node ≥ 20。**没装 CLI 时**本节的"会话背后调什么"一列退化为会话手工维护同名文件(`delivery/work/<ID>/` 与 `decisions.jsonl`):工件协议照用,但自动闭环、隔离 worktree、digest 绑定批准校验、预算与恢复都不存在,会话不得把手工维护表述成等价能力。
 
 > 给用户看的完整版(按项目阶段:未开始 → 立项定方案 → 准备执行 → 执行推进 → 验收合并 → 上线 → 完结换期复盘)在 [docs/v2/guide/00-how-to-talk.md](docs/v2/guide/00-how-to-talk.md);用户问"我该怎么说"时把它给用户,不要复述命令。
 
@@ -23,12 +25,13 @@ description: BuildBeat（旧称 Solobaton）—— 面向人和 AI 会话的工
 
 | 用户说 | 会话背后调什么 | 会话回给用户什么 |
 |---|---|---|
+| 「换会话」「删旧会话」「继续这个项目」「同事接手」 | 按 [接续指南](docs/v2/guide/11-session-handoff.md) 核对项目入口、Work、Git、`overview` / `inbox` / `status`;离开前补齐未落盘事实,接手后区分活动 Run / 中断 / 待批 / 终态 | 「已保存哪些上下文、工作停在哪、下一步」;不把删聊天当删工作树,不重启仍活动的 Run,不伪造或代批决定 |
 | 「当前进度」「待办是什么」「X 上线了吗」「离上线还差多远」 | `buildbeat-v2 overview --repo .`(每个 Work 的阶段 + 下一步该谁 + `cost:` 已花的 Run/review 轮/等人次数/worker 时长)+ `observe status --repo .` | 每件事一句:走到哪、卡在谁、下一步;**不列命令**;花费超过 intent 止损线的 Work 要主动说「已 N 轮 review / N 小时,继续还是砍」 |
 | 「有什么要我拍板」 | `buildbeat-v2 inbox --repo .` | 逐项:等什么、证据在哪、推荐 A/B;用户回「批准/拒绝」后会话调 `approve`/`reject` |
 | 「开个 Work:〔目标〕」 | 写 `delivery/work/<ID>/intent.md`(为什么做 + **止损线**:最多几个 Run / 几轮 review / 几小时,越线先问人)+ `plan.md`(怎么做)+ `run-config.yaml`(`budgets.reviewRoundsPerWork` 对应止损线);给用户看摘要 | 「看完说接受」;用户说「接受」→ `accept --artifact intent` / `--artifact plan`(digest 绑定) |
 | 「开工」「再来一轮」 | 先 `buildbeat-v2 doctor --config <run-config.yaml>`(会报本仓 intent/plan 是否存在且已接受、哪条 policy 会把 start 挡在哪步、每步预算),再 `start --config <run-config.yaml> --attempt new`(自动编号 RUN-X-01/02…,自动作废同 Work 的旧等待;**用 nohup/setsid 脱离启动**) | 「已起 RUN-X-02,停在合并决定时会通知/我会告诉你」 |
 | 「怎么样了」「卡住了吗」「正常吗」 | `buildbeat-v2 status --repo . --run <RUN>` | 一句:在跑第几步、跑了多久、历史通常多久、最后一次输出几分钟前;`STALLED` 就说「疑似卡住,建议停/等」;停在 kind `infra` 就说「worker 环境/后端故障,不是代码问题,恢复后我重跑,预算不扣」 |
-| 「批准 RUN-X」「拒绝,原因…」 | `approve --transition <t> --by <用户名>` / `reject --reason` → 若非终态再 `resume` | 「批准=merge-ready;合并/push/部署要你另说」 |
+| 「批准 RUN-X」「拒绝,原因…」 | 先看 `inbox` 该 Run 等的是哪条 transition,再 `approve --transition <t> --by <用户名>` / `reject --reason`;非终态转换(`enter-fix` / `resume-<step>` / `enter-review`)批准后再 `resume --config <cfg>` 续跑 | 说清批的是哪一步:「放行 fixer,续跑中」/「再跑一次,续跑中」/「合并决定已落,候选 <sha> 具备合并条件;合并/push/部署要你另说」。`SUCCEEDED` 不等于已合并 |
 | 会话自己在 Run 的 worktree 里把 finding 修完并提交了(Run 停在 enter-fix / resume-fix) | `resume --config <cfg> --adopt <sha> --by <会话名>`(跳过 fixer,从 verify 续跑;树必须干净、HEAD 必须是该 sha) | 「我已手修并提交 <sha>,验证重跑中」;**不要**为了让 fixer 空跑而 approve enter-fix |
 | 「这条 finding 不算,那条接受」 | `findings list` / `findings adjudicate --action dismiss|accept` → `approve --transition enter-fix` | 裁决结果一句 |
 | 「上线」「做生产动作」 | 用 `release-readback` 预设 + `riskPreset: release` 开 Run:preflight 回读 → 停 `enter-apply-readback` | 「回读全绿,现在轮到你做〔动作〕;做完说一声」→ 用户说「做完了」→ `approve enter-apply-readback` → 回读+观察 → 停关窗 |
@@ -50,25 +53,32 @@ description: BuildBeat（旧称 Solobaton）—— 面向人和 AI 会话的工
 ```yaml
 repo: ../../..
 work: WORK-X
-run: RUN-X                 # 家族名;start --attempt new 自动编成 RUN-X-01/02…
-workflow: <buildbeat>/src/v2/presets/software-delivery.yaml
-riskPreset: standard       # fast | standard | controlled | release(配 release-readback 预设)
+# 家族名;start --attempt new 自动编成 RUN-X-01/02…
+run: RUN-X
+# 从 $(npm root -g)/@haiyangbg/buildbeat/src/v2/presets/software-delivery.yaml 复制到本目录
+workflow: workflow.yaml
+# fast | standard | controlled | release(配 release-readback 预设)
+riskPreset: standard
 entry: build
 allowedPaths:
   - src
   - tests
-reviewTriage: required     # P0/P1 先过人分诊再派 fixer
-budgets:                   # 可省;run 配置 > 预设 > 默认。预算耗尽停人时,批准 resume-<step> 即多给一次
+# P0/P1 先过人分诊再派 fixer
+reviewTriage: required
+# 可省;run 配置 > 预设 > 默认。预算耗尽停人时,批准 resume-<step> 即多给一次;
+# reviewRoundsPerWork 跨本 Work 所有 Run 累计 review 轮数,超了新 Run 起跑前先问人
+budgets:
   maxAttempts:
     review: 2
-  reviewRoundsPerWork: 6   # 跨本 Work 所有 Run 累计的 review 轮数;超了新 Run 起跑前先问人
+  reviewRoundsPerWork: 6
+# 同树+同命令+同信封已通过就复用证据(标 REUSED)
 cache:
-  verify: tree             # 同树+同命令+同信封已通过就复用证据(标 REUSED)
+  verify: tree
+# prompts/<component>-<worker>.md 或 <worker>.md;内核喂给 worker($BUILDBEAT_PROMPT)。冻结信封时加 pin: <meta 提交 sha>
 envelope:
-  prompts: prompts         # prompts/<component>-<worker>.md 或 <worker>.md;内核喂给 worker($BUILDBEAT_PROMPT)
+  prompts: ../../envelope/prompts
   vars:
     component: auth
-  # pin: <meta 提交 sha>    # 冻结信封时钉住
 requires:
   - command: node
     min: "20"
@@ -76,20 +86,47 @@ requires:
     expect: PONG
     name: redis-reachable
 redact:
-  - "(?i)(token|secret|password)=[^\\s]+"
+  - "(token|secret|password|TOKEN|SECRET|PASSWORD)=\\S+"
+# worker.sh 与三份 prompt 从 templates/v2/envelope/ 拷到仓级 delivery/envelope/;换工具只改 -- 后面的命令
 workers:
   builder:
-    command: codex
-    args: [exec, -s, workspace-write, "按 $BUILDBEAT_PROMPT 实施,改动后 git commit"]
+    command: bash
+    args:
+      - delivery/envelope/worker.sh
+      - builder
+      - --
+      - codex
+      - exec
+      - -s
+      - workspace-write
   verifier:
     command: bash
-    args: [-lc, "npm test"]
+    args:
+      - -lc
+      - npm test
   reviewer:
-    command: codex
-    args: [exec, -s, read-only, "只读审查;若 BUILDBEAT_INPUT 里有 lastReviewed 只看 range 内 diff;JSON 信封写入 $BUILDBEAT_OUTPUT"]
+    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
 ```
 
-(严格 YAML 子集:上面为省行用了行内 `[]`,实际文件要写成块列表。)通知通道另放 `.buildbeat/notify.yaml`(URL 只能来自环境变量),见 [docs/v2/guide/07-approval-guide.md](docs/v2/guide/07-approval-guide.md);十件套指南索引 [docs/v2/guide/README.md](docs/v2/guide/README.md)。
+(严格 YAML 子集:只有块列表与块映射,没有行内 `[]` / `{}`,**注释必须独占一行**;上面这份可原样解析,机器验证在 `tests/v2-templates-firstrun.test.js`。**`fixer` 不能省**:没配它,verify 失败或 review 阻断时 Run 停 `WAITING_HUMAN` 等人手修,不会自动修。完整样板 [templates/v2/run-config.example.yaml](templates/v2/run-config.example.yaml),信封 [templates/v2/envelope/](templates/v2/envelope/worker.sh)。)通知通道另放 `.buildbeat/notify.yaml`(URL 只能来自环境变量),见 [docs/v2/guide/07-approval-guide.md](docs/v2/guide/07-approval-guide.md);十件套指南索引 [docs/v2/guide/README.md](docs/v2/guide/README.md)。
 
 **第一次为一个项目写 run-config 时,会话要多问用户一句**:「Run 停下来等你批、跑完、或疑似卡住时,要不要推到钉钉/webhook?给我一个只放在环境变量里的 URL 就行」——试点一直没启用通知,一张合并卡就绪后隔夜等了 9.5 小时。用户说不要就记一句「通知未启用,等待只在 inbox 里」。
 
@@ -307,10 +344,22 @@ Gate1 规格(人批) → Gate2 设计(人对着真渲染原型批) → 实现+
 
 ## 8. Bootstrap 新项目(引导式:自查 → 少量提问 → 确认 → 生成)
 
+### 8.0 先认项目形态,再选路(2.0.0 起默认 v2)
+
+收到「用 BuildBeat 开始 / 搭骨架 / 套流程」类请求,**先看目录再说话**,按下表路由,不问用户"要 v1 还是 v2":
+
+| 目录里有什么 | 形态 | 走哪条路 |
+|---|---|---|
+| `delivery/work/` 或 `.buildbeat/` | 已是 v2 项目 | 不再 Bootstrap;直接 §0.5:`buildbeat-v2 overview --repo .` 开场 |
+| `pm/NOW.md` 且没有 `delivery/` | v1 文件总线项目 | 给用户两句话:继续 v1(§8.2 / §8.5 旧流程原样可用)或迁到 v2([迁移指南](docs/v2/guide/08-migration-v1.md):升级 CLI 与迁移项目状态是两件事);用户不选就先不动,只做当前请求 |
+| 两者都没有 | 新项目或未接入的存量项目 | **默认 v2**:先按 §8.1 自查与少量提问(0→1)或 §8.5 步骤 1–4 摸底与划边界(10→N),再走 §8.3 v2 生成 checklist。用户明确说要 v1 文件总线(多仓 pm 看板、契约同步护栏是刚需)才走 §8.2 |
+
+v2 的自动闭环、隔离 worktree、digest 绑定批准都要 `buildbeat-v2` 在 PATH 上;没装时先装 `npm install --global @haiyangbg/buildbeat@latest`,装不了就明说"只能手工维护工件协议,没有自动闭环"(§0.5 开头),不得把手工路径说成等价能力。
+
 > 🔴 收到「搭骨架 / 用 BuildBeat 起项目」类请求时,流程 = **先自查代码 → 只问查不到的 → 一屏确认 → 生成**;不许直接拷模板留 `<占位符>` 让用户手改,也**不许把看代码就能搞清的事拿去问用户**。
 > **提问三原则:① 能从代码/配置查到的不问;② 问就问不懂技术的人也能答的话**(话术不出现"仓/部署单元/契约/CLI"这类词,能给选项就不开放问);**③ 合并一次问完(常规 3 问,查到有 UI 时 +1),不连环追问**。有 AskUserQuestion 类工具就用,没有就在对话里问;用户说「你定 / 随便」就取默认值,并在收尾报告标注。
 >
-> **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 或替业务项目批准发布。
+> **v1 生命周期 CLI 是确定性机械层,不是 Bootstrap 替身;它生成的是 v1 文件总线骨架,不生成 v2 的 `delivery/`。** 只在 §8.0 路由到 v1 时使用。Canonical npm 入口 `@haiyangbg/buildbeat@latest`(同包内含 `buildbeat` 与 `buildbeat-v2`)；先运行 `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 先自查,后提问
 
@@ -340,7 +389,7 @@ Gate1 规格(人批) → Gate2 设计(人对着真渲染原型批) → 实现+
 
 > **可选规范默认不生成。** `standards/` 缺失是合法状态,不增加提问预算;只有用户在同一屏确认中选择启用,才创建相应文件。STACK 首次生成保持 `Status: Draft`,Node/lockfile/Docker 可核对基线和人类声明一起被明确确认后才改 `Confirmed`;不能观测不等于 `n/a`。DESIGN 只在识别到 UI/视觉/交互交付时建议。ADR 只在 `templates/pm/adr/README.md` 的五项判据命中时按需创建,不随骨架批量生成。
 
-### 8.2 生成 checklist(确认过后由 agent 执行)
+### 8.2 v1 文件总线生成 checklist(仅 §8.0 路由到 v1 时;确认过后由 agent 执行)
 
 ```
 - [ ] 1. 默认只生成基础骨架并排除可选 `standards/` 与 `pm/adr/`。源码候选优先走“`init/adopt --dry-run` → 一屏确认 → apply”受控路径,随后按 `pendingPlaceholders` 填完项目事实；CLI 不可用时,手动等价路径为 `rsync -a --exclude '/standards/' --exclude '/pm/adr/' templates/ <新项目根>/`(会保留隐藏 `.claude/`;若无 rsync,先在新建的空 staging 中 `cp -R templates/.` 后排除可选目录,再拷到目标,不得对非空项目盲删)。**基础交付物的 <占位符> 最终必须按自查+确认结论填好**;`BUILDBEAT.md` 填拷入版本。用户选择启用的 optional 文件单独从模板生成:STACK 先留 `Status: Draft`,DESIGN 仅 UI 项目创建;未启用即不存在
@@ -356,10 +405,25 @@ Gate1 规格(人批) → Gate2 设计(人对着真渲染原型批) → 实现+
 
 > 各文件「填好之后长什么样」,参照仓库 [example/](example/)(虚构「简账」项目跑完一期的快照)。
 
+### 8.3 v2 生成 checklist(默认路径;确认过后由 agent 执行)
+
+```
+- [ ] 1. 装载入口:`templates/v2/AGENTS.md` → 项目根 `AGENTS.md`(填项目名、边界、视角路由;单仓项目删多仓相关行),`templates/v2/CLAUDE.md` → `CLAUDE.md`(一行指针,不复制内容),`templates/v2/指挥台.md` → `指挥台.md`,`templates/v2/BUILDBEAT.md` → `BUILDBEAT.md`(填运行时版本与日期)。`templates/gitignore.template` → `.gitignore`(已排除 `.buildbeat/runtime/` 与 `.buildbeat/worktrees/`;有测试框架的项目另配 exclude,见 Workflow 指南)
+- [ ] 2. 台账:`templates/pm/decisions.md` → `pm/decisions.md`(纯 v2 项目也只建这一个 v1 文件,记平台级决策包);多仓才建 `contracts/PROTOCOL.md`。**不建** `pm/NOW.md`、看板、`pm/status/`,不装 `bus-check`
+- [ ] 3. 信封:`templates/v2/envelope/` 整目录 → `delivery/envelope/`(worker.sh + builder / reviewer / fixer prompt);按项目补 prompt 里的环境事实(§0.5.3 末尾三条)。这一步进 Git,worktree 里才有
+- [ ] 4. 第一个 Work:`delivery/work/<WORK-ID>/` 写 `intent.md`(为什么 + 止损线)、`plan.md`;`templates/v2/run-config.example.yaml` → `run-config.yaml`(改 work / run / allowedPaths / 把 `--` 后的工具命令换成用户实际用的);`$(npm root -g)/@haiyangbg/buildbeat/src/v2/presets/software-delivery.yaml` → `workflow.yaml`
+- [ ] 5. 通知(问一句,§0.5.3):要就写 `.buildbeat/notify.yaml`,URL 只能来自环境变量;不要就在收尾说明"等待只在 inbox 里"
+- [ ] 6. 机器闸:各代码仓 `cp templates/scripts/pre-commit.sh .git/hooks/pre-commit`,只保留 gitleaks 那道(v1 的 bus-check --strict 一道在纯 v2 仓会因缺 `pm/NOW.md` 直接跳过);`command -v gitleaks` 查无则提醒安装
+- [ ] 7. 首跑验收:用户说「接受」→ `accept --artifact intent` / `plan`;`buildbeat-v2 doctor --config …` 全段读一遍(intent/plan 接受状态、env 姿态、预算、start 会停在哪);`start --config … --attempt new`(脱离启动)→ 停 `WAITING_HUMAN`;`overview` / `status` 把候选、verify 退出码、findings 读给用户。**这一次 Run 停在合并决定之前,不宣布"接入完成"**
+- [ ] 8. 收尾一屏:生成了什么 / 默认拿主意的项 / 首跑停在哪、证据在哪 / 下一步由谁做(合并是人的动作)
+```
+
+> 可核对的样例:`tests/v2-templates-firstrun.test.js` 用脚本 worker 代替真实模型,从上面的模板走到合并决定(含一次 verify 失败→fixer→重验)。它证明包内路径、配置、信封、提交机制、reviewer 信封连得上;不证明某个真实模型能完成业务任务。
+
 ## 8.5 接管存量项目(10→N 入口:先摸底、划边界、补验证)
 
 > §8 假设从零起步;公司里大多数项目是**存量**的,两类项目的成本结构相反:0→1 的瓶颈是需求不确定,10→N 的瓶颈是**理解成本 ≫ 编写成本**、改坏的损失 ≫ 改对的收益。收到「给现有项目上 BuildBeat」类请求走本节,别拿 §8 硬套;提问三原则(§8)同样适用。
-> 先跑 `node bin/buildbeat.js adopt <项目根> --dry-run --json`:已发布 legacy v0 只给只读计划；当前源码候选在一屏确认后可受控 apply,默认生成紧凑布局并列出/拒绝碰撞。两者都不会判断绞杀者边界、危险区或 L3 是否充分,这些仍按下方仪式核实和拍板；apply 后继续消费 `pendingPlaceholders`,不能把机械落盘当成接管完成。
+> 摸底与划边界(步骤 1–4)与协议版本无关,都要做。只在 §8.0 路由到 v1 时才跑 `npx --yes --package=@haiyangbg/buildbeat@latest buildbeat adopt <项目根> --dry-run --json`(一屏确认后可受控 apply,默认紧凑布局并列出/拒绝碰撞);它不判断绞杀者边界、危险区或 L3 是否充分,这些仍按下方仪式核实和拍板;apply 后继续消费 `pendingPlaceholders`,不能把机械落盘当成接管完成。
 > v1.16 拷出项目若没有 CLI 真实写入的 schema 2 manifest，`upgrade` 必须 blocked；不得手写 manifest、复制 `example/.buildbeat/manifest.json`、重命名 `.solobaton` 文件，或用当前文件 hash 伪造安装基线。默认继续手工维护；只在项目所有者明确批准时，按 [v1.16 legacy 迁移指南](docs/LEGACY-V1.16-MIGRATION.md) 在专用 Git 分支重建基线。
 
 ```
@@ -373,10 +437,11 @@ Gate1 规格(人批) → Gate2 设计(人对着真渲染原型批) → 实现+
         没有这一步,证据分级给不出 L3,后面所有 Gate 都在空转
 - [ ] 4. 产出分层 AGENTS.md:根一份(路由 + 新旧边界)+ 各业务模块一份(模块地图,给 AI 会话降理解成本)。
         靠标准的「向上合并、就近优先」层叠:改哪个模块只额外装载哪份,根文件因此能保持精简
-- [ ] 5. 骨架用**紧凑布局**(§3):`templates/scripts/` 整树拷成 `pm/scripts/`,`指挥台.md` 与 `BUILDBEAT.md` 拷进 `pm/`。
+- [ ] 5. 骨架默认 v2(§8.3 步骤 1–3):`AGENTS.md` 根一份写新旧边界与危险区,各模块一份地图;`delivery/envelope/` 的 builder / fixer prompt 里写明"老地盘只维护、改动一律先问人"。
+        用户明确要 v1 文件总线时改用**紧凑布局**(§3):`templates/scripts/` 整树拷成 `pm/scripts/`,`指挥台.md` 与 `BUILDBEAT.md` 拷进 `pm/`;
         脚本自定位不用改;要改的是文档里的调用路径——`AGENTS.md`、`pm/NOW.md`、`指挥台.md`、`pm/当期看板.md`、`contracts/PROTOCOL.md`、`ARCHITECTURE.md` 六处,
         改完 `grep -rn 'scripts/' <项目根> --include='*.md'` 复核:只该剩 `pm/scripts/` 与项目自己的 `scripts/`
-- [ ] 6. 之后按 §8.2 步骤 2-9 走(骨架/机器闸/第一期立项);一期起步的优先级:补测试 > 机械重构 > 新功能
+- [ ] 6. 之后 v2 按 §8.3 步骤 4-8 走(第一个 Work = 第 3 步的最小验证套件,`allowedPaths` 只放新地盘与 tests);v1 按 §8.2 步骤 2-9 走。一期起步的优先级:补测试 > 机械重构 > 新功能
 ```
 
 存量项目已有自定义 standards/ADR 时只读摸底并保留项目所有权,不得用上游模板覆盖。项目没有这些文件时仍默认不生成;若用户在接管确认屏选择启用,先用现有配置起草 STACK `Draft`,UI 项目才建议 DESIGN,长期不可逆决定才建 ADR。
@@ -385,8 +450,11 @@ Gate1 规格(人批) → Gate2 设计(人对着真渲染原型批) → 实现+
 
 | 模板 | 用途 |
 |---|---|
-| [templates/v2/AGENTS.md](templates/v2/AGENTS.md) / [templates/v2/指挥台.md](templates/v2/指挥台.md) | **v2 项目用这两份**:一页流程 + 视角路由 + 十一条规则(含可见命名进决策卡)+ 红线;指挥台是"用户一句话 → 会话调什么"的操作卡 |
-| [templates/AGENTS.md](templates/AGENTS.md) | v1 工作区路由 + 十条规则 + 红线(开放标准,每会话自动装载) |
+| [templates/v2/AGENTS.md](templates/v2/AGENTS.md) / [templates/v2/指挥台.md](templates/v2/指挥台.md) | **v2 项目装载入口**:一页流程 + 视角路由 + 十一条规则(含可见命名进决策卡)+ 红线;指挥台是"用户一句话 → 会话调什么"的操作卡 |
+| [templates/v2/CLAUDE.md](templates/v2/CLAUDE.md) / [templates/v2/BUILDBEAT.md](templates/v2/BUILDBEAT.md) | v2 项目的一行指针与版本标记(运行时版本、装载方式、v1 遗留冻结状态、升级 = 升级 CLI) |
+| [templates/v2/run-config.example.yaml](templates/v2/run-config.example.yaml) | 可原样解析的 run 配置样板(含 fixer、reviewTriage、budgets、cache、envelope、redact);机器验证见 `tests/v2-templates-firstrun.test.js` |
+| [templates/v2/envelope/worker.sh](templates/v2/envelope/worker.sh) + [prompts/](templates/v2/envelope/prompts/builder.md) | worker 包装(工具缺失 exit 75、喂 prompt、写入步机械 commit、只读步落信封)与 builder / reviewer / fixer 三份 prompt;拷到仓级 `delivery/envelope/` |
+| [templates/AGENTS.md](templates/AGENTS.md) | v1 工作区路由 + 十条规则 + 红线(开放标准,按工具装载) |
 | [templates/CLAUDE.md](templates/CLAUDE.md) | 一行指针 → `AGENTS.md`(兼容只认此名的工具;🔴 不复制内容) |
 | [templates/ARCHITECTURE.md](templates/ARCHITECTURE.md) | 全栈总图骨架(架构/基础设施/凭据位置/子项目索引) |
 | [templates/指挥台.md](templates/指挥台.md) | 给人看的一页操作卡 |
@@ -410,7 +478,7 @@ Gate1 规格(人批) → Gate2 设计(人对着真渲染原型批) → 实现+
 > 5 个 `.sh` 自己定位协调层根(向上找 `pm/NOW.md`),整树搬到 `pm/scripts/` 即得 §3 紧凑布局,脚本本身不用改。同伴脚本(`live-status.sh` / `live-config.sh`)要和它们放同一目录。
 >
 > 仓库级 CLI 的命令、exit code、schema 1 兼容/三策略 schema 2 文件所有权、机械 upgrade 与手动移除边界见 [docs/CLI.md](docs/CLI.md)。CLI 与 Skill 共用同一协议,但职责不同:Skill 做代码级理解与人 Gate,CLI 只做确定性生命周期机械动作;项目 `uninstall` 命令继续冻结。
-> Skill-only / 已发布 npm v0 / 当前本地源码候选的可用面、CLI 三组生命周期入口和双向互操作证据见 [docs/CAPABILITY-MATRIX.md](docs/CAPABILITY-MATRIX.md)。
+> Skill-only 手工路径 / v1 生命周期 CLI / v2 运行时 / Claude 插件各自的可用面、CLI 三组生命周期入口和双向互操作证据见 [docs/CAPABILITY-MATRIX.md](docs/CAPABILITY-MATRIX.md)。
 > legacy v1.16 项目的所有权分类、受控 rebaseline 步骤、回退和证据边界见 [docs/LEGACY-V1.16-MIGRATION.md](docs/LEGACY-V1.16-MIGRATION.md)。
 
 ## 10. 反模式与实战教训

package/docs/CAPABILITY-MATRIX.md

@@ -1,6 +1,17 @@
 # BuildBeat 能力矩阵 / Capability Matrix
 
-> 状态：BuildBeat v1.21 scoped 分发合同（2026-08-25）。本页同时区分 Skill-only、legacy npm v0 和 BuildBeat 1.21；源码、registry artifact 与真实项目证据仍分别核验。
+> 状态：BuildBeat `@haiyangbg/buildbeat@2.0.0`（dist-tag `latest`，2026-09-05）。本页按**产品层次**区分四个可用面：Skill-only 手工路径、v1 生命周期 CLI（`buildbeat`）、v2 运行时（`buildbeat-v2`）、Claude Code 插件；并保留 v1.21 分发合同的原始条目与 legacy npm v0 的边界。源码、registry artifact 与真实项目证据仍分别核验。
+
+## 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` 实证；其他工具"可通过命令接入"，未逐一验证） |
+| **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。
 
 ## 1. 三组生命周期入口
 
@@ -14,9 +25,11 @@ WP4.2 所说的“CLI 三命令”按职责分成三组，不是把 `version`
 
 `buildbeat version` 是纯信息工具。`diff` 与 `uninstall` 仍只是返回 `command_not_available` 的保留名；`check/status/gate/adr/standards` 属于 Skill 与项目脚本，不进 CLI。`solobaton` 是 legacy 可执行兼容别名，不是第四组能力。
 
-## 2. 可用面与权威边界
+## 2. v1 生命周期面：Skill-only / legacy v0 / `buildbeat`
 
-| 能力 | Skill-only / 手工路径 | legacy `solobaton@1.16.3` | BuildBeat `@haiyangbg/buildbeat@1.21.0` | 权威与边界 |
+本节是 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` |
@@ -30,6 +43,23 @@ WP4.2 所说的“CLI 三命令”按职责分成三组，不是把 `version`
 | 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` | 权威与边界 |
+|---|---|---|---|
+| 工件接受 | 会话记一行到 `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 是配置的任意命令，内核不内置模型 |
+| 进度与等待 | 会话读目录 | `overview`（每 Work 阶段 / 下一步 / 成本）、`inbox`（等人的 Run + 下一句命令）、`status`（步、耗时、STALLED、证据、findings）、`metrics` | 全部只读；本机绝对路径不进输出 |
+| 人批 | 会话记一行 | `approve --transition <t>` / `reject`：绑定 transition + candidate + planDigest + evidenceDigest，盖章前重读实况；非终态转换后 `resume` | 合并决定 = 候选具备合并条件；合并 / push / 部署无调用路径（不变量 20） |
+| 发现分诊与锚定 | 无 | `reviewTriage: required` + `findings list / adjudicate`；reviewer 输入带历史裁决 `anchor` | dismiss 后同指纹不阻断；严重度升级 = 新指纹 |
+| 预算与成本 | 无 | 每步 `maxAttempts`、Work 级 `reviewRoundsPerWork`、`BUDGET_EXTENDED` 续批、`overview` 的 `cost:` 行 | 预算耗尽是停人不是失败 |
+| 故障与恢复 | 无 | timeout / crash / invalid-output / exit 75 判 `infra` 停人不扣预算；`resume`（含 `--adopt <sha>`）；`replay` 校验台账；`gc` 清工作树 | 重启后可能重跑未落账的步；台账人工改过不保证可重建 |
+| 上线回读 | 手工记录 | `release-readback` 预设 + `riskPreset: release`：preflight 回读 → 人做 → apply 回读 → observe → 关窗 | 生产动作永远在 Runner 之外 |
+| 生产体检 | 无 | `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. 双向互操作结论
 
 | 转换 | 结论 | 已验证 | 不可外推 |
@@ -43,8 +73,9 @@ WP4.2 所说的“CLI 三命令”按职责分成三组，不是把 `version`
 
 - **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 1.21:** `@haiyangbg/buildbeat@1.21.0` is the independently verified canonical scoped distribution. 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.
+- **BuildBeat 2.0.0 (current `latest`):** `@haiyangbg/buildbeat@2.0.0` ships the unchanged v1 lifecycle CLI `buildbeat` and the v2 runtime `buildbeat-v2` in one package (evidence: [`V2.0.0-RELEASE-EVIDENCE-2026-09-05.md`](V2.0.0-RELEASE-EVIDENCE-2026-09-05.md)). 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.
 - **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 agent runtime.
+- **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.
 
-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). Command details remain authoritative in [`CLI.md`](CLI.md); legacy migration uses [`LEGACY-V1.16-MIGRATION.md`](LEGACY-V1.16-MIGRATION.md).
+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).

package/docs/CLI.md

@@ -1,10 +1,19 @@
 # BuildBeat CLI lifecycle contract
 
-Status: **BuildBeat `1.21.0` independently verified scoped distribution** · canonical package `@haiyangbg/buildbeat` · canonical executable `buildbeat` · legacy package `solobaton@1.16.3` remains the independently verified read-only v0 · Node.js 20+ · zero third-party runtime dependencies. The 1.21 release keeps the verified 1.20 lifecycle command and safety boundaries, and adds the standard domain-response contract to the Skill and managed scaffold. The genuine lifecycle version-increment pilot remains archived in [`PHASE4-V1.20-PILOT-2026-08-25.md`](PHASE4-V1.20-PILOT-2026-08-25.md); exact 1.21 registry and supply-chain evidence is archived in [`V1.21-RELEASE-EVIDENCE-2026-08-25.md`](V1.21-RELEASE-EVIDENCE-2026-08-25.md).
+Status: **BuildBeat `2.0.1` scoped distribution (stable `latest`; the v1 lifecycle CLI `buildbeat` is unchanged, the v2 delivery runtime `buildbeat-v2` ships alongside it — see `docs/v2/guide/`)** · previous independently verified stable `2.0.0` · canonical package `@haiyangbg/buildbeat` · canonical executable `buildbeat` · legacy package `solobaton@1.16.3` remains the independently verified read-only v0 · Node.js 20+ · zero third-party runtime dependencies. The 1.21 release keeps the verified 1.20 lifecycle command and safety boundaries, and adds the standard domain-response contract to the Skill and managed scaffold. The genuine lifecycle version-increment pilot remains archived in [`PHASE4-V1.20-PILOT-2026-08-25.md`](PHASE4-V1.20-PILOT-2026-08-25.md); exact 1.21 registry and supply-chain evidence is archived in [`V1.21-RELEASE-EVIDENCE-2026-08-25.md`](V1.21-RELEASE-EVIDENCE-2026-08-25.md).
 
 The CLI does not replace `SKILL.md`. The Skill owns code-aware reasoning, minimal questions, project semantics, and human Gates. The CLI owns deterministic inspection, scaffold mechanics, manifest/hash bookkeeping, and bounded mechanical upgrade in the current scoped distribution. Synchronous file-bus checks remain authoritative in the project-local scripts specified by [`CHECKS.md`](CHECKS.md).
 
-The bilingual [`CAPABILITY-MATRIX.md`](CAPABILITY-MATRIX.md) is the compact authority for what Skill-only, the legacy npm v0, and BuildBeat 1.21 can each do. Command details and safety semantics remain authoritative in this document.
+This document is the contract for the **v1 lifecycle CLI `buildbeat`** only. The v2 delivery runtime `buildbeat-v2` in the same package has its own surface (below) documented in [`v2/guide/`](v2/guide/README.md). The bilingual [`CAPABILITY-MATRIX.md`](CAPABILITY-MATRIX.md) is the compact authority for what Skill-only, the legacy npm v0, the v1 lifecycle CLI, and the v2 runtime can each do. v1 command details and safety semantics remain authoritative in this document.
+
+## Two executables, two jobs
+
+| Executable | Job | Does not do |
+|---|---|---|
+| `buildbeat` | Inspect (`doctor`), scaffold (`init` / `adopt`), and mechanically upgrade (`upgrade`) the **v1 file-bus skeleton** (`pm/`, `contracts/`, `scripts/`); `version` | Does not create `delivery/work/`, run-configs, or Runs; `buildbeat doctor` does not check a v2 run-config (that is `buildbeat-v2 doctor --config`); `buildbeat upgrade` does not migrate Work state |
+| `buildbeat-v2` | Run and query the **v2 delivery loop**: `accept`, `start`, `resume`, `status`, `inbox`, `overview`, `approve`, `reject`, `findings`, `doctor`, `preflight`, `events`, `replay`, `metrics`, `stop`, `gc`, `watch`, `observe` — run `buildbeat-v2` with no arguments for the usage text | Does not scaffold the v1 file bus; never merges, pushes, deploys, or publishes (invariant 20) |
+
+A project may use either or both: pure v2 projects have no `pm/NOW.md` and never run `bus-check`; v1 projects that adopt v2 freeze the file bus read-only ([`v2/guide/08-migration-v1.md`](v2/guide/08-migration-v1.md)).
 
 ## Command boundary and phased availability
 
@@ -47,6 +56,8 @@ The target command whitelist is intentionally small:
 |---|---|---|
 | legacy `solobaton@1.16.3` | `doctor`, `init --dry-run`, `adopt --dry-run`, `version` | independently verified read-only v0; deprecated distribution ID after scoped migration |
 | BuildBeat `1.21.0` | `doctor`, `init`, `adopt`, `upgrade`, `version` | unchanged Phase 0–3 command set; writes remain bounded by the transaction and human-Gate contracts below |
+| BuildBeat `2.0.0` | same `buildbeat` command set; second executable `buildbeat-v2` (run / overview / inbox / status / approve / observe / gc …) | `buildbeat` lifecycle and safety boundaries unchanged; `buildbeat-v2` is the v2 runtime documented in [`v2/guide/README.md`](v2/guide/README.md) and never merges, pushes, deploys or publishes (invariant 20); the managed scaffold version stays `v1.21` (templates unchanged), so `upgrade` reports up-to-date for 1.21 scaffolds; the manifest `cliVersion` is a record, not an upgrade trigger |
+| BuildBeat `2.0.1` | same command sets | patch: run-config `inheritEnv` / `env:` now reach the Shell Adapter through the CLI loader; `templates/v2/` gains `run-config.example.yaml`, `envelope/worker.sh` and prompts; documentation aligned with the parser (worker envelope `severity` + `summary`, P0/P1 block) and with the stable channel; no v1 lifecycle or scaffold change (`v1.21`) |
 
 `help`, `--help`, and `--version` are meta entry points. `diff` and `uninstall` stay reserved and return `command_not_available`; `gate`, `adr`, `standards`, `check`, and other workflow commands are outside the approved CLI scope. HELP text and regression tests must lock this boundary.
 
@@ -128,7 +139,7 @@ Schema 2 is the first write-capable shape targeted by Wave 1:
 {
   "schemaVersion": 2,
   "scaffoldVersion": "v1.21",
-  "cliVersion": "2.0.0-beta.5",
+  "cliVersion": "2.0.1",
   "layout": "default",
   "installedAt": "2026-08-24T00:00:00.000Z",
   "files": {

package/docs/README.md

@@ -0,0 +1,37 @@
+# docs/ 总入口
+
+> 这一页只回答"我该读哪份"。文件按**现行**与**历史**分开：现行文档描述今天的包（`@haiyangbg/buildbeat@latest`，v2 系列）并受 `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) |
+| 关闭旧会话后继续，或由其他成员/工具接手 | [`跨会话接续`](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) |
+| 项目装载入口与信封模板 | [`../templates/v2/`](../templates/v2/AGENTS.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`；带日期的生效修订写在正文顶部） |
+| 发布手册、通道、发布后同步清单 | [`RELEASING.md`](RELEASING.md) |
+| 分支策略、测试分层、文档权威分层 | [`../CONTRIBUTING.md`](../CONTRIBUTING.md)、[`../tests/README.md`](../tests/README.md) |
+| 每条机制背后的真实事故 | [`../lessons.md`](../lessons.md) |
+
+## 历史（保存当时事实，不改原文）
+
+| 类别 | 文件 |
+|---|---|
+| 发布证据 | `V2.0.0-RELEASE-EVIDENCE-2026-09-05.md`（当前 `latest`）、`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) |
+
+历史文件里的版本号、通道与测试数字是它们日期当天的事实，出现"`latest` 留 v1"之类的旧策略是正常的；判断现状只看现行文档与 registry 回读（`npm view @haiyangbg/buildbeat dist-tags`）。

package/docs/RELEASING.md

@@ -2,7 +2,16 @@
 
 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.
 
-Release evidence at source package version `@haiyangbg/buildbeat@2.0.0-beta.5` (pending publication verification); latest independently verified BuildBeat npm distribution `@haiyangbg/buildbeat@2.0.0-beta.4` (dist-tag `next`; `latest` remains `1.21.0`), anchored by annotated tag `v2.0.0-beta.4` at commit `02d1f5a`, workflow run [33460544343](https://github.com/HaiYangBG1/BuildBeat/actions/runs/33460544343), and archived 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 latest stable distribution stays `@haiyangbg/buildbeat@1.21.0`, 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). 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@2.0.1`; latest independently verified BuildBeat npm distribution `@haiyangbg/buildbeat@2.0.0` (dist-tag `latest`; `next` stays `2.0.0-beta.5`), anchored by annotated tag `v2.0.0` at commit `95e780e`, workflow run [33974396871](https://github.com/HaiYangBG1/BuildBeat/actions/runs/33974396871), and 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.
+
+## Channels and branches
+
+| Channel | Source | dist-tag | How |
+|---|---|---|---|
+| Stable | tip of `main` (a release branch → pull request → merge commit → annotated tag `vX.Y.Z` on that commit) | `latest` | `workflow_dispatch` of `publish.yml` with the exact tag; the workflow refuses a tag that is not on `main` for the stable channel |
+| Pre-release | the dispatching release branch (normally `v2`), version `X.Y.Z-beta.N` | `next` | same dispatch; `latest` never moves for a pre-release |
+
+`main` is protected (pull request only, seven required checks, admins included, no force-push); day-to-day work lands on `v2` and reaches `main` through PRs. Since 2.0.0 `latest` is the v2 line; `next` is only for later pre-releases.
 
 ## Release invariants
 
@@ -15,7 +24,7 @@ Release evidence at source package version `@haiyangbg/buildbeat@2.0.0-beta.5` (
 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 the exact 1.21 scoped artifact passed registry/provenance/signature/isolated-install/README readback. The old-name WP2.7 pilots remain historical compatibility evidence and do not redefine the scoped artifact.
+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.
 
 ## Candidate checks
 
@@ -60,7 +69,7 @@ npm publish --access public --tag bootstrap --registry=https://registry.npmjs.or
 npm view @haiyangbg/buildbeat dist-tags --json --registry=https://registry.npmjs.org/
 ```
 
-The intended bootstrap readback is `bootstrap: 0.0.0` without a stable `latest` claim. During the first BuildBeat package creation, npm also attached `latest: 0.0.0` despite the explicit non-default tag and rejected the authenticated delete with HTTP 400. Treat any such first-package `latest` as temporary bootstrap exposure: do not activate launch documentation, do not republish or unpublish the immutable version, and complete the reviewed OIDC release so the real version takes over `latest`. The current BuildBeat readback is `bootstrap: 0.0.0` and `latest: 1.21.0`. The bootstrap package page is registry-creation evidence only: it is not a BuildBeat release, is not tagged in Git, and has no provenance claim. The npm documentation requires 2FA or an allowed granular token for direct publication; no long-lived publish token belongs in Git, shell history, logs, or a chat transcript. See npm's guides for [scoped public packages](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/) and [Trusted Publishing](https://docs.npmjs.com/trusted-publishers/).
+The intended bootstrap readback is `bootstrap: 0.0.0` without a stable `latest` claim. During the first BuildBeat package creation, npm also attached `latest: 0.0.0` despite the explicit non-default tag and rejected the authenticated delete with HTTP 400. Treat any such first-package `latest` as temporary bootstrap exposure: do not activate launch documentation, do not republish or unpublish the immutable version, and complete the reviewed OIDC release so the real version takes over `latest`. The readback at the time of that first scoped release (2026-08-25) was `bootstrap: 0.0.0` and `latest: 1.21.0`; since 2026-09-05 `latest` is `2.0.0` and `next` is `2.0.0-beta.5` (see the current-state paragraph at the top of this runbook). The bootstrap package page is registry-creation evidence only: it is not a BuildBeat release, is not tagged in Git, and has no provenance claim. The npm documentation requires 2FA or an allowed granular token for direct publication; no long-lived publish token belongs in Git, shell history, logs, or a chat transcript. See npm's guides for [scoped public packages](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/) and [Trusted Publishing](https://docs.npmjs.com/trusted-publishers/).
 
 ## Independent readback
 
@@ -115,3 +124,18 @@ The workflow waits for exact registry-version readback, requires `dist.attestati
 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.
+
+## Post-release synchronization checklist
+
+Publishing the artifact is one surface. These are the others; each has drifted at least once, so tick them in the same sitting as the release (the docs check catches most of them, the two GitHub-side items it cannot):
+
+- [ ] `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.
+- [ ] `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.
+- [ ] GitHub Release marked Latest for a stable release, not for a pre-release.
+- [ ] Claude Code plugin: if `plugins/buildbeat/.claude-plugin/plugin.json` changed, its version bumped and `tests/plugin-marketplace.test.sh` updated; the plugin version is independent of the npm version.
+- [ ] `npm run check:docs` green on the release commit (it enforces the active-document claims above).

package/docs/V2-PLAN.md

@@ -1,5 +1,7 @@
 # BuildBeat v2 终版规划：工件协议 × 确定性内核 × 可恢复 Agent Loop
 
+> **状态更新（2026-09-05）**：本计划的目标已交付——`@haiyangbg/buildbeat@2.0.0` 发布到 `latest`（[`CHANGELOG.md`](../CHANGELOG.md)）。本文件此后是**历史执行基线**，原文不再修改；§8 里"`latest` 留 v1、`next` 发预发布"是 beta 期策略，已按计划结束。现行文档入口见 [`docs/README.md`](README.md)。
+>
 > 文档状态：**正式执行基线**（2026-08-27，项目所有者已拍板 `V2-D0=B`；决策见 [`V2-DECISIONS.md`](V2-DECISIONS.md)）
 > 基线日期：2026-08-27
 > 合并来源：报告 A（[`V2-PROPOSAL.md`](V2-PROPOSAL.md)，产品/方向层）× 报告 B（[《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)，运行时工程层）

package/docs/V2.0.0-BETA.5-RELEASE-EVIDENCE-2026-09-05.md

@@ -0,0 +1,10 @@
+# v2.0.0-beta.5 发布证据（2026-09-05）
+
+> 授权：所有者会话内「发，并且迭代5轮可以直接切换到线上版本了」（发布 + `npm-publish` 环境审批 + 发布后把本机 CLI 从源码链接切回正式包）；流程与 [beta.4](V2.0.0-BETA.4-RELEASE-EVIDENCE-2026-09-03.md) 完全一致。
+
+- 内容：迭代 09「预算是刹车、故障分开算、成本看得见」——预算耗尽后批准 `resume-<step>` 落 `BUDGET_EXTENDED` 多给一次、run 配置 `budgets:` 覆盖预设；worker 基础设施故障（timeout / crashed / invalid-output / exit 75）判 `infra` 停人、不派 fixer、不扣预算，无转移边的失败也停人；`overview` 每个 Work 一行 `cost:`、`budgets.reviewRoundsPerWork` 跨 Run 累计；overview 真相修正（MERGED 压过 CANCELLED、release 车道 `RELEASED`）；`doctor` 读 start 第一道门；`resume --adopt <sha>`；起跑被仓锁挡住时说清在等谁；模板与指南（gitignore 排除运行时/工作树、worker 环境事实、通知询问）；lessons #23–#25。明细见 [`CHANGELOG.md`](../CHANGELOG.md)。
+- 候选：`1d6553d`（`v2` tip），annotated tag `v2.0.0-beta.5`；本地候选门全过：`bash -n` / shellcheck / actionlint、`check:docs`（170 文件）、`test-scripts` 228 断言、pilot 15、plugin 7、skill-only、node 205/205、`pack:check`、`npm publish --dry-run`、gitleaks 无泄漏、`git diff --check`（工作树与 `795190e...HEAD` 区间均干净；上一提交 `69bce32` 曾因 lessons.md 末尾空行让 CI 的 whitespace 检查失败，本批已改掉）；CI run [33972673951](https://github.com/HaiYangBG1/BuildBeat/actions/runs/33972673951) success。发布前回读：registry `next` 仍为 `2.0.0-beta.4`、无 `2.0.0-beta.5`；tag ruleset `Protect release tags` = active。
+- 发布：workflow run [33972774150](https://github.com/HaiYangBG1/BuildBeat/actions/runs/33972774150)（`workflow_dispatch` from `v2`，tag `v2.0.0-beta.5`）双 job success（`Publish v2.0.0-beta.5 to npm` + `Verify v2.0.0-beta.5 from npm`）；`npm-publish` 环境审批按会话授权以所有者 gh 凭据落章，备注引用授权原文。
+- 本地独立回读（直连 registry.npmjs.org，不经镜像）：dist-tags `{bootstrap: 0.0.0, latest: 1.21.0, next: 2.0.0-beta.5}`（`latest` 未动）；`dist.integrity = sha512-BepG2UYo5ZsPwXqY4AntszoSE9lJQETqqnXqyonoHXt9ZJ9TOG2ncPLz1YNzaTWKB61eEulk4aZ2z57lLyi0FQ==`；`dist.attestations.url` 存在；隔离前缀安装 `buildbeat --version = 2.0.0-beta.5`，`buildbeat-v2` usage 含 `resume … --adopt`，`src/v2/runtime/` 含 `work-cost.js`；临时项目 `npm audit signatures` = 1 package has a verified attestation；`buildbeat doctor <空目录> --json` 返回有界 JSON（`cliVersion 2.0.0-beta.5`，`not-installed`），零写入。
+- 切换：所有者本机全局 `buildbeat-v2` 由源码 `npm link` 切回正式包（`npm i -g @haiyangbg/buildbeat@next`），`readlink` 指向全局 `node_modules/@haiyangbg/buildbeat/bin/buildbeat-v2.js`，`buildbeat --version = 2.0.0-beta.5`。
+- 未做：`latest` 仍指 v1.21.0（v2 仍是预发布）；GitHub Release 页未建（与前几个 beta 一致，npm 面为准）。

package/docs/V2.0.0-RELEASE-EVIDENCE-2026-09-05.md

@@ -0,0 +1,11 @@
+# v2.0.0 发布证据（2026-09-05）
+
+> 授权：所有者会话内「正式发布」（发布 + `npm-publish` 环境审批 + GitHub Release 标 Latest + 本机 CLI 切到 `@latest`）；稳定版通道：从 `main` 顶端以稳定 tag 发布到 dist-tag `latest`。
+
+- 内容：与 [2.0.0-beta.5](V2.0.0-BETA.5-RELEASE-EVIDENCE-2026-09-05.md) 同源（迭代 01～09 的 v2 运行时、Skill §0.5、`templates/v2/`、十件套指南、lessons #1–#25），外加 README 中英文「当前主线是 v2」段、`docs/CLI.md` 2.0.0 状态行与里程碑行、CHANGELOG 2.0.0 条目（对拷出项目：v1 生命周期与骨架 `v1.21` 不变）。
+- 路径：`v2` 经 PR #21 以 merge commit `0aa8165` 合入 `main`（main 受分支保护：PR + 7 项 check + admin 强制；用 merge commit 保留 beta tag 的祖先关系）；release 提交在 `release/2.0.0` 经 PR #22 合入，`main` 顶端 `95e780e`，annotated tag `v2.0.0` 指向它。本地候选门全过：`check:docs`（171 文件）、node 205/205、`test-scripts` 228、plugin 7、skill-only、`pack:check`、`npm publish --dry-run`（2.0.0）、gitleaks 无泄漏、`git diff --check`；PR #22 全部 check success（含 CodeQL）。发布前回读：`latest` = 1.21.0、`next` = 2.0.0-beta.5。
+- 发布：workflow run [33974396871](https://github.com/HaiYangBG1/BuildBeat/actions/runs/33974396871)（`workflow_dispatch` from `main`，tag `v2.0.0`，稳定通道 → `latest`）双 job success（`Publish v2.0.0 to npm` + `Verify v2.0.0 from npm`）；`npm-publish` 环境审批按会话授权以所有者 gh 凭据落章，备注引用授权原文。
+- 本地独立回读（直连 registry.npmjs.org，不经镜像）：dist-tags `{bootstrap: 0.0.0, latest: 2.0.0, next: 2.0.0-beta.5}`；`dist.integrity = sha512-jKYX+DwstFDcHScXdbO5xHBs2J0C5emqUc3EwEjvDZEdfpjrwxThjlVdGVNabtL7qGsPnELBIVpadW51RHXX3Q==`；`dist.attestations.url` 存在；隔离前缀安装 `@latest` → `buildbeat --version = 2.0.0`，`buildbeat-v2` usage 含 `resume … --adopt`，`buildbeat doctor <空目录> --json` 返回有界 JSON（`cliVersion 2.0.0`，`not-installed`）；临时项目 `npm audit signatures`：1 package has a verified registry signature。
+- GitHub：Release [v2.0.0](https://github.com/HaiYangBG1/BuildBeat/releases/tag/v2.0.0) 已建并标 **Latest**（此前 Latest 为 v1.21.0）；beta.3/4/5 已补为预发布页。
+- 切换：所有者本机全局 CLI `npm i -g @haiyangbg/buildbeat@latest`，`buildbeat --version = 2.0.0`，`buildbeat-v2` 指向全局 node_modules。
+- 未做：旧 `solobaton` 包不动；`next` 仍指 2.0.0-beta.5，留给后续预发布。

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-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。
 
 ## 7. 自研面与组装面（逐项自研理由）

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

@@ -3,6 +3,8 @@
 > 这是给**用户**看的一页。你在任意一个 AI 编程会话里工作（哪家工具都可以，一个会话就够），会话装载了 BuildBeat Skill；你说人话，它去调 `buildbeat-v2`、读输出、按「已做 → 未做 → 下一步」回你。**你不需要记任何命令**。下面的例句就是平时的说法，照抄即可；同一格里的几句话意思相同，挑顺口的。
 > 会话侧的对应规则在 `SKILL.md` §0.5；项目专属的路由与红线在各项目根的 `AGENTS.md`。
 
+准备换会话时说「把关键上下文落盘,我要关闭旧会话」;新会话说「读取项目入口,核对进度与待批,继续这个工作」。交给同事时说「同步项目记录与候选,让接手成员核对当前范围和原 Run 所在环境」。详细步骤与活动 Run 的保留范围见 [跨会话与团队接续](11-session-handoff.md)。
+
 ## 一张表：项目从零到换期
 
 | 阶段 | 你想干什么 | 你就这么说 | 会话背后做什么 | 你会得到什么 / 注意 |
@@ -23,7 +25,7 @@
 | | 看下一步 | 「下一步做什么」「需要我做什么」 | overview 的 next 行，只挑「在你手里」的 | 只列你要做的：DNS、凭据、批准、亲自操作 |
 | | 怕它卡住 | 「怎么样了」「卡住了吗」「半小时了正常吗」 | `status --run`（每步耗时、历史中位数、最后输出、STALLED） | 一句带数字：「verify 已 14 分钟，历史中位 6 分钟，最后输出 2 分钟前，还在动」；疑似卡住会直说 |
 | | 看有什么等我 | 「有什么要我批」「有什么等我」 | `inbox` + `delivery/observe/intents/` | 逐项：等什么、证据在哪、推荐 A/B |
-| | 批 / 不批 | 「批准」「批准 RUN-X」「拒绝，原因是…」 | `approve` / `reject`；非终态自动 `resume` | 批准 = merge-ready；合并 / push / 部署你另说 |
+| | 批 / 不批 | 「批准」「批准 RUN-X」「拒绝，原因是…」 | `approve` / `reject`；非终态转换批准后再 `resume` 续跑 | 说清批的是哪一步：放行 fixer / 再跑一次 / 合并决定；合并决定只表示候选够格合并，合并 / push / 部署你另说 |
 | | 裁 finding | 「这条不算，那条接受」「这个是误报」 | `findings adjudicate dismiss/accept` → 放行 fixer | 被 dismiss 的同一条以后不再阻断；严重度升级会重开 |
 | | 再来一轮 | 「再来一轮」「继续」 | 新 attempt | 旧的等待自动作废，inbox 只剩活的 |
 | | 停下来 | 「这次再不成功就停」「先停下来」 | 封顶轮数；`stop --reason` 记账，候选与证据保留 | 已做 / 未做 / 下一步，带 hash；之后由你决定改方案、手工修还是关掉 Work |