@haiyangbg/buildbeat 3.3.1 → 4.1.0

package/CHANGELOG.md

@@ -2,8 +2,34 @@
 
 > 本项目吃自己的狗粮(红线④:必更 CHANGELOG)。格式循 Keep a Changelog,倒序。
 
+## v4.1.0 — 2026-10-07（次版本：跨仓总览；提示里的命令与路径都能照做）
+
+- Add read-only `status --all-repos`: discover the main repository, configured target checkouts and immediate child repositories, deduplicate real paths, show pending decisions first and count settled work. JSON retains all work; `--work` filters across repositories, while `--run` requires single-repository status.
+- Fix main-repository status/overview reporting target-repository work as ready to start: read state, findings and decisions from the target, retain the main run configuration for commands, and quote paths relative to the caller. Missing/invalid targets warn without hiding other work. Ship `src/v2/runtime/overview-repos.js` and update the package-file inventory for this runtime helper.
+- Hints give commands that work as written. A merged work whose run configs were all read and none has a `release:` section is told there is nothing left to do, instead of being sent to `buildbeat release`, which fails without that section and left the work unable to close; with a `release:` section the hint names the config that has it. A waiting run with no reply commands points to `status --work`, and `check` names `status` instead of the 3.x `inbox`. The run config template comment (and its copies in the Skill, both quickstarts and the example) names `check` / `run` / `--new`, and the quickstart says where the npm package installs the templates. Found by a first run of a fresh project on 4.0.0 with real codex workers.
+- `status --all-repos` prints English labels like the rest of the CLI (`pending decisions · <repo>`, `repo <repo>:`, `<repo>: settled N (closed a · cancelled b · merged, no release step c)`, `repo:` / `runs in:` under a work), and single-repository status again shows `NO_INTENT` for a work directory without a work description even when it has runs, as 4.0.0 did; a work known only from runtime ledgers still shows its run.
+
+## v4.0.0 — 2026-10-04（主版本：聚焦可恢复交付，精简产品范围与操作入口）
+
+> **发布状态**：`@haiyangbg/buildbeat@4.0.0` 已于 2026-10-05 从 `main`（PR #70、#71 内容，release PR #72，merge commit `c15fbe0`，tag `v4.0.0`）经 OIDC Trusted Publishing 发布到 dist-tag **`latest`**（run 37262387333，publish 与 verify 双 job 一次 success；所有者授权「合并并发 4.0」）。独立回读（直连 npmjs.org）：`latest` = 4.0.0、`dist.integrity` 与本地用 Node 24 + npm 11.19.0 打的候选逐字一致、SLSA v1 provenance、隔离安装 `--version` = 4.0.0、裸调用零写入、用法含 `release` 与 `decide --action close`、`npm audit signatures` 通过；GitHub Release v4.0.0 标 Latest；本机两份全局安装均为 4.0.0；证据见 [`docs/releases/V4.0.0-RELEASE-EVIDENCE-2026-10-05.md`](docs/releases/V4.0.0-RELEASE-EVIDENCE-2026-10-05.md)。同日所有者本人经 npm 两步验证把 dist-tag `next` 从 3.3.1 挪到 4.0.0；直连 npmjs.org 回读 `next` = `latest` = 4.0.0。
+
+- Owner decisions before 4.0 (WORK-4.0-INTENT-FOLLOWUPS): `requireScreenshot: true` makes verify write PNG screenshots of the real render to `BUILDBEAT_SCREENSHOT_DIR`, records them as candidate-bound evidence after checking each decodes, fails a verify that leaves none, requires them in the merge check and lists them for the reviewer, the decision card and notifications; `buildbeat release` runs the project's read-only readback after a merged release and records it in `delivery/work/<ID>/releases.jsonl`, and `decide --action close` closes the window only on a passing readback; a one-page guide states what people and tools without the runtime may read and write; the governance-template rationale is corrected.
+
+- Focus the product on portable work context, the recoverable delivery loop, and evidence-backed human decisions.
+- Retire observe execution, the release lane, UI-specific gates, generic workflow/Policy authoring, the optional governance templates (outside the delivery loop and never generated by default; kept under `docs/history/retired-templates`), and the separate Skill-only product path. Existing target-project files and historical records are never deleted by the CLI.
+- Introduce work.md for new work; consolidate run/status/decide/check/history over shared runtime handlers. Core old command spellings remain compatibility aliases.
+- Replace programmable gates with built-in acceptance and current-candidate evidence/review checks. Freeze safeguards with each new run so approval and resume cannot bypass or weaken them.
+- Preserve official legacy delivery configurations and their exact workflow digest; reject unsupported custom/release configurations before side effects, with a migration route to finish active work on 3.3.1.
+- Preserve cache, recovery, scope checks, parallel isolation, notifications, event schema and archived release readback. Update package contents, first-run regression coverage, and bilingual guides together.
+- Review follow-ups: `run` only treats `<run>` and `<run>-NN` ledgers as its family; a finished run reports its outcome and points to `--new` instead of a configuration error; a legacy workflow config without riskPreset keeps having no artifact gate; legacy planner entry combined with an acceptance preset fails before any run; status hints name `run` / `work.md` for unified works.
+- Independent review follow-ups: final approval also checks the candidate's copy of the bound work artifact (and intent.md under the legacy controlled safeguards), and resume refuses a changed bound artifact; start pins the base commit, refuses an artifact missing from it, and compares the isolated checkout itself with the accepted bytes before anything is recorded (a refused checkout and its branch are discarded); `run` selects the unique unfinished run across the whole family; the `requires:` probe regression and a frozen severity-floor refusal test are restored.
+- The Skill checks `buildbeat --version` first and keeps 3.x runtimes on their own command spellings; status and notifications send a legacy 3.x run back to its original runtime instead of offering `decide`; the release checklist names the current install sections; workflow validation tests now change one field of the fixed workflow at a time; the 3.3.1 parity script also compares candidate trees, evidence, waiting kind and decisions.
+
+
 ## v3.3.1 — 2026-10-02（补丁：review 收敛判断认得出换了说法的同一问题；lessons 与发布 runbook 补齐）
 
+> **发布状态**：`@haiyangbg/buildbeat@3.3.1` 已于 2026-10-02 从 `main`（PR #66 内容，release PR #67，merge commit `cc7a6db`，tag `v3.3.1`）经 OIDC Trusted Publishing 发布到 dist-tag **`latest`**（run 36982501415，publish 与 verify 双 job 一次 success；所有者授权「合并并发 3.3.1」）。独立回读（直连 npmjs.org）：`latest` = 3.3.1、`dist.integrity` 与本地用 Node 24 + npm 11.19.0 打的候选逐字一致、SLSA v1 provenance、隔离安装 `--version` = 3.3.1、裸调用零写入、包内含 `sameIssue` 与教训 23、`npm audit signatures` 通过；GitHub Release v3.3.1 标 Latest；本机两份全局安装均为 3.3.1；证据见 [`docs/releases/V3.3.1-RELEASE-EVIDENCE-2026-10-02.md`](docs/releases/V3.3.1-RELEASE-EVIDENCE-2026-10-02.md)。同日所有者本人经 npm 两步验证把 dist-tag `next` 从 3.3.0 挪到 3.3.1；直连 npmjs.org 回读 `next` = `latest` = 3.3.1。
+
 - **review 收敛判断认得出换了说法的同一问题**：3.3.0 判断「修过的 finding 又出现」只认相同指纹（严重度 + 描述原文），而 reviewer 每轮会换行号、改措辞——回放 4 个仓 161 轮 review，按指纹一次都没对上，同一个问题却在一个 Run 里被连审三轮。新增 `sameIssue`：同指纹，或引用同一组文件且描述相近（字符二元组 Dice ≥ 0.5），或描述高度相近（≥ 0.6）；严重度不参与（P1 升 P0 仍算同一问题），同一组文件下描述只差行号也算；描述去掉文件与数字后不足 16 字时只认这两种精确情况。路径可以用反引号包起来。只用于收敛判断，finding 指纹、裁决台账与 dismiss 抑制不变。停人理由里换了说法的一条写成「本轮指纹 restates round N 原指纹」。阈值依据：回放中真实改写全部命中，无关 finding 最高 0.57、同文件无关 finding 最高 0.33。
 - **文档补齐**：`lessons.md` 教训 14 的解药改为现行机制（原文仍写每 Run 2 轮封顶、分诊后才派 fixer），新增教训 23（中途审批点被驾驶会话自批、同一问题换说法认不出）；发布 runbook 要求候选用与发布 workflow 相同的 Node / npm 打包（否则 gzip 层不同、integrity 对不上，改比解压后的 tar），发布后检查 `which -a buildbeat` 列出的每一份全局安装；3.3.0 发布证据更正本机只更新了一份全局安装的事实。
 

package/README.en.md

@@ -1,122 +1,44 @@
 # BuildBeat
 
-[简体中文](README.md) | **English**
-
 **Switch sessions. Keep building.**
-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.
-
-[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
-
-You should not have to preserve an ever-growing chat because it holds the only working context for your project. Open a fresh session when context fills up. Switch models or tools when you need to. Hand work to a teammate who can read the progress and next step from project files. Goals, constraints, plans, decisions, and delivery records belong in the filesystem, where the next session can find them without the old conversation.
-
-This is an **illustrative interaction** in a configured project, not a recorded test run:
-
-| Moment | What you say | What the session does |
-|---|---|---|
-| Session A: begin | “Add date filtering to exports. Plan it first.” | Reads project constraints and writes the goal and plan into a Work; starts execution after acceptance |
-| Before leaving | “Save decisions and unfinished work; I am closing this session.” | Updates project records, checks run state and uncommitted changes, and identifies the next step |
-| A new session takes over | “Read the project's BuildBeat entry point and continue date filtering.” | Reads the Work, Git, and run ledger to identify completed work, unverified results, decisions, and blockers |
-| Continue | “Continue under the accepted plan.” | Proceeds, handles recovery, or waits for a decision according to the actual state; brings evidence to the merge decision |
-
-You can open the next session yourself or hand work to someone else with project access. When changing people or machines, synchronize records and candidates and check the original Run environment.
-
-**Once the necessary context is saved, you can close or delete the old chat.** Unsaved discussion does not become project memory automatically. Keep the project, candidate branches, and required runtime files when removing chats. See [session handoffs](docs/v2/guide/11-session-handoff.en.md).
-
-## Context lives in the project
-
-Git manages project facts that need to last. Local files hold execution state. BuildBeat reads those facts to report progress, instead of asking every session to maintain another estimate of what happened.
-
-| Files and directories | What they hold | How they are used |
-|---|---|---|
-| `AGENTS.md`, project standards, and contracts | Entry points, constraints, perspectives, and write boundaries | A new session starts here, then reads the files relevant to its task |
-| `delivery/work/<ID>/` | Goals, plans, configuration, decisions, review adjudications, and terminal run records | Version in Git as the basis for continuing the same work |
-| `.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](docs/v2/guide/06-evidence-guide.en.md).
-
-## Different ways to continue the same work
-
-The project files carry the context needed to continue. A fresh session with BuildBeat loaded can read the same goals, decisions, and current state. Execution Workers connect through commands; model selection and authentication belong to the chosen AI tool.
-
-- **Across sessions:** close an old chat and continue the same Work with a fresh context.
-- **Across tools and models:** load the Skill in the target tool, configure its command and output contract, and reuse project records.
-- **Across people:** someone with project access can synchronize context, candidates, and required evidence, then continue within their responsibility and authorization. Existing valid decisions remain in effect.
-- **Across time and place:** sync committed project files and prepare another machine to take over. An ordinary Git clone does not migrate an active Run's runtime state or worktree.
-
-**Taking over anytime and anywhere starts with accessible records, a working environment, and appropriate permissions.** Whether you continue yourself or hand work to someone else, start from project files without carrying the old chat transcript. Git supplies version control and collaboration; repository hosting and execution platforms control access.
-
-Different tools can read and write the protocol. Running the Loop also requires a compatible adapter, permissions, and environment. Existing real Worker evidence covers `codex exec`, with deterministic tests for script Workers. Having a CLI alone does not establish that another tool is verified. See the [capability matrix](docs/CAPABILITY-MATRIX.md) and [adapter guide](docs/v2/guide/04-adapter-guide.en.md) (Chinese).
-
-## Multiple perspectives, one shared objective
 
-**End-to-end work packages** are the unit of collaboration. One Builder owns a user-level outcome and calls on three AI perspectives — product, full-stack, and testing — as needed. Several Builders can own separate work packages or hand over the same package. Record who is currently taking it forward, what is done, and the next step to avoid duplicate execution.
+BuildBeat keeps work context in project files, drives a recoverable delivery loop, and brings evidence to human decisions. It is for humans and AI sessions.
 
-| Perspective | Reads when taking over | Produces |
-|---|---|---|
-| Product | Goals, constraints, and existing decisions | Scope, a plan, and acceptance criteria |
-| Full-stack (incl. operations) | The accepted plan, contracts, and environment facts | Candidate code and implementation records |
-| Testing | Acceptance criteria and the candidate | Actual test results, coverage, and gaps |
+## Three promises
 
-These are available AI perspectives, not mandatory human-role handoffs or a requirement to open three chats. Review is not a session perspective: it is the read-only reviewer built into the Run, described in the next section. One person or several people can use these perspectives as needed. Shared facts move through project files, and each perspective respects its write boundaries. The current single-repository active-Run lock is local. Multiple perspectives or Git clones do not provide cross-machine execution coordination. Check the original execution environment before handing over the same Work to avoid duplicate starts.
+Switch sessions without losing progress; let the loop implement, verify, review and repair; inspect the candidate and evidence before deciding.
 
-## Put the work in a Loop
+## Start
 
-After the required plan acceptance, `buildbeat` calls configured Workers in an isolated Git worktree to implement, verify, review, and fix the change. Review is performed by a fresh-context, read-only reviewer worker; any write to the worktree is caught by a before/after snapshot comparison and recorded as a failure.
-
-```mermaid
-flowchart LR
-    P[Accept plan] --> B[Build]
-    B --> V[Verify]
-    V -->|Pass| R[Review]
-    V -->|Fail| F[Fix]
-    R -->|Blocking findings| F
-    F --> V
-    R -->|Pass| H[Human merge decision]
-```
-
-The diagram shows normal and repair paths. Risk presets, finding triage, infrastructure failures, and budgets can introduce additional waits.
-
-- **Completion has evidence:** candidates are read back from Git, and test conclusions come from actual commands. An AI's “done” does not replace verification.
-- **Approval has a subject:** decisions bind to a candidate, plan, and evidence. Changes can make an earlier approval stale.
-- **Interruption has a recovery path:** the Runner can resume from its ledger. An interrupted step may run again; a dirty worktree requires a decision first.
-- **Loops have limits:** budgets, repeated failures, and infrastructure problems become explicit pending actions. Notifications are configurable.
-
-The merge decision means the candidate is ready for a merge. A human or a separately authorized tool performs merge, push, and deployment outside the Runner. The `release-readback` workflow can record release checks and observations. Runtime checks and host isolation have distinct scopes; see [security and permission boundaries (Chinese)](docs/v2/guide/09-security-boundaries.en.md).
-
-## Start your first handoff
-
-You need Node.js ≥ 20, Git, Bash, and an installed, authenticated AI coding tool.
-
-**1. Install the runtime.** Stable packages use `@latest`. The package ships one executable: `buildbeat`.
+The runtime needs Node ≥ 20. Before upgrading from 3.x, finish or cancel runs still in progress with their original 3.x runtime (see [Migration](docs/MIGRATION.md)). Read [SKILL.md](SKILL.md) and the [quickstart](docs/v2/guide/01-quickstart.en.md).
 
 ```bash
 npm view @haiyangbg/buildbeat@latest version
 npm install --global @haiyangbg/buildbeat@latest
+buildbeat --version
 ```
 
-> The envelope templates the quickstart uses (`templates/v2/envelope/`) ship with the package; see the [CHANGELOG](CHANGELOG.md) for what each version contains.
+```bash
+buildbeat accept --repo . --work WORK-X --by owner
+buildbeat run --config delivery/work/WORK-X/run-config.yaml
+buildbeat status --repo . --work WORK-X
+```
 
-**2. Load the entry point.** Download or clone this repository, ask your AI tool to read its [`SKILL.md`](SKILL.md), and say this in the target project:
+## Records and handoffs
 
-> 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.
+End-to-end work packages contain work.md, configuration, decisions and terminal records under delivery/work/. Local in-flight events and logs live in .buildbeat/runtime/; candidates live in .buildbeat/worktrees/. Save missing facts before switching sessions. Active runs do not migrate through Git clone.
 
-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).
+[Handoff](docs/v2/guide/11-session-handoff.en.md) · [Recovery](docs/v2/guide/10-recovery.en.md)
 
-**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:
+## Boundaries
 
-> Read the project's BuildBeat entry point, inspect progress and pending decisions, explain the next step, and continue within the existing authorization.
+BuildBeat does not provide multi-user accounts, roles and permissions. It does not collect or upload project usage data and has no telemetry collection. Models and authentication belong to the configured AI tool. Merge, push, deployment and publication remain separately authorized external actions. Production monitoring, release lanes and arbitrary workflow/policy languages are outside the current product.
 
-Check the goal, candidate, verification results, and next step it reads back. Follow the [session handoff guide](docs/v2/guide/11-session-handoff.en.md).
+[Capabilities](docs/CAPABILITY-MATRIX.md) · [Security](docs/v2/guide/09-security-boundaries.en.md) · [Migration](docs/MIGRATION.md)
 
-<details>
-<summary>Claude Code plugin installation</summary>
+## Claude Code plugin
 
-The plugin loads the Skill and reference material. Install the runtime separately.
+The plugin supplies Skill, templates and docs; the runtime is installed separately.
 
 ```text
 /plugin marketplace add HaiYangBG1/BuildBeat
@@ -124,30 +46,4 @@ The plugin loads the Skill and reference material. Install the runtime separatel
 /buildbeat:buildbeat
 ```
 
-To install from source, replace the marketplace address with this checkout's absolute path. See the [plugin guide](plugins/buildbeat/README.md) for cache boundaries and installation checks.
-
-</details>
-
-## Everyday use and applicability
-
-Once configured, talk to the session directly:
-
-| What you need | What you can say |
-|---|---|
-| A new session or teammate to take over | “Sync project records, read the entry point, and continue this work.” |
-| Progress | “What is done, what remains, and who moves next?” |
-| A decision | “What needs my decision? Show the evidence with it.” |
-| Recovery | “Is this run stuck? Inspect the state and handle recovery.” |
-| A fresh session | “Save the necessary context and check which work is still running.” |
-
-BuildBeat fits ongoing projects with frequent AI context changes, specialist collaboration, and a need for verifiable delivery records. Individuals can keep their own work moving; teams can hand work over through shared records. One-off scripts and very small changes usually do not need the full workflow. The project should have real verification commands, or establish minimum verification first.
-
-Teams collaborate through a shared Git repository and project agreements. BuildBeat does not provide multi-user accounts, roles and permissions. It does not collect or upload project usage data and has no telemetry collection. Configured AI tools and notification services have their own data practices. More examples are in the [conversation guide (Chinese)](docs/v2/guide/00-how-to-talk.en.md).
-
-## Learn more and contribute
-
-- [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.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).
+[Contributing](CONTRIBUTING.md) · [MIT](LICENSE)

package/README.md

@@ -1,122 +1,44 @@
 # BuildBeat
 
-**简体中文** | [English](README.en.md)
-
 **会话随时换，项目接着干。**
-上下文存进文件，协作围绕 Git，工作持续推进。
-
-BuildBeat 是以 Git 和项目文件为基础的 AI 交付工作流，面向人和 AI 会话。目标、计划、决定与交付记录保存在项目里，换模型、换工具、换会话，或换一个人接手，都有继续工作的依据。Loop 推进实现、验证、审查与修复；进度和证据由内核从 Git 与真实命令回读，不靠会话自述；关键决定由人掌握。
-
-[使用指南](docs/v2/guide/README.md) · [跨会话接续](docs/v2/guide/11-session-handoff.md) · [npm](https://www.npmjs.com/package/@haiyangbg/buildbeat) · [CI](https://github.com/HaiYangBG1/BuildBeat/actions/workflows/ci.yml) · [MIT](LICENSE)
-
-## 告别祖传上下文
-
-不用再抱着一个越来越长的“祖传会话”不放。上下文满了，开个新会话；想换模型或工具，从项目记录接着做；今天交给同事，接手的人也能从文件了解进度和下一步。目标、约束、计划、决定和交付记录都应落在文件系统中，新会话不必依赖旧聊天历史来判断下一步。
-
-下面是已配置项目的**使用情景示意**，不是一次实测运行记录：
-
-| 时刻 | 你说什么 | 会话做什么 |
-|---|---|---|
-| 会话 A：开始 | “给导出功能加日期筛选，先定计划。” | 读取项目约束，把目标与计划写入 Work；接受后启动执行 |
-| 准备离开 | “把决定和未完成事项落盘，我要关闭这个会话。” | 补齐项目记录，核对运行状态与未提交改动，说明下一步 |
-| 新会话接手 | “读取项目的 BuildBeat 入口，接着做日期筛选。” | 读取 Work、Git 与运行台账，查清已完成、未验证、待批和阻塞 |
-| 继续推进 | “按当前已接受的计划继续。” | 根据实况继续执行、处理恢复或等待决定，带证据停在合并决定前 |
-
-新会话可以由自己打开，也可以交给另一位有项目权限的人；换人或换机器时，同步记录与候选，并核对原 Run 的执行环境。
-
-**关键上下文落盘后，旧聊天可以关闭或删除。** 未保存的讨论不会自动变成项目记忆；删除聊天时应保留项目、候选分支和所需运行文件。具体步骤见 [跨会话接续](docs/v2/guide/11-session-handoff.md)。
-
-## 上下文就在项目里
-
-Git 管理需要长期保留的项目事实；本机文件保存运行中的状态。BuildBeat 读取这些事实来回答“做到哪了”，而不是让每个会话重新写一份进度猜测。
-
-| 文件与目录 | 保存什么 | 怎样使用 |
-|---|---|---|
-| `AGENTS.md`、项目规范与契约 | 项目入口、约束、角色和写入边界 | 新会话从入口读取，按任务深入相关文件 |
-| `delivery/work/<ID>/` | 目标、计划、配置、决定、审查裁决与终态运行记录 | 纳入 Git，作为同一项工作的接续依据 |
-| `.buildbeat/runtime/` | 在途事件、检查点、锁与原始日志 | 留在本机，不进 Git；恢复活动 Run 时需要 |
-| `.buildbeat/worktrees/` | Run 的隔离工作树 | 保留候选代码与现场，不作为聊天缓存清理 |
-
-落在文件系统不等于每个文件都应该提交到 Git。秘密留在受保护的本地环境中；终态记录保存证据摘要和引用，原始日志需要按项目要求另行保留。详见 [证据指南](docs/v2/guide/06-evidence-guide.md)。
-
-## 换个方式，继续同一项工作
-
-继续工作所需的上下文由项目文件承载。装载了 BuildBeat 的新会话可以读取同一份目标、决定和当前状态；负责执行的 Worker 通过命令接入，模型选择与鉴权由所用 AI 工具处理。
-
-- **跨会话**：关闭旧聊天，用干净上下文接续同一个 Work。
-- **跨工具与模型**：按目标工具的方式加载 Skill、配置执行命令和输出合同，复用项目记录。
-- **跨人接手**：有项目访问权限的人，同步上下文、候选与必要证据后，可以在职责和授权范围内继续；有效的既有决定继续保留。
-- **跨时间与地点**：同步已提交的项目文件后，可在准备好环境的另一台机器重新接手；活动 Run 的运行状态和工作树不会随普通 Git clone 自动迁移。
-
-**随时随地接手的基础，是记录可达、环境可用、权限明确。** 自己继续或交给别人，都从项目文件开始，无需携带旧聊天全文。Git 提供协作与版本管理，访问权限沿用仓库托管和执行平台的设置。
-
-协议可由不同工具读写；具体工具能否直接执行 Loop，要看适配、权限和环境。现有真实 Worker 证据覆盖 `codex exec`，脚本 Worker 有确定性测试；其他工具不能仅因有 CLI 就算已验证。见 [能力矩阵](docs/CAPABILITY-MATRIX.md) 与 [Adapter 指南](docs/v2/guide/04-adapter-guide.md)。
-
-## 多个角色，共同推进一项工作
 
-**端到端工作包**是协作单元。一个 Builder 对一个用户级结果负责，按需要调用产品、全栈、测试三个 AI 视角；多个 Builder 可以分别拥有不同工作包，也可以交接同一工作包；交接时写清当前负责推进的人、已完成事项和下一步，避免重复执行。
+BuildBeat 面向人和 AI 会话，把工作上下文留在项目文件中，自动推进可恢复的交付循环，带证据交给人决定。
 
-| 会话视角 | 接手时读取什么 | 产出什么 |
-|---|---|---|
-| 产品 | 目标、约束与既有决定 | 可接受的范围、计划与验收条件 |
-| 全栈（含运维） | 已接受计划、契约与环境事实 | 候选代码与实现记录 |
-| 测试 | 验收条件与候选 | 实际测试结果、覆盖范围与缺口 |
+## 三个承诺
 
-这些是可调用的专业视角，不是人类岗位接力的固定流程，也不要求固定开三个会话。审查不是会话视角：它是 Run 内置的只读 reviewer，见下一节。一个人或多个人都可以按需要调用这些视角。共同事实通过项目文件传递，各视角遵守自己的写入边界。当前单仓活动 Run 锁在本地生效；多角色或多个 Git 副本不等于有跨机器的运行协调。同一工作包交接前应核对原执行环境，避免双方重复启动。
+换会话能接着干；实现、验证、审查和修复自动推进；候选和证据就绪后再做决定。
 
-## 让工作进入 Loop
+## 开始使用
 
-接受所需计划后，`buildbeat` 在隔离 Git worktree 中调用配置好的 Worker，推进实现、验证、审查与修复。审查由一个不带上下文、只读的 reviewer worker 执行，任何工作树写入都会被前后快照比对捕获并按失败落账。
-
-```mermaid
-flowchart LR
-    P[接受计划] --> B[实现]
-    B --> V[验证]
-    V -->|通过| R[审查]
-    V -->|失败| F[修复]
-    R -->|阻断性发现| F
-    F --> V
-    R -->|通过| H[等待人的合并决定]
-```
-
-图示为正常与修复路径；风险预设、发现分诊、故障和预算可能增加等待点。
-
-- **完成有证据**：候选提交由 Git 回读，测试结论来自实际命令；AI 的“已完成”不能代替验证。
-- **批准有对象**：批准绑定具体候选、计划与证据；对象变了，旧批准会失效。
-- **中断有去向**：Runner 可按台账恢复；中断步骤可能重跑，脏工作树会先请求处理。
-- **循环有止损**：预算、重复失败与基础设施故障形成明确的待处理事项；可配置通知。
-
-合并决定表示候选具备合并条件。合并、推送和部署由人或另行授权的工具在 Runner 之外执行；上线后可用 `release-readback` 保存回读与观察记录。执行检查与宿主隔离各有范围，见 [安全与权限边界](docs/v2/guide/09-security-boundaries.md)。
-
-## 开始你的第一次接力
-
-需要 Node.js ≥ 20、Git、Bash，以及已安装并完成鉴权的 AI 编程工具。
-
-**1. 安装运行时。** 稳定发布包使用 `@latest`，可执行文件只有一个：`buildbeat`。
+运行时需要 Node ≥ 20。从 3.x 升级前，先用原来的 3.x 运行时完成或取消仍在进行的 Run（见[迁移说明](docs/MIGRATION.md)）。先读 [SKILL.md](SKILL.md) 与[快速开始](docs/v2/guide/01-quickstart.md)。
 
 ```bash
 npm view @haiyangbg/buildbeat@latest version
 npm install --global @haiyangbg/buildbeat@latest
+buildbeat --version
 ```
 
-> 快速开始用到的信封模板（`templates/v2/envelope/`）随包分发；版本与内容对照见 [CHANGELOG](CHANGELOG.md)。
+```bash
+buildbeat accept --repo . --work WORK-X --by owner
+buildbeat run --config delivery/work/WORK-X/run-config.yaml
+buildbeat status --repo . --work WORK-X
+```
 
-**2. 让会话加载入口。** 下载或检出本仓，让你的 AI 工具读取其中的 [`SKILL.md`](SKILL.md)，然后在目标项目中说：
+## 记录与接续
 
-> 用 BuildBeat 接管这个项目。先检查代码和现有约束，为第一项工作准备上下文与运行配置。
+端到端工作包在 delivery/work/ 保存 work.md、配置、决定与终态记录；本机在途事件和日志在 .buildbeat/runtime/，候选在 .buildbeat/worktrees/。换会话前补齐未落盘事实。Git clone 不迁移活动进程和现场。
 
-会话先检查项目，补齐目标、计划、验证命令和执行配置；你接受后再启动。完整步骤见 [快速开始](docs/v2/guide/01-quickstart.md)；填好之后长什么样，看 [示例项目](example/README.md)。
+[Handoff](docs/v2/guide/11-session-handoff.md) · [Recovery](docs/v2/guide/10-recovery.md)
 
-**3. 试一次接力。** 在工作记录落盘后关闭旧会话，打开一个没有旧聊天历史的新会话；也可以同步记录与候选，让另一位有权限的成员用自己的工具接手：
+## 能力边界
 
-> 读取项目的 BuildBeat 入口，查看当前进度和待批事项，告诉我下一步，然后在已有授权范围内继续。
+BuildBeat 不提供多人账号、角色/权限系统，不采集或上传项目使用数据，没有遥测采集。模型和鉴权由配置的 AI 工具提供。合并、推送、部署、发布分别由获授权的外部操作完成。生产巡检、上线专用流程和任意工作流/规则语言已移出产品。
 
-核对它读出的目标、候选、验证结果和下一步，再继续。见 [跨会话接续指南](docs/v2/guide/11-session-handoff.md)。
+[Capabilities](docs/CAPABILITY-MATRIX.md) · [Security](docs/v2/guide/09-security-boundaries.md) · [Migration](docs/MIGRATION.md)
 
-<details>
-<summary>Claude Code 插件安装</summary>
+## Claude Code 插件
 
-插件负责加载 Skill 与参考资料，运行时需要另行安装。
+插件提供 Skill、模板与文档，运行时单独安装。
 
 ```text
 /plugin marketplace add HaiYangBG1/BuildBeat
@@ -124,30 +46,4 @@ npm install --global @haiyangbg/buildbeat@latest
 /buildbeat:buildbeat
 ```
 
-本地源码安装可把 marketplace 地址换成本仓绝对路径。缓存与安装检查见 [插件说明](plugins/buildbeat/README.md)。
-
-</details>
-
-## 日常使用与适用范围
-
-完成配置后，直接在会话里说：
-
-| 你想做什么 | 可以怎么说 |
-|---|---|
-| 新会话或新成员接手 | “同步项目记录，读取入口，继续这个工作。” |
-| 查进度 | “已经做了什么，还差什么，下一步该谁？” |
-| 处理决定 | “有什么需要我拍板？把证据一起给我。” |
-| 排查中断 | “这次运行卡住了吗？核对现场后处理恢复。” |
-| 准备换会话 | “把关键上下文落盘，核对哪些工作还在运行。” |
-
-BuildBeat 适合持续迭代、经常切换 AI 上下文、需要多角色协作与可核验交付记录的项目。个人可以连续推进自己的工作，团队也可以通过共享记录接力。一次性脚本和很小的修改通常无需完整工作流。项目应有真实验证命令，或先建立最小验证能力。
-
-团队协作使用共享 Git 仓库与项目约定。BuildBeat 不提供独立的多人账号、角色/权限管理；不采集或上传项目使用数据，没有遥测采集。你配置的 AI 工具和通知服务有各自的数据处理方式。更完整的日常话术见 [用户指南](docs/v2/guide/00-how-to-talk.md)。
-
-## 深入了解与贡献
-
-- [文档总入口](docs/README.md)：当前指南、规范与历史记录。
-- [能力矩阵](docs/CAPABILITY-MATRIX.md)：手工协议、运行时与插件的能力和验证范围。
-- [跨会话接续](docs/v2/guide/11-session-handoff.md) · [运行恢复](docs/v2/guide/10-recovery.md) · [批准与分诊](docs/v2/guide/07-approval-guide.md)。
-- [Skill](SKILL.md)：会话如何使用 BuildBeat；[lessons](lessons.md)：机制背后的真实事故。
-- [CHANGELOG](CHANGELOG.md) · [贡献指南](CONTRIBUTING.md) · [MIT 许可](LICENSE)。
+[Contributing](CONTRIBUTING.md) · [MIT](LICENSE)