@haiyangbg/buildbeat 3.3.1 → 4.1.0

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

@@ -1,61 +1,17 @@
-# How to talk to a session that has BuildBeat (by project stage)
+# Talk to your session
 
-[简体中文](00-how-to-talk.md) | **English**
+[简体中文](00-how-to-talk.md)
 
-> This page is for **users**. You work in any AI coding session (any tool will do, and one session is enough) that has loaded the BuildBeat Skill; you speak plainly, and the session calls `buildbeat`, reads the output and answers you as "done → not done → next". **You do not need to remember any command.** The example phrases below are what people normally say; copy them as they are. Phrases in the same cell mean the same thing; pick whichever comes naturally.
-> The session-side rules that correspond to this page are in `SKILL.md` §0.5; project-specific routing and red lines are in each project's root `AGENTS.md`.
-
-Before switching sessions, say "write the key context down, I am closing the old session"; in the new session say "read the project entry point, check progress and pending approvals, and carry on with this work". When handing over to a teammate, say "sync the project records and the candidate so the person taking over can check the current scope and the environment the original Run lives in". The detailed steps, and what an active Run needs to keep, are in [Session and team handoff](11-session-handoff.en.md).
-
-## One table: a project from zero to the next phase
-
-| Stage | What you want | Just say | What the session does behind it | What you get / watch for |
-|---|---|---|---|---|
-| **0. Not started** | Decide whether BuildBeat is worth it | "Is this project a good fit for BuildBeat?" | Looks at repository size, timeline, number of repositories / deployment units / sessions | A one-line verdict: worth it for multi-phase iterations / several repositories / several sessions; a job that wraps up within a week is simply done directly |
-| | Set up a new project | "Set this project up with BuildBeat" "Initialise the collaboration skeleton" | Reads the code first → asks a few questions (stack, repositories, deployment units, whether there is a UI) → one confirmation screen → generates `AGENTS.md`, `delivery/` (with the envelope), `.buildbeat/observe.yaml`, `.buildbeat/notify.yaml`, a gitleaks pre-commit hook | One confirmation screen; it writes only after you say "OK", then lists the files it generated |
-| | Take over an existing project | "Put this existing project on BuildBeat" "Take over this repository" | Surveys it (tests, contracts, deployment facts) → draws strangler boundaries (new ground / old ground / read-only) → phase 0 adds a minimal verification suite | A survey report plus a boundary draft; you decide the boundaries; history is not rewritten |
-| | Turn on notifications | "Notify me when a Run stops" | Writes `.buildbeat/notify.yaml` (DingTalk / webhook) | It tells you which robot to create and which environment variable to `export`; the URL never enters Git |
-| **1. Start a work · settle the approach** | Start something | "Open a Work: 〔one-line goal〕" "Turn the current goal into a Work" | Writes `delivery/work/<ID>/intent.md` (why, and what counts as done) + `plan.md` (how, in how many steps) + `run-config.yaml` | A summary + "say accept once you have read it"; only your "accept" makes the digest binding take effect |
-| | See the approach before any code | "Don't touch the code yet, give me the approach" "Tell me the difference between A and B" | Produces drafts and comparisons only; no Run starts | A comparison + a recommendation + consequences; nothing is built before you decide |
-| | Pick out what is mine to decide | "What in this approach needs my decision?" "Is there anything I need to decide?" | Compresses the acceptance list into real trade-offs (including names you will say out loud later: domains, service names, durations) | 2–5 decision items at once, each with a recommended value; no chain of one-by-one questions |
-| | Decide | "Accept" "Go with all the recommendations" "Take B for the second one, recommendations for the rest" | `accept` the intent/plan; decisions land in `decisions.jsonl` / `pm/decisions.md` | A one-line confirmation; editing the plan makes the acceptance stale automatically, and it must be accepted again |
-| | Set the risk level | "Use the fast track for this" "Be stricter with this one" | `riskPreset: fast / standard / controlled` | fast stops only before the merge; standard adds plan acceptance; controlled adds intent acceptance and the release gate |
-| **2. Get ready to run** | Check the environment | "What does the environment need?" "Run a preflight" | Checks `requires:` (binary versions + `probe:` probes); `preflight --step` dry-runs up to the first failure boundary | Everything missing reported at once; a dry run produces no evidence, a real Run has to reproduce it |
-| | Freeze the envelope | "Pin the prompts" "Freeze the envelope" | Adds `pin: <sha>` under `envelope:` | Every Run from then on records the envelopeDigest, so it can be traced |
-| **3. Run · move forward** | Put it to work | "Go" "〔WORK-ID〕, your turn" | `start --config … --attempt new` (numbered automatically, older waiting runs superseded, started detached) | "RUN-X-02 has started; I will tell you when it stops at the merge decision" |
-| | See progress | "Where are we?" "Current progress" "Per repository, please" | `overview` (each Work's stage + whose move is next) + `observe status` | One line per item: stage, who it is waiting on, next; no commands listed |
-| | See the next step | "What's next?" "What do you need from me?" | The `next` lines of `overview`, only those in your hands | Only what you have to do: DNS, credentials, approvals, hands-on actions |
-| | Worried it is stuck | "How's it going?" "Is it stuck?" "It has been half an hour, is that normal?" | `status --run` (time per step, historical median, last output, STALLED) | One line with numbers: "verify has run 14 minutes, the historical median is 6, last output 2 minutes ago, still moving"; a suspected stall is said plainly |
-| | See what is waiting for me | "What needs my approval?" "What's waiting on me?" | `inbox` + `delivery/observe/intents/` | Item by item: what it waits for, where the evidence is, a recommended A/B |
-| | Approve / refuse | "Approve" "Approve RUN-X" "Reject, because …" | `approve` / `reject`; after approving a non-terminal transition, `resume` continues the run | It says which step you approved: release the fixer / run once more / the merge decision; the merge decision only says the candidate is fit to merge, and merge / push / deploy are separate things you ask for |
-| | Rule on a finding | "This one doesn't count, accept that one" "This is a false positive" | `findings adjudicate dismiss/accept` → releases the fixer | The same dismissed finding no longer blocks; a higher severity reopens it |
-| | Another round | "One more round" "Continue" | A new attempt | The old waiting run is superseded automatically; the inbox shows only live items |
-| | Stop | "Stop if it fails again this time" "Stop for now" | Caps the rounds; `stop --reason` records it, and the candidate and evidence are kept | Done / not done / next, with hashes; then you decide whether to change the approach, fix it by hand or close the Work |
-| **4. Acceptance · merge** | Accept the result | "Run acceptance" "Check the RUN-X candidate" | The testing perspective verifies the exact candidate independently; the report lands in the Work directory | Pass / fail + evidence; the writer's own word is not evidence |
-| | Merge | "Go ahead and merge" "You may push" | A human action carried out by the session (within the red lines in `AGENTS.md`), then read back from the remote | The hash after the merge; `overview` shows MERGED |
-| **5. Release** | Release | "Release it" "Get ready to release" | The `release-readback` preset + `riskPreset: release`: read back first → stop | "Readback is all green; now it is your turn to do 〔the action〕; tell me when it is done" |
-| | I have done it | "Done" "Half done, check it for me" | Approves apply-readback → readback + observation → stops at closing the window | What is still missing, item by item; any failed step stops it |
-| | Decide the release card | "Approve the release" "Don't release yet" | Carries out / does not carry out the decision card | Production actions are always yours; it only reads back and records |
-| | Production alert | "Production is alerting" "Run a health check" | `observe run` → drafts queued | A one-line draft + "fix_now / schedule / dismiss, your call" |
-| **6. Wrap up · next phase · retrospective** | Close something | "This Work is done" "Close this Work" | Records the decision, confirms the run-record is in the Git plane | `overview` stops listing it as open |
-| | Clean up | "Tidy up" | `gc` (the plan first; `--apply` once you nod) | How many worktrees were cleaned; any candidate reachable only from its branch is always kept, with the reason |
-| | Next phase | "Start the next phase" "Move on to the next phase" | The phase-change compaction ritual: archive, truncate, reset pointers, ask what to feed back | One screen of checklist; the new phase starts from a clean entry point |
-| | Retrospective | "Review what BuildBeat did for us" "What went well and what didn't?" | `metrics` + Run ledgers + session records | Positives / negatives / changes, with numbers |
-| | Keep the lesson | "Write down what we learned from this blocker" | Writes `pm/<date>-<topic>.md` + `env-facts.md`, and turns what can be checked by machine into `requires:` probes | The next window refers to it directly instead of passing it on by word of mouth |
-| | Feed back upstream | "What could BuildBeat itself learn from this?" | Compares against lessons to find new pitfalls | A candidate list, each item A/B/C |
-| | Upgrade | "Update the BuildBeat version" | Updates `BUILDBEAT.md` / `AGENTS.md` / `.buildbeat/*.yaml`, runs `doctor` | The version marker + the doctor report |
-
-## Phrases that work at any stage
-
-| You say | It will |
+| You say | The session does |
 |---|---|
-| "Why?" "What happens if we don't?" "Where did this name come from?" | Explain in plain words, and turn what is yours to decide (names, durations, scope) into decision items for you to approve instead of deciding for you |
-| "Plain words, please" "No numbered lists" | One line each for done / not done / next; separate items only when they really differ |
-| "What do you think?" | Give one recommendation and the reason, not a pile of options |
-| "Authorised" or "Approved" on its own | Applies only to the one thing it explicitly proposed just before, never to other actions |
+| Continue this project | Read project instructions, work records, and status; identify the active run |
+| Prepare this feature | Write work.md: goal, scope, acceptance criteria, implementation plan |
+| Accept and start | Record the acceptance, then run; reuse existing explicit authorization |
+| Where are we, what needs my decision? | Show candidate, evidence, findings, decision subject and next step |
+| I fixed it | Read back the clean tree and commit, then run --adopt to verify |
+| Reject or cancel | Record the reason and preserve history; handle a live lock-owning driver separately |
+| Switch sessions | Save missing facts and retain active runtime files; continue from project records |
 
-## Three baselines (so you don't have to ask)
+The loop ends at the merge decision. Merge, push, deployment and publication each require their corresponding authorization.
 
-- **Approval ≠ execution**: merge, push, deploy, spending and deletion each need you to say so, one by one.
-- **Numbers must be concrete**: asking "is this normal?" always gets elapsed time / historical median / time of last output; with no data it says there is no data.
-- **Names go through you first**: domains, service names, environment names, auto-stop durations — anything you will say out loud later — come as recommended values on a decision card for you to approve; the session does not decide them itself.
+For a main repository with code repositories, inspect them together with `buildbeat status --repo . --all-repos`. See [Session handoff](11-session-handoff.en.md) for discovery, filters and settled counts.

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

@@ -1,61 +1,17 @@
-# 怎么和装了 BuildBeat 的会话说话（按项目阶段）
+# 怎么和会话说话
 
-**简体中文** | [English](00-how-to-talk.en.md)
+[English](00-how-to-talk.en.md)
 
-> 这是给**用户**看的一页。你在任意一个 AI 编程会话里工作（哪家工具都可以，一个会话就够），会话装载了 BuildBeat Skill；你说人话，它去调 `buildbeat`、读输出、按「已做 → 未做 → 下一步」回你。**你不需要记任何命令**。下面的例句就是平时的说法，照抄即可；同一格里的几句话意思相同，挑顺口的。
-> 会话侧的对应规则在 `SKILL.md` §0.5；项目专属的路由与红线在各项目根的 `AGENTS.md`。
-
-准备换会话时说「把关键上下文落盘,我要关闭旧会话」;新会话说「读取项目入口,核对进度与待批,继续这个工作」。交给同事时说「同步项目记录与候选,让接手成员核对当前范围和原 Run 所在环境」。详细步骤与活动 Run 的保留范围见 [跨会话与团队接续](11-session-handoff.md)。
-
-## 一张表：项目从零到换期
-
-| 阶段 | 你想干什么 | 你就这么说 | 会话背后做什么 | 你会得到什么 / 注意 |
-|---|---|---|---|---|
-| **0. 未开始** | 判断值不值得上 BuildBeat | 「这个项目适合用 BuildBeat 吗」 | 看仓库规模、周期、仓/部署单元/会话数 | 一句判断：多期迭代 / 多仓 / 多会话才值得；一周收尾的小活直接干 |
-| | 新项目搭骨架 | 「帮我用 BuildBeat 搭一下这个项目」「初始化协作骨架」 | 自查代码 → 少量提问（栈、仓、部署单元、有没有 UI）→ 一屏确认 → 生成 `AGENTS.md`、`delivery/`（含信封）、`.buildbeat/observe.yaml`、`.buildbeat/notify.yaml`、gitleaks pre-commit | 一屏确认单，你说「可以」它才写；生成后给文件清单 |
-| | 接管老项目 | 「给这个老项目套上 BuildBeat」「接管这个仓」 | 摸底（测试、契约、部署事实）→ 划绞杀边界（新地盘 / 老地盘 / 只读）→ 第 0 期补最小验证 | 摸底报告 + 边界草案，你拍板边界；历史不回改 |
-| | 装上通知 | 「Run 停下来时通知我」 | 写 `.buildbeat/notify.yaml`（钉钉 / webhook） | 它告诉你要建什么机器人、`export` 哪个环境变量；URL 永远不进 Git |
-| **1. 立项 · 定方案** | 立一件事 | 「开个 Work：〔一句话目标〕」「把当前目标收成一个 Work」 | 写 `delivery/work/<ID>/intent.md`（为什么做、做到什么算完）+ `plan.md`（怎么做、分几步）+ `run-config.yaml` | 摘要 + 「看完说接受」；你说「接受」才 digest 绑定生效 |
-| | 先看方案不写代码 | 「先别动代码，给我方案」「A 和 B 的差别是什么，说给我听听」 | 只出草案与对比，不起 Run | 方案对比 + 推荐 + 后果；没拍板不动手 |
-| | 把该我定的挑出来 | 「方案里哪些要我拍板」「有什么需要我拍板的吗」 | 把验收清单压成真实取舍（含域名 / 服务名 / 时长这类你以后要念的名字） | 一次给 2～5 个决策项，每项带推荐值；不逐条连环问 |
-| | 拍板 | 「接受」「全部按推荐」「第 2 个选 B，其余按推荐」 | `accept` intent/plan；决策落 `decisions.jsonl` / `pm/decisions.md` | 一句确认；改了 plan 会自动变 stale，需要再接受 |
-| | 定风险等级 | 「这个用快轨」「这个要严一点」 | `riskPreset: fast / standard / controlled` | fast 只在合并前停；standard 加 plan 接受；controlled 加 intent 接受与发布门 |
-| **2. 准备执行** | 看环境齐不齐 | 「环境有什么要求」「预检一下」 | `requires:`（二进制版本 + `probe:` 探针）核验；`preflight --step` 干跑首个失败边界 | 一次报清缺什么；干跑不产证据，正式 Run 要复现 |
-| | 冻结信封 | 「把 prompt 钉住」「信封冻结」 | `envelope:` 加 `pin: <sha>` | 之后每个 Run 记 envelopeDigest，可追溯 |
-| **3. 执行 · 推进** | 让它干活 | 「开工」「〔WORK-ID〕该你了」 | `start --config … --attempt new`（自动编号、旧等待自动作废、脱离启动） | 「已起 RUN-X-02，停在合并决定会通知你」 |
-| | 看进度 | 「当前进度」「到哪了」「按仓分别说」 | `overview`（每个 Work 的阶段 + 下一步该谁）+ `observe status` | 每件事一句：阶段、卡在谁、下一步；不列命令 |
-| | 看下一步 | 「下一步做什么」「需要我做什么」 | overview 的 next 行，只挑「在你手里」的 | 只列你要做的：DNS、凭据、批准、亲自操作 |
-| | 怕它卡住 | 「怎么样了」「卡住了吗」「半小时了正常吗」 | `status --run`（每步耗时、历史中位数、最后输出、STALLED） | 一句带数字：「verify 已 14 分钟，历史中位 6 分钟，最后输出 2 分钟前，还在动」；疑似卡住会直说 |
-| | 看有什么等我 | 「有什么要我批」「有什么等我」 | `inbox` + `delivery/observe/intents/` | 逐项：等什么、证据在哪、推荐 A/B |
-| | 批 / 不批 | 「批准」「批准 RUN-X」「拒绝，原因是…」 | `approve` / `reject`；非终态转换批准后再 `resume` 续跑 | 说清批的是哪一步：放行 fixer / 再跑一次 / 合并决定；合并决定只表示候选够格合并，合并 / push / 部署你另说 |
-| | 裁 finding | 「这条不算，那条接受」「这个是误报」 | `findings adjudicate dismiss/accept` → 放行 fixer | 被 dismiss 的同一条以后不再阻断；严重度升级会重开 |
-| | 再来一轮 | 「再来一轮」「继续」 | 新 attempt | 旧的等待自动作废，inbox 只剩活的 |
-| | 停下来 | 「这次再不成功就停」「先停下来」 | 封顶轮数；`stop --reason` 记账，候选与证据保留 | 已做 / 未做 / 下一步，带 hash；之后由你决定改方案、手工修还是关掉 Work |
-| **4. 验收 · 合并** | 验收 | 「验收」「验 RUN-X 候选」 | 测试视角对精确 candidate 独立核验，报告落 Work 目录 | 通过 / 不通过 + 证据；写者的话不算证据 |
-| | 合并 | 「merge 吧」「授权 push」 | 人类动作由会话代执行（在 `AGENTS.md` 红线内），回读远端 | 报合并后 hash；`overview` 显示 MERGED |
-| **5. 上线** | 上线 | 「上线」「准备上线」 | `release-readback` 预设 + `riskPreset: release`：先回读 → 停下来 | 「回读全绿，现在轮到你做〔动作〕；做完说一声」 |
-| | 我做完了 | 「做完了」「做到一半了，你核一下」 | 批准 apply-readback → 回读 + 观察 → 停关窗 | 差什么逐条说；任一步失败即停 |
-| | 拍上线卡 | 「批准上线」「先不上线」 | 按决策卡执行 / 不执行 | 生产动作永远是你的；它只回读和记账 |
-| | 生产报警 | 「生产有报警」「体检一下」 | `observe run` → 草稿入队 | 草稿一句 + 「fix_now / schedule / dismiss 你选」 |
-| **6. 完结 · 换期 · 复盘** | 收尾一件事 | 「这个 Work 完了」「关掉这个 Work」 | 记决策、确认 run-record 在 Git 面 | `overview` 不再把它列为待办 |
-| | 打扫 | 「打扫卫生」 | `gc`（先出计划，你点头再 `--apply`） | 清了几个工作树；仅此分支可达的候选一律保留并说明 |
-| | 换期 | 「换期」「进入下一期」 | 换期压缩仪式：归档、截断、指针清零、回灌一问 | 一屏清单；新一期从干净的入口开始 |
-| | 复盘 | 「复盘一下 BuildBeat 做了什么」「正向负向各是什么」 | `metrics` + Run 台账 + 会话记录 | 正向 / 负向 / 改革条，带数字 |
-| | 记经验 | 「把这次卡点的经验记一下」 | 写 `pm/<日期>-<主题>.md` + `env-facts.md`，能机器化的转成 `requires:` 探针 | 下一窗直接引用，不口口相传 |
-| | 回灌 | 「有哪些是 BuildBeat 可以吸收的」 | 对照 lessons 找新坑 | 候选清单，逐条 A/B/C |
-| | 升级 | 「更新一下 BuildBeat 版本」 | 改 `BUILDBEAT.md` / `AGENTS.md` / `.buildbeat/*.yaml`，跑 `doctor` | 版本标记 + doctor 报告 |
-
-## 贯穿全程的几句话
-
-| 你说 | 它会 |
+| 你说什么 | 会话做什么 |
 |---|---|
-| 「为什么」「不做会怎样」「这名字怎么起的」 | 用人话解释，并把该你定的（名字、时长、范围）转成决策项让你批，而不是替你定 |
-| 「说人话」「别列 1234」 | 已做 / 未做 / 下一步各一句；只有事项差异大才分条 |
-| 「你觉得呢」 | 给一个推荐和理由，不是一堆选项 |
-| 「授权」「批准」单独出现 | 只对它上一条明确提出的那件事生效，不外推到别的动作 |
+| 继续这个项目 | 读取项目入口与工作记录，查看 status，识别活动 Run |
+| 准备这项功能 | 写一份 work.md：目标、范围、验收条件、实施计划 |
+| 接受，开工 | 记录接受后用 run 推进；已有明确授权不重复询问 |
+| 到哪了、需要我决定什么 | 状态中列出候选、证据、问题、待决策对象与下一步 |
+| 我已经修好了 | 核对工作树和提交，用 run --adopt 接回验证 |
+| 拒绝或取消 | 记录理由，保留候选与历史；取消活动进程需要先处理持锁驱动 |
+| 换会话 | 保存未落盘事实，保留活动运行现场；新会话按项目记录接续 |
 
-## 三条底线（省你追问）
+工作流默认停在合并决定。合并、推送、部署和发布分别需要对应授权。
 
-- **批准 ≠ 执行**：合并、push、部署、花费、删除，每一项都要你逐项说。
-- **数字必须落地**：问「正常吗」得到的回答一定带已用时间 / 历史中位数 / 最后输出时间；没数据就说没数据。
-- **名字先过你**：域名、服务名、环境名、自停时长这类你以后要念的东西，会话在决策卡里给推荐值让你批，不自己定。
+主仓有多个代码仓时，用 `buildbeat status --repo . --all-repos` 一起查看；发现范围、筛选与已了结计数见[跨会话接续](11-session-handoff.md)。

package/docs/v2/guide/01-quickstart.en.md

@@ -1,55 +1,54 @@
-# Quickstart: your first Run
+# Quickstart
 
-[简体中文](01-quickstart.md) | **English**
+Install the runtime: `npm install --global @haiyangbg/buildbeat@latest` (Node ≥ 20). Before upgrading from 3.x, finish or cancel runs still in progress with their original 3.x runtime, see [Migration](../../MIGRATION.md); never replace a runtime underneath an active run.
 
-Goal: in a real Git repository, let the Runner drive Build → Verify → Review to completion and **stop at the merge decision**, which you make with the evidence in front of you. The order is fixed: install → prepare the Work → write the run config → accept the plan → doctor → start → read the evidence and decide. Every step says what success looks like. How long it takes depends on your workers and the task; this page promises no numbers.
-
-> People who use BuildBeat inside an AI session never type these commands: `SKILL.md` §0.5 is the driving manual the session reads, and you just say "start", "where are we", "approve". This page shows what runs behind the session so you can check it.
-
-## 0. Install
-
-```bash
-npm install --global @haiyangbg/buildbeat@latest
-buildbeat | head -3    # printing "BuildBeat runtime" plus the usage means the install worked
-```
-
-Stable releases live on `@latest`; there is exactly one executable, `buildbeat` (the runtime this page uses). `@next` is only for pre-releases. Requirements: Node ≥ 20, Git, bash, zero runtime dependencies.
-
-> Before continuing, confirm that `$(npm root -g)/@haiyangbg/buildbeat/templates/v2/envelope/` exists. If it does not, reinstall with `npm install --global @haiyangbg/buildbeat@latest`.
-
-## 1. Prepare the Work (Git plane)
-
-In the target repository, create the Work directory and write the intent and the plan (their digests get bound into the approval subject), copy the official workflow preset next to the Work (copy, do not reference the install directory: the workflow file's digest is recorded in the Run and travels with the project in Git), then copy the envelope templates (worker wrapper script plus three prompts) into the repository-level `delivery/envelope/`:
+1. Check Node ≥20, Git, Bash and an authenticated AI tool. Keep project-owned instructions.
+2. The templates ship with the npm package under `$(npm root -g)/@haiyangbg/buildbeat/templates/`. Install `v2/AGENTS.md` and `v2/CLAUDE.md` according to the tool's loading rules; copy runtime exclusions from `gitignore.template` (in `templates/`, not in `v2/`).
+3. Create delivery/work/WORK-X/work.md using the goal, scope, acceptance and implementation sections in work.example.md.
+4. Copy templates/v2/envelope/ to delivery/envelope/ and configure real tool and verification commands. New work needs no workflow.yaml copy.
+5. After the user accepts the work, use the commands below. Detach long runs from short host timeouts and handle the decision shown by status.
 
 ```bash
-BB="$(npm root -g)/@haiyangbg/buildbeat"
-mkdir -p delivery/work/WORK-DEMO-1
-printf "# Intent\nAdd date filtering to the CSV export.\nStop-loss: at most 3 Runs, 4 review rounds.\n" > delivery/work/WORK-DEMO-1/intent.md
-printf "# Plan\n1. Add from/to parameters in src/export.js; 2. add boundary cases under tests/.\n" > delivery/work/WORK-DEMO-1/plan.md
-cp "$BB/src/v2/presets/software-delivery.yaml" delivery/work/WORK-DEMO-1/workflow.yaml
-cp -R "$BB/templates/v2/envelope" delivery/envelope
-git add delivery && git commit -qm "buildbeat: work WORK-DEMO-1 + envelope"
+buildbeat accept --repo . --work WORK-X --by owner
+buildbeat check --config delivery/work/WORK-X/run-config.yaml
+buildbeat run --config delivery/work/WORK-X/run-config.yaml
+buildbeat status --repo . --work WORK-X
 ```
 
-The envelope must be committed: workers run in an isolated worktree and only see committed files. `delivery/envelope/worker.sh <role> -- <tool command…>` takes care of "exit 75 when the tool is not on PATH, append the prompt as the last argument, commit mechanically after a writing step, capture stdout as the envelope for a read-only step"; the three prompts only need the project's environment facts added ([Worker contract](05-worker-contract.md), Chinese).
-
-## 2. Write the run config
-
-`delivery/work/WORK-DEMO-1/run-config.yaml`. Paths resolve relative to **this file**; the YAML is a strict subset: block lists and block maps only (list items may sit at their key's indentation), inline only for the empty `[]` / `{}`, no anchors, comments on their own line; quote a list item that contains `": "`. The config below parses as-is (machine-checked by `tests/v2-templates-firstrun.test.js`); the full sample and the envelope templates are in [`templates/v2/`](../../../templates/v2/run-config.example.yaml).
-
 ```yaml
+# BuildBeat v2 run 配置样板。拷到 delivery/work/<WORK-ID>/run-config.yaml 后改 work / run / allowedPaths / workers。
+# 路径相对本文件解析。严格 YAML 子集：只有块列表与块映射（列表项可与键同缩进），行内只允许空的 [] / {}，无锚点，注释必须独占一行。
+# 起跑前：buildbeat check --config <本文件>；起跑：buildbeat run --config <本文件>
 repo: ../../..
-work: WORK-DEMO-1
-run: RUN-DEMO
-workflow: workflow.yaml
-riskPreset: standard
-entry: build
+work: WORK-X
+# 家族名；run 自动编成 RUN-X-01/02…，--new 开新一轮
+run: RUN-X
+# builder / fixer 只能改这些目录；越界改动不成为候选
 allowedPaths:
   - src
   - tests
+# off = P0/P1 finding 直接派 fixer；高风险项目改成 required，每轮先停人分诊再派 fixer
 reviewTriage: off
+# 非只读步成功不扣次数；review 按轮计费。review 不收敛（修过的 finding 又出现，或阻断数多于上一轮）才在 enter-fix 停人。
+# reviewRoundsPerWork 是 review 轮数唯一的上限（默认 6），跨本 Work 所有 Run 累计，对应 intent 的止损线；
+# 到顶的阻断 review 在 enter-fix 一次批准修复、重验、再审。总 attempt 超过（配置值 + 人批扩额）的 3 倍前仍兜底停人。
+budgets:
+  reviewRoundsPerWork: 6
+# 默认一个仓库同时只驱动一个 Run。确认本项目的测试不抢固定端口、不共用数据库后，
+# 可加 parallel: true，让本 Work 的 Run 与其他同样打开开关的 Work 并行（同一 Work 仍互斥）
+# 同树 + 同命令 + 同信封已通过就复用 verify 证据
+cache:
+  verify: tree
+# 内核把 prompts/<worker>.md 喂给 worker（$BUILDBEAT_PROMPT）；模板见 templates/v2/envelope/prompts/
 envelope:
   prompts: ../../envelope/prompts
+  vars:
+    component: app
+# worker 输出落成证据前按这些 JS 正则脱敏（不支持 (?i) 这类内联标志）
+redact:
+  - "(token|secret|password|TOKEN|SECRET|PASSWORD)=\\S+"
+# worker 以隔离 worktree 为 cwd 运行；delivery/envelope/worker.sh 已随仓库进 worktree。
+# 换工具只改 `--` 后面的命令：codex exec … / claude -p … / 任意脚本。
 workers:
   builder:
     command: bash
@@ -61,6 +60,7 @@ workers:
       - exec
       - -s
       - workspace-write
+  # 真实测试命令；环境不满足就 exit 75（内核当基础设施故障停人）
   verifier:
     command: bash
     args:
@@ -76,6 +76,7 @@ workers:
       - exec
       - -s
       - read-only
+  # 不能省：没配它，verify 失败 / review 阻断时 Run 停人等手修
   fixer:
     command: bash
     args:
@@ -88,78 +89,8 @@ workers:
       - workspace-write
 ```
 
-- `workers.<role>` is any CLI: to switch tools, change only what follows `--` (`claude -p`, any script), see the [Adapter guide](04-adapter-guide.md) (Chinese); the reviewer's output format is in the [Worker contract](05-worker-contract.md) (Chinese) and already spelled out in the prompt template.
-- **`fixer` is not optional**: without it, a failed verify or a blocking review stops the Run at `WAITING_HUMAN` (reason `no adapter configured for worker fixer`) waiting for you to fix by hand; nothing gets fixed automatically.
-- Worker subprocesses receive only `PATH HOME LANG LC_ALL TMPDIR TERM USER SHELL` by default; inject anything else by name with `env:` ([Adapter guide](04-adapter-guide.md), Chinese).
-- `reviewTriage: off` (the default) sends P0/P1 findings straight to the fixer, and review rounds stay bounded by `budgets`. Set it to `required` to see every round before a fixer runs, which suits high-risk projects.
-
-## 3. Accept the plan
-
-The `standard` preset requires the plan to be an accepted artifact before build (`controlled` also requires the intent). Acceptance is digest-bound: edit the plan after accepting it and the acceptance expires on its own; `doctor` reports `stale`.
-
-```bash
-buildbeat accept --repo . --work WORK-DEMO-1 --artifact plan --by <your name>
-```
-
-Success: it prints `accepted plan as A-WORK-DEMO-1-<n>` and `digest: sha256:…`.
-
-## 4. doctor: read what start will read, before starting
-
-```bash
-buildbeat doctor --config delivery/work/WORK-DEMO-1/run-config.yaml
-```
-
-Check section by section: declared versus actual enforcement for each entry under `policies`; whether each worker under `worker isolation` is `env allowlist` or `WARNING inherit`; `push protection`; the per-step budgets; under `work artifacts`, whether intent and plan exist, are accepted, are stale, and the preview of where `start` will stop. A `WARNING` does not mean you cannot run, but you should know what it means; exit code 0 does not mean everything is ready.
-
-## 5. Start the Run; it stops for a human
+[Migration](../../MIGRATION.md) · [Worker contract](05-worker-contract.en.md) · [Recovery](10-recovery.en.md)
 
-```bash
-buildbeat start --config delivery/work/WORK-DEMO-1/run-config.yaml --attempt new
-```
-
-`--attempt new` numbers the run automatically (`RUN-DEMO-01/02…`) and supersedes older Runs of the same Work that are still waiting for a human. The Runner will: open an isolated worktree (branch `run/RUN-DEMO-01`, pushing to the configured remote is blocked) → the builder produces a commit and the candidate is pinned → the verifier really runs the tests (the exit code is read back as evidence) → the reviewer produces structured findings read-only → the Run reaches `WAITING_HUMAN`.
-
-When starting from inside an AI session, detach the process (`nohup` / `setsid`); otherwise the host session's timeout kills the Run.
-
-**What success looks like**: the output ends with `status: WAITING_HUMAN`, and `waiting on human:` is followed by `enter-wait-merge` (the merge decision) or `enter-fix` (triage). **Stopping with `infra` is an environment problem, not a code problem**: timeouts, crashes, non-JSON envelopes and exit code 75 all count; fix the worker or the environment, then `approve --transition resume-<step>` to continue. No budget is consumed.
-
-## 6. Read the evidence, decide
-
-```bash
-buildbeat overview --repo .                       # where each Work is, whose move is next, what it has cost
-buildbeat inbox --repo .                          # Runs waiting for you, each with the copyable next command
-buildbeat status --repo . --run RUN-DEMO-01       # steps, durations, evidence, findings, the reason it waits
-```
-
-Before approving, look at: the candidate SHA, the verify exit code and log, every review finding. Then run the line `inbox` gives you, usually:
-
-```bash
-buildbeat approve --repo . --run RUN-DEMO-01 --transition enter-wait-merge --by <your name> --config delivery/work/WORK-DEMO-1/run-config.yaml
-```
-
-**Be clear about which step you are approving** ([Approval guide](07-approval-guide.en.md)): `enter-wait-merge` is the merge decision; the Run reaches the terminal state `SUCCEEDED`, meaning the candidate is fit to merge. The actual merge, push and release are always your actions outside the Runner. `enter-fix` / `resume-<step>` are non-terminal transitions: after approving them, `resume --config …` lets the Run continue. When findings block, the Run routes fix → verify → review on its own; when the budget is exhausted or a failure fingerprint repeats, it stops and hands back to you ([Recovery](10-recovery.en.md)).
-
-After `start --attempt new` numbers a Run, `resume --config <run-config.yaml>` resumes the family’s only non-terminal Run and prints its ID. Use `--run <RUN-ID>` to select the configured Run itself or `<family>-NN` explicitly (at least two digits). An existing ledger for the exact configured ID takes precedence. Multiple non-terminal Runs are listed with a request to select one using `--run`; if none remain, the error reports the latest ID and terminal status, or states that no ledgers were found.
-
-## 7. Walk the failure branch once
-
-To see the automatic repair loop, commit a failing test case under `tests/` and `start --attempt new` again: verify fails → the fixer repairs with the failure summary → verify reruns → review. `status` shows `step fix: SUCCEEDED` and a second `verify`. To route findings through your hands first: `reviewTriage: required` together with `findings list` / `findings adjudicate` adjudicates fingerprint by fingerprint; a dismissed fingerprint no longer blocks.
-
-## 8. Recovery, notifications, cleanup
-
-- Process killed / machine rebooted: `resume --config <run-config.yaml>`, see [Recovery](10-recovery.en.md).
-- You fixed the problem yourself in the worktree and committed it: `resume --config … --adopt <sha> --by <name>` skips the fixer and continues from verify.
-- Not watching the screen: configure one DingTalk / webhook channel in `.buildbeat/notify.yaml` (the URL comes only from an environment variable) and the Run finds you when it stops ([Approval guide](07-approval-guide.en.md)).
-- Worktrees left by terminal Runs: `gc --repo .` prints the plan first, `--apply true` cleans.
-- To dry-run a single step before a real Run: `preflight --step <id>` (main checkout, minute-scale, produces no evidence); declare the envelope's environment dependencies with `requires:` so they are checked fail-closed before start ([Workflow guide](02-workflow-guide.md), Chinese).
-
-## 9. observe: let the system watch production (v0)
-
-```bash
-cp "$(npm root -g)/@haiyangbg/buildbeat/src/v2/presets/observe.yaml" .buildbeat/observe.yaml   # replace with the project's real probes
-buildbeat observe run --config .buildbeat/observe.yaml            # one invocation = one cycle; leave scheduling to cron
-buildbeat observe status --repo .
-buildbeat observe triage --repo . --intent delivery/observe/intents/INTENT-<fp>.md --action fix_now --by <you>
-```
+Before starting, commit work.md and worker scripts into the selected base so the isolated checkout sees the accepted scope. Acceptance records may be committed afterward.
 
-A probe fails or cannot collect → evidence `failed` / `unverified` → bands escalate (record → read-only diagnosis → Intent draft queued). Drafts are **never executed automatically**; `dismiss` feeds the threshold back so the same fingerprint stays quiet until its severity rises. Details in the [Evidence guide](06-evidence-guide.en.md) §observe.
+For a main repository with code repositories, use `buildbeat status --repo . --all-repos` for pending decisions and open work across repositories; add `--work <ID>` or `--json` as needed. See [Session handoff](11-session-handoff.en.md).

package/docs/v2/guide/01-quickstart.md

@@ -1,55 +1,54 @@
-# 快速开始：第一个 Run
+# 快速开始
 
-**简体中文** | [English](01-quickstart.en.md)
+安装运行时：`npm install --global @haiyangbg/buildbeat@latest`（Node ≥ 20）。从 3.x 升级前，先用原来的 3.x 运行时完成或取消仍在进行的 Run，见[迁移说明](../../MIGRATION.md)；不要在 Run 进行中替换运行时。
 
-目标：在一个真实 Git 仓库里，让 v2 Runner 驱动 Build→Verify→Review 自动跑完，**停在合并决定**，由你带着证据拍板。下面的顺序是固定的：安装 → 准备工作项 → 写 run 配置 → 接受计划 → doctor → start → 看证据、拍板。每一步都写了"成功是什么样"。耗时取决于你的 worker 与任务，本文不给承诺数字。
-
-> 在 AI 会话里用 BuildBeat 的人不需要手敲这些命令：`SKILL.md` §0.5 是给会话读的驾驶手册，你说「开工 / 当前进度 / 批准」即可。本文给的是会话背后跑的东西，方便你核对。
-
-## 0. 安装
-
-```bash
-npm install --global @haiyangbg/buildbeat@latest
-buildbeat | head -3    # 打印 "BuildBeat runtime" 与用法即安装成功
-```
-
-稳定版走 `@latest`，可执行文件只有一个：`buildbeat`（本文用的运行时）。预发布才用 `@next`。要求 Node ≥ 20、Git、bash，零运行时依赖。
-
-> 继续之前确认 `$(npm root -g)/@haiyangbg/buildbeat/templates/v2/envelope/` 存在；不存在就重新 `npm install --global @haiyangbg/buildbeat@latest`。
-
-## 1. 准备工作项（Git 面）
-
-在目标仓库建工作项目录并写下意图与计划（它们的 digest 会绑进批准对象），把官方 workflow 预设复制到工作项旁边（复制而不是引用安装目录：workflow 文件的 digest 会记进 Run，随项目一起进 Git），再把信封模板（worker 包装脚本 + 三份 prompt）拷到仓级 `delivery/envelope/`：
+1. 检查 Node ≥20、Git、Bash 和已鉴权的 AI 工具；保留项目自己的规范。
+2. 模板随 npm 包安装在 `$(npm root -g)/@haiyangbg/buildbeat/templates/`。将其中 `v2/AGENTS.md`、`v2/CLAUDE.md` 按工具装载方式放入项目；从 `gitignore.template`（在 `templates/` 下，不在 `v2/` 里）复制运行时排除项。
+3. 建 delivery/work/WORK-X/work.md，使用 work.example.md 的目标、范围、验收、实施计划结构。
+4. 把 templates/v2/envelope/ 复制为 delivery/envelope/；配置真实工具和验证命令。新工作不用复制 workflow.yaml。
+5. 用户接受工作说明后运行下面命令。长运行使用宿主支持的脱离方式启动；根据 status 的待决定对象处理例外。
 
 ```bash
-BB="$(npm root -g)/@haiyangbg/buildbeat"
-mkdir -p delivery/work/WORK-DEMO-1
-printf "# 意图\n给 CSV 导出加日期筛选。\n止损线：最多 3 个 Run、4 轮 review。\n" > delivery/work/WORK-DEMO-1/intent.md
-printf "# 计划\n1. 在 src/export.js 加 from/to 参数；2. tests/ 补边界用例。\n" > delivery/work/WORK-DEMO-1/plan.md
-cp "$BB/src/v2/presets/software-delivery.yaml" delivery/work/WORK-DEMO-1/workflow.yaml
-cp -R "$BB/templates/v2/envelope" delivery/envelope
-git add delivery && git commit -qm "buildbeat: work WORK-DEMO-1 + envelope"
+buildbeat accept --repo . --work WORK-X --by owner
+buildbeat check --config delivery/work/WORK-X/run-config.yaml
+buildbeat run --config delivery/work/WORK-X/run-config.yaml
+buildbeat status --repo . --work WORK-X
 ```
 
-信封要进 Git：worker 在隔离 worktree 里运行，只看得到已提交的文件。`delivery/envelope/worker.sh <角色> -- <工具命令…>` 负责"工具不在 PATH 就 exit 75、把 prompt 追加为最后一个参数、写入步机械 commit、只读步把 stdout 落成信封"，三份 prompt 按项目补环境事实即可（[Worker 合同](05-worker-contract.md)）。
-
-## 2. 写 run 配置
-
-`delivery/work/WORK-DEMO-1/run-config.yaml`。路径相对**本文件**解析；YAML 是严格子集：只有块列表与块映射（列表项可与键同缩进），行内只允许空的 `[]` / `{}`，没有锚点，注释必须独占一行；含 `": "` 的列表项要加引号。下面这份可以原样解析（机器验证在 `tests/v2-templates-firstrun.test.js`）；完整样板与信封模板在 [`templates/v2/`](../../../templates/v2/run-config.example.yaml)。
-
 ```yaml
+# BuildBeat v2 run 配置样板。拷到 delivery/work/<WORK-ID>/run-config.yaml 后改 work / run / allowedPaths / workers。
+# 路径相对本文件解析。严格 YAML 子集：只有块列表与块映射（列表项可与键同缩进），行内只允许空的 [] / {}，无锚点，注释必须独占一行。
+# 起跑前：buildbeat check --config <本文件>；起跑：buildbeat run --config <本文件>
 repo: ../../..
-work: WORK-DEMO-1
-run: RUN-DEMO
-workflow: workflow.yaml
-riskPreset: standard
-entry: build
+work: WORK-X
+# 家族名；run 自动编成 RUN-X-01/02…，--new 开新一轮
+run: RUN-X
+# builder / fixer 只能改这些目录；越界改动不成为候选
 allowedPaths:
   - src
   - tests
+# off = P0/P1 finding 直接派 fixer；高风险项目改成 required，每轮先停人分诊再派 fixer
 reviewTriage: off
+# 非只读步成功不扣次数；review 按轮计费。review 不收敛（修过的 finding 又出现，或阻断数多于上一轮）才在 enter-fix 停人。
+# reviewRoundsPerWork 是 review 轮数唯一的上限（默认 6），跨本 Work 所有 Run 累计，对应 intent 的止损线；
+# 到顶的阻断 review 在 enter-fix 一次批准修复、重验、再审。总 attempt 超过（配置值 + 人批扩额）的 3 倍前仍兜底停人。
+budgets:
+  reviewRoundsPerWork: 6
+# 默认一个仓库同时只驱动一个 Run。确认本项目的测试不抢固定端口、不共用数据库后，
+# 可加 parallel: true，让本 Work 的 Run 与其他同样打开开关的 Work 并行（同一 Work 仍互斥）
+# 同树 + 同命令 + 同信封已通过就复用 verify 证据
+cache:
+  verify: tree
+# 内核把 prompts/<worker>.md 喂给 worker（$BUILDBEAT_PROMPT）；模板见 templates/v2/envelope/prompts/
 envelope:
   prompts: ../../envelope/prompts
+  vars:
+    component: app
+# worker 输出落成证据前按这些 JS 正则脱敏（不支持 (?i) 这类内联标志）
+redact:
+  - "(token|secret|password|TOKEN|SECRET|PASSWORD)=\\S+"
+# worker 以隔离 worktree 为 cwd 运行；delivery/envelope/worker.sh 已随仓库进 worktree。
+# 换工具只改 `--` 后面的命令：codex exec … / claude -p … / 任意脚本。
 workers:
   builder:
     command: bash
@@ -61,6 +60,7 @@ workers:
       - exec
       - -s
       - workspace-write
+  # 真实测试命令；环境不满足就 exit 75（内核当基础设施故障停人）
   verifier:
     command: bash
     args:
@@ -76,6 +76,7 @@ workers:
       - exec
       - -s
       - read-only
+  # 不能省：没配它，verify 失败 / review 阻断时 Run 停人等手修
   fixer:
     command: bash
     args:
@@ -88,78 +89,8 @@ workers:
       - workspace-write
 ```
 
-- `workers.<角色>` 是任意 CLI：换工具只改 `--` 后面的命令（`claude -p`、任意脚本都行），见 [Adapter 指南](04-adapter-guide.md)；reviewer 的输出格式见 [Worker 合同](05-worker-contract.md)，prompt 模板已写明。
-- **`fixer` 不是可选项**：没配它，verify 失败或 review 阻断时 Run 会停 `WAITING_HUMAN`（理由 `no adapter configured for worker fixer`）等你手修，不会自动修。
-- worker 子进程默认只拿到 `PATH HOME LANG LC_ALL TMPDIR TERM USER SHELL`；需要别的变量用 `env:` 点名注入（[Adapter 指南](04-adapter-guide.md)）。
-- `reviewTriage: off`（默认）时 P0/P1 finding 直接派 fixer，review 轮数仍受 `budgets` 上限约束。想每轮都先过你的手，改成 `required`，适合高风险项目。
-
-## 3. 接受计划
-
-`standard` 预设在 build 前要求 plan 是已接受工件（`controlled` 还要求 intent）。接受是 digest 绑定的：接受后改了 plan，接受自动过期，`doctor` 会报 `stale`。
-
-```bash
-buildbeat accept --repo . --work WORK-DEMO-1 --artifact plan --by <你的名字>
-```
-
-成功：打印 `accepted plan as A-WORK-DEMO-1-<n>` 与 `digest: sha256:…`。
-
-## 4. doctor：起跑前把 start 会读的事实读一遍
-
-```bash
-buildbeat doctor --config delivery/work/WORK-DEMO-1/run-config.yaml
-```
-
-逐段核对：`policies` 每条的 declared 与 actual 强制等级；`worker isolation` 每个 worker 是 `env allowlist` 还是 `WARNING inherit`；`push protection`；每步预算；`work artifacts` 里 intent / plan 是否存在、是否已接受、是否 stale，以及"start 会停在哪一步"的预告。有 `WARNING` 不代表不能跑，但要知道它意味着什么；退出码 0 不等于全部就绪。
-
-## 5. 起 Run，停在人批
+[Migration](../../MIGRATION.md) · [Worker contract](05-worker-contract.md) · [Recovery](10-recovery.md)
 
-```bash
-buildbeat start --config delivery/work/WORK-DEMO-1/run-config.yaml --attempt new
-```
-
-`--attempt new` 自动编号 `RUN-DEMO-01/02…`，并作废同一 Work 下仍在等人的旧 Run。Runner 会：开隔离 worktree（分支 `run/RUN-DEMO-01`，对配置 remote 的 push 已被封禁）→ builder 产出提交并固定 candidate → verifier 真实跑测试（退出码回读为证据）→ reviewer 只读出结构化 findings → 到达 `WAITING_HUMAN`。
-
-从 AI 会话里启动时要脱离启动（`nohup` / `setsid`），否则宿主会话超时会把 Run 杀掉。
-
-**成功是什么样**：输出末尾 `status: WAITING_HUMAN`，`waiting on human:` 后面是 `enter-wait-merge`（合并决定）或 `enter-fix`（分诊）。**停在 `infra` 是环境问题不是代码问题**：超时、崩溃、非 JSON 信封、退出码 75 都算，修好 worker / 环境后 `approve --transition resume-<step>` 续跑，预算不扣。
-
-## 6. 看证据、拍板
-
-```bash
-buildbeat overview --repo .                       # 每个 Work 走到哪、下一步该谁、花了多少
-buildbeat inbox --repo .                          # 等你批的 Run，每条附可复制的下一句命令
-buildbeat status --repo . --run RUN-DEMO-01       # 步、耗时、证据、findings、待批理由
-```
-
-批之前先看：候选 SHA、verify 的退出码与日志、review 的每条 finding。然后按 `inbox` 给出的那一句执行，通常是：
-
-```bash
-buildbeat approve --repo . --run RUN-DEMO-01 --transition enter-wait-merge --by <你的名字> --config delivery/work/WORK-DEMO-1/run-config.yaml
-```
-
-**批的是哪一步要分清**（[Approval 指南](07-approval-guide.md)）：`enter-wait-merge` 是合并决定，Run 进终态 `SUCCEEDED`，表示候选具备合并条件——真正的合并、push、发布永远是你在 Runner 之外的动作；`enter-fix` / `resume-<step>` 是非终态转换，批准后要 `resume --config …` 让它续跑。被 findings 阻断时会自动路由 fix→verify→review 重走，超预算或失败指纹重复则停下交还给你（[Recovery](10-recovery.md)）。
-
-使用 `start --attempt new` 自动编号时，`resume --config <run-config.yaml>` 会续跑该家族唯一未终态的 Run，并打印选中的 ID；也可用 `--run <RUN-ID>` 显式指定配置中的 Run 本身或 `<家族>-NN`（数字至少两位）。配置本身已有台账时优先使用该精确 ID。多个未终态 Run 会列出候选并要求用 `--run` 选择；没有未终态 Run 会报告最新一次的 ID 和终态，没有台账则明确说明。
-
-## 7. 走一次失败分支
-
-想看自动修复闭环，把一条会失败的用例提交进 `tests/`，再 `start --attempt new`：verify 失败 → fixer 带着失败摘要修 → verify 重跑 → review。`status` 会显示 `step fix: SUCCEEDED` 与第二次 `verify`。想让 finding 先过你的手：`reviewTriage: required` 配套 `findings list` / `findings adjudicate` 逐指纹裁决，dismiss 后同指纹不再阻断。
-
-## 8. 恢复、通知、打扫
-
-- 进程被杀 / 机器重启：`resume --config <run-config.yaml>`，见 [故障恢复](10-recovery.md)。
-- 自己在 worktree 里把问题修好并提交了：`resume --config … --adopt <sha> --by <名字>` 跳过 fixer 从 verify 续跑。
-- 不想一直盯着：`.buildbeat/notify.yaml` 配一条钉钉 / webhook 通道（URL 只能来自环境变量），Run 停下会来找你（[Approval 指南](07-approval-guide.md)）。
-- 终态 Run 留下的工作树：`gc --repo .` 先出计划，`--apply true` 再清。
-- 正式起 Run 前想干跑单步：`preflight --step <id>`（主 checkout、分钟级、不产证据）；信封的环境依赖用 `requires:` 声明，启动前 fail-closed 核验（[Workflow 指南](02-workflow-guide.md)）。
-
-## 9. observe：让系统盯生产（v0）
-
-```bash
-cp "$(npm root -g)/@haiyangbg/buildbeat/src/v2/presets/observe.yaml" .buildbeat/observe.yaml   # 改成项目真实探针
-buildbeat observe run --config .buildbeat/observe.yaml            # 一次=一个周期；周期化交给 cron
-buildbeat observe status --repo .
-buildbeat observe triage --repo . --intent delivery/observe/intents/INTENT-<fp>.md --action fix_now --by <你>
-```
+启动前将 work.md 和 worker 脚本提交到所选 base，确保隔离工作树能读到同一份已确认范围；接受记录可以随后提交。
 
-探针失败/采不到 → 证据 `failed`/`unverified` → bands 分层（记录→只读诊断→Intent 草稿入队）。草稿**绝不自动执行**；`dismiss` 会回调阈值，同指纹在严重度升级前不再打扰。详见 [Evidence 指南](06-evidence-guide.md) §observe。
+主仓管理多个代码仓时，用 `buildbeat status --repo . --all-repos` 查看跨仓待批与未了结工作；可加 `--work <ID>` 或 `--json`。详见[跨会话接续](11-session-handoff.md)。