@haiyangbg/buildbeat 3.1.0 → 3.2.0

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

@@ -2,8 +2,8 @@
 
 > 状态：`FINAL`（2026-08-28 项目所有者定稿，`V2-D3`；M0 随三份 RFC 与 [`SPEC-0001-events-v1.md`](SPEC-0001-events-v1.md) 定稿退出）
 > 日期：2026-08-28
-> 上游：[`V2-PLAN.md`](../V2-PLAN.md)（执行基线，`V2-D0=B`）；内核范围：完整内核（`V2-D2=A`，[`V2-DECISIONS.md`](../V2-DECISIONS.md)）
-> 需求来源：M-1 试点记录——[`pilot/metrics.md`](../../pilot/metrics.md)（能力矩阵 + 卡点 1–5）、[`pilot/evidence/2026-08-28-m1-runtime-gap.md`](../../pilot/evidence/2026-08-28-m1-runtime-gap.md)（F5/F6）、[`V2-ITERATION-01.md`](../V2-ITERATION-01.md)
+> 上游：[`V2-PLAN.md`](../history/V2-PLAN.md)（执行基线，`V2-D0=B`）；内核范围：完整内核（`V2-D2=A`，[`V2-DECISIONS.md`](../history/V2-DECISIONS.md)）
+> 需求来源：M-1 试点记录——[`pilot/metrics.md`](../../pilot/metrics.md)（能力矩阵 + 卡点 1–5）、[`pilot/evidence/2026-08-28-m1-runtime-gap.md`](../../pilot/evidence/2026-08-28-m1-runtime-gap.md)（F5/F6）、[`V2-ITERATION-01.md`](../history/V2-ITERATION-01.md)
 
 ---
 
@@ -11,7 +11,7 @@
 
 > **BuildBeat v2 是一个工件驱动的 AI 交付闭环。确定性内核按 Workflow 与 Policy 推进状态，外部 Agent 作为 Worker 执行计划、构建、验证、修复与审查；一切完成以 Runner 回读的真实证据为准；人只在不可委托的判断点被请求最小决策。协议（工件 + 证据 + 决策）永远人机可读、落在 Git——Runner 是引擎，不是协议存在的前提。**
 
-对外定位词可用"AI 原生交付控制面 / 交付闭环"（[`V2-PLAN.md`](../V2-PLAN.md) 裁决 #9、D1）；**产品之魂是协议**：厂商 runtime 正在被商品化，协议 + 参考实现才是可防守的位置。
+对外定位词可用"AI 原生交付控制面 / 交付闭环"（[`V2-PLAN.md`](../history/V2-PLAN.md) 裁决 #9、D1）；**产品之魂是协议**：厂商 runtime 正在被商品化，协议 + 参考实现才是可防守的位置。
 
 MVP 核心承诺：
 
@@ -41,7 +41,7 @@ M-1 的核心教训（卡点 1、卡点 5）：协议工件齐备但没有 Runne
 
 ## 5. 手工模式的地位
 
-v1 的"Skill-only 完整等价"拆成两个承诺（[`V2-PLAN.md`](../V2-PLAN.md) §5）：
+v1 的"Skill-only 完整等价"拆成两个承诺（[`V2-PLAN.md`](../history/V2-PLAN.md) §5）：
 
 | 承诺 | v2 处置 |
 |---|---|
@@ -52,7 +52,7 @@ v1 的"Skill-only 完整等价"拆成两个承诺（[`V2-PLAN.md`](../V2-PLAN.md
 
 > **生效修订（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。原文保留为决策记录。
+> **生效修订（2026-09-05）**：下段"`latest` 留 v1"是 beta 期策略，已按计划结束——`@haiyangbg/buildbeat@2.0.0` 于 2026-09-05 发布到 `latest`（[`CHANGELOG.md`](../../CHANGELOG.md)、[发布证据](../releases/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-0002-domain-model.md

@@ -2,7 +2,7 @@
 
 > 状态：`FINAL`（2026-08-28 项目所有者定稿，`V2-D3`）
 > 日期：2026-08-28
-> 上游：[`V2-PLAN.md`](../V2-PLAN.md) §3–4；报告 B §6 / §13 / §14（经基线裁决修订）
+> 上游：[`V2-PLAN.md`](../history/V2-PLAN.md) §3–4；报告 B §6 / §13 / §14（经基线裁决修订）
 > 需求来源：[`pilot/metrics.md`](../../pilot/metrics.md) 卡点 1–5；[`pilot/evidence/2026-08-28-m1-runtime-gap.md`](../../pilot/evidence/2026-08-28-m1-runtime-gap.md)
 
 ---

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

@@ -2,7 +2,7 @@
 
 > 状态：`FINAL`（2026-08-28 项目所有者定稿，`V2-D3`；§8 observe/bands schema 已随定稿冻结）
 > 日期：2026-08-28
-> 上游：[`V2-PLAN.md`](../V2-PLAN.md) §3.2–3.7；报告 B §8–11 / WP1.4–1.5 / WP4.3–4.5
+> 上游：[`V2-PLAN.md`](../history/V2-PLAN.md) §3.2–3.7；报告 B §8–11 / WP1.4–1.5 / WP4.3–4.5
 > 需求来源：[`pilot/metrics.md`](../../pilot/metrics.md) 卡点 3/5、故障矩阵 F1–F6；[`pilot/evidence/2026-08-28-m1-runtime-gap.md`](../../pilot/evidence/2026-08-28-m1-runtime-gap.md)
 
 ---
@@ -57,7 +57,7 @@ budgets:
 Intent → [Spec] → Plan → Build → Verify ⇄ Fix → Independent Review ⇄ Fix → WAIT_HUMAN(merge)
 ```
 
-- **Spec 步默认可选；识别到 UI/视觉/交互交付时强制**，且其 Approval subject 必须包含可渲染入口 + 截图 digest（不变量 22；v1 lessons #3 的 v2 化，经 [`V2-PLAN.md`](../V2-PLAN.md) 裁决 #3）。
+- **Spec 步默认可选；识别到 UI/视觉/交互交付时强制**，且其 Approval subject 必须包含可渲染入口 + 截图 digest（不变量 22；v1 lessons #3 的 v2 化，经 [`V2-PLAN.md`](../history/V2-PLAN.md) 裁决 #3）。
 - 各步执行规则照报告 B §8.1：Builder 只写授权 Workspace；Fixer 输入必须含失败命令/退出码/日志摘要/candidate/允许范围，不接受泛化的"再检查一下"；Reviewer fresh-context、默认只读、不改代码、产出结构化 findings（不变量 9）。
 - MVP 到 merge 决定即暂停，不自动合并（不变量 20）。
 

package/docs/v2/SPEC-0001-events-v1.md

@@ -1,6 +1,6 @@
 # SPEC-0001：Event Ledger 格式 v1（冻结）
 
-> 状态：**FROZEN**（2026-08-28 项目所有者定稿，`V2-D3`；[`V2-PLAN.md`](../V2-PLAN.md) 裁决 #8：格式 day-1 冻结，此后 additive-only）
+> 状态：**FROZEN**（2026-08-28 项目所有者定稿，`V2-D3`；[`V2-PLAN.md`](../history/V2-PLAN.md) 裁决 #8：格式 day-1 冻结，此后 additive-only）
 > 日期：2026-08-28
 > 冻结范围：**信封字段、通用规则、损坏处理、reducer 合同、初始事件类型注册表的语义**。文件摆放位置、快照格式、CLI 展示均为非规范内容，可变。
 > 演进规则：一切修改 **additive-only**（新增可选字段、新增事件类型）；破坏性变更必须升 `v` 并提供旧版读取器。

package/docs/v2/guide/02-workflow-guide.md

@@ -48,6 +48,10 @@ error: run config delivery/work/WORK-X/run-config.yaml has 3 problem(s):
 
 校验范围：必填键（`repo` `work` `run` `workflow` `workers`）；未知顶层键与 worker / envelope 的未知字段（给最接近的拼写）；类型与取值（正整数、列表、`inheritEnv` 只能是 `true` / `false`）；worker 名必须被工作流步骤用到；`stopAt` / `entry` 必须是工作流步骤；`work` / `run` 只允许字母、数字、`.` `_` `-`，写成数字要加引号。
 
+**并行 Run（`parallel: true`，默认关）**：默认一个仓库同时只驱动一个 Run，其他 Work 的 `start` 会被挡并提示在谁后面排队（真实事故：一个会话在另一个 Work 的 Run 后面等了 3 小时 23 分钟）。
+run 配置写 `parallel: true` 的 Work，可以与其他同样打开开关的 Work 同时驱动；同一 Work 的 Run 永远互斥；没打开的 Run 照旧独占整个仓库——它在跑时并行 Run 起不来，并行 Run 在跑时它也起不来。
+打开前先确认：verify 不抢固定端口、不共用同一个数据库或其他外部状态，否则并行会互相打架。`doctor` 会打印当前模式；被杀进程留下的并行标记与锁一样按持有者自动回收。
+
 run 配置还可声明（beta.3，皆来自三十轮部署战役的真实事故）：
 
 - **`requires:` 环境契约**——信封隐式依赖的二进制与最低版本，Run 启动前 fail-closed 全量核验，一次报清所有问题（真实事故：`rg` 只在某会话 vendored PATH、`/bin/bash` 3.2、新 shell 解析到 Node 14，各烧掉整轮 Run 才见真因）：

package/docs/v2/guide/09-security-boundaries.md

@@ -1,6 +1,6 @@
 # 安全与权限边界
 
-权威：[`RFC-0001 §保护动作`](../RFC-0001-product-definition.md)、[`V2-PLAN.md`](../../V2-PLAN.md) §9 不变量。设计哲学：**保护动作 = 能力移除**——不是"请 Agent 别做"，而是让它做不到。
+权威：[`RFC-0001 §保护动作`](../RFC-0001-product-definition.md)、[`V2-PLAN.md`](../../history/V2-PLAN.md) §9 不变量。设计哲学：**保护动作 = 能力移除**——不是"请 Agent 别做"，而是让它做不到。
 
 ## Runner 侧的本地边界（LOCAL_ENFORCED，均有测试）
 

package/docs/v2/guide/10-recovery.en.md

@@ -2,7 +2,7 @@
 
 [简体中文](10-recovery.md) | **English**
 
-Design premise (invariant 23 in [`V2-PLAN.md`](../../V2-PLAN.md), Chinese): **the whole `.buildbeat/runtime/` directory can be deleted at any time**. Accepted artifacts, decisions, Intent drafts with their triage, and the compacted records of finished Runs all live in the Git plane. "Delete and rebuild" is the default troubleshooting move, not the last resort.
+Design premise (invariant 23 in [`V2-PLAN.md`](../../history/V2-PLAN.md), Chinese): **the whole `.buildbeat/runtime/` directory can be deleted at any time**. Accepted artifacts, decisions, Intent drafts with their triage, and the compacted records of finished Runs all live in the Git plane. "Delete and rebuild" is the default troubleshooting move, not the last resort.
 
 ## Symptom → action
 

package/docs/v2/guide/10-recovery.md

@@ -2,7 +2,7 @@
 
 **简体中文** | [English](10-recovery.en.md)
 
-设计前提（[`V2-PLAN.md`](../../V2-PLAN.md) 不变量 23）：**`.buildbeat/runtime/` 整个目录随时可删**——已接受工件、Decision、Intent 草稿与分诊、已终结 Run 的压实记录全部活在 Git 面。"删了重建"是默认排障手段，不是最后手段。
+设计前提（[`V2-PLAN.md`](../../history/V2-PLAN.md) 不变量 23）：**`.buildbeat/runtime/` 整个目录随时可删**——已接受工件、Decision、Intent 草稿与分诊、已终结 Run 的压实记录全部活在 Git 面。"删了重建"是默认排障手段，不是最后手段。
 
 ## 症状 → 处置
 

package/docs/v2/skill/01-principles.md

@@ -0,0 +1,26 @@
+# BuildBeat 方法论 · 原则与分工（原 §1–§2）
+
+> 从 [`SKILL.md`](../../../SKILL.md) 移出的正文，原文与原节号不变，只调整了相对链接；入口、驾驶手册与红线摘要仍在 `SKILL.md`。
+
+## 1. 四根支柱(命根子,所有零件都为它们服务)
+
+1. **端到端工作包**:一个 Builder 对一个需求/功能工作包(= Work)的产品判断、实现、测试、合并与发布证据负责;需要隔离时再调用独立 AI 视角(独立 cwd / 上下文 / 写边界)。
+2. **人在决定点**:接受 intent/plan、合并决定、上线关窗必须人拍板,**不可自动跨过**;Run 内的 Build→Verify→Review→Fix 由内核自动闭环。人只当"节拍器 + 拍板者",不当信息搬运工。
+3. **上下文在项目文件**:会话间不靠人转述,长期事实全部走 Git(`AGENTS.md` → `delivery/work/<ID>/` → 契约 → 决策台账),运行态由内核落台账;开工自取,进度由内核回读而不是会话自述。
+4. **证据制完成**:任何工作包声明"完成"必须带 ① Git 回读的候选 commit ② 可核验证据(真实命令的 verify 结果 / 只读 reviewer 的 findings / 线上回读 / 截图)。**无证据 = 没完成。**
+
+> 需求编号可以细,但**执行边界不能跟着编号碎掉**:一个 Builder 同时认领一个可验收的用户级工作包,通常覆盖多个任务 ID / 文档 / commit;同一工作包可调用多个 AI 视角按各自写边界协作。多个 Builder 默认按项目/需求工作包切分,不按人类产品→研发→测试岗位接力。子产物提交、reviewer 返回、Run 停下都只是工作包内事件,不是自动结束会话的理由。
+
+## 2. 工作包所有权与 AI 专业视角
+
+**人类责任按工作包端到端闭环。** 下表是同一 Builder 可调用的默认 AI 视角,用于上下文和写边界隔离;它不是成员目录、岗位分工或审批链。多个 Builder 协作时各自拥有不同工作包,共享契约冲突线下收敛后只落最终事实。
+
+| AI 视角 | 在当前工作包内做什么 | 典型写入边界 |
+|---|---|---|
+| **产品**(规格/编排) | 拆需求、写 intent/plan、定契约要点、维护决策台账、分诊 finding | `delivery/**`、`pm/decisions.md`、`contracts/` |
+| **全栈**(实现,含运维) | 实现 + 改契约 + 部署;可同持多仓但**按仓分别 stage**;Run 内受 `allowedPaths` 机器约束 | 代码仓 |
+| **测试**(E2E·走查) | 对精确 candidate 独立核验、视觉回归、设计走查,不合格直接提带图 bug;报告落所属 Work 目录 | `tests/**` + 所属 Work 目录 |
+
+- **审查不是会话视角**:reviewer 是 Run 内置的 fresh-context 只读 worker,输入固定 candidate,输出结构化 findings;任何工作树写入都会被前后快照抓住并按失败落账。会话不另开"审查会话"。
+- **设计生成 = 外部工具**(可选):当前工作包的产品视角写 brief → 人喂设计工具 → 稿落 `design/design_N期/`;走查归测试视角。
+- **拆 AI 视角的依据是"物理边界(仓/部署单元)+ 是否需要独立核查",不是人类公司职能表。** 实践教训:按职能切出 6 个会话,两个月内被迫合并回 4 个(前端+后端合并、设计+测试合并)——每多一个上下文,编排成本和信息差面积都扩大。合并视角会丢"天然独立核查"防线,由 Run 内置 reviewer + 测试视角独立核两端补回。

package/docs/v2/skill/02-project-layout.md

@@ -0,0 +1,31 @@
+# BuildBeat 方法论 · 项目文件布局（原 §3）
+
+> 从 [`SKILL.md`](../../../SKILL.md) 移出的正文，原文与原节号不变，只调整了相对链接；入口、驾驶手册与红线摘要仍在 `SKILL.md`。
+
+## 3. 项目文件布局
+
+```
+<项目根>/                          ← 工作区(单仓项目就是代码仓本身;多仓项目是协调层 meta 仓)
+├── AGENTS.md                      # 会话路由 + 协作规则 + 红线(开放标准,按工具装载)
+├── CLAUDE.md                      # 一行指针 → AGENTS.md(兼容只认此名的工具;🔴 不复制内容)
+├── 指挥台.md                       # 给人看的一页:日常六句话、视角开场白
+├── BUILDBEAT.md                   # 运行时版本标记 + 升级/回灌说明
+├── ARCHITECTURE.md                # 全栈总图(多仓项目;按需读,不自动装载)
+├── contracts/PROTOCOL.md          # 跨边界契约唯一入口(多仓项目;单仓可无)
+├── standards/                     # 可选:STACK / CODE / REVIEW / DESIGN(Policy 输入工件,默认不生成)
+├── pm/decisions.md                # 🔴 平台级拍板台账(全工作区决策单点);可选 pm/adr/
+├── delivery/
+│   ├── envelope/                  # worker.sh + builder / reviewer / fixer prompt(仓级,进 Git)
+│   ├── work/<WORK-ID>/            # intent.md / plan.md / run-config.yaml / workflow.yaml / decisions.jsonl
+│   │   └── runs/<RUN-ID>/         #   run-record.json(终态记录,进 Git)
+│   └── observe/intents/           # observe 的 Intent 草稿(人分诊,绝不自动执行)
+├── .buildbeat/
+│   ├── notify.yaml / observe.yaml # 通知通道(URL 只走环境变量)/ 生产体检配置
+│   ├── runtime/                   # 🔴 事件台账、锁、日志(本机,不进 Git)
+│   └── worktrees/                 # 🔴 每个 Run 的隔离工作树(本机,不进 Git;gc 清)
+└── <代码子仓们>/                   # 多仓项目:各自独立 git + 该仓自己的 AGENTS.md(只写本仓局部细节)
+```
+
+> 🔴 **装载入口走开放标准 `AGENTS.md`,不绑厂商**(lessons.md「上下文载体绑死单一厂商」)。标准语义 = 会话从被编辑文件所在目录**向上收集沿途所有 `AGENTS.md` 合并、离得最近的优先**,所以「根写全局、子仓写局部」是白捡的层叠能力,不用自己发明。只认 `CLAUDE.md` 的工具靠根上一份**一行指针**兼容(内容单点在 `AGENTS.md`,复制过去 = 自造 SSOT 腐烂;也别用符号链接,Windows 上 git 默认 `core.symlinks=false` 会静默退化成文本文件)。同理**不要**引入 gitignore 的本地覆盖文件(如 `AGENTS.override.md`):本文件装的是红线与护栏,允许不进 git 的本地覆盖 = 给绕过护栏开后门,reviewer 与 pre-commit 都看不见。
+>
+> **不建进度文件、状态文件或看板**:进度由内核从台账与 Git 回读(`overview` / `status`),写进文档的进度从写下那一刻开始腐烂(lessons.md「SSOT 腐烂」)。`.gitignore` 排除 `.buildbeat/runtime/` 与 `.buildbeat/worktrees/`;有 vitest / jest / pytest 的仓另配 exclude `**/.buildbeat/**`,否则主干测试会把旧候选的用例一起跑。

package/docs/v2/skill/03-collaboration-rules.md

@@ -0,0 +1,45 @@
+# BuildBeat 方法论 · 协作规则、任务包、审批分层与决策包（原 §4）
+
+> 从 [`SKILL.md`](../../../SKILL.md) 移出的正文，原文与原节号不变，只调整了相对链接；入口、驾驶手册与红线摘要仍在 `SKILL.md`。
+
+## 4. 协作规则(写进项目根 AGENTS.md,模板已含)
+
+规则原文在 [templates/v2/AGENTS.md](../../../templates/v2/AGENTS.md) §2(十一条),本节只列每条为什么存在:
+
+1. **唯一入口**:活动工作看 `delivery/`(`overview` / `inbox`),不另建进度文件——多处进度必漂移。
+2. **契约落盘不喊话(双向)**:跨边界接口先改 `contracts/` 再动代码;收到协议声明独立核查再信;实现中发现契约不够用不得就地消化,停下记契约缺口交产品视角裁决。
+3. **交接靠 candidate hash + 台账**:Run 停在合并决定时 candidate 已由 Git 回读固定,`resume --adopt <sha>` 要求树干净且 HEAD 就是该 sha;hash 不得编造。
+4. **护栏与不可逆动作**:开工 `overview`;部署/改契约/migration 等不可逆动作前再核一次并走人批;exit 0 不消除 `warning/unverified`。
+5. **风险分轨**:Risk Preset 决定人批点(§5);别用牛刀杀鸡,也别借 `fast` 绕过高风险 delta 的独立核查。
+6. **核查门**:Run 内 reviewer 只读、结构化 findings;`reviewTriage: required` 时 P0/P1 先过人分诊再派 fixer;review 每 Run 默认 2 轮封顶。**完成 = hash + 可核验证据**;证据分 L0 声称 / L1 `文件:行` / L2 编译·类型 / L3 自动化测试 / L4 线上实测,`standard` 最低 L3,上线必须 L4;`UNVERIFIED` 永不当作通过。
+7. **状态单点**:事实进 Run 证据与 Work 记录;进度看 `overview`,度量看 `metrics`。
+8. **视觉问题带图对比**:提 UI bug 必附『实现截图 ⟷ 设计稿截图』并排 + 标注差异点。
+9. **单点事实**:线上版本只信实查(`observe status` / 部署平台),任何文档不写「当前线上 vX」;每个收敛后的真实决策包只在 `pm/decisions.md` 记一行;历史台账不回改。
+10. **真渲染拍板**:有 UI 的拍板对象必须是真渲染证据(可点入口 + 截图 digest),静态稿/规范数值不充当拍板对象;上线前终签同样要含真渲染走查。
+11. **所有者可见命名进决策卡**:域名、服务名、环境名、自停时长、窗口时长等所有者以后要看见或念出来的名字与参数,不由 worker 顺手定;进 intent 或门前决策卡(`BATCH_AT_GATE`),给推荐值和理由。
+
+> 十一条之外的一条**元原则:能实查的不问人**——查代码 / 配置 / 部署平台 / `overview` / `status` / `observe status` 能得到的事实,不拿去问用户、不信文档、不信上游转述(§8 Bootstrap 的提问三原则同源)。
+
+### 4.1 任务包协议:不因子任务完成而过早结束
+
+多步骤工作开工时,从用户目标与活动 Work 得到一个**任务包信封**(即 Work 的 intent/plan)。一个工作包可跨视角接力,但每个会话同时只认领一个并遵守自己的写边界;多个独立目标可以并行成多个 Work,不要重新退化成按文件切包。
+
+- `objective`:这轮要交付的用户级结果,不是文件名或动作名。
+- `in_scope`:为达成目标可自动继续的关联任务/AI 视角/文件边界。
+- `terminal_condition`:只有以下三类——目标带证据完成;遇到必须由人处理的真实阻塞(Run 停 `WAITING_HUMAN` 或 `infra`);用户明确只要阶段性检查点。
+
+需求 ID、验收项和原子 commit 继续保持细粒度,用于追踪、回滚和验证;**它们不自动成为会话结束条件**。只要仍有安全、可逆、在 `in_scope` 内且能推进 `objective` 的工作,会话就继续做。单个文档提交、一次 reviewer 返回、一次 Run 停下都只发中间进展,不得用 final 把接力棒交还给用户。跨视角且当前会话只读时,落盘接力棒并派给有权视角/明确真实阻塞,而不是把"请继续"变成人工调度协议。
+
+### 4.2 审批分层:立即停、门前批、无需批
+
+| 层级 | 什么时候 | 会话动作 |
+|---|---|---|
+| **STOP_NOW 立即停** | 跨发布门;扩大已批准范围或重开 non-goal;修改**已冻结**对外契约;部署/发布/花费/删除等不可逆外部动作;接受安全或合规风险;权威事实冲突且无法实查 | 停在动作前,一次给出推荐方案、影响和最小问题;获批后继续当前工作包 |
+| **BATCH_AT_GATE 门前批** | 冻结前可逆草案选择;已批准目标内的默认值/阈值/失败态归类/实现语义;多个互相关联的产品取舍;所有者可见命名 | 先记入 intent/plan 草稿或门前决策卡,继续不依赖该决定的工作;到人批的转换(accept / merge / release)或约定节奏一次提交**默认 2–5 个真实取舍**(确实只有 1 个就单项),每项带推荐值与后果 |
+| **NO_APPROVAL 无需批** | 能实查的事实;已批准信封内的派生约束;文案/归档/证据整理;普通 P2;不改变外部语义的可逆实现细节 | 自主完成并在证据/收口中说明,不把"告知"包装成"请审批" |
+
+判断顺序:先实查 → 再看是否越过 `in_scope`/人批转换/冻结线/不可逆线 → 只有命中 `STOP_NOW` 才立即中断。**人批预算默认每个工作包、每道人批转换只有 1 个 `BATCH_AT_GATE` 请求**;`STOP_NOW` 是越界例外。未决项不得悄悄固化成冻结事实;若它阻塞当前关键路径,把相关真实取舍合并成同一次提问,不要逐条连环问。用户只回答一部分或要求解释时,保持同一决策包编号,补充说明并更新决策卡,不得另造一轮"新审批"。
+
+### 4.3 决策包:验收条件不是 14 个拍板
+
+当前工作包的产品视角先把清单分成两类:① 人必须取舍的**独立决策变量**;② 由已选变量和现有契约推导出的验收约束。只把前者送人批,后者自动写入 plan/契约并随候选一起验收。一次门前默认提交 2–5 个决策变量;用户分轮回答时,未收敛项留在决策卡,收敛后按决策包在 `pm/decisions.md` 记一次,不为"3/14、11/14、14/14"分别制造拍板记录。

package/docs/v2/skill/04-rhythm-and-rituals.md

@@ -0,0 +1,102 @@
+# BuildBeat 方法论 · 节奏与三个仪式（原 §5–§6）
+
+> 从 [`SKILL.md`](../../../SKILL.md) 移出的正文，原文与原节号不变，只调整了相对链接；入口、驾驶手册与红线摘要仍在 `SKILL.md`。
+
+## 5. 节奏:风险预设决定人批点
+
+```
+写 intent/plan → 人接受(digest 绑定) → Run:Build → Verify → Review → Fix(自动闭环,预算封顶)
+→ 停在合并决定(人批;SUCCEEDED ≠ 已合并) → 人合并/push → release-readback 车道:回读 → 人做 → 回读 → 观察 → 人关窗
+```
+
+| Risk Preset | 人批点 | 用在 |
+|---|---|---|
+| `fast` | 仅合并决定 | 小改、可逆、不碰契约 |
+| `standard`(默认) | plan 接受 + 合并决定 | 单功能 |
+| `controlled` | intent + plan 接受 + 合并决定 + 上线 | 契约变更、大改、不可逆副作用 |
+| `release` | 配 `release-readback` 预设:preflight 回读 → 人做 → apply 回读 → 关窗 | 生产动作 |
+
+机器闸(gitleaks pre-commit)、证据制与合并候选一次核查任何预设都不跳;高风险 delta 不得借 `fast` 绕过独立核查。预算耗尽是停人不是失败。非只读步(build / verify / fix)成功不扣 `maxAttempts`,只读步仍按尝试次数计费,review 按轮计费;基础设施故障(超时 / 崩溃 / 非 JSON / exit 75)判 `infra` 停人、不派 fixer、不扣预算。真失败到顶仍停 `resume-<step>`,批准多给一次。同一步总 attempt 达到有效预算上限(配置值 + 人批扩额)的 3 倍后,下一次执行前以 kind `budget` 兜底停人,防止成功循环失控;退款不抬高该兜底上限。
+
+**一轮一问**:review 发现阻断问题且下一轮会超 Run 或 Work 上限时,提前停 `enter-fix`;有分诊用 `finding-triage`,无分诊用 `budget`。批准覆盖「修复 + 重新验证 + 再审一轮」,所需扩额随请求的可选 `grants` 落账,Run/Work 同时到顶只问一次;拒绝结束本 Run,由人按现有证据决定是否合并。批准旧的 `enter-review` / `resume-review` 预算停车时也同时放行已到顶的另一层上限。新候选或过期批准不能沿用旧请求的 grants。默认上限不变。
+
+## 6. 三个仪式(防腐烂的关键,缺了机制必朽)
+
+### 6.1 开工同步
+
+1. 协调层与每个要动的子仓分别 `git pull`;无上游或离线必须明说,不伪称已同步。
+2. `buildbeat overview --repo .`:活动 Work、等人的 Run、成本;`inbox` 看有没有等你批的;`observe status` 看生产。
+3. 按 `AGENTS.md → 所属 Work 的 intent/plan → contracts → pm/decisions.md → 最近 run-record` 读承重事实。
+4. 认领一个端到端工作包,确认 `objective / in_scope / terminal_condition` 与止损线。
+5. 核对要动的文件、契约、candidate 与现有证据没有 stale(`overview` 会标 `stale`);不可逆动作前必须再跑一遍开工同步。
+6. 只在确认写边界后动手;无法实查的范围记为 `unverified`,不猜。
+
+**每条规则都问「违反了会怎样」;答案只是「靠自觉」时,就该机器化。**
+
+### 6.2 执行中同步
+
+1. 契约/决策先落权威文件,再改共享实现;冻结后的语义 delta 命中 `STOP_NOW`。
+2. 原子 commit 可以细,但只在工作包里程碑候选、完成或真实阻塞时向人收口。
+3. 不在 Run 跑着的时候改它的候选;要手修就等它停下,在 worktree 里改完提交,`resume --adopt <sha>`。
+4. 新事实若使 intent/plan/contracts 失配,在同一变更批次内修回(plan 改了要重新 `accept`);不等收工补旧账。
+5. 对无法验证、远端未回读的部分保留 `unverified`,不把局部绿外推为全局通过。
+
+### 6.3 收工同步
+
+1. 确认工作包达到 `terminal_condition`,不把单个子产物当完成。
+2. 里程碑候选必须来自一次完整 Run:verify 真跑、reviewer 真核,证据在 run-record 与 `status` 里;会话自己跑的测试只是补充。
+3. 回写 contracts / `pm/decisions.md` / intent-plan;已完成工作包的证据就是 run-record + 合并决定,不再另写证据文件。
+4. 再跑一次 `overview`,把 warning / unverified 原样写进收口;不用 exit 0 替代覆盖面判断。
+5. 确认各仓工作树与 staged 范围;他人 WIP、散落临时文件未收敛时,不声称候选就绪。
+6. 一屏收尾(§6.4):交付结果、证据、未验证边界、挂账/真实阻塞、下一步该谁。
+
+### 6.4 域回复格式
+
+每个 AI 视角面向用户收口、交接或回复明确检查点时,统一按「已做 → 未做 → 下一步」输出。这个格式只约束收口事实,不要求中间进展或探索讨论套模板。
+
+```md
+## 〔当前视角〕｜✅ 已完成 / 🔄 未完成
+
+### 已做
+
+1. 〔功能或业务结果〕
+   - 证据：〔candidate、Run、verify 结果或报告〕
+
+### 未做
+
+1. 〔还没完成或没验证什么〕
+   - 原因：〔具体原因〕
+
+### 下一步
+
+- **本视角已完成：** 下一棒是〔哪个视角 / 谁〕，负责〔业务级目标〕。
+- **本视角未完成：** 需要〔谁〕提供或确认〔什么〕。
+- **无需协助：** 我继续做，暂不交棒。
+```
+
+口径:
+
+- `已做`只写功能或业务级结果,不罗列文件和实现细节;证据紧跟它所支持的事项。多项共用同一份证据时,改在列表末尾写一次「共同证据」。
+- `未做`必须同时写原因;未验证范围也放这里。没有就写「无」,不把局部验证外推为整体完成。
+- `下一步`只保留符合当前状态的一项。下一棒按剩余目标决定,不是固定的产品 → 全栈 → 测试流水线;整个工作包已完成就写「下一棒:无」。
+- 本视角未完成但仍能在已批范围内安全推进时,不向用户伪求助;继续做。只有真实阻塞或用户明确要检查点时,才用「需要帮助」或「我继续做,暂不交棒」收口。
+
+### 6.5 读数怎么读
+
+先按级别处理,不要只看退出码。`overview` / `status` / `doctor` 全是只读;它们的读数从台账、Git 主干和真实命令推导,不从会话自述来。
+
+| 读数 | 它证明什么 | 当下动作 |
+|---|---|---|
+| Run `SUCCEEDED`(停在合并决定) | 候选通过 verify 与 review,具备合并条件 | 人看证据后合并;`SUCCEEDED` ≠ 已合并 |
+| `WAITING_HUMAN` kind `approval` / `triage` / `budget` | 内核在等一个具体的人批转换 | `inbox` 看等什么,批哪一步说清哪一步 |
+| `WAITING_HUMAN` kind `infra` | worker 环境/后端故障,不是候选缺陷 | 修环境,`approve --transition resume-<step>`;不派 fixer |
+| `STALLED` | 无输出超过阈值,只标不杀 | 看最后输出与历史中位数,决定等还是停 |
+| `stale`(intent/plan/批准) | 被批准的对象改过 | 重新 `accept` / 重新批,旧批准不复用 |
+| 证据 `UNVERIFIED` / `REUSED` | 没核到 / 同树同命令复用 | 前者不得当通过;后者可信但要能说出复用自哪次 |
+| `overview` 的 `MERGED` / `RELEASED` / `STOPPED_*` | 从主干、车道、门推导出的阶段 | 按 `next:` 行行动;已合并/已发布不再提未裁决数 |
+
+### 6.6 拍板仪式与换期
+
+当前工作包的产品视角先把验收清单压成真实决策变量并批量呈现;用户拍板后 → 该视角**按收敛决策包**在 `pm/decisions.md` 落一行(决策+回写落点)→ 再分发回写各 SSOT。部分对话进度留在决策卡,不污染永久台账。
+
+换期 = 关闭 Work:候选已合并/已发布后在 `decisions.jsonl` 记关闭,`gc --repo .` 清终态 Run 的工作树,`overview` 不再列它。**同时做回灌一问**:本期踩到 BuildBeat 没覆盖的新坑了吗?有 → 回上游 `lessons.md` 登记。

package/docs/v2/skill/05-red-lines.md

@@ -0,0 +1,13 @@
+# BuildBeat 方法论 · 红线全文（原 §7）
+
+> 从 [`SKILL.md`](../../../SKILL.md) 移出的正文，原文与原节号不变，只调整了相对链接；入口、驾驶手册与红线摘要仍在 `SKILL.md`。
+
+## 7. 红线(每个会话受约束,单点写进根 AGENTS.md §3)
+
+1. **凭据不入 git、不出本机**:文档只标位置不写值;本地 .env 必须 gitignore + 600 权限;Bootstrap 默认装 gitleaks pre-commit 闸,报警即拦——红线不能只靠自觉(lessons.md「自动化便利与安全红线打架」);Worker 默认 env 白名单,`env:` 只注入点名的变量;通知 URL 只能来自环境变量。
+2. **不 `git add -A`**:多会话共编,只 stage 自己工作包的具体文件;同持多仓时按仓分别提交。
+3. **不未授权部署**、不 force-push、不 `--amend` 已推送历史、不 `--no-verify`。合并决定只表示候选具备合并条件,合并/push/发布是其后的人类动作、逐项授权。
+4. **每次部署完必更对应仓 CHANGELOG**(Keep a Changelog,倒序);部署后 `observe run` 一轮。
+5. **写者≠审者**:Run 内置只读 reviewer 机器强制;写者转述不构成证据。
+6. **事实分层**:代码已确认事实 / 运行时待核事实 / 拟议需求 / 已实现行为,四类严格分开;未实查一律写「待核」。
+7. 资源选型 **稳定 > 便宜**;长连接服务部署带优雅下线(PreStop/drain)。

package/docs/v2/skill/06-bootstrap-and-takeover.md

@@ -0,0 +1,84 @@
+# BuildBeat 方法论 · Bootstrap 新项目与接管存量项目（原 §8、§8.5）
+
+> 从 [`SKILL.md`](../../../SKILL.md) 移出的正文，原文与原节号不变，只调整了相对链接；入口、驾驶手册与红线摘要仍在 `SKILL.md`。
+
+## 8. Bootstrap 新项目(引导式:自查 → 少量提问 → 确认 → 生成)
+
+### 8.0 先认项目形态
+
+收到「用 BuildBeat 开始 / 搭骨架 / 套流程」类请求,**先看目录再说话**:
+
+| 目录里有什么 | 形态 | 走哪条路 |
+|---|---|---|
+| `delivery/work/` 或 `.buildbeat/` | 已是 BuildBeat 项目 | 不再 Bootstrap;直接 §0.5:`buildbeat overview --repo .` 开场 |
+| 什么都没有,且是空仓/新项目 | 0→1 | §8.1 自查与少量提问 → §8.3 生成 checklist |
+| 什么都没有,但已有代码 | 10→N 存量项目 | §8.5:先摸底、划边界、补最小验证,再 §8.3 |
+
+自动闭环、隔离 worktree、digest 绑定批准都要 `buildbeat` 在 PATH 上;没装时先装 `npm install --global @haiyangbg/buildbeat@latest`,装不了就明说"只能手工维护工件协议,没有自动闭环"(§0.5 开头),不得把手工路径说成等价能力。
+
+> 🔴 收到「搭骨架 / 用 BuildBeat 起项目」类请求时,流程 = **先自查代码 → 只问查不到的 → 一屏确认 → 生成**;不许直接拷模板留 `<占位符>` 让用户手改,也**不许把看代码就能搞清的事拿去问用户**。
+> **提问三原则:① 能从代码/配置查到的不问;② 问就问不懂技术的人也能答的话**(话术不出现"仓/部署单元/契约/CLI"这类词,能给选项就不开放问);**③ 合并一次问完(常规 3 问,查到有 UI 时 +1),不连环追问**。有 AskUserQuestion 类工具就用,没有就在对话里问;用户说「你定 / 随便」就取默认值,并在收尾报告标注。
+
+### 8.1 先自查,后提问
+
+**第一步:自查(带证据)。** 扫一遍项目,下表尽量自己填,每项记下依据(文件路径 / 命令输出):
+
+| 要搞清的事 | 怎么自查 | 结论怎么用 |
+|---|---|---|
+| 几个仓 / 部署单元 | 找各级 `.git`、Dockerfile / compose / CI / 部署配置 | 仅 1 仓 → 结合问题 A 判断是否劝退(§0);多仓 → 建 `contracts/PROTOCOL.md` 与 `ARCHITECTURE.md` |
+| 验证命令 | 测试脚本、CI 配置、Makefile / package scripts | 填 run-config `verifier`;没有可跑的测试 → 第一个 Work 就是补最小验证套件 |
+| 用哪个 AI 工具跑 worker | `command -v codex claude aider …`;用户当前会话是什么工具 | 填 run-config 各 worker `--` 后的命令;信封 worker.sh 不用改 |
+| 部署平台、有无 CLI | 认平台配置文件;`command -v` 试探平台 CLI | 有 → `.buildbeat/observe.yaml` 加只读探针;无 → 留桩,`observe status` 会如实说未配置 |
+| 有无 UI | 前端依赖(package.json 等)/ HTML / 客户端工程 | 无 UI → 删 AGENTS.md §1.5、reviewer prompt 删 UI 项;有 → 拍板对象必须真渲染 |
+| 契约边界 | 读跨服务调用代码(HTTP client / API 路由),**自己起草**边界清单 | 草稿填 PROTOCOL.md §1 并标「待确认」;单仓内部接口走共享类型/schema,不进 PROTOCOL |
+| 项目名、栈事实 | README / 包清单 / 版本文件 / lockfile / Dockerfile | 填模板各处 <占位符>;可核对的精确值转成 run-config `requires:`;可选 STACK 只在用户启用后生成并保持 `Draft` |
+
+**第二步:只问自查不出来的(通常就剩这三四件):**
+
+| 问题(示例话术) | 答案怎么用 |
+|---|---|
+| A.「这个项目是几天就收尾,还是要长期做下去?」 | 几天收尾 + 单仓 → **劝退**:单会话直接干,不搭流程,到此为止 |
+| B.「现在会同时推进几个互不依赖的功能?先从哪一个开始?」 | 每个功能建一个 Work;默认只开当前优先包,不建立成员/岗位目录 |
+| C.「一个功能我会从想清楚、做出来、测好一直跟到可上线;需要时再开几个专业 AI 会话帮忙。就按这个来吗?」 | 默认 → 一个 Builder 端到端拥有工作包,产品/全栈/测试仅作 AI 视角(§2);若要并行,按工作包或物理边界拆,不按人类岗位流水线拆 |
+| D.(自查到有 UI 才问)「界面效果谁说了算——有设计工具/设计师出稿,还是做出来你看着提意见?」 | 有稿 → 设计拍板走真渲染全流程;无稿 → 简化为"实现后真渲染给你过目再上线" |
+| E.「Run 停下来等你批、跑完或疑似卡住时,要不要推到钉钉/webhook?」(§0.5.3) | 要 → `.buildbeat/notify.yaml`,URL 只走环境变量;不要 → 收尾写明「等待只在 inbox 里」 |
+
+**第三步:一屏确认再动手。** 把「自查结论(带证据)+ 你的回答 + 我按默认拿主意的项 + 风险预设与人批点的理由草案 + 可选 STACK/DESIGN 建议」汇成一屏给用户点头——点头即本项目第一次拍板(落 `pm/decisions.md`),然后才开始生成。无法从事实确认有无 UI/部署时如实写「待核」,不得猜。
+
+> **可选规范默认不生成。** `standards/` 缺失是合法状态,不增加提问预算;只有用户在同一屏确认中选择启用,才创建相应文件。STACK 首次生成保持 `Status: Draft`;DESIGN 只在识别到 UI/视觉/交互交付时建议。ADR 只在 `templates/pm/adr/README.md` 的五项判据命中时按需创建,不随骨架批量生成。
+
+### 8.3 生成 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`(记平台级决策包,第一行就是这次 Bootstrap 的确认);多仓才建 `contracts/PROTOCOL.md`(`templates/contracts/`)与 `ARCHITECTURE.md`(`templates/ARCHITECTURE.md`)
+- [ ] 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 / verifier / 把 `--` 后的工具命令换成用户实际用的);`$(npm root -g)/@haiyangbg/buildbeat/src/v2/presets/software-delivery.yaml` → `workflow.yaml`
+- [ ] 5. 通知(问题 E):要就写 `.buildbeat/notify.yaml`,URL 只能来自环境变量;不要就在收尾说明"等待只在 inbox 里"。有生产环境就再放一份 `.buildbeat/observe.yaml`(只读探针)
+- [ ] 6. 机器闸:各代码仓装 gitleaks pre-commit(`command -v gitleaks` 查无则提醒安装,并记入收尾报告);meta 仓 git init + 远端,代码子仓各自独立 git
+- [ ] 7. 首跑验收:用户说「接受」→ `accept --artifact intent` / `plan`;`buildbeat doctor --config …` 全段读一遍(intent/plan 接受状态、env 姿态、预算、start 会停在哪);`start --config … --attempt new`(脱离启动)→ 停 `WAITING_HUMAN`;`overview` / `status` 把候选、verify 退出码、findings 读给用户。**这一次 Run 停在合并决定之前,不宣布"接入完成"**
+- [ ] 8. 收尾一屏:生成了什么 / 默认拿主意的项 / 首跑停在哪、证据在哪 / 下一步由谁做(合并是人的动作)
+```
+
+> 各文件「填好之后长什么样」,参照 [example/](../../../example/README.md)(虚构「简账」项目跑完一个 Work 的快照)。可核对的样例:`tests/v2-templates-firstrun.test.js` 与 `tests/example-firstrun.test.js` 用脚本 worker 代替真实模型,从上面的模板走到合并决定(含一次 verify 失败→fixer→重验)。它证明包内路径、配置、信封、提交机制、reviewer 信封连得上;不证明某个真实模型能完成业务任务。
+
+## 8.5 接管存量项目(10→N 入口:先摸底、划边界、补验证)
+
+> §8 假设从零起步;公司里大多数项目是**存量**的,两类项目的成本结构相反:0→1 的瓶颈是需求不确定,10→N 的瓶颈是**理解成本 ≫ 编写成本**、改坏的损失 ≫ 改对的收益。收到「给现有项目上 BuildBeat」类请求走本节,别拿 §8 硬套;提问三原则(§8)同样适用。
+
+```
+- [ ] 1. 摸底(全自查,不问人):规模(文件/行数)、模块依赖、测试现状(几个测试/能不能跑/跑多久)、
+        危险区(被广泛依赖、一改炸全站的模块)、分支状态(落后多少/几个长命分支)、技术栈可观测事实 → 摸底报告一屏给用户。
+        报告固定增加「历史债务与接管边界」:已确认债务(带证据)、尚未验证范围、这次接管会治理的新地盘、只维护不重写的老地盘、明确不碰的外部/危险区;不得把存量缺口伪装成本次承诺
+- [ ] 2. 划绞杀者边界(用户拍板):「新地盘」(新功能/新模块)走全套流程;「老地盘」只维护、改动一律 `controlled`。
+        边界写进根 AGENTS.md §1 与 PROTOCOL,并作为 run-config `allowedPaths` 的依据——同一项目里两种速度,不是折中成一种。
+        只问两个人话问题:「这项目还要长期投入吗?」「哪块最怕改坏?」(危险区,人比代码清楚)
+- [ ] 3. 第 0 期 = 补最小验证套件(强制,不做业务需求):核心链路 E2E 起步,作为 run-config `verifier`。
+        没有这一步,证据分级给不出 L3,后面所有人批都在空转
+- [ ] 4. 产出分层 AGENTS.md:根一份(路由 + 新旧边界 + 危险区)+ 各业务模块一份(模块地图,给 AI 会话降理解成本)。
+        靠标准的「向上合并、就近优先」层叠:改哪个模块只额外装载哪份,根文件因此能保持精简
+- [ ] 5. 骨架按 §8.3 步骤 1–3;`delivery/envelope/` 的 builder / fixer prompt 里写明"老地盘只维护、改动一律先问人"
+- [ ] 6. 之后按 §8.3 步骤 4–8 走(第一个 Work = 第 3 步的最小验证套件,`allowedPaths` 只放新地盘与 tests)。一期起步的优先级:补测试 > 机械重构 > 新功能
+```
+
+存量项目已有自定义 standards/ADR 时只读摸底并保留项目所有权,不得用上游模板覆盖。项目没有这些文件时仍默认不生成;若用户在接管确认屏选择启用,先用现有配置起草 STACK `Draft`,UI 项目才建议 DESIGN,长期不可逆决定才建 ADR。

package/docs/v2/skill/07-templates-and-lessons.md

@@ -0,0 +1,24 @@
+# BuildBeat 方法论 · 模板索引与实战教训（原 §9–§10）
+
+> 从 [`SKILL.md`](../../../SKILL.md) 移出的正文，原文与原节号不变，只调整了相对链接；入口、驾驶手册与红线摘要仍在 `SKILL.md`。
+
+## 9. 模板索引(templates/,直接拷贝后改占位符)
+
+| 模板 | 用途 |
+|---|---|
+| [templates/v2/AGENTS.md](../../../templates/v2/AGENTS.md) / [templates/v2/指挥台.md](../../../templates/v2/指挥台.md) | **项目装载入口**:一页流程 + 视角路由 + 十一条规则(含可见命名进决策卡)+ 红线;指挥台是"用户一句话 → 会话调什么"的操作卡 |
+| [templates/v2/CLAUDE.md](../../../templates/v2/CLAUDE.md) / [templates/v2/BUILDBEAT.md](../../../templates/v2/BUILDBEAT.md) | 一行指针与版本标记(运行时版本、装载方式、升级 = 升级 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/pm/decisions.md](../../../templates/pm/decisions.md) | 平台级决策包台账(全工作区唯一决策单点;Run 级批准由内核落 `decisions.jsonl`) |
+| [templates/pm/adr/README.md](../../../templates/pm/adr/README.md) / [ADR 模板](../../../templates/pm/adr/ADR-0000-template.md) | 可选 ADR 判据、四态 Status 与替代链;默认不生成 |
+| [templates/contracts/PROTOCOL.md](../../../templates/contracts/PROTOCOL.md) | 跨边界契约唯一入口骨架(多仓项目) |
+| [templates/ARCHITECTURE.md](../../../templates/ARCHITECTURE.md) | 全栈总图骨架(架构/基础设施/凭据位置/子项目索引;多仓项目) |
+| [templates/standards/STACK.md](../../../templates/standards/STACK.md) / [CODE](../../../templates/standards/CODE.md) / [REVIEW](../../../templates/standards/REVIEW.md) / [DESIGN](../../../templates/standards/DESIGN.md) | 可选 project-owned 规范(Policy 输入工件);缺失跳过,Draft 显式待确认,DESIGN 仅 UI 项目 |
+| [templates/gitignore.template](../../../templates/gitignore.template) | 工作区 .gitignore 模板(排除子仓、*.env、`.buildbeat/runtime/`、`.buildbeat/worktrees/`;拷入后改名) |
+
+> 运行时命令面(`accept / start / resume / status / inbox / overview / approve / reject / findings / doctor / preflight / gc / metrics / observe / watch`)见 [docs/v2/guide/README.md](../guide/README.md);Skill-only 手工路径 / 运行时 / Claude 插件各自的可用面见 [docs/CAPABILITY-MATRIX.md](../../CAPABILITY-MATRIX.md)。
+
+## 10. 反模式与实战教训
+
+血泪清单(每条都真实发生过)见 [lessons.md](../../../lessons.md)——SSOT 腐烂、读过期 race、静态稿拍板返工螺旋、视角过细收敛史、"当前版本"声明漂移、走查漏独立弹窗、构建产物混入他人 WIP、平台侧配置漂移、UI 元注释复发、核查门吞掉交付、追踪项当任务边界、等待找不到人、预算是刹车不是墙、基础设施故障当候选失败、台账说的和人看到的不是一回事等。**搭完骨架后建议通读一遍,大部分零件就是为这些坑而生。**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haiyangbg/buildbeat",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "BuildBeat: Git-based AI delivery across models, tools, sessions, and people, with context in project files, build-test-review-fix loops, and human decisions.",
   "type": "module",
   "bin": {
@@ -8,20 +8,11 @@
   },
   "files": [
     "bin/",
-    "docs/",
-    "!docs/*-RELEASE-EVIDENCE-*.md",
-    "!docs/V2-ITERATION-*.md",
-    "!docs/V2-PLAN.md",
-    "!docs/V2-PROPOSAL.md",
-    "!docs/V2-DECISIONS.md",
-    "!docs/V2-D2-DECISION-CARD.md",
-    "!docs/BuildBeat v2*.md",
+    "docs/README.md",
+    "docs/CAPABILITY-MATRIX.md",
+    "docs/RELEASING.md",
+    "docs/v2/",
     "!docs/v2/M[124]-*.md",
-    "!docs/ROADMAP.md",
-    "!docs/EXECUTION-PLAN.md",
-    "!docs/PHASE*.md",
-    "!docs/CLI-STRATEGY-2026-08.md",
-    "!docs/CLI-PILOT-2026-08-23.md",
     "example/",
     "src/",
     "templates/",

package/src/v2/cli/run-config-check.js

@@ -27,8 +27,10 @@ const TOP_KEYS = [
   "reviewTriage",
   "supersede",
   "stallAfterMs",
+  "parallel",
 ];
 const REQUIRED = ["repo", "work", "run", "workflow"];
+const NULL_REPORTED = ["base", "entry", "riskPreset", "stepTimeoutMs", "maxAttemptsPerStep"];
 const WORKER_KEYS = ["command", "args", "timeoutMs", "inheritEnv", "env"];
 const ENVELOPE_KEYS = ["prompts", "vars", "pin"];
 const LISTS = ["stopAt", "allowedPaths", "policies", "redact", "requires"];
@@ -110,10 +112,11 @@ export function checkRunConfigShape(config) {
       problems.push(`${key}: required and missing`);
     }
   }
-  // An explicit null (key: null, key: ~) is never "use the default": say so
-  // instead of silently falling back.
-  for (const [key, value] of Object.entries(config)) {
-    if (value === null && TOP_KEYS.includes(key) && !REQUIRED.includes(key)) {
+  // An explicit null on a scalar key (base: null, entry: ~) would silently
+  // fall back to the default: say so. Other keys keep their own handling
+  // (cache: null has always meant no cache; lists must be lists).
+  for (const key of NULL_REPORTED) {
+    if (Object.hasOwn(config, key) && config[key] === null) {
       problems.push(`${key}: has no value; remove the line to use the default, or give it a value`);
     }
   }
@@ -134,6 +137,9 @@ export function checkRunConfigShape(config) {
       problems.push(`${key}: "${value}" may only use letters, digits, ".", "_" and "-", start with a letter or digit, contain no "..", and be at most 100 characters (it becomes part of paths and branch names)`);
     }
   }
+  if (config.parallel !== undefined && typeof config.parallel !== "boolean") {
+    problems.push(`parallel: must be true or false, got ${JSON.stringify(config.parallel)}`);
+  }
   for (const key of ["stepTimeoutMs", "maxAttemptsPerStep"]) {
     if (config[key] !== undefined && !positiveInteger(config[key])) {
       problems.push(`${key}: must be a positive integer, got ${JSON.stringify(config[key])}`);

package/src/v2/cli/run.js

@@ -406,6 +406,7 @@ function loadRunConfig(flags, command) {
     requires: config.requires ?? [],
     reviewTriage: config.reviewTriage === "required" ? "required" : null,
     supersede: config.supersede ?? "waiting",
+    parallel: config.parallel === true,
     stallAfterMs: config.stallAfterMs !== undefined ? Number(config.stallAfterMs) : DEFAULT_STALL_AFTER_MS,
     planDigest: digestOfWorkFile("plan.md"),
     intentDigest: digestOfWorkFile("intent.md"),
@@ -531,7 +532,7 @@ async function commandStart(flags) {
         console.error(`blocked by ${holder}: ${summary}`);
         console.error(`  watch it: buildbeat status --repo ${label} --run ${holder}`);
       }
-      console.error("queue position: next after the holder(s) above stop or wait on a human (the repository allows one driving run at a time; worktrees are already isolated)");
+      console.error("queue position: next after the holder(s) above stop or wait on a human (by default one run drives a repository at a time; works whose run configs both set parallel: true can drive together)");
     }
     throw error;
   }
@@ -829,6 +830,11 @@ function commandDoctor(flags) {
     console.log("environment contract: none declared (implicit PATH facts stay unchecked)");
   }
   console.log(`supersede: ${options.supersede} (new run for the same work ${options.supersede === "off" ? "leaves" : "supersedes"} older WAITING_HUMAN runs)`);
+  console.log(
+    options.parallel
+      ? "concurrency: parallel (runs of other works with parallel: true may drive at the same time; runs of this work stay exclusive; verifiers must not share fixed ports or databases)"
+      : "concurrency: exclusive (default: one driving run per repository; set parallel: true to drive alongside other works)",
+  );
   console.log(`stall threshold: ${formatMs(options.stallAfterMs)} without worker output`);
   const { config: notify, error: notifyError } = notifyConfigFor(options.repoRoot);
   if (notifyError) {