@haiyangbg/buildbeat 3.0.1 → 3.2.0

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.0.1",
+  "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

@@ -0,0 +1,229 @@
+// Run-config validation. The loader used to accept almost anything: a
+// missing `repo` surfaced as Node's "paths[1] must be of type string", a
+// misspelled key (`stopat`) or worker (`reviwer`) was silently ignored, and
+// `inheritEnv: yes` quietly meant false. Run configs are mostly written by
+// AI sessions, so every problem is reported at once, naming the key, what is
+// wrong and the closest valid spelling, before anything runs.
+
+const TOP_KEYS = [
+  "repo",
+  "work",
+  "run",
+  "workflow",
+  "riskPreset",
+  "base",
+  "entry",
+  "stopAt",
+  "stepTimeoutMs",
+  "maxAttemptsPerStep",
+  "allowedPaths",
+  "budgets",
+  "cache",
+  "envelope",
+  "requires",
+  "workers",
+  "policies",
+  "redact",
+  "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"];
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export class RunConfigError extends Error {
+  constructor(label, problems) {
+    super(`run config ${label} has ${problems.length} problem(s):\n${problems.map((problem) => `  - ${problem}`).join("\n")}`);
+    this.name = "RunConfigError";
+    this.problems = problems;
+  }
+}
+
+function isMap(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i += 1) {
+    let previous = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const kept = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+      previous = kept;
+    }
+  }
+  return row[b.length];
+}
+
+// The closest known name, if it is plausibly what was meant.
+export function suggest(name, known) {
+  const lower = String(name).toLowerCase();
+  const exact = known.find((candidate) => candidate.toLowerCase() === lower);
+  if (exact) {
+    return exact;
+  }
+  let best = null;
+  let bestDistance = 3;
+  for (const candidate of known) {
+    const d = distance(lower, candidate.toLowerCase());
+    if (d < bestDistance) {
+      best = candidate;
+      bestDistance = d;
+    }
+  }
+  return best;
+}
+
+function unknownKey(where, key, known) {
+  const guess = suggest(key, known);
+  return `${where}${key}: unknown key${guess ? ` (did you mean ${guess}?)` : `; known: ${known.join(", ")}`}`;
+}
+
+function positiveInteger(value) {
+  return Number.isInteger(value) && value > 0;
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+// First pass: everything that does not need the workflow. Runs right after
+// parsing, so a missing `repo` is reported by name instead of crashing path
+// resolution.
+export function checkRunConfigShape(config) {
+  if (!isMap(config)) {
+    return ["the file must be a map of keys (repo, work, run, workflow, workers, ...)"];
+  }
+  const problems = [];
+  for (const key of Object.keys(config)) {
+    if (!TOP_KEYS.includes(key)) {
+      problems.push(unknownKey("", key, TOP_KEYS));
+    }
+  }
+  for (const key of REQUIRED) {
+    if (config[key] === undefined || config[key] === null) {
+      problems.push(`${key}: required and missing`);
+    }
+  }
+  // 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`);
+    }
+  }
+  for (const key of ["repo", "workflow", "riskPreset", "base", "entry"]) {
+    const value = config[key];
+    if (value !== undefined && value !== null && !nonEmptyString(value)) {
+      problems.push(`${key}: must be a non-empty string, got ${JSON.stringify(value)}`);
+    }
+  }
+  for (const key of ["work", "run"]) {
+    const value = config[key];
+    if (value === undefined || value === null) {
+      continue;
+    }
+    if (typeof value !== "string") {
+      problems.push(`${key}: must be a string, got ${JSON.stringify(value)} (quote it, e.g. ${key}: "${value}")`);
+    } else if (!ID.test(value) || value.includes("..") || value.length > 100) {
+      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])}`);
+    }
+  }
+  for (const key of LISTS) {
+    if (config[key] !== undefined && !Array.isArray(config[key])) {
+      problems.push(`${key}: must be a list (one "- item" per line), got ${JSON.stringify(config[key])}`);
+    }
+  }
+  if (Array.isArray(config.allowedPaths)) {
+    config.allowedPaths.forEach((entry, index) => {
+      if (!nonEmptyString(entry)) {
+        problems.push(`allowedPaths[${index}]: must be a non-empty path, got ${JSON.stringify(entry)}`);
+      }
+    });
+  }
+  if (config.envelope !== undefined) {
+    if (!isMap(config.envelope)) {
+      problems.push("envelope: must be a map (prompts, vars, pin)");
+    } else {
+      for (const key of Object.keys(config.envelope)) {
+        if (!ENVELOPE_KEYS.includes(key)) {
+          problems.push(unknownKey("envelope.", key, ENVELOPE_KEYS));
+        }
+      }
+    }
+  }
+  if (config.workers === undefined || config.workers === null) {
+    problems.push("workers: required and missing (at least the verifier; see templates/v2/run-config.example.yaml)");
+  } else if (!isMap(config.workers)) {
+    problems.push("workers: must be a map of worker name -> { command, args, ... }");
+  } else {
+    for (const [name, spec] of Object.entries(config.workers)) {
+      const where = `workers.${name}`;
+      if (!isMap(spec)) {
+        problems.push(`${where}: must be a map with at least a command`);
+        continue;
+      }
+      for (const key of Object.keys(spec)) {
+        if (!WORKER_KEYS.includes(key)) {
+          problems.push(unknownKey(`${where}.`, key, WORKER_KEYS));
+        }
+      }
+      if (!nonEmptyString(spec.command)) {
+        problems.push(`${where}.command: required, a non-empty string`);
+      }
+      if (spec.args !== undefined && !Array.isArray(spec.args)) {
+        problems.push(`${where}.args: must be a list (one "- arg" per line)`);
+      }
+      if (spec.timeoutMs !== undefined && !(typeof spec.timeoutMs === "number" && spec.timeoutMs > 0)) {
+        problems.push(`${where}.timeoutMs: must be a positive number, got ${JSON.stringify(spec.timeoutMs)}`);
+      }
+      if (spec.inheritEnv !== undefined && typeof spec.inheritEnv !== "boolean") {
+        problems.push(`${where}.inheritEnv: must be true or false, got ${JSON.stringify(spec.inheritEnv)} (anything else used to mean false silently)`);
+      }
+      if (spec.env !== undefined && !isMap(spec.env)) {
+        problems.push(`${where}.env: must be a map of NAME -> value`);
+      }
+    }
+  }
+  return problems;
+}
+
+// Second pass, once the workflow is loaded: names that must exist in it.
+export function checkRunConfigAgainstWorkflow(config, workflow) {
+  const problems = [];
+  const steps = [...workflow.stepIds];
+  const workers = [...new Set(workflow.steps.map((step) => step.worker).filter(Boolean))];
+  for (const name of Object.keys(isMap(config.workers) ? config.workers : {})) {
+    if (!workers.includes(name)) {
+      const guess = suggest(name, workers);
+      problems.push(`workers.${name}: no step of the workflow uses this worker${guess ? ` (did you mean ${guess}?)` : ""}; workers in this workflow: ${workers.join(", ")}`);
+    }
+  }
+  for (const step of Array.isArray(config.stopAt) ? config.stopAt : []) {
+    if (!workflow.stepIds.has(step)) {
+      const guess = suggest(step, steps);
+      problems.push(`stopAt: "${step}" is not a step of the workflow${guess ? ` (did you mean ${guess}?)` : ""}; steps: ${steps.join(", ")}`);
+    }
+  }
+  if (config.entry !== undefined && config.entry !== null && !workflow.stepIds.has(config.entry)) {
+    const guess = suggest(config.entry, steps);
+    problems.push(`entry: "${config.entry}" is not a step of the workflow${guess ? ` (did you mean ${guess}?)` : ""}; steps: ${steps.join(", ")}`);
+  }
+  return problems;
+}