@haiyangbg/buildbeat 0.0.0 → 1.20.0

package/README.en.md

@@ -0,0 +1,288 @@
+# BuildBeat
+
+[简体中文](README.md) | **English**
+
+**Keep humans and AI sessions aligned around the same delivery facts.**
+
+BuildBeat (formerly Solobaton) is a **file-first, human-gated engineering-delivery protocol and scaffold** for humans and AI sessions. Its Git-based file bus, human Gates, and verifiable evidence keep long-running work synchronized, controlled, and auditable across repositories and AI contexts. It does not create agents, manage models, model team roles, or provide an agent runtime.
+
+> **Information moves through files, not through a human messenger. Done requires evidence. Humans approve specification, design, merge, and release.**
+
+Requirements, boards, contracts, decisions, status, and verification evidence live in Git-managed files. A session can be closed or replaced without taking the project's working context with it.
+
+BuildBeat began with one person coordinating four AI sessions across a complex, multi-iteration product. That is its origin, not an audience limit. One Builder can use it, or several Builders can share one Git project and close separate requirement/work packages end to end.
+
+> **Language note:** `SKILL.md`, the scaffold templates, and script output are currently Chinese-first. The delivery protocol is language-independent, and a project can translate its generated scaffold during bootstrap.
+
+## The problem it solves
+
+When several AI coding sessions work on one project, code generation is rarely the hardest part. Delivery state is:
+
+- Session A keeps working against an old interface after session B changed it.
+- The builder copy-pastes context between sessions and becomes the message bus.
+- An agent says “done” without a test, commit, or live evidence.
+- A session hands work back after one document or commit and waits to be told “continue.”
+- Every reversible draft choice interrupts the builder until real stage Gates disappear in confirmation noise.
+- Current progress, production version, and decisions are copied into several documents and begin to contradict one another.
+
+BuildBeat reduces those problems to four pillars:
+
+1. **End-to-end work packages:** one Builder owns product judgment, implementation, testing, merge, and release evidence for a requirement/feature package. Product, Fullstack, and Testing are optional AI perspectives, not mandatory human-role handoffs.
+2. **File bus:** `NOW → board → contracts → status`; handoffs do not depend on chat memory.
+3. **Human at the Gate:** specification, design, merge, and release cannot be crossed automatically.
+4. **Evidence-based done:** completion requires a commit hash and verifiable evidence. No evidence means not done.
+
+## Start in five minutes
+
+### Recommended: guided bootstrap
+
+Keep this repository at any stable local path, or place it in a local skill directory currently supported by your AI coding tool. Ask the session to read [`SKILL.md`](SKILL.md), then say:
+
+> Use BuildBeat to scaffold collaboration for my project.
+
+It inspects the code and configuration first, identifying repositories, deploy units, UI surfaces, and contract boundaries. It asks only three or four simple questions that cannot be answered from the project, shows one confirmation screen, then generates a scaffold filled with project facts and runs its self-check.
+
+> Do not apply the new-project template directly to a large existing codebase. Use the **brownfield takeover ritual** in `SKILL.md` §8.5: survey the system, draw the old/new boundary, establish minimum verification, and use the compact `pm/scripts/` layout so BuildBeat does not collide with the project's own `scripts/` directory.
+
+### Claude Code plugin: BuildBeat repository
+
+This repository contains a standalone Claude Code marketplace package. Once installed, `/buildbeat:buildbeat` routes to the same canonical [`SKILL.md`](SKILL.md). It can be installed from a local checkout in isolation:
+
+```text
+/plugin marketplace add /absolute/path/to/BuildBeat
+/plugin install buildbeat@buildbeat-plugins
+/buildbeat:buildbeat
+```
+
+For GitHub installation, use `/plugin marketplace add HaiYangBG1/BuildBeat`. The plugin carries the Skill, templates, example, and reference documentation without exposing the npm CLI's top-level `bin/` to Claude Code. Project writes remain bounded by the CLI version, its confirmation screen, and human Gates. See [`plugins/buildbeat/README.md`](plugins/buildbeat/README.md) for the packaging boundary.
+
+### CLI: the scoped BuildBeat package carries the bounded lifecycle
+
+The canonical npm distribution ID is `@haiyangbg/buildbeat`; the unscoped `buildbeat` name is owned by another project and is not claimed here. Read the exact `@latest` version back from the official registry before use; for reproducibility, substitute that recorded version in later commands:
+
+```bash
+npm view @haiyangbg/buildbeat@latest version
+npx --yes --package=@haiyangbg/buildbeat@latest buildbeat doctor /path/to/project
+npx --yes --package=@haiyangbg/buildbeat@latest buildbeat init /path/to/project --dry-run
+npx --yes --package=@haiyangbg/buildbeat@latest buildbeat adopt /path/to/project --dry-run --json
+npx --yes --package=@haiyangbg/buildbeat@latest buildbeat upgrade /path/to/project --dry-run --json
+```
+
+For regular use, manage an explicit global CLI installation:
+
+```bash
+npm install --global @haiyangbg/buildbeat@latest
+buildbeat doctor /path/to/project
+npm install --global @haiyangbg/buildbeat@latest  # update the CLI package
+npm uninstall --global @haiyangbg/buildbeat       # remove only the global CLI package
+```
+
+Package-manager install, update, and removal operations manage only the **CLI package and executables**; they never create, upgrade, or delete a project's scaffold. `doctor` is read-only. `init/adopt` show the complete plan and write only after clean-Git, collision, blocker, and confirmation checks. `upgrade` accepts only a canonical schema 2 baseline and performs manifest/hash-based mechanical changes with zero writes on unresolved conflict. `diff/uninstall` and workflow-command expansion remain frozen. `buildbeat` is canonical; the `solobaton` executable remains only as a compatibility alias. See [`docs/CLI.md`](docs/CLI.md) for the complete contract.
+
+`1.20.0` is the merged Phase 0–3 version: bounded Wave 1 `init/adopt` writes, schema-2-only `upgrade`, stronger Gate/evidence joins, multi-repository drift, and scan-boundary reporting. `--force` still cannot overwrite project-owned content or unsafe paths, and a major transition separately requires `--major`. A source checkout, Git tag, and npm artifact remain different evidence surfaces; use [`docs/RELEASING.md`](docs/RELEASING.md) plus the matching GitHub Release and registry readback for release and pilot status.
+
+Copied v1.16 legacy projects must not hand-author, copy, or rename a manifest to fabricate schema 2 ownership. Continue with manual CHANGELOG-based maintenance by default; if mechanical upgrades are genuinely required, use the [v1.16 legacy migration guide](docs/LEGACY-V1.16-MIGRATION.md) to rebuild the baseline under review on a dedicated Git branch.
+
+The old `solobaton@latest` package stays on the legacy read-only v0 capability and points users to this scoped package; it does not gain project writes or upgrades. A write-enabled first-screen command must use `@haiyangbg/buildbeat`, still shows its plan first, and remains subject to Git, collision, ownership, and human-Gate boundaries.
+
+### Manual installation
+
+Use this path only when you already understand the templates:
+
+```bash
+git clone https://github.com/HaiYangBG1/BuildBeat.git
+rsync -a --exclude '/standards/' --exclude '/pm/adr/' "BuildBeat/templates/" /path/to/new-project/
+cd /path/to/new-project
+```
+
+This default path preserves the hidden `.claude/` tree but does not generate optional `standards/` or `pm/adr/`. Those project-owned libraries still ship in the source repository. Copy and render one only when the Bootstrap confirmation explicitly enables it or a real decision meets the ADR criteria; absence is valid.
+
+You must then:
+
+1. replace every `<placeholder>` in every copied file;
+2. merge `gitignore.template` into the project's `.gitignore`;
+3. configure real test commands in `verify-status.sh`;
+4. run `bash scripts/bus-check.sh` and inspect every capability boundary;
+5. install the pre-commit guard in the meta repo and in each code sub-repo:
+
+```bash
+cp scripts/pre-commit.sh .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+Installing [`gitleaks`](https://github.com/gitleaks/gitleaks) is strongly recommended. Without it, the remaining pre-commit checks still run, but secret scanning degrades to a warning instead of a blocking gate. Git hooks are not part of ordinary Git history; install them again after a fresh clone, or explicitly configure a versioned `core.hooksPath`.
+
+## Daily operation
+
+Start by claiming one independently acceptable work package from the board; the same Builder owns it end to end. Product, Fullstack, and Testing sessions may provide parallel specialist perspectives inside that package, but they are not mandatory handoffs between human roles. With several Builders, each claims a different work package and shares final facts through Git.
+
+```text
+You are the Product perspective for the current work package. Clarify requirements, board state, and decision facts. Start.
+```
+
+```text
+You are the Fullstack perspective for the current work package. Own implementation, contracts, and the deployment candidate. Start.
+```
+
+```text
+You are the Testing perspective for the current work package. Own black-box acceptance, E2E, and evidence. Verify the current candidate.
+```
+
+At the start of every session, synchronize the repository and run the guardrail:
+
+```bash
+git pull
+bash scripts/bus-check.sh
+```
+
+Synchronize every sub-repo separately in a multi-repo project. Run `bus-check.sh` again before changing a contract, running a migration, deploying, or taking another irreversible action.
+
+Common commands:
+
+```bash
+bash scripts/bus-check.sh --format=json  # emits schema 1 JSON without hiding warnings or unverified scope
+bash scripts/bus-check.sh --strict       # exits non-zero on any conflict/error finding
+bash scripts/verify-status.sh --run       # runs configured project suites and records the latest green result
+bash scripts/design-preview.sh 1          # opens the real clickable prototype before Gate 2 for UI work
+```
+
+## Core mechanisms
+
+- **Work packages:** keep moving toward one independently acceptable user outcome instead of handing back after one file, commit, or reviewer result.
+- **Three approval levels:** `STOP_NOW` for authorization, frozen semantics, and irreversible actions; `BATCH_AT_GATE` for reversible choices; `NO_APPROVAL` for derived in-scope work.
+- **Three tracks:** fast, standard, and heavy tracks select process weight by risk rather than applying every ceremony to every change.
+- **Single sources of truth:** `NOW.md` stays a thin pointer, while contracts, decisions, status, and live queries each have one authoritative entry point.
+- **Review-ready gate:** launch one independent milestone reviewer only after the candidate is stable, worktrees are clean, L3 evidence is green, and there are no known pending fixes.
+- **Machine guardrails:** `bus-check --strict`, pre-commit, gitleaks, and project tests turn deterministic rules into executable checks.
+- **Multi-repository drift:** a multi-repo project explicitly joins each sub-repository CHANGELOG, contract-version source, and local deployment-baseline app at the contract entry point. Definite mismatches block; missing repositories or sources stay unverified instead of being inferred from prose.
+- **Optional standards and ADRs:** STACK/CODE/REVIEW/DESIGN are not generated by default. When present, their declarations, Rule IDs, and Draft/Confirmed state are checked. A Confirmed STACK also gets a read-only comparison between its explicit baseline and observed Node, lockfile, and Docker FROM facts; incomplete scope stays unverified. Only durable, hard-to-reverse decisions need ADRs, whose Status and Superseded chain are validated.
+- **Production-state evidence:** after a project supplies `live-status.sh` and `live-config.sh`, BuildBeat can compare deployment-platform configuration with a baseline. It does not automatically prove that a running container loaded the latest configuration.
+- **Brownfield takeover:** establish system boundaries and minimum verification before applying the full bus to new territory; do not rewrite unknown legacy behavior.
+
+The complete rules, bootstrap, and takeover procedure live in [`SKILL.md`](SKILL.md). Real failure modes and their design rationale live in [`lessons.md`](lessons.md).
+
+## Operating model
+
+```mermaid
+flowchart LR
+    Views["AI specialist perspectives<br/>Product · Fullstack · Testing"] --> WPA["Builder / work package A<br/>judgment → implementation → test → merge/release evidence"]
+    Views --> WPB["Builder / work package B<br/>judgment → implementation → test → merge/release evidence"]
+    Human["Human Gates<br/>specification · design · merge · release"] --> WPA
+    Human --> WPB
+    WPA --> Bus["Git file bus<br/>NOW · contracts · decisions · status · evidence"]
+    WPB --> Bus
+```
+
+Each work package closes vertically instead of becoming a Product→Engineering→Testing human-role pipeline. Humans do not relay context between sessions; they make judgments that cannot be delegated, while ordinary facts, archiving, status updates, and reversible implementation inside an approved boundary continue autonomously.
+
+## Applicability
+
+Recommended for projects that:
+
+- have at least two repositories or deploy units;
+- will evolve for several weeks or longer;
+- have one or more Builders coordinating multiple AI contexts and closing separate work packages end to end;
+- need stable handoffs between several AI coding sessions;
+- value verifiable delivery records without introducing a complex agent runtime.
+
+Not recommended for:
+
+- small single-repo changes;
+- one-off scripts;
+- work expected to finish within a week;
+- projects with no verification capability and no intent to establish a minimum test suite first.
+
+Known boundaries: the human remains the final decision-maker. The protocol raises confidence that an agreed goal was delivered correctly; it does not guarantee that the product direction was correct. Automatic rule loading and skill directories also differ between AI coding tools, so compatibility claims should follow each tool's current documentation and real tests.
+
+Current non-goals: multi-user accounts, roles and permissions, or an organization administration surface; telemetry collection, team-performance scoring, or a metrics dashboard. The BuildBeat CLI does not collect or upload project usage data. These are not unfinished maintenance items. Any future proposal needs a separate product milestone with explicit requirements, data definitions, privacy/authorization governance, and an acceptance Gate.
+
+## Installed project layout
+
+```text
+<project-root>/
+├── AGENTS.md                       # session routing, bus rules, and red lines
+├── CLAUDE.md                       # compatibility pointer; never duplicates the rules
+├── ARCHITECTURE.md                 # system facts and sub-project index
+├── contracts/PROTOCOL.md           # cross-boundary contract entry point
+├── pm/
+│   ├── NOW.md                      # thin pointer to the current iteration
+│   ├── <iteration>-board.md
+│   ├── decisions.md
+│   ├── status/
+│   ├── changes/
+│   ├── adr/                         # optional durable technical decisions and supersession links
+│   └── archive/<iteration>/evidence/
+├── standards/                      # optional STACK/CODE/REVIEW; DESIGN for UI projects
+├── scripts/
+│   ├── bus-check.sh
+│   ├── verify-status.sh
+│   ├── drift-check.sh
+│   ├── design-preview.sh
+│   └── pre-commit.sh
+├── .claude/agents/reviewer.md      # read-only milestone / risk-delta / closure review
+├── 指挥台.md                        # one-page operator card
+└── BUILDBEAT.md                    # installed BuildBeat version and upgrade record
+```
+
+The compact brownfield layout moves the scripts, operator card, and version marker into `pm/`. Optional `standards/` and `pm/adr/` are not part of the default scaffold. See `SKILL.md` §3/§8 for the complete rules.
+
+## Capabilities and dependencies
+
+| Capability | Dependency | When missing |
+|---|---|---|
+| File bus and basic checks | Git, Bash | The core workflow cannot run |
+| Real-render design preview | Python 3 | The bundled preview script cannot run |
+| Blocking secret scan | gitleaks | Degrades to a warning; do not claim a secret gate exists |
+| Production-config drift | `jq`, a SHA tool, project `live-config.sh` | Explicitly skipped; no production-state conclusion |
+| Live-version query | project `live-status.sh` and platform CLI | Explicitly unconfigured; documentation is not treated as live truth |
+| L3 test evidence | real `SUITES` in project `verify-status.sh` | Reports unconfigured; cannot claim automation is green |
+| CLI inspection/scaffolding/mechanical upgrade | Node.js 20+, the npm registry, or this source checkout | Legacy npm v0 remains read-only; scoped BuildBeat 1.20 has completed a genuine schema 2 version-increment pilot, while registry-artifact availability still requires independent readback; project uninstall remains frozen, and the Skill/manual equivalent stays supported |
+
+Skill-only, legacy npm v0, and scoped BuildBeat 1.20 are distinct availability surfaces; the source checkout, registry artifact, and real project must also be verified separately. `doctor`, `init/adopt`, and `upgrade` own different responsibilities. See the bilingual [BuildBeat capability matrix](docs/CAPABILITY-MATRIX.md) and the [v1.20 real-project pilot](docs/PHASE4-V1.20-PILOT-2026-08-25.md).
+
+## Continue reading
+
+- [`SKILL.md`](SKILL.md): the single complete entry point for the methodology and bootstrap;
+- [`example/`](example/): the protocol teaching snapshot of a fictional project after one completed iteration (executable scripts still reference the template SSOT);
+- [`lessons.md`](lessons.md): real anti-patterns, root causes, and fixes;
+- [`docs/ROADMAP.md`](docs/ROADMAP.md): the new product direction, design principles, and the CLI execution amendment effective on 2026-08-24;
+- [`docs/EXECUTION-PLAN.md`](docs/EXECUTION-PLAN.md): the current phased work packages, dependencies, acceptance criteria, and frozen boundaries;
+- [`docs/CLI-STRATEGY-2026-08.md`](docs/CLI-STRATEGY-2026-08.md): the official-source CLI comparison and its evidence limits;
+- [`docs/CHECKS.md`](docs/CHECKS.md): file-bus invariants, Gate/evidence tokens, finding codes, and strict-mode semantics;
+- [`docs/CLI.md`](docs/CLI.md): command boundaries, file ownership, manifest, mechanical upgrade, and manual-removal contract;
+- [`docs/CAPABILITY-MATRIX.md`](docs/CAPABILITY-MATRIX.md): bilingual capability and interoperability mapping across Skill-only, legacy npm v0, and scoped BuildBeat 1.20;
+- [`docs/LEGACY-V1.16-MIGRATION.md`](docs/LEGACY-V1.16-MIGRATION.md): safe paths for a copied v1.16 project to remain manually managed or rebuild a schema 2 baseline under review (Chinese);
+- [`docs/CLI-PILOT-2026-08-23.md`](docs/CLI-PILOT-2026-08-23.md): read-only CLI v0 evidence from three real brownfield projects and the write-boundary decision;
+- [`docs/PHASE1-PILOT-2026-08-24.md`](docs/PHASE1-PILOT-2026-08-24.md): the read-only Phase 1 file-bus pilot across the example, an active multi-repo projection, and a real single-repo code tree;
+- [`docs/PHASE2-PILOT-2026-08-25.md`](docs/PHASE2-PILOT-2026-08-25.md): the three real-directory Wave 1 write paths, Tide preservation hashes, UI-detection feedback, and final local Git/hook/hash evidence;
+- [`docs/PHASE2-BUILDBEAT-PILOT-2026-08-25.md`](docs/PHASE2-BUILDBEAT-PILOT-2026-08-25.md): the fresh BuildBeat canonical namespace regression, Tide preservation recheck, and Gate3 closure evidence;
+- [`docs/PHASE4-V1.20-PILOT-2026-08-25.md`](docs/PHASE4-V1.20-PILOT-2026-08-25.md): the genuine schema 2 version-increment upgrade, project-ownership preservation, and read-only real multi-repository refresh;
+- [`docs/PHASE4-STABILITY-AUDIT-2026-08-25.md`](docs/PHASE4-STABILITY-AUDIT-2026-08-25.md): the status, evidence boundary, and still-open release blocker for all 12 roadmap §15 hard gates (Chinese);
+- [`docs/RELEASING.md`](docs/RELEASING.md): npm release Gates, verification, and the Trusted Publishing migration;
+- [`CONTRIBUTING.md`](CONTRIBUTING.md): contribution, verification, and pull-request boundaries;
+- [`SECURITY.md`](SECURITY.md): supported versions and the private vulnerability-reporting channel;
+- [`CHANGELOG.md`](CHANGELOG.md): version history and upgrade instructions for copied projects.
+
+## Contributing
+
+Issues and pull requests are welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the complete submission rules. Do not open a public issue for an undisclosed vulnerability; report it privately through [`SECURITY.md`](SECURITY.md). A change to workflow semantics should update `SKILL.md`, affected templates, both READMEs, the example, and the changelog. Explain:
+
+1. which real failure mode the change addresses;
+2. how to reproduce it;
+3. which automated checks show that it did not regress existing behavior.
+
+Run at least:
+
+```bash
+bash -n templates/scripts/*.sh tests/*.sh
+npm test
+npm run test:scripts
+npm run test:skill-only
+npm run check:docs
+npm run pack:check
+git diff --check
+```
+
+## License
+
+[MIT](LICENSE) © 2026 HaiYangBG

package/README.md

@@ -1,7 +1,286 @@
-# BuildBeat registry bootstrap
+# BuildBeat
 
-This `0.0.0` artifact exists only to establish the public `@haiyangbg/buildbeat` package before binding npm Trusted Publishing.
+**简体中文** | [English](README.en.md)
 
-It is not a BuildBeat release, does not expose a CLI, and is intentionally published under the non-default `bootstrap` dist-tag. Use only a version independently verified under the `latest` tag.
+**让人和 AI 会话围绕同一组项目事实完成交付。**
 
-Canonical repository: https://github.com/HaiYangBG1/BuildBeat
+BuildBeat（旧称 Solobaton）是一套面向人和 AI 会话的、**file-first、human-gated 工程交付协议与脚手架**。它通过 Git 中的文件总线、人工 Gate 和可验证证据，让项目在长期迭代、多个仓库和多个 AI 上下文之间保持同步、可控、可核验。它不负责创建 Agent、管理模型、建模团队岗位或提供运行时编排。
+
+> **信息走文件，不走人嘴。完成必须有证据。规格、设计、合并和上线由人拍板。**
+
+需求、看板、契约、决策、状态和验证证据都落在 Git 管理的文件中。会话可以关闭或替换，项目上下文不会跟着聊天窗口消失。
+
+BuildBeat 最初蒸馏自一个人指挥 4 个 AI 会话、持续多期交付复杂产品的实践；这说明了方法的来源，不限定使用人数。一个 Builder 可以使用，多个 Builder 也可以共享同一 Git 项目并按需求/工作包分别闭环。
+
+## 解决什么问题
+
+当一个项目同时打开多个 AI Coding 会话，最容易失控的不是代码生成，而是交付状态：
+
+- A 会话不知道 B 已经改了接口，继续基于旧上下文工作；
+- 人在会话之间复制粘贴，自己变成消息总线；
+- Agent 声称“完成”，却没有测试、commit 或线上证据；
+- 一个子文档或 commit 完成后，会话过早停下等人说“继续”；
+- 草案中的每个小选择都打断人，真正的阶段 Gate 被确认噪音淹没；
+- 当前进度、线上版本和决策被重复写进多个文档，逐渐互相矛盾。
+
+BuildBeat 把这些问题收敛成四个支柱：
+
+1. **端到端工作包**：一个 Builder 对一个需求/功能工作包的产品判断、实现、测试、合并与发布证据负责；产品、全栈、测试是可调用的 AI 专业视角，不是人类岗位接力。
+2. **文件总线**：`NOW → 看板 → contracts → status`，交接不依赖聊天记忆。
+3. **人在 Gate**：规格、设计、合并、上线四个关键决策不允许自动跨过。
+4. **证据制完成**：完成必须带 commit hash 和可核验证据；无证据，不算完成。
+
+## 5 分钟开始
+
+### 推荐：引导式 Bootstrap
+
+把本仓库放到本机任意稳定位置，或放进 AI Coding 工具当前支持的本地 skill 目录。然后让会话读取 [`SKILL.md`](SKILL.md)，并说：
+
+> 用 BuildBeat 给我的项目搭协作骨架。
+
+它会先自己检查代码和配置，识别仓库数量、部署单元、UI 和契约边界；只问 3–4 个无法从项目中查到的简单问题；给出一屏确认后，再生成已经填好项目事实的骨架并运行自检。
+
+> 已经存在大量代码的项目不要直接套新项目模板。使用 `SKILL.md` §8.5 的**存量接管仪式**：先摸底、划新旧边界、补最小验证能力，再采用 `pm/scripts/` 紧凑布局，避免撞上原项目自己的 `scripts/`。
+
+### Claude Code 插件：BuildBeat 仓库
+
+本仓提供独立的 Claude Code marketplace 包，安装后以 `/buildbeat:buildbeat` 路由同一份 canonical [`SKILL.md`](SKILL.md)。可从本地 checkout 隔离安装：
+
+```text
+/plugin marketplace add /absolute/path/to/BuildBeat
+/plugin install buildbeat@buildbeat-plugins
+/buildbeat:buildbeat
+```
+
+从 GitHub 安装时使用 `/plugin marketplace add HaiYangBG1/BuildBeat`。插件只携带 Skill、模板、示例和参考文档，不把 npm CLI 的顶层 `bin/` 暴露进 Claude Code；是否对项目执行写入仍受 CLI 版本、确认屏和人工 Gate 约束。完整打包边界见 [`plugins/buildbeat/README.md`](plugins/buildbeat/README.md)。
+
+### CLI：scoped BuildBeat 包承载完整有界生命周期
+
+canonical npm 分发标识是 `@haiyangbg/buildbeat`；未加 scope 的 `buildbeat` 已被其他项目占用，本仓不会冒用。使用前先从官方 registry 回读 `@latest` 的精确版本；需要复现时，把后续命令中的 `@latest` 换成已记录版本：
+
+```bash
+npm view @haiyangbg/buildbeat@latest version
+npx --yes --package=@haiyangbg/buildbeat@latest buildbeat doctor /path/to/project
+npx --yes --package=@haiyangbg/buildbeat@latest buildbeat init /path/to/project --dry-run
+npx --yes --package=@haiyangbg/buildbeat@latest buildbeat adopt /path/to/project --dry-run --json
+npx --yes --package=@haiyangbg/buildbeat@latest buildbeat upgrade /path/to/project --dry-run --json
+```
+
+需要长期使用时，可以显式管理全局 CLI：
+
+```bash
+npm install --global @haiyangbg/buildbeat@latest
+buildbeat doctor /path/to/project
+npm install --global @haiyangbg/buildbeat@latest  # 更新 CLI 包
+npm uninstall --global @haiyangbg/buildbeat       # 只移除全局 CLI 包
+```
+
+包管理器的安装、更新、移除只管理 **CLI 包和可执行文件**，不会创建、升级或删除项目里的协作骨架。`doctor` 只读检查；`init/adopt` 必须先看完整计划，并在无 blocker、干净 Git 和明确确认后才写入；`upgrade` 只接受 canonical schema 2 基线，按 manifest/hash 做机械升级，冲突时零写。`diff/uninstall` 与工作流命令扩张继续冻结。canonical 命令是 `buildbeat`；`solobaton` executable 只保留兼容别名。完整契约见 [`docs/CLI.md`](docs/CLI.md)。
+
+`1.20.0` 是 Phase 0–3 的合并版本：包含 Wave 1 `init/adopt` 受控写入、schema-2-only `upgrade`、Gate/证据强关联、多仓漂移与扫描边界报告。`--force` 也永不覆盖 project-owned 内容或不安全路径；跨 major 另需 `--major`。源码 checkout、Git tag 和 npm artifact 仍是不同证据面，发布状态与真实试点边界必须以 [`docs/RELEASING.md`](docs/RELEASING.md) 和对应 GitHub Release/registry 回读为准。
+
+已拷出的 v1.16 legacy 项目不得手写、复制或重命名 manifest 来伪造 schema 2 所有权。默认继续按 CHANGELOG 手工维护；如果确需进入机械升级，按 [v1.16 legacy 迁移指南](docs/LEGACY-V1.16-MIGRATION.md) 在专用 Git 分支受控重建基线。
+
+旧 `solobaton@latest` 固定在 legacy v0 只读能力，并迁移提示到本 scoped package；它不会获得新的项目写入或升级能力。写入式首屏命令必须使用 `@haiyangbg/buildbeat`，并且仍先展示计划、受 Git/碰撞/所有权检查约束，不能跨人工 Gate。
+
+### 手动安装
+
+只建议在你已经理解模板含义时使用：
+
+```bash
+git clone https://github.com/HaiYangBG1/BuildBeat.git
+rsync -a --exclude '/standards/' --exclude '/pm/adr/' "BuildBeat/templates/" /path/to/new-project/
+cd /path/to/new-project
+```
+
+上面的默认路径保留隐藏 `.claude/`，但不生成可选的 `standards/` 与 `pm/adr/`。它们仍作为 project-owned 模板随源仓提供：只有在 Bootstrap 一屏确认中明确启用相应规范，或真实决定命中 ADR 判据时，才单独复制并按项目事实填写；缺失是合法状态。
+
+接着必须：
+
+1. 逐文件替换所有 `<占位符>`；
+2. 将 `gitignore.template` 的规则合并进项目 `.gitignore`；
+3. 为 `verify-status.sh` 配置真实测试命令；
+4. 运行 `bash scripts/bus-check.sh`，确认骨架指针和能力边界；
+5. 在 meta 仓和每个代码子仓分别安装 pre-commit 护栏：
+
+```bash
+cp scripts/pre-commit.sh .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+强烈建议同时安装 [`gitleaks`](https://github.com/gitleaks/gitleaks)。未安装时，pre-commit 仍会运行其它检查，但 Secret 扫描会降级成警告而不是阻断。Git hooks 不进入普通 Git 历史，新 clone 后需要重新安装，或显式配置版本化的 `core.hooksPath`。
+
+## 日常怎么运行
+
+先从看板认领一个可独立验收的工作包；同一个 Builder 对它端到端负责。需要并行专业视角时，可以打开产品、全栈、测试会话，但它们是该工作包内的 AI 视角，不是三个人类岗位的强制交接。多个 Builder 协作时，各自认领不同工作包并通过 Git 共享最终事实。
+
+```text
+你是当前工作包的产品视角，负责澄清需求、看板和决策事实。开工。
+```
+
+```text
+你是当前工作包的全栈视角，负责实现、契约和部署候选。开工。
+```
+
+```text
+你是当前工作包的测试视角，负责黑盒验收、E2E 和证据。验收当前候选。
+```
+
+每个会话开工先同步代码，再运行护栏：
+
+```bash
+git pull
+bash scripts/bus-check.sh
+```
+
+多仓项目要在各子仓分别同步。修改契约、执行 migration、部署等不可逆动作前，再运行一次 `bus-check.sh`。
+
+常用命令：
+
+```bash
+bash scripts/bus-check.sh --format=json  # 输出 schema 1 JSON；warning/unverified 不会被吞掉
+bash scripts/bus-check.sh --strict       # 任一 conflict/error finding 会非零退出
+bash scripts/verify-status.sh --run       # 跑项目配置的真实测试套件并记录最近全绿
+bash scripts/design-preview.sh 1          # 有 UI 时，Gate2 前打开真实可点原型
+```
+
+## 核心机制
+
+- **工作包**：按一个可验收的用户级结果持续推进，不因单个文件、commit 或 reviewer 返回而提前结束。
+- **三级审批**：`STOP_NOW` 处理越权、冻结语义和不可逆动作；`BATCH_AT_GATE` 集中可逆取舍；`NO_APPROVAL` 自主完成派生工作。
+- **三轨制**：快轨、标准轨、重轨按风险选择流程重量，小事不上全套仪式。
+- **单点事实**：`NOW.md` 只做薄指针，契约、决策、状态和线上查询各有唯一入口。
+- **review-ready 核查门**：候选稳定、工作树干净、L3 证据已绿且没有已知待修项后，才启动一次独立 milestone reviewer。
+- **机器护栏**：`bus-check --strict`、pre-commit、gitleaks 和项目测试把确定性规则变成可执行检查。
+- **多仓漂移**：多仓项目在契约入口显式绑定各子仓 CHANGELOG、契约版本来源和本地部署基线 app；确定不一致才阻塞，缺仓或缺来源保持 unverified，不猜自然语言。
+- **可选规范与 ADR**：STACK/CODE/REVIEW/DESIGN 默认不生成；存在时检查三行声明、Rule ID 和 Draft/Confirmed 状态。Confirmed STACK 还只读比对显式基线与 Node、lockfile、Docker FROM 事实，无法覆盖时保持 unverified。长期难回退决定才建 ADR，并校验 Status 与 Superseded 链。
+- **生产状态证据**：项目接入 `live-status.sh` / `live-config.sh` 后，可检查部署平台配置与基线的漂移；它不自动证明运行中容器已经加载最新配置。
+- **存量接管**：先建立系统边界和最小验证能力，再把新地盘纳入完整总线，避免直接重写未知遗留行为。
+
+完整规则、Bootstrap 和接管流程见 [`SKILL.md`](SKILL.md)；真实失败模式和设计理由见 [`lessons.md`](lessons.md)。
+
+## 运转模型
+
+```mermaid
+flowchart LR
+    Views["AI 专业视角<br/>产品 · 全栈 · 测试"] --> WPA["Builder / 工作包 A<br/>判断 → 实现 → 测试 → 合并/发布证据"]
+    Views --> WPB["Builder / 工作包 B<br/>判断 → 实现 → 测试 → 合并/发布证据"]
+    Human["人工 Gate<br/>规格 · 设计 · 合并 · 上线"] --> WPA
+    Human --> WPB
+    WPA --> Bus["Git 文件总线<br/>NOW · 契约 · 决策 · 状态 · 证据"]
+    WPB --> Bus
+```
+
+每个工作包都纵向闭环，不按人类职能切成产品→研发→测试流水线。人不负责在会话之间搬运上下文，只负责不能委托的判断；普通事实、归档、状态回写和已授权范围内的可逆实现继续自动推进。
+
+## 适用边界
+
+推荐用于：
+
+- 至少 2 个仓库或部署单元；
+- 会持续迭代数周或更久；
+- 一个或多个 Builder 需要分别驾驭多个 AI 上下文，并按工作包端到端闭环；
+- 多个 AI Coding 会话需要稳定交接；
+- 项目重视可核验记录，但不希望引入复杂 Agent Runtime。
+
+不建议用于：
+
+- 单仓小任务；
+- 一次性脚本；
+- 一周内即可收尾的工作；
+- 没有验证能力、又不准备先补最小测试的项目。
+
+已知边界：人仍是最终决策者；流程提高“按已定目标正确交付”的可信度，不保证产品方向本身正确。自动加载规则和 skill 目录也因 AI Coding 工具而异，正式宣称兼容前应以对应工具的当前文档和实测为准。
+
+当前非目标：多人账号、角色/权限和组织管理后台；遥测采集、团队效能评分或指标仪表盘。BuildBeat CLI 不采集或上传项目使用数据。这些不是未完成的维护项；若未来立项，必须单独定义需求、数据口径、隐私/权限治理和验收 Gate。
+
+## 安装后的项目结构
+
+```text
+<项目根>/
+├── AGENTS.md                       # 会话路由、总线规则和红线
+├── CLAUDE.md                       # 兼容指针，不复制规则正文
+├── ARCHITECTURE.md                 # 系统事实和子项目索引
+├── contracts/PROTOCOL.md           # 跨边界契约入口
+├── pm/
+│   ├── NOW.md                      # 当前期薄指针
+│   ├── <期>-看板.md
+│   ├── decisions.md
+│   ├── status/
+│   ├── changes/
+│   ├── adr/                         # 可选；长期技术决定与替代链
+│   └── archive/<期>/evidence/
+├── standards/                      # 可选；STACK/CODE/REVIEW，UI 项目可加 DESIGN
+├── scripts/
+│   ├── bus-check.sh
+│   ├── verify-status.sh
+│   ├── drift-check.sh
+│   ├── design-preview.sh
+│   └── pre-commit.sh
+├── .claude/agents/reviewer.md      # 只读 milestone / risk-delta / closure 核查
+├── 指挥台.md                        # 给人的一页操作卡
+└── BUILDBEAT.md                    # 所用 BuildBeat 版本与升级记录
+```
+
+存量项目的紧凑布局会把脚本、指挥台和版本标记放进 `pm/`。`standards/` 与 `pm/adr/` 两个可选目录不属于默认骨架；具体规则见 `SKILL.md` §3/§8。
+
+## 能力与依赖
+
+| 能力 | 依赖 | 缺失时 |
+|---|---|---|
+| 文件总线和基础检查 | Git、Bash | 无法使用核心流程 |
+| 真渲染设计预览 | Python 3 | 不能使用自带预览脚本 |
+| Secret 提交阻断 | gitleaks | 降级为警告，不能声称 Secret gate 已建立 |
+| 生产配置漂移 | `jq`、SHA 工具、项目 `live-config.sh` | 明确跳过，不能外推生产状态 |
+| 线上版本查询 | 项目 `live-status.sh` 和平台 CLI | 明确未配置，不引用文档版本冒充线上事实 |
+| L3 测试证据 | 项目填写 `verify-status.sh` 的 `SUITES` | 只能报告未配置，不能声称自动化测试已绿 |
+| CLI 检查/脚手架/机械升级 | Node.js 20+、npm registry 或本仓库源码 | legacy npm v0 仍只读；scoped BuildBeat 1.20 已完成真实 schema 2 版本增量试点，registry artifact 是否可用仍须独立回读；项目 uninstall 继续冻结，Skill/手动等价路径始终保留 |
+
+Skill-only、legacy npm v0 和 scoped BuildBeat 1.20 是三个不同可用面；源码 checkout、registry artifact 与真实项目也必须分别核验。`doctor`、`init/adopt`、`upgrade` 不承担相同责任。完整对照见 [BuildBeat 能力矩阵](docs/CAPABILITY-MATRIX.md)，真实版本增量证据见 [v1.20 试点记录](docs/PHASE4-V1.20-PILOT-2026-08-25.md)。
+
+## 继续阅读
+
+- [`SKILL.md`](SKILL.md)：方法论与 Bootstrap 的唯一完整入口；
+- [`example/`](example/)：虚构「简账」项目一期收尾的协议教学快照（可执行脚本仍引用模板 SSOT）；
+- [`lessons.md`](lessons.md)：真实反模式、根因与解法；
+- [`docs/ROADMAP.md`](docs/ROADMAP.md)：新版产品方向、设计原则与 2026-08-24 生效的 CLI 执行修订；
+- [`docs/EXECUTION-PLAN.md`](docs/EXECUTION-PLAN.md)：当前分阶段工作包、依赖、验收和冻结边界；
+- [`docs/CLI-STRATEGY-2026-08.md`](docs/CLI-STRATEGY-2026-08.md)：基于官方来源的 CLI 策略对照与证据边界；
+- [`docs/CHECKS.md`](docs/CHECKS.md)：文件总线不变量、Gate/证据令牌、finding code 与严格模式规格；
+- [`docs/CLI.md`](docs/CLI.md)：CLI 命令边界、文件所有权、manifest、机械升级和手动移除合同；
+- [`docs/CAPABILITY-MATRIX.md`](docs/CAPABILITY-MATRIX.md)：Skill-only、legacy npm v0 与 scoped BuildBeat 1.20 的双语能力/互操作对照；
+- [`docs/LEGACY-V1.16-MIGRATION.md`](docs/LEGACY-V1.16-MIGRATION.md)：v1.16 拷出项目继续手工维护或受控重建 schema 2 基线的安全路径；
+- [`docs/CLI-PILOT-2026-08-23.md`](docs/CLI-PILOT-2026-08-23.md)：三个真实存量项目的 CLI v0 只读试点与写入边界决策；
+- [`docs/PHASE1-PILOT-2026-08-24.md`](docs/PHASE1-PILOT-2026-08-24.md)：Phase 1 文件总线在 example、活跃多仓投影和真实单仓代码树上的只读试点；
+- [`docs/PHASE2-PILOT-2026-08-25.md`](docs/PHASE2-PILOT-2026-08-25.md)：Wave 1 三条真实目录写路径、Tide 保护摘要、UI 探测反馈与最终本地 Git/Hook/hash 证据；
+- [`docs/PHASE2-BUILDBEAT-PILOT-2026-08-25.md`](docs/PHASE2-BUILDBEAT-PILOT-2026-08-25.md)：BuildBeat canonical namespace 的新真实目录回归、Tide 保护复核与 Gate3 关闭证据；
+- [`docs/PHASE4-V1.20-PILOT-2026-08-25.md`](docs/PHASE4-V1.20-PILOT-2026-08-25.md)：schema 2 真实版本增量升级、项目所有权保护与真实多仓只读刷新证据；
+- [`docs/PHASE4-STABILITY-AUDIT-2026-08-25.md`](docs/PHASE4-STABILITY-AUDIT-2026-08-25.md)：演进书 §15 的 12 条硬门槛现状、证据边界与未关闭发布阻塞；
+- [`docs/RELEASING.md`](docs/RELEASING.md)：npm 发布 Gate、验证与 Trusted Publishing 迁移；
+- [`CONTRIBUTING.md`](CONTRIBUTING.md)：贡献、验证和 PR 边界；
+- [`SECURITY.md`](SECURITY.md)：支持版本与私密漏洞报告通道；
+- [`CHANGELOG.md`](CHANGELOG.md)：版本历史和拷出项目升级说明。
+
+## 贡献
+
+欢迎 Issue 和 Pull Request。完整提交规则见 [`CONTRIBUTING.md`](CONTRIBUTING.md)；未公开漏洞请勿发公开 Issue，按 [`SECURITY.md`](SECURITY.md) 私密报告。修改流程语义时，请同时更新 `SKILL.md`、相关模板、中文/英文 README、示例和 CHANGELOG，并说明：
+
+1. 解决了哪个真实失败模式；
+2. 如何复现；
+3. 哪些自动化检查证明没有回归。
+
+提交前至少运行：
+
+```bash
+bash -n templates/scripts/*.sh tests/*.sh
+npm test
+npm run test:scripts
+npm run test:skill-only
+npm run check:docs
+npm run pack:check
+git diff --check
+```
+
+## License
+
+[MIT](LICENSE) © 2026 HaiYangBG