@haiyangbg/buildbeat 4.2.1 → 4.2.3

package/CHANGELOG.md

@@ -2,8 +2,22 @@
 
 > 本项目吃自己的狗粮(红线④:必更 CHANGELOG)。格式循 Keep a Changelog,倒序。
 
+## v4.2.3 — 2026-10-11（补丁：README 改成「装好后跟 AI 说话」）
+
+- README (zh/en) rewritten in plain words for people who hand the work to an AI (PRs #84–#87). The opening states the one pain (switch session, tool, computer or person and you explain everything again) and what BuildBeat keeps in the project and Git. Get started is a single prompt to paste into the AI coding tool: it checks the environment, installs or upgrades the runtime (with the 3.x rule), reads `SKILL.md` and the quickstart from the npm package and puts the templates in place; the Claude Code plugin sits in a collapsed block. Examples are short "you / AI" exchanges by situation (first time, starting a work, new session/computer/person, one more change, your own fix, stuck on the environment, several repositories), with the real `status` output collapsed. New sections explain what a work is (the smallest unit BuildBeat keeps records in) and the project's folder layout, including which folders travel with Git. The three promises, the boundaries section and most links to guides are gone; the facts that mattered are written into the page.
+- `check:docs` requires only the quickstart, contributing and license links from the README and no longer requires the product-boundary or "end-to-end work package" phrases there; the facts stay in the capability matrix.
+- GitHub About is bilingual and plain, with the npm page as homepage and `claude-code-plugin` / `code-review` topics.
+
+## v4.2.2 — 2026-10-07（补丁：README 重新设计）
+
+> **发布状态**：`@haiyangbg/buildbeat@4.2.2` 已于 2026-10-07 从 `main`（release PR #81，merge commit `3a43ae3`，tag `v4.2.2`）经 OIDC Trusted Publishing 发布到 dist-tag **`latest`**（run 37637179739，publish 与 verify 双 job 一次 success；所有者授权「合并并发 4.2.2」）。独立回读（直连 npmjs.org）：`latest` = 4.2.2、`dist.integrity` 与本地用 Node 24 + npm 11.19.0 打的候选逐字一致、注册表 tarball 解压后与候选逐字节相同、SLSA v1 provenance、隔离安装 `--version` = 4.2.2、裸调用零写入、`npm audit signatures` 通过；GitHub Release v4.2.2 标 Latest；证据见 [`docs/releases/V4.2.2-RELEASE-EVIDENCE-2026-10-07.md`](docs/releases/V4.2.2-RELEASE-EVIDENCE-2026-10-07.md)。同日所有者本人经 npm 两步验证把 dist-tag `next` 从 4.2.0 挪到 4.2.2；直连 npmjs.org 回读 `next` = `latest` = 4.2.2。
+
+- README (zh/en) redesigned for reading: a hero picture, the name's meaning (every step is a note the agent plays; the played score stays in Git), a delivery-loop diagram in light and dark with a stacked layout for phones, the three promises as short sections, a real `status` excerpt at the merge decision, and which records travel with Git and which stay on this machine. Pictures live in `docs/assets/readme/` (the loop diagram is drawn by `diagrams.mjs`) and are linked through raw URLs so the npm page shows them too; `check:docs` now requires every README picture to exist, carry alt text and stay under 600 KB.
+
 ## v4.2.1 — 2026-10-07（补丁：审查没交报告当场停；成本按去向分开等待）
 
+> **发布状态**：`@haiyangbg/buildbeat@4.2.1` 已于 2026-10-07 从 `main`（release PR #79，merge commit `8d2625b`，tag `v4.2.1`）经 OIDC Trusted Publishing 发布到 dist-tag **`latest`**（run 37626818833，publish 与 verify 双 job 一次 success；所有者授权「推送并发 4.2.1」）。独立回读（直连 npmjs.org）：`latest` = 4.2.1、`dist.integrity` 与本地用 Node 24 + npm 11.19.0 打的候选逐字一致、注册表 tarball 解压后与候选逐字节相同、SLSA v1 provenance、隔离安装 `--version` = 4.2.1、裸调用零写入、`npm audit signatures` 通过；GitHub Release v4.2.1 标 Latest，仓库 About 同日更新；证据见 [`docs/releases/V4.2.1-RELEASE-EVIDENCE-2026-10-07.md`](docs/releases/V4.2.1-RELEASE-EVIDENCE-2026-10-07.md)。`next` 仍为 4.2.0。
+
 - A review step that exits 0 without writing a report to `$BUILDBEAT_OUTPUT` now stops as `invalid-output` (an infrastructure failure: no fixer, no charge, `resume-review` waits for a person) instead of passing with no evidence until the merge approval refused it. The stop reason says where the report belongs and, when the reviewer printed something, how many bytes went to stdout. Found in a replay of real runs, where a reviewer's 3 P1, 6 P2 and 4 P3 findings reached stdout only.
 - The cost line splits human waits by how they ended: `human waits N (decided … · superseded … · stopped … · open …)`, listing only kinds that occurred; a request repeated before any decision continues the same wait, so overlapping time is not counted twice; JSON carries `cost.waits` with `{count, ms}` per kind and run-records keep it. In the same replay one work showed 32 minutes of decided waits while 11 hours passed on a request a new run superseded.
 - README (zh/en) describes the 4.x product: the three promises now name the mechanisms behind them (one `work.md` driven by `buildbeat run` and `status --all-repos`; evidence read back from Git and infrastructure stops instead of code fixes; merge approvals bound to the candidate and repairs at the merge decision), the cost line's waits, taking part without the runtime and the release readback.

package/README.en.md

@@ -1,46 +1,61 @@
-# BuildBeat
+<p align="center">
+  <img src="https://raw.githubusercontent.com/HaiYangBG1/BuildBeat/main/docs/assets/readme/hero.jpg" width="100%" alt="Five notes on a musical staff, build, verify, review, fix and decide, joined by a pulse line that ends in a stack of written sheet music">
+</p>
 
-**Switch sessions. Keep building.**
+<h1 align="center">BuildBeat</h1>
 
-BuildBeat is for humans and AI sessions: the work description and every record stay in project files and Git; implementation, verification, review and repair move forward outside the session and can always resume; the candidate waits with its evidence for your merge decision.
+<p align="center"><strong>Switch sessions. Keep building.</strong></p>
 
-## Three promises
+<p align="center">
+  <a href="https://www.npmjs.com/package/@haiyangbg/buildbeat"><img alt="npm version" src="https://img.shields.io/npm/v/@haiyangbg/buildbeat?color=d97706&amp;label=npm"></a>
+  <a href="https://github.com/HaiYangBG1/BuildBeat/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/HaiYangBG1/BuildBeat/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-e5534b"></a>
+</p>
 
-- **Walk away.** Each work gets one `work.md`; once accepted, `buildbeat run` drives it. Close the session, switch AI tools or hand over to someone else, and continue from the project files and the run ledger. In a main repository with several code repositories, `buildbeat status --repo . --all-repos` shows what is pending everywhere.
-- **Come back to facts.** Verification runs the project's own commands, and the runtime reads results back from Git and the ledger instead of trusting what an AI says; review is independent and read-only. Missing tools, an unavailable backend or a review that hands in no report stop as infrastructure failures for a person, instead of being "fixed" as code.
-- **Decide with confidence.** A merge approval is bound to the candidate you reviewed (`--candidate`). When you spot a small problem at the merge decision, commit a fix and hand it over (`run --adopt`) or send it back to the fixer in one line (`decide --action fix`), without starting a new run. Merge, push, release and deployment stay with people.
+<p align="center"><a href="README.md">中文</a> · English</p>
 
-## Start
+When you code with AI, every switch of session, tool, computer or person means explaining everything from the start.
 
-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).
+BuildBeat is for humans and AI sessions. It keeps what needs doing, how far it got and what was decided in the project and Git, so whoever picks it up can carry on. Once the AI has written the code, it goes on to run the tests, review and fix problems, then stops and waits for your go-ahead.
 
-```bash
-npm view @haiyangbg/buildbeat@latest version
-npm install --global @haiyangbg/buildbeat@latest
-buildbeat --version
-```
-
-```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
-```
+## At a glance
 
-## Records and handoffs
+<picture>
+  <source media="(max-width: 600px) and (prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/HaiYangBG1/BuildBeat/main/docs/assets/readme/loop-en-dark-narrow.png">
+  <source media="(max-width: 600px)" srcset="https://raw.githubusercontent.com/HaiYangBG1/BuildBeat/main/docs/assets/readme/loop-en-light-narrow.png">
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/HaiYangBG1/BuildBeat/main/docs/assets/readme/loop-en-dark.png">
+  <img src="https://raw.githubusercontent.com/HaiYangBG1/BuildBeat/main/docs/assets/readme/loop-en-light.png" width="100%" alt="The delivery loop: after work.md come build, verify and review; findings go to fix, verify and review again; then the run stops for you to decide; work.md, decisions, findings and each run's final record stay in Git">
+</picture>
 
-End-to-end work packages contain work.md, configuration, decisions, review findings and terminal records under delivery/work/. Local in-flight events and logs live in .buildbeat/runtime/; candidates live in .buildbeat/worktrees/. The cost line in `status` shows review rounds, findings and where human waits went (decided, superseded, stopped, still open). Save missing facts before switching sessions; active runs do not migrate through Git clone. People and tools without the runtime can still read status and write work descriptions.
+1. You say what you want; the AI first writes a `work.md` for you to read: goal, scope, what counts as done
+2. You say yes; it writes the code in a separate copy and runs your project's own tests
+3. Another read-only AI reviews it; findings get fixed, then tested and reviewed again
+4. When it's done, it stops and waits for your go-ahead
 
-[Handoff](docs/v2/guide/11-session-handoff.en.md) · [Recovery](docs/v2/guide/10-recovery.en.md) · [Without the runtime](docs/v2/guide/12-without-runtime.en.md)
+BuildBeat reads the test results itself instead of relying on the AI's report. If it stops halfway, say "continue" and it carries on.
 
-## Boundaries
+## Get started
 
-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; after a release, `buildbeat release` records the project's own readback and the window closes only when it passes. Production monitoring and arbitrary workflow/policy languages are outside the product.
+Copy the text below into your AI coding tool (Claude Code, Codex or Cursor) and it installs and sets everything up itself:
 
-[Capabilities](docs/CAPABILITY-MATRIX.md) · [Security](docs/v2/guide/09-security-boundaries.en.md) · [Migration](docs/MIGRATION.md)
+```
+Please set up BuildBeat (https://github.com/HaiYangBG1/BuildBeat) in this project:
+
+1. Check that this machine has Node 20 or later and Git; if anything is missing, tell me how to install it.
+2. Install or upgrade the BuildBeat runtime:
+   npm view @haiyangbg/buildbeat@latest version
+   npm install --global @haiyangbg/buildbeat@latest
+   buildbeat --version
+   If a 3.x version is installed and still has unfinished work, finish or cancel it with the old version before upgrading.
+3. Read SKILL.md and docs/v2/guide/01-quickstart.en.md from the npm package (under $(npm root -g)/@haiyangbg/buildbeat/) and work the way SKILL.md describes from now on.
+4. Following the quickstart, put the templates into this project and update .gitignore. By default, use the AI command-line tool already signed in on this machine for building, reviewing and fixing; ask me if unsure.
+5. When you're done, tell me in a sentence or two that we can start. From then on I'll just tell you in plain words what I want, and you run the commands.
+```
 
-## Claude Code plugin
+Once it's set up, just talk to it; common situations are under "What it looks like" below.
 
-The plugin supplies Skill, templates and docs; the runtime is installed separately.
+<details>
+<summary>Using Claude Code? You can also install the plugin</summary>
 
 ```text
 /plugin marketplace add HaiYangBG1/BuildBeat
@@ -48,4 +63,108 @@ The plugin supplies Skill, templates and docs; the runtime is installed separate
 /buildbeat:buildbeat
 ```
 
-[Contributing](CONTRIBUTING.md) · [MIT](LICENSE)
+</details>
+
+To install step by step yourself, see the [quickstart](docs/v2/guide/01-quickstart.en.md).
+
+## What it looks like
+
+**First time**
+
+- **You**: (paste the text above)
+- **AI**: All set, we can start.
+
+**Starting a work**
+
+- **You**: Add CSV export to the ledger.
+- **AI**: I wrote `work.md`: export the filtered entries, quote fields with commas, done when all tests pass. Look right?
+- **You**: Yes, go.
+
+**New session, computer or person**
+
+- **You**: Where are we?
+- **AI**: "CSV export" is done and waiting for your go-ahead. The first review found unquoted commas; that's fixed and retested, and the second review passed.
+- **You**: Approve and merge it.
+
+**One more change**
+
+- **You**: Empty lists should export too.
+- **AI**: OK, I'll keep going, test and review again, and call you when it passes.
+
+**You changed something yourself**
+
+- **You**: I reworded the button and committed it.
+- **AI**: Got it, I'll test and review your change again.
+
+**Stuck**
+
+- **AI**: I've stopped: the local database isn't running. That's not a code problem, so I haven't touched the code.
+- **You**: It's up, continue.
+
+**Several repositories**
+
+- **You**: Where are all the repos at?
+- **AI**: Three works across two repos: one waits for your go-ahead, two are still running.
+
+It only stops to find you in these cases: the work is done and waits for your go-ahead, the budget is used up, a review keeps finding new problems, or the environment is broken.
+
+<details>
+<summary>What the AI sees behind "Where are we?"</summary>
+
+```text
+$ buildbeat status --repo . --work WORK-CSV-EXPORT
+WORK-CSV-EXPORT  MERGE_DECISION
+  [P1 0b5e258117cb5602] (accept) csv: quote fields that contain commas
+  work.md ✓ · runs 1
+  cost: review rounds 2 · findings 1 · human waits 1 (open 33s) · worker 2s
+work WORK-CSV-EXPORT:
+  RUN-CSV-EXPORT-01 [final-decision] enter-wait-merge — waiting 33s
+    candidate: ede20b668cb04ae30cba1676b5e031930e711c8d
+    next: buildbeat decide --action approve … --candidate ede20b6… --by <you>
+    next: buildbeat decide --action reject … --reason <why> --by <you>
+    next: buildbeat run … --adopt <sha> --by <you>   # commit a manual repair in the run worktree …
+    next: buildbeat decide … --action fix --reason <what to repair> --by <you>
+```
+
+</details>
+
+## What a work is
+
+**What**: the smallest unit BuildBeat keeps records in. One result you can see, like "CSV export", is one work, with one folder.
+
+**Why**: the AI doesn't remember things, and sessions change at any time. What the work is for, how far it got, what review found and what you decided all go into that folder, so whoever picks it up carries on from there, and later you can look back at how it got done.
+
+## Files in your project
+
+The first time, the AI puts these files in place from the templates:
+
+```
+your-project/
+├── AGENTS.md, CLAUDE.md            tell AI tools this project uses BuildBeat
+├── .gitignore                      add the two .buildbeat/ folders below
+├── delivery/                       travels with Git
+│   ├── envelope/
+│   │   ├── worker.sh               wraps an AI tool as a step BuildBeat can call
+│   │   └── prompts/                prompts for build, review and fix
+│   └── work/
+│       └── WORK-X/                 one folder per work
+│           ├── work.md             what to do and what counts as done
+│           ├── run-config.yaml     which AI, which tests, which folders it may change
+│           ├── decisions.jsonl     accept, approve, close and other decisions
+│           ├── review-findings.jsonl  problems the review found and your rulings
+│           ├── releases.jsonl      checks after going live (only if used)
+│           └── runs/RUN-X-01/
+│               └── run-record.json this run's outcome, evidence and cost
+└── .buildbeat/
+    ├── notify.yaml                 optional: webhook or DingTalk alerts when you're needed
+    ├── runtime/                    this machine only: live ledger, logs, screenshots
+    └── worktrees/                  this machine only: isolated copies the AI works in
+```
+
+- `delivery/` goes into Git: switching sessions, tools, computers or people just means pulling the code and carrying on
+- `.buildbeat/runtime/` and `.buildbeat/worktrees/` stay on this machine: a run in progress does not travel with Git, so finish or stop it where it started
+- People and AI tools without BuildBeat installed can still read these files and draft `work.md`
+
+To contribute, see [Contributing](CONTRIBUTING.md); the code is open source under the [MIT license](LICENSE).
+
+> **Why the name**: every step is a note, and the agent plays them beat by beat; the score it has played (context, decisions and outcomes) stays in Git, ready to read again.

package/README.md

@@ -1,46 +1,61 @@
-# BuildBeat
+<p align="center">
+  <img src="https://raw.githubusercontent.com/HaiYangBG1/BuildBeat/main/docs/assets/readme/hero.jpg" width="100%" alt="五线谱上依次排着实现、验证、审查、修复、拍板五个音符，一条脉搏线把它们连起来，末端收进一叠写满音符的乐谱">
+</p>
 
-**会话随时换，项目接着干。**
+<h1 align="center">BuildBeat</h1>
 
-BuildBeat 面向人和 AI 会话：工作说明和全部记录留在项目文件与 Git 里，实现、验证、审查和修复在会话之外自动推进、随时可恢复，候选带着证据停在你的合并决定前。
+<p align="center"><strong>会话随时换，项目接着干。</strong></p>
 
-## 三个承诺
+<p align="center">
+  <a href="https://www.npmjs.com/package/@haiyangbg/buildbeat"><img alt="npm 版本" src="https://img.shields.io/npm/v/@haiyangbg/buildbeat?color=d97706&amp;label=npm"></a>
+  <a href="https://github.com/HaiYangBG1/BuildBeat/actions/workflows/ci.yml"><img alt="CI 状态" src="https://github.com/HaiYangBG1/BuildBeat/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="MIT 许可证" src="https://img.shields.io/badge/license-MIT-e5534b"></a>
+</p>
 
-- **走得开**：一项工作写一份 `work.md`，接受后由 `buildbeat run` 推进。关掉会话、换 AI 工具、换人，都能从项目文件和运行台账接着干；主仓带多个代码仓时，`buildbeat status --repo . --all-repos` 一条命令看全所有仓的待办。
-- **回来能信**：验证跑项目自己的命令，结果由运行时从 Git 和台账回读，不听 AI 自述；审查独立、只读。缺工具、后端不可用、审查没交报告，都按环境故障停下等人，不会把环境问题当成代码问题去修。
-- **敢拍板**：合并批准绑定你看过的那一版候选（`--candidate`）。在合并决定点发现小问题，可以自己修好交回（`run --adopt`），或一句话退回给修复者（`decide --action fix`），不必重开一轮。合并、推送、发布、部署始终由人决定。
+<p align="center">中文 · <a href="README.en.md">English</a></p>
 
-## 开始使用
+用 AI 写代码，换个会话、换个软件、换台电脑、换个人，事情都得从头讲一遍。
 
-运行时需要 Node ≥ 20。从 3.x 升级前，先用原来的 3.x 运行时完成或取消仍在进行的 Run（见[迁移说明](docs/MIGRATION.md)）。先读 [SKILL.md](SKILL.md) 与[快速开始](docs/v2/guide/01-quickstart.md)。
+BuildBeat 面向人和 AI 会话，把要做的事、做到哪、定过什么都记在项目和 Git 里，谁接手都能接着干。AI 写完代码，它会接着跑测试、做审查、修问题，最后停下来等你拍板。
 
-```bash
-npm view @haiyangbg/buildbeat@latest version
-npm install --global @haiyangbg/buildbeat@latest
-buildbeat --version
-```
-
-```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
-```
+## 一眼看懂
 
-## 记录与接续
+<picture>
+  <source media="(max-width: 600px) and (prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/HaiYangBG1/BuildBeat/main/docs/assets/readme/loop-zh-dark-narrow.png">
+  <source media="(max-width: 600px)" srcset="https://raw.githubusercontent.com/HaiYangBG1/BuildBeat/main/docs/assets/readme/loop-zh-light-narrow.png">
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/HaiYangBG1/BuildBeat/main/docs/assets/readme/loop-zh-dark.png">
+  <img src="https://raw.githubusercontent.com/HaiYangBG1/BuildBeat/main/docs/assets/readme/loop-zh-light.png" width="100%" alt="交付循环：work.md 之后依次是实现、验证、审查，审查有问题就修复、重验、再审，最后停下等你拍板；work.md、决定、审查问题和每轮运行的终态记录留在 Git 里">
+</picture>
 
-端到端工作包在 delivery/work/ 保存 work.md、配置、决定、审查问题与终态记录；本机在途事件和日志在 .buildbeat/runtime/，候选在 .buildbeat/worktrees/。`status` 的成本行列出审查轮数、问题数，以及人工等待各自的去向（已决定、被替代、被停掉、仍在等）。换会话前补齐未落盘事实；Git clone 不迁移活动进程和现场。没装运行时的人和工具也能读状态、写工作说明。
+1. 你说要做什么，AI 先写一份 `work.md` 给你看：目标、范围、做到什么算完
+2. 你点头，它在一个单独的副本里写代码、跑你项目自己的测试
+3. 另一个只读的 AI 来审查；有问题就修，修完重新测、重新审
+4. 做完了停下来，等你拍板
 
-[Handoff](docs/v2/guide/11-session-handoff.md) · [Recovery](docs/v2/guide/10-recovery.md) · [没有运行时](docs/v2/guide/12-without-runtime.md)
+测试结果由 BuildBeat 自己去读，不靠 AI 汇报。中途断了，说一句「继续」就接着跑。
 
-## 能力边界
+## 开始用
 
-BuildBeat 不提供多人账号、角色/权限系统，不采集或上传项目使用数据，没有遥测采集。模型和鉴权由配置的 AI 工具提供。合并、推送、部署、发布分别由获授权的外部操作完成；上线后可用 `buildbeat release` 记录项目自己的回读，回读通过才关窗。生产巡检和任意工作流/规则语言不在产品范围内。
+把下面这段复制给你的 AI 编程工具（Claude Code、Codex、Cursor 都行），它会自己装好、配好：
 
-[Capabilities](docs/CAPABILITY-MATRIX.md) · [Security](docs/v2/guide/09-security-boundaries.md) · [Migration](docs/MIGRATION.md)
+```
+请帮我在这个项目里用上 BuildBeat（https://github.com/HaiYangBG1/BuildBeat）：
+
+1. 检查本机有没有 Node 20 以上和 Git，缺了就告诉我怎么装。
+2. 安装或升级 BuildBeat 运行时：
+   npm view @haiyangbg/buildbeat@latest version
+   npm install --global @haiyangbg/buildbeat@latest
+   buildbeat --version
+   如果本机已经装了 3.x，并且还有没跑完的工作，先用旧版跑完或取消，再升级。
+3. 读一遍 npm 包里的 SKILL.md 和 docs/v2/guide/01-quickstart.md（在 $(npm root -g)/@haiyangbg/buildbeat/ 下），之后都按 SKILL.md 的方式干活。
+4. 按快速开始把模板放进这个项目、补好 .gitignore。实现、审查、修复默认用本机已登录的 AI 命令行工具，拿不准就问我。
+5. 弄好后用一两句话告诉我可以开始了。之后我只用平常的话跟你说要做什么，命令都由你来跑。
+```
 
-## Claude Code 插件
+装好之后，就用平常的话跟它说，常见场景见下面「用起来是什么样」。
 
-插件提供 Skill、模板与文档，运行时单独安装。
+<details>
+<summary>用 Claude Code？也可以装插件</summary>
 
 ```text
 /plugin marketplace add HaiYangBG1/BuildBeat
@@ -48,4 +63,108 @@ BuildBeat 不提供多人账号、角色/权限系统，不采集或上传项目
 /buildbeat:buildbeat
 ```
 
-[Contributing](CONTRIBUTING.md) · [MIT](LICENSE)
+</details>
+
+想自己动手一步步装，见[快速开始](docs/v2/guide/01-quickstart.md)。
+
+## 用起来是什么样
+
+**第一次用**
+
+- **你**：（复制上面那段）
+- **AI**：装好了，可以开始了。
+
+**开始一项工作**
+
+- **你**：给账本加个导出 CSV 的功能。
+- **AI**：写好了 `work.md`：导出当前筛选的账目，带逗号的字段加引号，测试全过才算完。你看行吗？
+- **你**：行，开工。
+
+**换会话、换电脑、换人**
+
+- **你**：到哪了？
+- **AI**：「导出 CSV」做完了，等你拍板。第一轮审查发现带逗号没加引号，已经修好、重新测过，第二轮通过了。
+- **你**：批准，合并吧。
+
+**想再改改**
+
+- **你**：空表也要能导出。
+- **AI**：好，我接着改，重新测、重新审，过了再叫你。
+
+**你自己动手改了**
+
+- **你**：按钮文案我改了，已经提交。
+- **AI**：看到了，我把你的改动重新测一遍、审一遍。
+
+**卡住了**
+
+- **AI**：停下来了：本地数据库没启动。这不是代码问题，我没改代码。
+- **你**：开好了，继续。
+
+**好几个仓库**
+
+- **你**：所有仓库到哪了？
+- **AI**：两个仓库一共三项工作：一项等你拍板，两项还在跑。
+
+它会停下来找你的情况只有这几种：做完了等你拍板、预算用完、审查一直不收敛、环境出了问题。
+
+<details>
+<summary>「到哪了？」时 AI 背后看到的输出</summary>
+
+```text
+$ buildbeat status --repo . --work WORK-CSV-EXPORT
+WORK-CSV-EXPORT  MERGE_DECISION
+  [P1 0b5e258117cb5602] (accept) csv: quote fields that contain commas
+  work.md ✓ · runs 1
+  cost: review rounds 2 · findings 1 · human waits 1 (open 33s) · worker 2s
+work WORK-CSV-EXPORT:
+  RUN-CSV-EXPORT-01 [final-decision] enter-wait-merge — waiting 33s
+    candidate: ede20b668cb04ae30cba1676b5e031930e711c8d
+    next: buildbeat decide --action approve … --candidate ede20b6… --by <you>
+    next: buildbeat decide --action reject … --reason <why> --by <you>
+    next: buildbeat run … --adopt <sha> --by <you>   # commit a manual repair in the run worktree …
+    next: buildbeat decide … --action fix --reason <what to repair> --by <you>
+```
+
+</details>
+
+## 什么是一项工作
+
+**是什么**：BuildBeat 记东西的最小单位。一个你能看到的结果，比如「导出 CSV」，就是一项工作，对应一个文件夹。
+
+**为什么要有它**：AI 记不住事，会话也随时会换。把这件事要做什么、做到哪、审出过什么问题、你拍过什么板，都收进这个文件夹，谁接手都从这里接着干，回头也能翻出来看它是怎么做成的。
+
+## 项目里的文件
+
+第一次接入时，AI 会照模板把这些文件放好：
+
+```
+你的项目/
+├── AGENTS.md、CLAUDE.md            告诉 AI 工具：这个项目用 BuildBeat
+├── .gitignore                      加上下面两行 .buildbeat/ 目录
+├── delivery/                       跟着 Git 走
+│   ├── envelope/
+│   │   ├── worker.sh               把 AI 工具包成 BuildBeat 能调用的一步
+│   │   └── prompts/                实现、审查、修复各自的提示词
+│   └── work/
+│       └── WORK-X/                 一项工作一个文件夹
+│           ├── work.md             要做什么、做到什么算完
+│           ├── run-config.yaml     用哪个 AI、跑什么测试、能改哪些目录
+│           ├── decisions.jsonl     接受、批准、关闭这些决定
+│           ├── review-findings.jsonl  审查挑出的问题和你的裁决
+│           ├── releases.jsonl      上线后的检查记录（用到才有）
+│           └── runs/RUN-X-01/
+│               └── run-record.json 这一轮的结果、证据和成本
+└── .buildbeat/
+    ├── notify.yaml                 可选：等你拍板时发 webhook 或钉钉通知
+    ├── runtime/                    只在本机：正在跑的台账、日志、截图
+    └── worktrees/                  只在本机：AI 干活用的隔离副本
+```
+
+- `delivery/` 进 Git：换会话、换软件、换电脑、换人，拉下代码就能接着干
+- `.buildbeat/runtime/`、`.buildbeat/worktrees/` 只在本机：正在跑的那一轮不跟着 Git 走，要在原来那台机器上跑完或停掉
+- 没装 BuildBeat 的人和 AI 也能读这些文件、起草 `work.md`
+
+参与贡献看[贡献指南](CONTRIBUTING.md)，代码以 [MIT 许可证](LICENSE)开源。
+
+> **名字的由来**：每一步是一个音符，Agent 按节拍把它们演奏出来；演奏过的乐谱——上下文、决定和结论——留在 Git 里，随时翻阅。

package/docs/CAPABILITY-MATRIX.md

@@ -1,6 +1,6 @@
 # BuildBeat capability matrix / 能力矩阵
 
-Current release: 4.2.1. One product path: Skill → local runtime →
+Current release: 4.2.3. One product path: Skill → local runtime →
 project records. The Claude Code plugin distributes the Skill and references;
 install the runtime separately. Files remain readable without the runtime, but
 manual work has no automatic loop, isolation, budget or approval enforcement;

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@4.2.1`; latest independently verified BuildBeat npm distribution `@haiyangbg/buildbeat@4.2.0` (dist-tags `latest` and `next`; the owner moved `next` from `4.0.0` to `4.2.0` with npm 2FA on 2026-10-07), anchored by annotated tag `v4.2.0` at commit `cc52ad3`, workflow run [37597691057](https://github.com/HaiYangBG1/BuildBeat/actions/runs/37597691057), and archived in [`V4.2.0-RELEASE-EVIDENCE-2026-10-07.md`](releases/V4.2.0-RELEASE-EVIDENCE-2026-10-07.md). The 4.1.0 chain (`latest` on 2026-10-07 until 4.2.0 took over the same day) stays archived in [`V4.1.0-RELEASE-EVIDENCE-2026-10-07.md`](releases/V4.1.0-RELEASE-EVIDENCE-2026-10-07.md). The 4.0.0 chain (`latest` from 2026-10-05 until 4.1.0 took over on 2026-10-07; the owner moved `next` from `3.3.1` to `4.0.0` with npm 2FA on 2026-10-05) stays archived in [`V4.0.0-RELEASE-EVIDENCE-2026-10-05.md`](releases/V4.0.0-RELEASE-EVIDENCE-2026-10-05.md). The 3.3.1 chain (`latest` from 2026-10-02 until 4.0.0 took over on 2026-10-05; the owner moved `next` from `3.3.0` to `3.3.1` with npm 2FA on 2026-10-02) stays archived in [`V3.3.1-RELEASE-EVIDENCE-2026-10-02.md`](releases/V3.3.1-RELEASE-EVIDENCE-2026-10-02.md). The 3.3.0 chain (`latest` on 2026-10-02 until 3.3.1 took over the same day; the owner moved `next` from `3.2.1` to `3.3.0` with npm 2FA that day) stays archived in [`V3.3.0-RELEASE-EVIDENCE-2026-10-02.md`](releases/V3.3.0-RELEASE-EVIDENCE-2026-10-02.md). The 3.2.1 chain (`latest` from 2026-09-26 until 3.3.0 took over on 2026-10-02; the owner moved `next` from `3.0.1` to `3.2.1` with npm 2FA on 2026-09-26) stays archived in [`V3.2.1-RELEASE-EVIDENCE-2026-09-26.md`](releases/V3.2.1-RELEASE-EVIDENCE-2026-09-26.md). The 3.2.0 chain (`latest` on 2026-09-26 until 3.2.1 took over the same day) stays archived in [`V3.2.0-RELEASE-EVIDENCE-2026-09-26.md`](releases/V3.2.0-RELEASE-EVIDENCE-2026-09-26.md). The 3.1.0 chain (`latest` on 2026-09-26 until 3.2.0 took over the same day) stays archived in [`V3.1.0-RELEASE-EVIDENCE-2026-09-26.md`](releases/V3.1.0-RELEASE-EVIDENCE-2026-09-26.md). The 3.0.1 chain (`latest` from 2026-09-09 until 3.1.0 took over on 2026-09-26) stays archived in [`V3.0.1-RELEASE-EVIDENCE-2026-09-09.md`](releases/V3.0.1-RELEASE-EVIDENCE-2026-09-09.md). The 3.0.0 chain (`latest` from 2026-09-09 until 3.0.1 took over the same day; the first version without the removed generation) stays archived in [`V3.0.0-RELEASE-EVIDENCE-2026-09-09.md`](releases/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`](releases/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`](releases/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`](releases/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`](releases/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`](releases/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`](releases/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`](releases/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`](releases/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/releases/`.
+Release evidence at source package version `@haiyangbg/buildbeat@4.2.3`; latest independently verified BuildBeat npm distribution `@haiyangbg/buildbeat@4.2.2` (dist-tags `latest` and `next`; the owner moved `next` from `4.2.0` to `4.2.2` with npm 2FA on 2026-10-07), anchored by annotated tag `v4.2.2` at commit `3a43ae3`, workflow run [37637179739](https://github.com/HaiYangBG1/BuildBeat/actions/runs/37637179739), and archived in [`V4.2.2-RELEASE-EVIDENCE-2026-10-07.md`](releases/V4.2.2-RELEASE-EVIDENCE-2026-10-07.md). The 4.2.1 chain (`latest` on 2026-10-07 until 4.2.2 took over the same day) stays archived in [`V4.2.1-RELEASE-EVIDENCE-2026-10-07.md`](releases/V4.2.1-RELEASE-EVIDENCE-2026-10-07.md). The 4.2.0 chain (`latest` on 2026-10-07 until 4.2.1 took over the same day; the owner moved `next` from `4.0.0` to `4.2.0` with npm 2FA that day) stays archived in [`V4.2.0-RELEASE-EVIDENCE-2026-10-07.md`](releases/V4.2.0-RELEASE-EVIDENCE-2026-10-07.md). The 4.1.0 chain (`latest` on 2026-10-07 until 4.2.0 took over the same day) stays archived in [`V4.1.0-RELEASE-EVIDENCE-2026-10-07.md`](releases/V4.1.0-RELEASE-EVIDENCE-2026-10-07.md). The 4.0.0 chain (`latest` from 2026-10-05 until 4.1.0 took over on 2026-10-07; the owner moved `next` from `3.3.1` to `4.0.0` with npm 2FA on 2026-10-05) stays archived in [`V4.0.0-RELEASE-EVIDENCE-2026-10-05.md`](releases/V4.0.0-RELEASE-EVIDENCE-2026-10-05.md). The 3.3.1 chain (`latest` from 2026-10-02 until 4.0.0 took over on 2026-10-05; the owner moved `next` from `3.3.0` to `3.3.1` with npm 2FA on 2026-10-02) stays archived in [`V3.3.1-RELEASE-EVIDENCE-2026-10-02.md`](releases/V3.3.1-RELEASE-EVIDENCE-2026-10-02.md). The 3.3.0 chain (`latest` on 2026-10-02 until 3.3.1 took over the same day; the owner moved `next` from `3.2.1` to `3.3.0` with npm 2FA that day) stays archived in [`V3.3.0-RELEASE-EVIDENCE-2026-10-02.md`](releases/V3.3.0-RELEASE-EVIDENCE-2026-10-02.md). The 3.2.1 chain (`latest` from 2026-09-26 until 3.3.0 took over on 2026-10-02; the owner moved `next` from `3.0.1` to `3.2.1` with npm 2FA on 2026-09-26) stays archived in [`V3.2.1-RELEASE-EVIDENCE-2026-09-26.md`](releases/V3.2.1-RELEASE-EVIDENCE-2026-09-26.md). The 3.2.0 chain (`latest` on 2026-09-26 until 3.2.1 took over the same day) stays archived in [`V3.2.0-RELEASE-EVIDENCE-2026-09-26.md`](releases/V3.2.0-RELEASE-EVIDENCE-2026-09-26.md). The 3.1.0 chain (`latest` on 2026-09-26 until 3.2.0 took over the same day) stays archived in [`V3.1.0-RELEASE-EVIDENCE-2026-09-26.md`](releases/V3.1.0-RELEASE-EVIDENCE-2026-09-26.md). The 3.0.1 chain (`latest` from 2026-09-09 until 3.1.0 took over on 2026-09-26) stays archived in [`V3.0.1-RELEASE-EVIDENCE-2026-09-09.md`](releases/V3.0.1-RELEASE-EVIDENCE-2026-09-09.md). The 3.0.0 chain (`latest` from 2026-09-09 until 3.0.1 took over the same day; the first version without the removed generation) stays archived in [`V3.0.0-RELEASE-EVIDENCE-2026-09-09.md`](releases/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`](releases/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`](releases/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`](releases/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`](releases/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`](releases/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`](releases/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`](releases/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`](releases/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/releases/`.
 
 ## Channels and branches
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haiyangbg/buildbeat",
-  "version": "4.2.1",
+  "version": "4.2.3",
   "description": "BuildBeat: Git-based AI delivery across models, tools, sessions, and people, with context in project files, build-test-review-fix loops, and human decisions.",
   "type": "module",
   "bin": {