@haiyangbg/buildbeat 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -2,8 +2,15 @@
 
 > 本项目吃自己的狗粮(红线④:必更 CHANGELOG)。格式循 Keep a Changelog,倒序。
 
+## v3.0.1 — 2026-09-09（补丁：示例项目、英文指南）
+
+- **英文指南补齐四篇**：快速开始、Human Approval、Evidence、故障恢复各加 `.en.md`（与中文逐节对应，互相加语言切换行）；指南索引、docs 总入口、英文 README 指向英文版。快速开始安装注释里的 `BuildBeat v2 runtime` 改为 3.0.0 实际打印的 `BuildBeat runtime`，信封存在性说明去掉版本号。
+- **示例项目回来了**：`example/` 现在是虚构单仓项目「简账」跑完一个 Work 的快照——填好的 `AGENTS.md` / `指挥台.md` / `BUILDBEAT.md` / `pm/decisions.md`、通知与 observe 配置样例、带项目环境事实的信封、完整的 `delivery/work/WORK-EXPORT-DATE-FILTER/`（intent / plan / run-config / workflow 副本）以及运行时真跑一遍得到的 `decisions.jsonl` 与 `run-record.json`，外加应用本体与真实 `npm test`。随 npm 包与 Claude 插件分发；`tests/example-firstrun.test.js` 锁住工件一致性并把原样拷贝再跑到合并决定。README、docs 索引、SKILL §8.3 指向它。
+
 ## v3.0.0 — 2026-09-09（大版本：只剩一个产品，v1 移除）
 
+> **发布状态**：`@haiyangbg/buildbeat@3.0.0` 已于 2026-09-09 从 `main`（PR #37，merge commit `0289415`，tag `v3.0.0`）经 OIDC Trusted Publishing 发布到 dist-tag **`latest`**（run 34362068004；publish 一次成功，verify 因 npm 异步处理约 6 分钟才可见而首次超时、版本可见后重跑成功；所有者授权「合并，然后发 3.0.0」）。独立回读（直连 npmjs.org）：`latest` = 3.0.0、integrity 与本地 dry-run 一致、attestation、隔离安装只有 `buildbeat` 一个可执行文件、裸调用零写入、包内无 v1 面全过，GitHub Release v3.0.0 标 Latest，证据见 [`docs/V3.0.0-RELEASE-EVIDENCE-2026-09-09.md`](docs/V3.0.0-RELEASE-EVIDENCE-2026-09-09.md)。
+
 > **3.0.0（破坏性变更）**：v1 已移除。需要 v1 文件总线或 `buildbeat doctor/init/adopt/upgrade` 的项目请停留在 2.0.2；3.0.0 起仓库与包只描述一个产品。
 
 - **可执行文件只剩 `buildbeat`**：它就是运行时（原 `buildbeat-v2`）；`buildbeat-v2` 与 `solobaton` 两个入口删除。新增 `buildbeat --version`。所有文档、模板、信封、`overview` / `inbox` / 通知里可复制的下一句命令统一改名。

package/README.en.md

@@ -7,7 +7,7 @@ Context in files. Collaboration through Git. Work keeps moving.
 
 BuildBeat is a Git-based AI delivery workflow for humans and AI sessions. Goals, plans, decisions, and delivery records stay in the project, providing a basis for continuing when models, tools, sessions, or the person doing the work change. A build, verify, review, and fix loop moves execution forward; progress and evidence are read back by the kernel from Git and real commands, never taken from a session's own account; key decisions remain human.
 
-[User guides (Chinese)](docs/v2/guide/README.md) · [Session handoffs](docs/v2/guide/11-session-handoff.en.md) · [npm](https://www.npmjs.com/package/@haiyangbg/buildbeat) · [CI](https://github.com/HaiYangBG1/BuildBeat/actions/workflows/ci.yml) · [MIT](LICENSE)
+[Quickstart](docs/v2/guide/01-quickstart.en.md) · [Session handoffs](docs/v2/guide/11-session-handoff.en.md) · [npm](https://www.npmjs.com/package/@haiyangbg/buildbeat) · [CI](https://github.com/HaiYangBG1/BuildBeat/actions/workflows/ci.yml) · [MIT](LICENSE)
 
 ## Let go of that irreplaceable chat
 
@@ -37,7 +37,7 @@ Git manages project facts that need to last. Local files hold execution state. B
 | `.buildbeat/runtime/` | In-flight events, checkpoints, locks, and raw logs | Local and excluded from Git; needed to recover an active Run |
 | `.buildbeat/worktrees/` | Each Run's isolated working tree | Preserves candidate code and the working state; keep it when clearing chats |
 
-Filesystem storage does not mean every file belongs in Git. Secrets stay in a protected local environment. Terminal records retain evidence digests and references; retain raw logs separately when the project requires them. See the [evidence guide (Chinese)](docs/v2/guide/06-evidence-guide.md).
+Filesystem storage does not mean every file belongs in Git. Secrets stay in a protected local environment. Terminal records retain evidence digests and references; retain raw logs separately when the project requires them. See the [evidence guide](docs/v2/guide/06-evidence-guide.en.md).
 
 ## Different ways to continue the same work
 
@@ -105,7 +105,7 @@ npm install --global @haiyangbg/buildbeat@latest
 
 > Set up BuildBeat for this project. Inspect the code and existing constraints first, then prepare context and execution configuration for the first piece of work.
 
-The session inspects the project and prepares a goal, plan, verification commands, and Worker configuration. Execution starts after your acceptance. See the [quickstart](docs/v2/guide/01-quickstart.md) (Chinese).
+The session inspects the project and prepares a goal, plan, verification commands, and Worker configuration. Execution starts after your acceptance. See the [quickstart](docs/v2/guide/01-quickstart.en.md) and the [example project](example/README.md) (Chinese).
 
 **3. Try a handoff.** Once work records are saved, close the old session and open one without its chat history. Or synchronize the records and candidate so another authorized teammate can take over with their own tool:
 
@@ -148,6 +148,6 @@ Teams collaborate through a shared Git repository and project agreements. BuildB
 
 - [Documentation index](docs/README.md): current guides, specifications, and historical records (Chinese).
 - [Capability matrix](docs/CAPABILITY-MATRIX.md): manual protocol, runtime, plugin, and verification scope (Chinese).
-- [Session handoffs](docs/v2/guide/11-session-handoff.en.md) · [Run recovery](docs/v2/guide/10-recovery.md) · [Approval and triage](docs/v2/guide/07-approval-guide.md) (last two in Chinese).
+- [Session handoffs](docs/v2/guide/11-session-handoff.en.md) · [Run recovery](docs/v2/guide/10-recovery.en.md) · [Approval and triage](docs/v2/guide/07-approval-guide.en.md) · [Evidence](docs/v2/guide/06-evidence-guide.en.md).
 - [Skill](SKILL.md): how a session uses BuildBeat; [lessons](lessons.md): the real incidents behind its mechanisms (Chinese).
 - [CHANGELOG](CHANGELOG.md) (Chinese) · [Contributing](CONTRIBUTING.md) · [MIT license](LICENSE).

package/README.md

@@ -105,7 +105,7 @@ npm install --global @haiyangbg/buildbeat@latest
 
 > 用 BuildBeat 接管这个项目。先检查代码和现有约束，为第一项工作准备上下文与运行配置。
 
-会话先检查项目，补齐目标、计划、验证命令和执行配置；你接受后再启动。完整步骤见 [快速开始](docs/v2/guide/01-quickstart.md)。
+会话先检查项目，补齐目标、计划、验证命令和执行配置；你接受后再启动。完整步骤见 [快速开始](docs/v2/guide/01-quickstart.md)；填好之后长什么样，看 [示例项目](example/README.md)。
 
 **3. 试一次接力。** 在工作记录落盘后关闭旧会话，打开一个没有旧聊天历史的新会话；也可以同步记录与候选，让另一位有权限的成员用自己的工具接手：
 

package/SKILL.md

@@ -390,7 +390,7 @@ worker prompt 里要写清三条环境事实(模板 AGENTS 第 ⑨ 条):沙箱
 - [ ] 8. 收尾一屏:生成了什么 / 默认拿主意的项 / 首跑停在哪、证据在哪 / 下一步由谁做(合并是人的动作)
 ```
 
-> 可核对的样例:`tests/v2-templates-firstrun.test.js` 用脚本 worker 代替真实模型,从上面的模板走到合并决定(含一次 verify 失败→fixer→重验)。它证明包内路径、配置、信封、提交机制、reviewer 信封连得上;不证明某个真实模型能完成业务任务。
+> 各文件「填好之后长什么样」,参照 [example/](example/README.md)(虚构「简账」项目跑完一个 Work 的快照)。可核对的样例:`tests/v2-templates-firstrun.test.js` 与 `tests/example-firstrun.test.js` 用脚本 worker 代替真实模型,从上面的模板走到合并决定(含一次 verify 失败→fixer→重验)。它证明包内路径、配置、信封、提交机制、reviewer 信封连得上;不证明某个真实模型能完成业务任务。
 
 ## 8.5 接管存量项目(10→N 入口:先摸底、划边界、补验证)
 

package/docs/README.md

@@ -7,11 +7,12 @@
 | 你要做什么 | 读 |
 |---|---|
 | 第一次用，在 AI 会话里 | [`v2/guide/00-how-to-talk.md`](v2/guide/00-how-to-talk.md) → 会话读 [`SKILL.md`](../SKILL.md) §0.5 |
-| 第一次用，自己敲命令核对 | [`v2/guide/01-quickstart.md`](v2/guide/01-quickstart.md) |
+| 第一次用，自己敲命令核对 | [`v2/guide/01-quickstart.md`](v2/guide/01-quickstart.md) · [English](v2/guide/01-quickstart.en.md) |
 | 指南索引（日常 / 配置） | [`v2/guide/README.md`](v2/guide/README.md) |
 | 关闭旧会话后继续，或由其他成员/工具接手 | [`跨会话接续`](v2/guide/11-session-handoff.md) · [English](v2/guide/11-session-handoff.en.md) |
 | 三个可用面各能做什么（Skill-only / 运行时 / 插件） | [`CAPABILITY-MATRIX.md`](CAPABILITY-MATRIX.md) |
 | 项目装载入口与信封模板 | [`../templates/v2/`](../templates/v2/AGENTS.md) |
+| 填好之后长什么样：一个 Work 跑到合并决定的快照 | [`../example/`](../example/README.md) |
 
 ## 现行：规范与维护
 
@@ -26,7 +27,7 @@
 
 | 类别 | 文件 |
 |---|---|
-| 发布证据 | `V2.0.2-RELEASE-EVIDENCE-2026-09-09.md`（当前 `latest`）、`V2.0.1-RELEASE-EVIDENCE-2026-09-06.md`、`V2.0.0-RELEASE-EVIDENCE-2026-09-05.md`、`V2.0.0-BETA.1～5-RELEASE-EVIDENCE-*.md`、`V1.21-RELEASE-EVIDENCE-2026-08-25.md`、`WP4.3-RELEASE-EVIDENCE-2026-08-25.md` |
+| 发布证据 | `V3.0.0-RELEASE-EVIDENCE-2026-09-09.md`（当前 `latest`）、`V2.0.2-RELEASE-EVIDENCE-2026-09-09.md`、`V2.0.1-RELEASE-EVIDENCE-2026-09-06.md`、`V2.0.0-RELEASE-EVIDENCE-2026-09-05.md`、`V2.0.0-BETA.1～5-RELEASE-EVIDENCE-*.md`、`V1.21-RELEASE-EVIDENCE-2026-08-25.md`、`WP4.3-RELEASE-EVIDENCE-2026-08-25.md` |
 | 规划与决策（2026-08） | [`V2-PLAN.md`](V2-PLAN.md)（执行基线，已交付）、[`V2-PROPOSAL.md`](V2-PROPOSAL.md)、[`V2-DECISIONS.md`](V2-DECISIONS.md)、[`V2-D2-DECISION-CARD.md`](V2-D2-DECISION-CARD.md)、[《BuildBeat v2：AI 原生软件交付控制平面》](BuildBeat%20v2%EF%BC%9AAI%20%E5%8E%9F%E7%94%9F%E8%BD%AF%E4%BB%B6%E4%BA%A4%E4%BB%98%E6%8E%A7%E5%88%B6%E5%B9%B3%E9%9D%A2.md) |
 | 迭代与里程碑记录 | `V2-ITERATION-01～08.md`、[`v2/`](v2/) 下的 M1/M2/M4 验收与试点记录 |
 | 早期版本史 | [`../CHANGELOG-v1.md`](../CHANGELOG-v1.md)（2026-06 ～ 2026-08 的条目原文；当前条目在根 [`CHANGELOG.md`](../CHANGELOG.md)） |

package/docs/RELEASING.md

@@ -2,7 +2,7 @@
 
 This runbook governs BuildBeat's public npm distribution. The canonical package is `@haiyangbg/buildbeat` in `HaiYangBG1/BuildBeat`; the only executable is `buildbeat`. No other package name or executable alias receives publications.
 
-Release evidence at source package version `@haiyangbg/buildbeat@3.0.0`; latest independently verified BuildBeat npm distribution `@haiyangbg/buildbeat@2.0.2` (dist-tag `latest`; `next` stays `2.0.0-beta.5`), anchored by annotated tag `v2.0.2` at commit `a077367`, workflow run [34351668694](https://github.com/HaiYangBG1/BuildBeat/actions/runs/34351668694), and archived in [`V2.0.2-RELEASE-EVIDENCE-2026-09-09.md`](V2.0.2-RELEASE-EVIDENCE-2026-09-09.md). The 2.0.1 chain (`latest` from 2026-09-06 until 2.0.2 took over on 2026-09-09) stays archived in [`V2.0.1-RELEASE-EVIDENCE-2026-09-06.md`](V2.0.1-RELEASE-EVIDENCE-2026-09-06.md). The 2.0.0 chain (`latest` from 2026-09-05 until 2.0.1 took over on 2026-09-06) stays archived in [`V2.0.0-RELEASE-EVIDENCE-2026-09-05.md`](V2.0.0-RELEASE-EVIDENCE-2026-09-05.md). The beta.5 chain stays archived in [`V2.0.0-BETA.5-RELEASE-EVIDENCE-2026-09-05.md`](V2.0.0-BETA.5-RELEASE-EVIDENCE-2026-09-05.md). The beta.4 chain stays archived in [`V2.0.0-BETA.4-RELEASE-EVIDENCE-2026-09-03.md`](V2.0.0-BETA.4-RELEASE-EVIDENCE-2026-09-03.md); the beta.3 chain in [`V2.0.0-BETA.3-RELEASE-EVIDENCE-2026-09-01.md`](V2.0.0-BETA.3-RELEASE-EVIDENCE-2026-09-01.md). The beta.2 chain stays archived in [`V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md`](V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md); the beta.1 chain stays archived in [`V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md`](V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md). Earlier distributions and the retired legacy package name are archived in the dated evidence files under `docs/`.
+Release evidence at source package version `@haiyangbg/buildbeat@3.0.1`; latest independently verified BuildBeat npm distribution `@haiyangbg/buildbeat@3.0.0` (dist-tag `latest`; `next` stays `2.0.0-beta.5`), anchored by annotated tag `v3.0.0` at commit `0289415`, workflow run [34362068004](https://github.com/HaiYangBG1/BuildBeat/actions/runs/34362068004), and archived in [`V3.0.0-RELEASE-EVIDENCE-2026-09-09.md`](V3.0.0-RELEASE-EVIDENCE-2026-09-09.md). The 2.0.2 chain (`latest` from 2026-09-09 until 3.0.0 took over the same day; the last version carrying the removed generation) stays archived in [`V2.0.2-RELEASE-EVIDENCE-2026-09-09.md`](V2.0.2-RELEASE-EVIDENCE-2026-09-09.md). The 2.0.1 chain (`latest` from 2026-09-06 until 2.0.2 took over on 2026-09-09) stays archived in [`V2.0.1-RELEASE-EVIDENCE-2026-09-06.md`](V2.0.1-RELEASE-EVIDENCE-2026-09-06.md). The 2.0.0 chain (`latest` from 2026-09-05 until 2.0.1 took over on 2026-09-06) stays archived in [`V2.0.0-RELEASE-EVIDENCE-2026-09-05.md`](V2.0.0-RELEASE-EVIDENCE-2026-09-05.md). The beta.5 chain stays archived in [`V2.0.0-BETA.5-RELEASE-EVIDENCE-2026-09-05.md`](V2.0.0-BETA.5-RELEASE-EVIDENCE-2026-09-05.md). The beta.4 chain stays archived in [`V2.0.0-BETA.4-RELEASE-EVIDENCE-2026-09-03.md`](V2.0.0-BETA.4-RELEASE-EVIDENCE-2026-09-03.md); the beta.3 chain in [`V2.0.0-BETA.3-RELEASE-EVIDENCE-2026-09-01.md`](V2.0.0-BETA.3-RELEASE-EVIDENCE-2026-09-01.md). The beta.2 chain stays archived in [`V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md`](V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md); the beta.1 chain stays archived in [`V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md`](V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md). Earlier distributions and the retired legacy package name are archived in the dated evidence files under `docs/`.
 
 ## Channels and branches
 
@@ -118,6 +118,8 @@ gh workflow run publish.yml --ref main -f tag=vX.Y.Z
 gh run watch --exit-status
 ```
 
+npm now processes a publish asynchronously (`npm publish` prints "being processed and may take a few minutes"); the verify job waits up to ten minutes for the exact version, the dist-tag and the provenance to read back. If it still fails **only** on readback, wait for `npm view` to show the version and re-run the failed job (`gh run rerun <run-id> --failed`); never publish again. Real incident: 3.0.0 became readable about six minutes after `npm publish` returned.
+
 The workflow waits for exact registry-version readback, requires `dist.attestations` to expose an npm attestation URL with the SLSA v1 provenance predicate, installs the public package into a clean temporary prefix, checks its executable version, and runs `npm audit signatures`. The release operator must still repeat the isolated-install and read-only `doctor` check independently before publishing the matching GitHub Release. Never use `workflow_dispatch` to bypass the repository's human merge or tag Gate.
 
 Trusted Publishing removes the long-lived write token and automatically emits provenance for supported public GitHub repositories. Configure the exact owner, repository, workflow filename, allowed `npm publish` action, and the exact `npm-publish` environment on npmjs.com. A GitHub Environment without the matching npm-side environment binding is not sufficient evidence. See npm's [Trusted Publishing](https://docs.npmjs.com/trusted-publishers/) and [provenance](https://docs.npmjs.com/generating-provenance-statements/) documentation.

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

@@ -0,0 +1,163 @@
+# Quickstart: your first Run
+
+[简体中文](01-quickstart.md) | **English**
+
+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/`:
+
+```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"
+```
+
+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, no inline `[]` / `{}`, no anchors, comments on their own line. 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
+repo: ../../..
+work: WORK-DEMO-1
+run: RUN-DEMO
+workflow: workflow.yaml
+riskPreset: standard
+entry: build
+allowedPaths:
+  - src
+  - tests
+reviewTriage: required
+envelope:
+  prompts: ../../envelope/prompts
+workers:
+  builder:
+    command: bash
+    args:
+      - delivery/envelope/worker.sh
+      - builder
+      - --
+      - codex
+      - exec
+      - -s
+      - workspace-write
+  verifier:
+    command: bash
+    args:
+      - -lc
+      - npm test
+  reviewer:
+    command: bash
+    args:
+      - delivery/envelope/worker.sh
+      - reviewer
+      - --
+      - codex
+      - exec
+      - -s
+      - read-only
+  fixer:
+    command: bash
+    args:
+      - delivery/envelope/worker.sh
+      - fixer
+      - --
+      - codex
+      - exec
+      - -s
+      - workspace-write
+```
+
+- `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: required` routes P0/P1 findings through you before a fixer is dispatched; delete the line if you do not want that.
+
+## 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
+
+```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)).
+
+## 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>
+```
+
+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.

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

@@ -1,5 +1,7 @@
 # 快速开始：第一个 Run
 
+**简体中文** | [English](01-quickstart.en.md)
+
 目标：在一个真实 Git 仓库里，让 v2 Runner 驱动 Build→Verify→Review 自动跑完，**停在合并决定**，由你带着证据拍板。下面的顺序是固定的：安装 → 准备工作项 → 写 run 配置 → 接受计划 → doctor → start → 看证据、拍板。每一步都写了"成功是什么样"。耗时取决于你的 worker 与任务，本文不给承诺数字。
 
 > 在 AI 会话里用 BuildBeat 的人不需要手敲这些命令：`SKILL.md` §0.5 是给会话读的驾驶手册，你说「开工 / 当前进度 / 批准」即可。本文给的是会话背后跑的东西，方便你核对。
@@ -8,12 +10,12 @@
 
 ```bash
 npm install --global @haiyangbg/buildbeat@latest
-buildbeat | head -3    # 打印 "BuildBeat v2 runtime" 与用法即安装成功
+buildbeat | head -3    # 打印 "BuildBeat runtime" 与用法即安装成功
 ```
 
 稳定版走 `@latest`，可执行文件只有一个：`buildbeat`（本文用的运行时）。预发布才用 `@next`。要求 Node ≥ 20、Git、bash，零运行时依赖。
 
-> 下文用到的 `templates/v2/envelope/` 与 run 配置 `env:` 透传修复自 2.0.1 起随包分发。装好后确认 `$(npm root -g)/@haiyangbg/buildbeat/templates/v2/envelope/` 存在再继续；不存在说明装到的是 2.0.0，先 `npm install --global @haiyangbg/buildbeat@latest` 更新。
+> 继续之前确认 `$(npm root -g)/@haiyangbg/buildbeat/templates/v2/envelope/` 存在；不存在就重新 `npm install --global @haiyangbg/buildbeat@latest`。
 
 ## 1. 准备工作项（Git 面）
 

package/docs/v2/guide/06-evidence-guide.en.md

@@ -0,0 +1,51 @@
+# Evidence guide
+
+[简体中文](06-evidence-guide.md) | **English**
+
+Authority: [`RFC-0002 §4`](../RFC-0002-domain-model.md) (Chinese); implementation: `src/v2/evidence/collector.js`, `src/v2/observe/`. Core idea: **evidence is a fact the Runner read back, not a worker's account of itself**.
+
+## The shape of an evidence record
+
+Every piece of evidence enters the event ledger (`EVIDENCE_RECORDED`) with: `kind` (command / screenshot / drift / runtime-health / diagnosis / …), `subject` (candidate SHA or deployment unit), `digest` (sha256 of the raw log; the runtime may be deleted, the digest lives on), `status`, `grade`, producer, start and end times. Raw logs land in the runtime plane, `.buildbeat/runtime/`; the ledger and the compacted record reference only digests.
+
+## Status: three values, fail-closed
+
+| status | Meaning |
+|---|---|
+| `passed` | Zero exit code, no timeout, not killed by a signal |
+| `failed` | Non-zero exit / timeout / signal |
+| `unverified` | **Could not collect**: failed to start, data missing. Never means "no problem" |
+
+`unverified` is never treated as a pass by any gate (three-valued logic, [Policy guide](03-policy-guide.md), Chinese). Fail-closed is kernel semantics, not a convention.
+
+## Grades L0–L4
+
+`L0` self-report → `L1` static check → `L2` real local execution (the default grade for command readback) → `L3` post-deployment verification → `L4` production readback. Gates state their requirement with `minGrade` (for example a merge floor of L2; closing a production switch needs L4).
+
+**Verification pyramid warning (the most expensive lesson of the thirty-round campaign)**: the marginal value of polishing a lower layer toward theoretical completeness is far below moving one layer closer to the real machine one step earlier. In practice a 7,400-line L3 suite was polished to its limit, while the four real release blockers (systemd parsing behaviour, deployment/service identity split, probe budgets calibrated against a stand-in, TLS ref format) **were all structurally invisible to L3** and were found in one evening at L4. Rule of thumb: **move up a layer as soon as the simulated layer has zero real defect classes left; do not chase theoretical completeness**. Similarly, re-running the full verify when the candidate touched only a part is pure repetition; caching or trimming by content hash belongs to the envelope layer (the campaign measured 25 → 13 minutes) and the kernel does not do it for you: cache correctness depends on assumptions about a stable environment, which the envelope owner carries.
+
+## Preflight is not evidence
+
+`buildbeat preflight --config <run-config> --step <id>` dry-runs one step's worker command directly in the main checkout: no worktree, no ledger, no evidence of any kind (the output carries a `PREFLIGHT (dry signal, never evidence)` banner and the environment variable `BUILDBEAT_PREFLIGHT=1`). Its purpose is a minute-scale loop that reaches the first failure boundary before entering a Run (in the campaign every harness defect cost a whole Run round; preflight mode dismantled them in one evening). **Anything preflight finds counts only once a Run reproduces it.**
+
+## Candidate scope
+
+Evidence is bound to the candidate through `subject`: the merge gate counts only the current candidate's evidence; records from old candidates or old review rounds are not mixed in (a real-incident regression, see the `fix-loop` eval).
+
+## observe: production joins the evidence plane (v0)
+
+Frozen in [`RFC-0003 §8`](../RFC-0003-workflow-policy.md) (Chinese), implemented in M5 (`src/v2/observe/`):
+
+- **Providers** (project probes such as drift checks and live status) produce records under the same Evidence Contract into a separate observe ledger (same chain verification, `.buildbeat/runtime/observe/`); a broken probe is `unverified` (default severity warn), never silent;
+- **Three bands** (thresholds configurable, order fixed): `log` records only → `diagnose` triggers a read-only diagnostic command and produces `diagnosis` evidence → `intent` writes an Intent **draft** into the Git plane at `delivery/observe/intents/` (never executed automatically);
+- **Human triage**: `observe triage --action fix_now|schedule|dismiss`. After `fix_now` a human carries it into a software-delivery Run and the loop closes; `dismiss` feeds the bands back so the same fingerprint is not queued again until its severity rises (alert-fatigue protection); the triage outcome is written into the draft file itself and survives deleting the runtime (invariant 23);
+- **Scheduling boundary in v0**: the `schedule` field is parsed and recorded but there is no built-in scheduler; periodic runs are the host's cron calling `observe run` repeatedly.
+
+## Completeness
+
+`buildbeat metrics` prints evidence completeness (steps with evidence / steps that should have it); the M4/M5 exit line is ≥ 95%, the pilots measured 100%.
+
+## Live readings are not evidence
+
+> Since 2.0.0-beta.4 (iteration 08).
+While a step runs, the Shell Adapter streams the worker's stdout/stderr to `.buildbeat/runtime/runs/<RUN>/<step>-<n>.{stdout,stderr}.live` and keeps a `live.json` (command, start time). These are **readings**: `status` uses them to answer "is it still moving, for how long, when was the last output", and they are reclaimed as soon as the step ends; the evidence log is still produced by readback, and the digest still binds the final log. Durations likewise: per-step elapsed time and the repository's historical median (`typical step duration` in `metrics`) are derived from ledger timestamps and enter neither the ledger nor the run-record.

package/docs/v2/guide/06-evidence-guide.md

@@ -1,5 +1,7 @@
 # Evidence 指南
 
+**简体中文** | [English](06-evidence-guide.en.md)
+
 权威：[`RFC-0002 §4`](../RFC-0002-domain-model.md)；实现：`src/v2/evidence/collector.js`、`src/v2/observe/`。核心：**证据是 Runner 回读到的事实，不是 Worker 的自述**。
 
 ## 证据记录的形状

package/docs/v2/guide/07-approval-guide.en.md

@@ -0,0 +1,115 @@
+# Human approval guide
+
+[简体中文](07-approval-guide.md) | **English**
+
+Authority: [`RFC-0003 §5`](../RFC-0003-workflow-policy.md) (Chinese); implementation: `src/v2/runtime/decisions.js`. Principle: **a human approves a digest-bound subject, not a sentence that says "fine"**.
+
+## What an approval binds
+
+One approval = the quadruple `transition + candidate + planDigest + evidenceDigest`. If any of the four changes afterwards, the approval becomes `APPROVAL_STALE` on its own and the Run returns to `WAITING_HUMAN`: an old stamp never covers a new subject (zero reuse of stale approvals is an exit metric; the pilots measured zero).
+
+## Daily commands
+
+```bash
+buildbeat inbox --repo .                 # every Run waiting for a human: transition, candidate, digest, reason
+buildbeat status --repo . --run RUN-X    # the full derived view of one Run (steps, evidence, findings)
+buildbeat approve --repo . --run RUN-X --transition enter-wait-merge --by <name> --config <run-config>
+buildbeat reject  --repo . --run RUN-X --reason "<why>" --by <name>
+buildbeat accept  --repo . --work WORK-X --artifact plan --by <name>   # artifact acceptance (digest-bound)
+```
+
+Decisions land in the Git plane at `delivery/work/<id>/decisions.jsonl`; the event ledger records `DECISION_RECORDED` at the same time.
+
+## The safety semantics of approve (all tested)
+
+1. **The transition must match** the pending request;
+2. **Reality is re-read before stamping**: if the pending snapshot and reality disagree (the candidate moved, the plan changed), the approval is refused and a refresh is required; nothing is stamped;
+3. **Transition gates are re-checked at the instant of stamping**: if merge-evidence-floor / ui-render-gate do not PASS right then, the approval is refused;
+4. Approving a final decision (a pending request of the final-decision kind) means `RUN_TERMINAL SUCCEEDED` plus compacting the run-record into the Git plane.
+
+## Five words and what each means (approving is not executing)
+
+Sessions and documents used to mix "accept / approve / resume / succeeded / merged". The vocabulary is fixed as follows:
+
+| Word | Command | Meaning | Is not |
+|---|---|---|---|
+| **Accept** | `accept --artifact intent\|plan` | A human endorses one artifact's digest; editing it makes the acceptance `stale` | Starting work; it creates no Run |
+| **Approve a transition** | `approve --transition <t>` | Lets the Run take **this one** transition: `enter-fix` (release the fixer after triage), `resume-<step>` (run the step once more after a budget or infra stop; records `BUDGET_EXTENDED`), `enter-review` (one more review round after the Work-level cap), `enter-apply-readback` ("I have done it" on the release lane) | Approving any other transition; after a non-terminal transition is approved the Run **does not move by itself**: `resume --config <run-config>` continues it (the `next:` line printed by `approve` says so) |
+| **Merge decision** (final approval) | `approve --transition enter-wait-merge` | The candidate is fit to merge: candidate + planDigest + evidenceDigest all hold at this instant; the Run reaches the terminal state `SUCCEEDED` and the run-record is compacted into the Git plane | Code merged, pushed or deployed: those three remain your actions outside the Runner, always |
+| **Run SUCCEEDED** | — | The Run stopped where it should and the evidence is complete | The Work is finished. `overview` shows `MERGED` only after reading back that the candidate is on the current branch |
+| **Reject** | `reject --reason` | The Run ends (`FAILED`, reason recorded) | The artifacts are invalidated; the acceptance state of intent/plan does not change |
+
+Likewise, `fix_now` on an observe draft is only acceptance; a human starts the Run. Protected actions are listed under [Security boundaries](09-security-boundaries.md) (Chinese).
+
+## Risk presets decide where humans approve
+
+`fast`: Merge only; `standard`: Plan + Merge; `controlled`: Intent + Plan + Merge + Release. A pending request must carry the findings summary and the reason, which prevents the "rubber stamp" decay; human waiting time goes into `metrics`.
+
+## The finding triage gate and anchored review
+
+> Since 2.0.0-beta.3.
+The biggest structural lesson of the thirty-round deployment campaign: **a finding is a prescription, not a fact**. A memoryless fresh reviewer writes contradictory prescriptions and overturns designs that were accepted long ago; routing a fixer automatically turns that oscillation straight into cost. Two mechanisms work together:
+
+1. **The triage gate**: with `reviewTriage: required` in the run config, P0/P1 findings from review no longer dispatch a fixer automatically; the Run stops at `WAITING_HUMAN` (kind `finding-triage`) and the pending reason lists every finding fingerprint. A human adjudicates first, then `approve --transition enter-fix` releases the fixer (or `reject` ends the Run).
+2. **The adjudication ledger**: every finding lands in the Git plane at `delivery/work/<id>/review-findings.jsonl` (fingerprint = hash of severity plus normalized text):
+
+   ```bash
+   buildbeat findings list --repo . --work WORK-X
+   buildbeat findings adjudicate --repo . --work WORK-X --fingerprint <fp> --action dismiss --by <name> --note "<why>"
+   ```
+
+   After `dismiss`, the same fingerprint no longer blocks (raising it again is recorded visibly as `RE-RAISED`, but does not restart the loop); **a severity upgrade is a new fingerprint and blocks again on its own**: noise is suppressed, real signal is not, the same principle as observe's dismiss feedback.
+3. **Anchor injection**: the reviewer (a readonly step) receives `anchor` in `BUILDBEAT_INPUT`, the full table of past findings and adjudications, and the envelope prompt should tell the reviewer that adjudicated conclusions must not be overturned; writing steps such as the fixer receive `findings` (last round's findings with their adjudication state), and the fixer repairs only accepted/open ones instead of guessing.
+
+Adjudication memory lives in the Git plane; deleting the runtime does not lose it (covered by the same tests as invariant 23).
+
+## Waiting must be able to find a person
+
+> Since 2.0.0-beta.4 (iteration 08).
+In the pilot workspace, 32 of 58 Runs were cancelled, most of them after hanging in `WAITING_HUMAN` for a full day; the average human wait was 7 to 12 hours. The cause was not slow people but **nobody knowing something was waiting for them**. Three things go together:
+
+1. **What to say next**: `status` and `inbox` print the copyable command right after each wait (`approve` / `reject`, plus `findings list|adjudicate` during triage); `inbox` groups by Work and shows how long each has waited. The `--repo` in that output is a relative path inside the project and the placeholder `<repo-path>` outside it: a machine-local absolute path never enters the output.
+2. **A new Run of the same Work supersedes the old wait**: on `start`, older Runs of the same Work that are still waiting are recorded as `SUPERSEDED` (terminal, compacted into a run-record), and the new Run's `RUN_CREATED.data.supersedes` records the lineage; the inbox keeps only live waits. Write `supersede: off` in the run config if you do not want this. RUNNING Runs are unaffected (active lock); old Runs locked by another process are skipped and reported.
+3. **Outbound notifications**: `.buildbeat/notify.yaml` in the Git plane:
+
+   ```yaml
+   kind: notify
+   version: 1
+   channels:
+     - id: owner
+       type: dingtalk          # or webhook
+       urlEnv: BUILDBEAT_NOTIFY_URL   # the URL comes only from an environment variable; a literal url is refused
+       events:
+         - HUMAN_REQUESTED
+         - RUN_TERMINAL
+         - STALLED
+   ```
+
+   The CLI sends when a Run stops for a human or reaches a terminal state; subscribing to `STALLED` makes `start`/`resume` spawn a detached `watch` process that watches for silent worker output (threshold `stallAfterMs`, default 15 minutes). A failed send is only logged to `runs/<RUN>/notify.log` and the screen and **never affects the Run**; the payload carries identifiers, the reason, the candidate SHA and the next command, with zero logs and zero candidate content. A DingTalk custom robot needs its keyword configured (default `BuildBeat`). `doctor` reports whether the channel and its environment variable are in place.
+
+Notification is not an approval channel: decisions are still made only through the CLI, with digest binding unchanged.
+
+## From "waiting for me" to "where are we": overview
+
+> Since 2.0.0-beta.4 (iteration 08).
+`inbox` only knows which Run waits for a human; `buildbeat overview --repo .` answers per Work "how far, whose move next": whether intent/plan are accepted (edited after acceptance means `stale`), the latest Run's state and candidate, whether the candidate is merged into the current branch, the number of unadjudicated P0/P1 findings, whether `env-facts.md` exists, each row with its next command. After the runtime is deleted, the Git-plane run-records fill in. A session runs it first, then answers "where are we".
+
+**Stage truth corrections (iteration 09)**: once a candidate is merged into the current branch the Work is `MERGED`, even if the latest Run is CANCELLED (a pilot login Run was cancelled over a budget problem while its candidate was already in production, and overview reported `STOPPED_CANCELLED` and urged a retry); a Work whose `release-readback` lane closed successfully shows `RELEASED` instead of "nothing to merge"; merged / released / closed Works no longer report unadjudicated finding counts. Each Work in `overview` also carries a `cost:` line (see the Work-level budgets in the [Workflow guide](02-workflow-guide.md), Chinese).
+
+## You fixed it yourself: `resume --adopt`
+
+> Since 2.0.0-beta.5 (iteration 09).
+When a Run stops at `enter-fix` / `resume-fix`, the driving session or a person has often already fixed the problem in the Run's worktree and committed it. Approving at that point dispatches a fixer with nothing to do and runs verify once more (a pilot frontend Run reached its 5th verify and 3rd fix this way). Use instead:
+
+```bash
+buildbeat resume --config <run-config.yaml> --adopt <sha> --by <name>
+```
+
+The kernel reads the worktree back: the tree must be clean and HEAD must be exactly `<sha>` (7-character prefix or longer), otherwise it refuses; then it records `CANDIDATE_PINNED` with a human actor (`adopted: true`), records `DECISION_RECORDED` with that commit as subject (`adopted`, `resumeAt`), and continues from verify (the step after a successful fix in the preset). The ledger shows who supplied this candidate. Adoption is not accepted at the merge decision.
+
+`doctor` now also prints whether intent / plan exist and are accepted in this repository's `delivery/work/<ID>/`, and for every policy requiring `artifact.accepted` it previews where `start` will stop; before that, doctor passed twice while start was blocked by "plan not mirrored into the sub-repository".
+
+## Visible names are gate decisions
+
+> Since 2.0.0-beta.4 (iteration 08).
+The `BATCH_AT_GATE` tier of the three approval tiers explicitly includes domain names, service names, environment names, auto-stop durations, window durations: **names and parameters the owner will later see or say out loud**. Names a worker picks in passing never reach the ledger; the planner lists them in the intent with recommended values, and the human approves them in one go.

package/docs/v2/guide/07-approval-guide.md

@@ -1,5 +1,7 @@
 # Human Approval 指南
 
+**简体中文** | [English](07-approval-guide.en.md)
+
 权威：[`RFC-0003 §5`](../RFC-0003-workflow-policy.md)；实现：`src/v2/runtime/decisions.js`。原则：**人批的是一个 digest 绑定的对象，不是一句"可以了"**。
 
 ## 批准绑定什么

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

@@ -0,0 +1,83 @@
+# Recovery handbook
+
+[简体中文](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.
+
+## Symptom → action
+
+### The ledger reports corrupted
+
+`status`/`inbox` shows `LEDGER CORRUPTED after seq=N (<reason>)`: the ledger truncates its view at the last valid event and **refuses to append**; recovery is a human decision, nothing is repaired silently.
+
+1. `buildbeat events --repo . --run RUN-X` shows the valid prefix; `replay` verifies the reduction;
+2. If the broken Run is in flight: usually abandon it (the candidate in the worktree is still readable on its branch) and start a new Run;
+3. If someone edited the ledger file by hand: rebuild the judgement from Git-plane facts; do not patch event lines by hand.
+
+### The Run process was killed / the machine rebooted
+
+```bash
+buildbeat resume --config <run-config.yaml>
+```
+
+The in-flight step is closed as `crashed` (the fact is recorded), then **the step itself is rerun** (changed in beta.3): a dead process says nothing about the candidate; the lost attempt still counts against the step's budget, and an exhausted budget stops for a human. The earlier semantics treated a crash as a step failure and followed the failure edge; real incident (deploy-18): the host tool's timeout killed the verify worker, the crash was routed to fix, and the fixer burned a round facing zero verifier evidence. A dirty worktree still stops for a human first. Resuming with approvals re-checks candidate/plan freshness and turns `APPROVAL_STALE` over to a human if anything changed. If it cannot be recovered, delete the runtime and rerun: the candidate branch and the Git-plane records are not lost.
+
+**Launch discipline** (the other half of the same incident): a Run longer than minutes must be launched in a way that escapes the host tool's timeout (`nohup`/`setsid`); `start` prints this reminder in an interactive shell.
+
+### A stuck lock ("another run is active")
+
+A Run that exited abnormally may leave the repository lock behind. Once you have confirmed that no Run is really active:
+
+```bash
+buildbeat stop --repo . --run RUN-X --reason "crashed; releasing lock"
+```
+
+`stop` records the terminal state and the reason; for a mere leftover lock you may also delete `.buildbeat/runtime/` and start over.
+
+### Abnormal worker behaviour
+
+- **Worker infrastructure failure (iteration 09)**: a timeout, a crash, output that is not an envelope (`invalid-output`), or the worker ending itself with exit code **75** (`EX_TEMPFAIL`, "environment unavailable"): the kernel classifies it as `infra`: no failure fingerprint is recorded, no fixer is dispatched, **the step's budget is not consumed**, the Run stops at `WAITING_HUMAN` (kind `infra`, transition `resume-<step>`), notifications go out as usual. Once the backend is back, `approve --transition resume-<step>` reruns the step; `reject` ends the Run. Real incidents: a worker backend returning 404 and non-JSON output killed five Runs in two days while the driving session hand-wrote a probe every two minutes; a missing rg on PATH, a port collision and a host load of 280 each dispatched a fixer.
+- **A failure with no transition edge** (such as `failed` on build / review / fix in the preset) no longer ends in FAILED; it stops at `resume-<step>` as well, and a human decides whether to rerun or end.
+- Out-of-scope writes → the Run BLOCKs and no candidate is pinned: check `allowedPaths` and the scope declared in the worker prompt;
+- Timeouts → first check whether it is the environment (`infra` already stopped for you), then adjust `timeoutMs`; an exhausted budget is a brake, not a fault: approve `resume-<step>` to grant one more attempt, or narrow the scope.
+
+### The observe plane
+
+- A probe stays `unverified`: fix the probe's reachability first; unverified means "could not collect", not "no problem";
+- False alarms flooding: `observe triage --action dismiss`; the same fingerprint stays out of the queue until its severity rises;
+- Observe cycle counts reset to zero after the runtime was deleted: normal; triage memory lives in the Git-plane drafts, and suppression keeps working (tested).
+
+### Everything is a mess
+
+```bash
+rm -rf .buildbeat/runtime/
+```
+
+Then start again from the Git plane. Any phenomenon where a long-term metric or a terminal-state explanation depends on the runtime is a bug; please report it.
+
+## Diagnostic entry point
+
+`buildbeat doctor --config <run-config>`: the config parses, the workflow has no exit loop, adapter env posture, digests can be computed, supersede and stall thresholds, whether the notification channel and its environment variable are in place. `events`/`replay`/`metrics` are all read-only and can run at any time.
+
+## "Is it stuck?"
+
+> Since 2.0.0-beta.4 (iteration 08).
+Look at `buildbeat status --repo . --run <RUN>` first: the step in flight shows elapsed time, the repository's historical median, the worker command, how long ago the last output was and its last three lines. No output beyond the threshold (default 15 minutes, `--stall-after <minutes>` or `stallAfterMs` in the run config) marks `STALLED`: **marked, never killed**. How to judge:
+
+- Output keeps coming → wait (compare against `typical` to see whether it is far beyond the median);
+- STALLED and the worker is an agent CLI → most likely a long reasoning stretch or waiting for an interaction that never comes; `stop --reason`, then rerun by the crash recovery path (the interrupted step reruns itself);
+- STALLED and the worker is a script → read the last three lines; usually it waits on an external resource (port, lock, network).
+
+To avoid watching the screen, subscribe to `STALLED` notifications ([Approval guide](07-approval-guide.en.md)). `watch --repo . --run <RUN> --once true` probes once by hand.
+
+## Cleanup: gc
+
+> Since 2.0.0-beta.4 (iteration 08).
+Terminal Runs leave worktrees, `run/*` branches and the occasional lock. `buildbeat gc --repo .` prints the plan by default, `--apply true` executes it:
+
+- It touches only Runs that are **terminal and already compacted into a run-record** (the Git plane must have the record before the runtime plane is touched);
+- Worktrees may be deleted (the commits are on the branch); a dirty worktree is left alone without `--force true`;
+- A branch is deleted only when the candidate **is reachable from another ref** (merged / tagged / on the remote) or the Run produced no candidate; otherwise it reports "reachable only from this branch, kept": that branch is the last thread to the evidence;
+- Leftover `locks/<RUN>.lock` of terminal Runs are cleaned; the `active-run` lock is still handled by hand as above.
+
+gc never writes to the ledger (after the terminal state only `RUN_COMPACTED` is allowed), so it can run at any time and repeatedly.

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

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