@haiyangbg/buildbeat 2.0.1 → 3.0.0

package/templates/standards/STACK.md

@@ -16,15 +16,9 @@
 | CI 与测试 | <CI 与测试命令> | CI workflow / 测试配置 |
 | 供应链 | <许可证 / 供应链约束> | LICENSE / lockfile / 安全策略 |
 
-## 可核对基线（bus-check v1）
+## 可核对事实
 
-下面的注释块是仓库事实的精确比对入口，不从上表自然语言猜值。每个键至少一行；有多个已观测值时重复该键；确认不适用时将唯一值填为 n/a。Node 值逐字对应 .nvmrc 或 package.json 的 engines.node；lockfile 填文件名；容器填 Dockerfile FROM 的镜像令牌。
-
-<!-- buildbeat-stack-baseline:v1
-nodeConstraint=<.nvmrc / engines.node 的精确值；多值重复本行；无则 n/a>
-lockfileKind=<lockfile 文件名；多类重复本行；无则 n/a>
-dockerFromImage=<Dockerfile FROM 镜像；多值重复本行；无则 n/a>
--->
+上表每一行都要能指回一个仓库事实（`.nvmrc` / `engines.node`、lockfile 文件名、Dockerfile `FROM` 镜像等）。不确定的值保留占位符或标 `n/a`，不猜。Run 配置里的 `requires:`（command / probe）是这些事实的可执行形态，起跑前 fail-closed。
 
 ## Rules
 

package/templates/v2/AGENTS.md

@@ -1,35 +1,35 @@
-# AGENTS.md — <项目名> 工作区 · BuildBeat v2 协作契约
+# AGENTS.md — <项目名> 工作区 · BuildBeat 协作契约
 
 > 本文件走开放标准 `AGENTS.md`，由工作区下的会话按各工具自己的方式装载（Claude Code / Codex / Cursor / Gemini CLI / Aider / Zed 等多数会自动读根目录 `AGENTS.md` 或 `CLAUDE.md`；不自动读的工具由人开场贴给会话——用哪个工具就按它的文档核对一次，不要假设）。目的：每个会话开工即知道「当前工作在哪 / 我是什么视角 / 读哪 / 写哪 / 该调哪条命令」，不靠人转述上下文。
 > **层叠规则**（标准语义）：会话从被编辑文件所在目录向上收集沿途所有 `AGENTS.md` 合并，**离得越近优先级越高**。本文件只写全局的（路由 / 协作规则 / 红线），各代码子仓的局部细节写进**该仓自己的 `AGENTS.md`**。
 > 根目录 `CLAUDE.md` 只是一行指针（兼容只认该文件名的工具），内容单点在本文件。全栈总图见 `./ARCHITECTURE.md`，按需读。
-> **本仓运行 BuildBeat v2**（运行时 `@haiyangbg/buildbeat@<版本>`，`buildbeat-v2` 由会话调用，人不必手敲）。若由 v1 迁来：`pm/NOW.md`、当期看板、`pm/status/*` 冻结只读，**禁止双写**。
+> **本仓运行 BuildBeat**（运行时 `@haiyangbg/buildbeat@<版本>`，`buildbeat` 由会话调用，人不必手敲）。
 
-## 0. v2 下工作怎么发生（一页流程）
+## 0. 工作怎么发生（一页流程）
 
-1. **工作项**：每件事一个 `delivery/work/<WORK-ID>/`（`intent.md` 为什么做 + **止损线**（最多几个 Run / 几轮 review / 几小时，越线先问所有者"继续还是砍"）+ `plan.md` 怎么做，可选 `env-facts.md` 记踩出来的环境事实）；被 digest 绑定接受（`buildbeat-v2 accept`）前只是草稿、不产生义务。`overview` 的 `cost:` 行就是止损线的读数。
-2. **代码工作跑 Run**：`buildbeat-v2 start --config <run-config.yaml> --attempt new` → 隔离 worktree 内 Build→Verify→Fix→Review 自动闭环 → **停在合并决定**。push、合并、部署永远是人批之后的人类动作。
-3. **人怎么知道该做什么**：`buildbeat-v2 overview --repo .` 回答「每件事走到哪、下一步该谁」；`inbox` 只列等人批的 Run，每条后面附可复制的下一句命令；`status --run <RUN>` 回答「还在动吗、动了多久、卡没卡」。
+1. **工作项**：每件事一个 `delivery/work/<WORK-ID>/`（`intent.md` 为什么做 + **止损线**（最多几个 Run / 几轮 review / 几小时，越线先问所有者"继续还是砍"）+ `plan.md` 怎么做，可选 `env-facts.md` 记踩出来的环境事实）；被 digest 绑定接受（`buildbeat accept`）前只是草稿、不产生义务。`overview` 的 `cost:` 行就是止损线的读数。
+2. **代码工作跑 Run**：`buildbeat start --config <run-config.yaml> --attempt new` → 隔离 worktree 内 Build→Verify→Fix→Review 自动闭环 → **停在合并决定**。push、合并、部署永远是人批之后的人类动作。
+3. **人怎么知道该做什么**：`buildbeat overview --repo .` 回答「每件事走到哪、下一步该谁」；`inbox` 只列等人批的 Run，每条后面附可复制的下一句命令；`status --run <RUN>` 回答「还在动吗、动了多久、卡没卡」。
 4. **上线**：生产动作是人的；`release-readback` 预设 + `release` 风险预设把「做之前回读 → 人做 → 做之后回读 → 观察 → 人关窗」记成 L4 证据，任一步失败即停人批。
-5. **observe 盯生产**：`buildbeat-v2 observe run --config .buildbeat/observe.yaml` 一次=一轮只读体检；异常分层（落账→只读诊断→intent 草稿入队 `delivery/observe/intents/`），草稿**绝不自动执行**，人用 `observe triage` 分诊。
-6. **拍板台账**：平台级真实决策包一行进 `pm/decisions.md`（纯 v2 项目也只建这一个 v1 文件，从 `templates/pm/decisions.md` 拷）；Run 级批准落各 Work 的 `decisions.jsonl`；finding 裁决落 `review-findings.jsonl`。跨仓契约在 `contracts/`（单仓项目可无）。
+5. **observe 盯生产**：`buildbeat observe run --config .buildbeat/observe.yaml` 一次=一轮只读体检；异常分层（落账→只读诊断→intent 草稿入队 `delivery/observe/intents/`），草稿**绝不自动执行**，人用 `observe triage` 分诊。
+6. **拍板台账**：平台级真实决策包一行进 `pm/decisions.md`（从 `templates/pm/decisions.md` 拷，`pm/` 下只有这一个文件与可选的 `adr/`）；Run 级批准落各 Work 的 `decisions.jsonl`；finding 裁决落 `review-findings.jsonl`。跨仓契约在 `contracts/`（单仓项目可无）。
 7. **通知**：`.buildbeat/notify.yaml` 配一条通道（URL 只能来自环境变量），Run 停在人批 / 终态 / 疑似卡住会来找人。
-8. **打扫**：终态 Run 留下的工作树用 `buildbeat-v2 gc --repo .` 清（默认只出计划）。工作树在仓内 `.buildbeat/worktrees/`：`.gitignore` 排除 `.buildbeat/runtime/` 与 `.buildbeat/worktrees/`，测试框架的收集范围也要排除 `**/.buildbeat/**`（vitest `exclude`、jest `testPathIgnorePatterns`、pytest `norecursedirs`），否则主干测试会把旧候选的用例一起跑。
+8. **打扫**：终态 Run 留下的工作树用 `buildbeat gc --repo .` 清（默认只出计划）。工作树在仓内 `.buildbeat/worktrees/`：`.gitignore` 排除 `.buildbeat/runtime/` 与 `.buildbeat/worktrees/`，测试框架的收集范围也要排除 `**/.buildbeat/**`（vitest `exclude`、jest `testPathIgnorePatterns`、pytest `norecursedirs`），否则主干测试会把旧候选的用例一起跑。
 9. **worker 信封**：`delivery/envelope/`（从 `templates/v2/envelope/` 拷）放 `worker.sh` 与 builder / reviewer / fixer 的 prompt，run 配置 `envelope.prompts` 指向它；换工具只改 run 配置里 `--` 后的命令。**worker 环境事实（写进 prompt）**：worker 的沙箱通常**不能监听端口**，需要起服务或绑定 loopback 的集成测试交给 verify 步，worker 只跑单测与静态检查，不要反复尝试；PATH 只认 POSIX 工具（`grep -E` 不用 `rg`，`find` 不用 `fd`）或在 `requires:` 里声明；verify / 包装脚本发现环境不满足（命令不在 PATH、端口被占、后端 404）就 `exit 75`，内核会当基础设施故障停人、不派 fixer、不扣预算。
 
 ## 1. 工作包路由 —— Builder 端到端负责，会话按 AI 视角隔离
 
-> 协作单元是需求/功能工作包（= v2 Work）。一个 Builder 对工作包的产品判断、实现、测试、合并与发布证据端到端负责；下表是可调用的 AI 专业视角和文件写边界，不是人类岗位或固定交接流水线。共享事实走 Git（`delivery/` 与 Run 台账）。
+> 协作单元是需求/功能工作包（= Work）。一个 Builder 对工作包的产品判断、实现、测试、合并与发布证据端到端负责；下表是可调用的 AI 专业视角和文件写边界，不是人类岗位或固定交接流水线。共享事实走 Git（`delivery/` 与 Run 台账）。
 
 | AI 视角 | cwd | 可写（拥有） | 只读 | 开工先读 |
 |---|---|---|---|---|
-| **产品**（规格/编排） | 工作区根 | `delivery/**`、`pm/decisions.md`、根规划文档、`contracts/**` | 全仓 | `buildbeat-v2 overview --repo .` |
+| **产品**（规格/编排） | 工作区根 | `delivery/**`、`pm/decisions.md`、根规划文档、`contracts/**` | 全仓 | `buildbeat overview --repo .` |
 | **全栈**（实现，含运维） | `<代码仓>/` | `<代码仓>/**`（Run 内受 `allowedPaths` 机器约束） | `delivery/*`、契约 | 所属 Work 的 intent/plan + `run-config.yaml` |
 | **测试**（契约验证·E2E） | 工作区根 | `tests/**`、独立核验报告（落所属 Work 目录） | 实现 + 规格 + 契约 | 所属 Work + 契约 |
 
 > 🔴 **边界（按项目填写）**：<新地盘 / 老地盘 / 只读模块 / 不得借道写入的目录>。
-> 🔴 **写者≠审者的机器化**：v2 Run 内置 fresh-context 只读 reviewer（快照强制，写入即失败落账）；merge 门绑定 candidate + plan + 证据 digest，过期即 stale。
-> **开工/收工护栏**：任意会话开工先各仓 `git pull`，再 `buildbeat-v2 overview --repo .`（活动 Work、等人的 Run、成本）；收工前再跑一次 `overview` 并把 warning / unverified 原样写进收口。**只有从 v1 迁来、仓里还有 `pm/NOW.md` 的项目**才另跑 `bash scripts/bus-check.sh`（它只检查 v1 文件总线那部分：契约版本、子仓同步、幽灵 hash），纯 v2 项目没有 `pm/NOW.md` 就不装、不跑、不为了它伪造 v1 文件。生产状态问 `observe status`，不猜。
+> 🔴 **写者≠审者的机器化**：Run 内置 fresh-context 只读 reviewer（快照强制，写入即失败落账）；merge 门绑定 candidate + plan + 证据 digest，过期即 stale。
+> **开工/收工护栏**：任意会话开工先各仓 `git pull`，再 `buildbeat overview --repo .`（活动 Work、等人的 Run、成本）；收工前再跑一次 `overview` 并把 warning / unverified 原样写进收口。生产状态问 `observe status`，不猜。
 
 ## 1.5 UI 规范摘要（非 UI 项目可删）
 
@@ -37,17 +37,17 @@
 - **界面零元注释**：上线的可见界面不得出现给"做的人"看的文字；每次上线核查门必查。
 - UI 交付的拍板对象必须含可渲染证据（真渲染入口 + 截图 digest）；静态描述不构成拍板对象。
 
-## 2. 协作规则（v2 版）
+## 2. 协作规则
 
-**① 唯一入口** —— 活动工作看 `delivery/`（`overview` / `inbox`）；v1 遗留入口 `pm/NOW.md` 只读。
+**① 唯一入口** —— 活动工作看 `delivery/`（`overview` / `inbox`）；不另建进度文件、状态文件或看板，进度由内核从台账与 Git 回读。
 **② 契约落盘不喊话（双向）** —— 跨边界接口先改 `contracts/` 再动代码；收到协议声明独立核查再信。反向流：实现中发现契约不够用 → 不得就地消化，停下记契约缺口交产品域裁决。
 **③ 交接靠 candidate hash + 台账** —— Run 停在合并决定时 candidate 已由 Git 回读固定；跨会话接力读 `delivery/work/<id>/` 即知全部事实，hash 不得编造。
-**④ 护栏与不可逆动作** —— 开工 `overview`（v1 迁来的仓另加 `bus-check`）；部署/改契约/migration 等不可逆动作前再核一次并走人批；exit 0 不消除 `warning/unverified`。
+**④ 护栏与不可逆动作** —— 开工 `overview`；部署/改契约/migration 等不可逆动作前再核一次并走人批；exit 0 不消除 `warning/unverified`。
 **⑤ 风险分轨** —— Risk Preset：`fast`（仅 merge 人批）/ `standard`（plan+merge，默认）/ `controlled`（intent+plan+merge+release）/ `release`（上线回读车道）。
 **⑥ 核查门** —— Run 内 reviewer 只读、结构化 findings；`reviewTriage: required` 时 P0/P1 先过人分诊再派 fixer；review 每 Run 默认 2 轮封顶。**完成 = hash + 可核验证据**；标准轨最低 L3，上线必须 L4。`UNVERIFIED` 永不当作通过。
 **⑦ 状态单点** —— 事实进 Run 证据与 Work 记录；进度看 `overview`，度量看 `metrics`（本地只读）。
 **⑧ 视觉问题带图对比** —— 提 UI bug 必附『实现截图 ⟷ 设计稿截图』并排 + 标注差异点。
-**⑨ 单点事实** —— 线上版本只信实查（`bus-check` / `observe status`）；每个收敛后的真实决策包只在 `pm/decisions.md` 记一行；历史台账不回改。
+**⑨ 单点事实** —— 线上版本只信实查（`observe status` / 部署平台）；任何文档不写「当前线上 vX」；每个收敛后的真实决策包只在 `pm/decisions.md` 记一行；历史台账不回改。
 **⑩ 真渲染拍板** —— 有 UI 的拍板对象必须是真渲染证据。
 **⑪ 所有者可见命名进决策卡** —— 域名、服务名、环境名、自停时长、窗口时长等**所有者以后要看见或要念出来的名字与参数**，不由 worker 顺手定：进 intent 或门前决策卡（`BATCH_AT_GATE`），给推荐值和理由（用业务上听得懂的名字，不用内部术语）。
 
@@ -65,7 +65,7 @@
 
 ## 3. 红线（每个会话受约束）
 
-1. **凭据不入 git、不出本机**：文档只标位置不写值；本地 .env gitignore + 600；机器闸 = gitleaks pre-commit；v2 Worker 默认 env 白名单；通知 URL 只能来自环境变量。
+1. **凭据不入 git、不出本机**：文档只标位置不写值；本地 .env gitignore + 600；机器闸 = gitleaks pre-commit；Worker 默认 env 白名单；通知 URL 只能来自环境变量。
 2. **不 `git add -A`**：只 stage 当前工作包拥有的具体文件；各仓分别提交。
 3. **不未授权部署**、不 force-push、不 `--amend` 已推送历史、不 `--no-verify`。Run 的合并决定只表示候选具备合并条件（`SUCCEEDED` ≠ 已合并），合并/push/发布是其后的人类动作、逐项授权。
 4. **每次部署完必更对应仓 `CHANGELOG.md`**；部署后 `observe run` 一轮。

package/templates/v2/BUILDBEAT.md

@@ -1,9 +1,8 @@
-# BUILDBEAT.md — 本项目的 BuildBeat v2 标记
+# BUILDBEAT.md — 本项目的 BuildBeat 标记
 
-**本项目运行 BuildBeat v2**：运行时 `@haiyangbg/buildbeat@<X.Y.Z>`（<yyyy-mm-dd> 首次接入；查看本机版本 `npm ls -g @haiyangbg/buildbeat`，查看最新 `npm view @haiyangbg/buildbeat@latest version`）
+**本项目运行 BuildBeat**：运行时 `@haiyangbg/buildbeat@<X.Y.Z>`（<yyyy-mm-dd> 首次接入；查看本机版本 `npm ls -g @haiyangbg/buildbeat`，查看最新 `npm view @haiyangbg/buildbeat@latest version`）
 **装载方式**：会话读根目录 `AGENTS.md`（`CLAUDE.md` 是一行指针）；驾驶手册在 BuildBeat Skill `SKILL.md` §0.5
 **活动工作**：`delivery/work/<WORK-ID>/`（intent / plan / run-config / decisions.jsonl / runs/）；信封与 worker 包装在 `delivery/envelope/`
-**v1 遗留**：<无 | `pm/NOW.md` 等已于 <yyyy-mm-dd> 冻结只读，禁止双写>
 来源：<https://github.com/HaiYangBG1/BuildBeat>
 
 ## 升级

package/templates/v2/CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md — 指针(🔴 勿在此处写内容)
 
-本工作区的会话路由、协作总线十条规则、红线,**单点在同目录的 [`AGENTS.md`](AGENTS.md)** —— 请立即读取那份。
+本工作区的会话路由、协作规则、红线,**单点在同目录的 [`AGENTS.md`](AGENTS.md)** —— 请立即读取那份。
 
 > 本文件只为兼容「只认 `CLAUDE.md` 这个文件名的工具」而存在,**永远保持这几行**。
 > 往这里复制任何规则 = 两份文档必然漂移(上游 `lessons.md` 第 1 条:SSOT 腐烂)。

package/templates/v2/run-config.example.yaml

@@ -1,6 +1,6 @@
 # BuildBeat v2 run 配置样板。拷到 delivery/work/<WORK-ID>/run-config.yaml 后改 work / run / allowedPaths / workers。
 # 路径相对本文件解析。严格 YAML 子集：只有块列表与块映射，无行内 [] / {}、无锚点、注释必须独占一行。
-# 起跑前：buildbeat-v2 doctor --config <本文件>；起跑：buildbeat-v2 start --config <本文件> --attempt new
+# 起跑前：buildbeat doctor --config <本文件>；起跑：buildbeat start --config <本文件> --attempt new
 repo: ../../..
 work: WORK-X
 # 家族名；--attempt new 自动编成 RUN-X-01/02…

package/templates/v2//346/214/207/346/214/245/345/217/260.md

@@ -1,16 +1,16 @@
-# 指挥台 — Builder 怎么驱动 v2 工作（忘了怎么开场就看这页）
+# 指挥台 — Builder 怎么驱动工作（忘了怎么开场就看这页）
 
-> 本仓运行 BuildBeat v2。会话按所用工具的方式装载 `AGENTS.md`（多数工具自动读根目录 `AGENTS.md` / `CLAUDE.md`；不自动读的，开场把它贴给会话）；活动工作在 `delivery/`。你基本只需说下面这几句话，命令由会话调、不用你手敲。
+> 本仓运行 BuildBeat。会话按所用工具的方式装载 `AGENTS.md`（多数工具自动读根目录 `AGENTS.md` / `CLAUDE.md`；不自动读的，开场把它贴给会话）；活动工作在 `delivery/`。你基本只需说下面这几句话，命令由会话调、不用你手敲。
 
 ## 日常六句话
 
 | 你想干什么 | 说什么 | 会话背后调什么 |
 |---|---|---|
-| 看现在到哪了、该谁动 | 「当前进度」/「待办是什么」 | `buildbeat-v2 overview --repo .`（每个 Work 的阶段 + 下一步）+ `observe status` |
-| 看有什么等我批 | 「有什么要我拍板」 | `buildbeat-v2 inbox --repo .`（每条附可复制的下一句） |
+| 看现在到哪了、该谁动 | 「当前进度」/「待办是什么」 | `buildbeat overview --repo .`（每个 Work 的阶段 + 下一步）+ `observe status` |
+| 看有什么等我批 | 「有什么要我拍板」 | `buildbeat inbox --repo .`（每条附可复制的下一句） |
 | 立一件新事 | 「开个 Work：〔一句话目标〕」→ 看完说「接受」 | 建 `delivery/work/<ID>/intent.md + plan.md` → `accept`（digest 绑定） |
-| 让它干活 | 「开工」/「再来一轮」 | 先 `buildbeat-v2 doctor --config …`（配置、intent/plan 接受状态、env 姿态、预算），再 `start --config … --attempt new`（自动编号、自动作废旧等待，停在合并决定） |
-| 它是不是卡了 | 「怎么样了」/「卡住了吗」 | `buildbeat-v2 status --repo . --run <RUN>`（耗时、历史中位数、最后输出、STALLED） |
+| 让它干活 | 「开工」/「再来一轮」 | 先 `buildbeat doctor --config …`（配置、intent/plan 接受状态、env 姿态、预算），再 `start --config … --attempt new`（自动编号、自动作废旧等待，停在合并决定） |
+| 它是不是卡了 | 「怎么样了」/「卡住了吗」 | `buildbeat status --repo . --run <RUN>`（耗时、历史中位数、最后输出、STALLED） |
 | 拍板 | 「批准 / 拒绝〔RUN-ID〕」；分诊时「这条接受，那条不算」 | `approve` / `reject` / `findings adjudicate`；会话说清批的是哪一步（放行 fixer / 再跑一次 / 合并决定），非终态批准后 `resume` 续跑；合并决定只表示候选够格合并，合并/push/部署逐项另说 |
 
 其他：生产报警看 `delivery/observe/intents/` 草稿 → 「fix_now / schedule / dismiss」；上线用 `release-readback` 预设开一个 Run，「我做完了」就是批准 `enter-apply-readback`；「打扫卫生」= `gc --repo .`（先看计划再 `--apply true`）。

package/bin/buildbeat-v2.js

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

package/bin/solobaton.js

@@ -1,6 +0,0 @@
-#!/usr/bin/env node
-
-import { run } from "../src/cli.js";
-
-// Legacy executable alias for the published `solobaton` npm package.
-process.exitCode = await run(process.argv.slice(2));