@haiyangbg/buildbeat 2.0.2 → 3.0.0

package/docs/CLI.md

@@ -1,245 +0,0 @@
-# BuildBeat CLI lifecycle contract
-
-Status: **BuildBeat `2.0.2` scoped distribution (stable `latest`; the v1 lifecycle CLI `buildbeat` is unchanged, the v2 delivery runtime `buildbeat-v2` ships alongside it — see `docs/v2/guide/`)** · previous independently verified stable `2.0.1` · canonical package `@haiyangbg/buildbeat` · canonical executable `buildbeat` · legacy package `solobaton@1.16.3` remains the independently verified read-only v0 · Node.js 20+ · zero third-party runtime dependencies. The 1.21 release keeps the verified 1.20 lifecycle command and safety boundaries, and adds the standard domain-response contract to the Skill and managed scaffold. The genuine lifecycle version-increment pilot remains archived in [`PHASE4-V1.20-PILOT-2026-08-25.md`](PHASE4-V1.20-PILOT-2026-08-25.md); exact 1.21 registry and supply-chain evidence is archived in [`V1.21-RELEASE-EVIDENCE-2026-08-25.md`](V1.21-RELEASE-EVIDENCE-2026-08-25.md).
-
-The CLI does not replace `SKILL.md`. The Skill owns code-aware reasoning, minimal questions, project semantics, and human Gates. The CLI owns deterministic inspection, scaffold mechanics, manifest/hash bookkeeping, and bounded mechanical upgrade in the current scoped distribution. Synchronous file-bus checks remain authoritative in the project-local scripts specified by [`CHECKS.md`](CHECKS.md).
-
-This document is the contract for the **v1 lifecycle CLI `buildbeat`** only. The v2 delivery runtime `buildbeat-v2` in the same package has its own surface (below) documented in [`v2/guide/`](v2/guide/README.md). The bilingual [`CAPABILITY-MATRIX.md`](CAPABILITY-MATRIX.md) is the compact authority for what Skill-only, the legacy npm v0, the v1 lifecycle CLI, and the v2 runtime can each do. v1 command details and safety semantics remain authoritative in this document.
-
-## Two executables, two jobs
-
-| Executable | Job | Does not do |
-|---|---|---|
-| `buildbeat` | Inspect (`doctor`), scaffold (`init` / `adopt`), and mechanically upgrade (`upgrade`) the **v1 file-bus skeleton** (`pm/`, `contracts/`, `scripts/`); `version` | Does not create `delivery/work/`, run-configs, or Runs; `buildbeat doctor` does not check a v2 run-config (that is `buildbeat-v2 doctor --config`); `buildbeat upgrade` does not migrate Work state |
-| `buildbeat-v2` | Run and query the **v2 delivery loop**: `accept`, `start`, `resume`, `status`, `inbox`, `overview`, `approve`, `reject`, `findings`, `doctor`, `preflight`, `events`, `replay`, `metrics`, `stop`, `gc`, `watch`, `observe` — run `buildbeat-v2` with no arguments for the usage text | Does not scaffold the v1 file bus; never merges, pushes, deploys, or publishes (invariant 20) |
-
-A project may use either or both: pure v2 projects have no `pm/NOW.md` and never run `bus-check`; v1 projects that adopt v2 freeze the file bus read-only ([`v2/guide/08-migration-v1.md`](v2/guide/08-migration-v1.md)).
-
-## Command boundary and phased availability
-
-The canonical scoped-package commands are:
-
-```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
-npx --yes --package=@haiyangbg/buildbeat@latest buildbeat upgrade /path/to/project --dry-run
-```
-
-Record the version returned by `npm view` and substitute that exact version for `@latest` when the invocation must be reproducible. Before registry publication is independently verified, the same lifecycle can only be evaluated from a locked repository checkout via `node bin/buildbeat.js`; `node bin/solobaton.js` remains a compatibility alias. The old `solobaton@latest` package remains frozen on read-only v0 and is not the write-capable distribution.
-
-- `doctor` reads an existing project and reports installation state, layout, version marker, required files, unresolved canonical placeholders, hooks, and capability dependencies.
-- `init/adopt --dry-run` inspect a target and emit the complete default/compact plan with zero writes.
-- `init/adopt` without `--dry-run` apply only after all blockers are absent and interactive confirmation or explicit `--yes` is present.
-- `upgrade --dry-run` plans a schema-2-only mechanical version transition; apply is fail-closed on unresolved conflict.
-- `--json` returns a versioned JSON document for agents and CI.
-- `diff` and `uninstall` remain reserved and disabled. Workflow commands remain in Skill/project scripts.
-
-The locked-checkout equivalent is:
-
-```bash
-node bin/buildbeat.js init /path/to/project --dry-run --json
-node bin/buildbeat.js init /path/to/project             # plan + interactive confirmation
-node bin/buildbeat.js adopt /path/to/project --yes      # non-interactive only after plan approval
-node bin/buildbeat.js upgrade /path/to/project --dry-run --json
-node bin/buildbeat.js upgrade /path/to/project          # apply only when the complete plan is ready
-```
-
-`--yes` skips only the `init/adopt` prompt; `--dry-run --yes` is invalid. If no interactive terminal is available, an apply call without `--yes` returns `confirmation_required` and performs zero writes. `upgrade` has no `--yes`; naming the write command is the explicit apply request, and `--force`/`--major` acknowledge only their documented narrow boundaries. JSON apply keeps the machine result on stdout and prints the pre-write human plan on stderr.
-
-Wave 1 has bounded BuildBeat real-directory, Git, hook, evidence-commit, and Gate3 closure in [`PHASE2-BUILDBEAT-PILOT-2026-08-25.md`](PHASE2-BUILDBEAT-PILOT-2026-08-25.md). The `v1.16 → v1.20` schema 2 upgrade and real multi-repository refresh are archived in [`PHASE4-V1.20-PILOT-2026-08-25.md`](PHASE4-V1.20-PILOT-2026-08-25.md). None of these project tests substitute for npm artifact verification.
-
-The target command whitelist is intentionally small:
-
-| Milestone | Enabled main commands | Boundary |
-|---|---|---|
-| legacy `solobaton@1.16.3` | `doctor`, `init --dry-run`, `adopt --dry-run`, `version` | independently verified read-only v0; deprecated distribution ID after scoped migration |
-| BuildBeat `1.21.0` | `doctor`, `init`, `adopt`, `upgrade`, `version` | unchanged Phase 0–3 command set; writes remain bounded by the transaction and human-Gate contracts below |
-| BuildBeat `2.0.0` | same `buildbeat` command set; second executable `buildbeat-v2` (run / overview / inbox / status / approve / observe / gc …) | `buildbeat` lifecycle and safety boundaries unchanged; `buildbeat-v2` is the v2 runtime documented in [`v2/guide/README.md`](v2/guide/README.md) and never merges, pushes, deploys or publishes (invariant 20); the managed scaffold version stays `v1.21` (templates unchanged), so `upgrade` reports up-to-date for 1.21 scaffolds; the manifest `cliVersion` is a record, not an upgrade trigger |
-| BuildBeat `2.0.1` | same command sets | patch: run-config `inheritEnv` / `env:` now reach the Shell Adapter through the CLI loader; `templates/v2/` gains `run-config.example.yaml`, `envelope/worker.sh` and prompts; documentation aligned with the parser (worker envelope `severity` + `summary`, P0/P1 block) and with the stable channel; no v1 lifecycle or scaffold change (`v1.21`) |
-| BuildBeat `2.0.2` | same command sets | patch: the npm tarball no longer carries historical documents (release evidence, iteration logs, pilots, plans); current docs still ship; `tests/pack-firstrun.test.sh` guards both; no runtime, v1 lifecycle or scaffold change (`v1.21`) |
-
-`help`, `--help`, and `--version` are meta entry points. `diff` and `uninstall` stay reserved and return `command_not_available`; `gate`, `adr`, `standards`, `check`, and other workflow commands are outside the approved CLI scope. HELP text and regression tests must lock this boundary.
-
-Exit codes:
-
-| Code | Meaning |
-|---:|---|
-| `0` | The inspection/plan completed and has no blocker-level finding |
-| `1` | The command completed, but the project has an error or lifecycle blocker |
-| `2` | Usage/confirmation error, or a reserved command that the running version does not support |
-
-## CLI package lifecycle is not project lifecycle
-
-The public npm package gives the executable a conventional, reversible distribution path:
-
-| Intent | Command | Project effect |
-|---|---|---|
-| Current one-off run | `npx --yes --package=@haiyangbg/buildbeat@latest buildbeat doctor <project>` | Runs the registry version without a persistent global installation |
-| Resolve an exact version | `npm view @haiyangbg/buildbeat@latest version` | Records the version to substitute for `@latest` in a reproducible invocation |
-| Install or update the global CLI | `npm install --global @haiyangbg/buildbeat@latest` | Replaces only the globally installed package and executables |
-| Remove the global CLI | `npm uninstall --global @haiyangbg/buildbeat` | Removes only the global package and executables |
-
-Package-manager operations never create, update, or remove a project's scaffold. `buildbeat upgrade` is a separate schema-2-only project lifecycle; `buildbeat uninstall` and its legacy alias remain disabled. Removing an `npx` cache is also outside BuildBeat's project lifecycle.
-
-## Skill and CLI responsibilities
-
-| Layer | Owns | Must not claim |
-|---|---|---|
-| `SKILL.md` | code-aware inspection, minimal human questions, project-specific reasoning, Gate semantics | deterministic installation state or safe file ownership by itself |
-| CLI | bounded filesystem inspection, plans, manifest/hash handling, repeatable lifecycle mechanics | product judgment, contract discovery, Agent runtime, or automatic Gate approval |
-| Scaffold files | project facts, decisions, contracts, status, evidence | that template defaults are current project facts |
-| Shell guardrails | deterministic local checks | server-side enforcement or live production truth without project adapters |
-
-An AI-assisted bootstrap should consume CLI JSON as evidence, inspect the code for facts the CLI cannot infer, ask only the remaining simple questions, and obtain the existing one-screen confirmation before any write-capable release is allowed to apply a plan.
-
-## File ownership policies
-
-The manifest records the installed baseline hash of every lifecycle-managed path. “Managed” never means “overwrite regardless of local edits.” Policy validity is schema-specific:
-
-- schema 1 remains readable and may contain the historical `three-way-only` value;
-- schema 2 may contain only `replace-if-unmodified`, `project-owned`, and `merge-only`;
-- new plans and writes must never emit `three-way-only`.
-
-| Schema 2 policy | Examples | Write/upgrade rule |
-|---|---|---|
-| `replace-if-unmodified` | `AGENTS.md`, `BUILDBEAT.md`, operator card, `CLAUDE.md` pointer, reviewer, unconfigured managed scripts | Replace only when the current hash still equals the installed baseline; otherwise report a conflict. `--force` may replace this class after an explicit warning. |
-| `project-owned` | architecture, contract, boards, decisions, status, configured `verify-status.sh` | Initial scaffold may create a non-colliding template. Upgrade never creates, replaces, or deletes it; provide migration instructions or a patch candidate instead. `--force` does not override this rule. |
-| `merge-only` | the owned `.gitignore` fragment | Modify only the uniquely marked fragment. Never replace the host file; missing, duplicated, or locally changed markers are conflicts. |
-
-The `.gitignore` host file is represented by `integrations.gitignore`, not duplicated in `files`. Hooks remain outside CLI writes. The compact layout maps the five scripts, operator card, and version marker into `pm/`; root `AGENTS.md`, `CLAUDE.md`, `.claude/agents/`, architecture, contracts, and coordination records keep their established locations.
-
-## Manifest contract
-
-The canonical manifest path is `.buildbeat/manifest.json`. Doctor continues to read the legacy `.solobaton/manifest.json` path, but new scaffolds never create it. Schema 1 is the read-only compatibility shape already recognized by v0:
-
-```json
-{
-  "schemaVersion": 1,
-  "scaffoldVersion": "v1.16",
-  "cliVersion": "1.16.3",
-  "layout": "default",
-  "installedAt": "2026-08-22T00:00:00.000Z",
-  "files": {
-    "scripts/bus-check.sh": {
-      "policy": "replace-if-unmodified",
-      "baselineSha256": "<64 lowercase hex characters>"
-    }
-  },
-  "integrations": {
-    "gitignore": null,
-    "hooks": null
-  }
-}
-```
-
-Schema 2 is the first write-capable shape targeted by Wave 1:
-
-```json
-{
-  "schemaVersion": 2,
-  "scaffoldVersion": "v1.21",
-  "cliVersion": "2.0.2",
-  "layout": "default",
-  "installedAt": "2026-08-24T00:00:00.000Z",
-  "files": {
-    "AGENTS.md": {
-      "policy": "replace-if-unmodified",
-      "baselineSha256": "<64 lowercase hex characters>"
-    },
-    "contracts/PROTOCOL.md": {
-      "policy": "project-owned",
-      "baselineSha256": "<64 lowercase hex characters>"
-    }
-  },
-  "integrations": {
-    "gitignore": {
-      "path": ".gitignore",
-      "beginMarker": "# >>> buildbeat managed >>>",
-      "endMarker": "# <<< buildbeat managed <<<",
-      "baselineSha256": "<SHA-256 of the exact owned fragment bytes, including markers>"
-    },
-    "hooks": null
-  }
-}
-```
-
-Rules common to both schemas:
-
-1. Only the documented top-level and nested fields are accepted. `installedAt` is a canonical UTC timestamp with milliseconds.
-2. Paths are normalized POSIX repository-relative paths, cannot be absolute, cannot contain `.`/`..` traversal segments, cannot traverse symlinks, and must stay inside the target root.
-3. Every file record contains exactly `policy` and a 64-character lowercase hexadecimal `baselineSha256`. The hash describes the exact bytes initially installed or last mechanically upgraded by the CLI, not the current bytes after project edits.
-4. `files` records actual scaffold paths. It excludes both `.buildbeat/manifest.json` and the legacy `.solobaton/manifest.json`, excludes the source-only `gitignore.template`, and excludes the `.gitignore` host file represented under `integrations`.
-5. No credential, environment value, file content, inferred private architecture fact, account identifier, or remote state enters the manifest.
-6. Unknown schema versions and malformed known schemas fail closed. Validation uses a schema-specific policy set: schema 1 continues accepting its historical policies, while schema 2 rejects `three-way-only`.
-7. A missing manifest means a legacy/unmanaged install. `doctor` may inspect it, but `upgrade` must not guess ownership or synthesize a baseline without an explicit adoption decision.
-8. The manifest itself does not make a project healthy; unresolved placeholders, checks, evidence, and human Gates remain separate.
-
-Schema 2 integration rules:
-
-1. `integrations` contains exactly `gitignore` and `hooks`; `hooks` is `null` because hook installation stays a documented Skill/manual step.
-2. `gitignore` is either `null` when no fragment was written, or the exact four-field object shown above. Marker strings are fixed constants, distinct, non-empty, and must occur exactly once in the host file before an automated fragment update.
-3. `baselineSha256` covers the exact UTF-8 fragment bytes from the first byte of `beginMarker` through the final line ending after `endMarker`. A changed fragment is a conflict; `--force` may replace only that fragment, never the rest of `.gitignore`.
-4. The manifest is written last. If it is absent after an interrupted write, later commands classify the target as partial/mixed and refuse to infer ownership.
-
-## Scaffold write transaction (Wave 1 / BuildBeat 1.20)
-
-A write-capable `init` or `adopt` must:
-
-1. inspect without following symlinks and show the complete plan before any mutation; `--dry-run` performs this path and never asks for confirmation;
-2. refuse mixed/partial/already-installed targets, unsafe paths, and every destination collision. Wave 1 has no project-file `--force`;
-3. when the target root itself contains `.git`, require `git status --porcelain=v1 --untracked-files=all` to be empty. A parent repository does not substitute for a target-root repository;
-4. copy the bundled template tree for the selected layout while excluding `standards/` and `pm/adr/` by the shared optional-prefix constant;
-5. render only deterministic values—project name, the invocation's local calendar date, scaffold version, and layout (including compact-layout script references). Preserve every remaining canonical placeholder, return its path/token in `pendingPlaceholders`, and tell the caller to continue with `SKILL.md` §8 or §8.5;
-6. print the final plan and require interactive confirmation. `--yes` skips only this prompt; it does not bypass dirty-worktree, collision, ownership, or path checks;
-7. write each new file through a temporary sibling on the target filesystem followed by an atomic rename. Record every file and directory created by this invocation;
-8. merge only the fixed, uniquely marked BuildBeat fragment into `.gitignore`. A pre-existing BuildBeat or legacy Solobaton marker without matching ownership metadata blocks the write. Do not install or change hooks;
-9. write schema 2 manifest last, after all scaffold files and the integration fragment are durable; and
-10. return the written paths, deterministic replacements, pending placeholders, manifest path, and next Skill/manual action. `doctor` may be run immediately, but pending placeholders are expected warnings until the AI rendering step finishes. A newly created target with no root `.git` must also keep the honest `git.not_initialized` finding until the Skill/manual path initializes Git; the CLI never does that itself. `bus-check` becomes a completion check only after Git and project facts are ready.
-
-The write-capable JSON envelope increments `OUTPUT_SCHEMA_VERSION` from 1 to 2 and adds `writesPerformed`, `writtenPaths`, `manifestPath`, `nextAction`, `renderedPlaceholders`, and `pendingPlaceholders`. Each deterministic replacement is `{path, token, value}`; each unresolved entry is `{path, tokens}`. Dry-run returns the same replacement/pending inventory with `writesPerformed: false`, while successful apply returns the actual written paths with `writesPerformed: true`. The changelog identifies this output-schema change. Existing v0 doctor/plan fields keep their meaning.
-
-In-process rollback is mandatory. On any failure before manifest completion, remove only the files and empty directories created by this invocation and restore an existing `.gitignore` to its exact pre-write bytes through an atomic replacement. Never delete or rewrite a path that predated the invocation. There is no persistent recovery journal: an abrupt process kill may require the user to inspect or restore the already-clean Git worktree, and the next CLI run must classify any manifest-less partial state as blocked rather than guessing.
-
-No command may initialize Git, add a remote, commit, push, install a package globally, or cross a human Gate without separate explicit authority.
-
-## Mechanical upgrade and manual removal
-
-BuildBeat 1.20 implements `buildbeat upgrade [path] [--dry-run] [--json] [--force] [--major]`; the old executable remains only a compatibility alias. It is available only for one canonical BuildBeat installation, a valid canonical schema 2 manifest, and a clean target-root Git worktree. Schema 1, a missing/invalid/legacy manifest, a legacy marker namespace, or a mixed/partial installation is blocked; follow the [v1.16 legacy migration guide](LEGACY-V1.16-MIGRATION.md) for the manual-maintenance or explicitly approved re-baselining path instead of inferring ownership.
-
-The JSON plan contains only bounded metadata: version-gate state, paths, policies, actions, SHA-256 values, blockers, warnings, and conflict eligibility/resolution. It never returns template or project file contents. Any unresolved conflict keeps apply mode at zero writes. A ready apply rechecks every expected hash or absence before mutation, prints the plan, updates the manifest last, and performs in-process byte/mode rollback on failure.
-
-Version gates compare `manifest.scaffoldVersion` with the bundled `SCAFFOLD_VERSION`:
-
-- equal version → no template upgrade is needed;
-- installed version newer than the bundle → block; downgrade is not supported;
-- newer bundle in the same major → eligible for mechanical upgrade;
-- newer bundle in another major → block unless `--major` explicitly acknowledges the major transition.
-
-The planner evaluates the manifest baseline, current project bytes, and new bundled template without performing a three-way merge:
-
-| State | Default action |
-|---|---|
-| `replace-if-unmodified`, current hash equals baseline, new template changed | atomically replace and record the new baseline hash |
-| `replace-if-unmodified`, current file changed or is missing | conflict; leave it untouched |
-| `project-owned`, whether existing or newly introduced upstream | never write, replace, or delete; emit a migration note or patch candidate |
-| new `replace-if-unmodified` path with no collision | create it and add it to the manifest |
-| template removed upstream | report it; do not automatically delete the project path |
-| `.gitignore` fragment markers unique and fragment hash equals baseline | replace only the owned fragment and record its new hash |
-| `.gitignore` fragment missing, duplicated, or changed | conflict; leave the whole host file untouched |
-
-`--force` may overwrite a conflicting `replace-if-unmodified` path and may replace the owned `.gitignore` fragment between unique markers. It never touches `project-owned` paths, never replaces the `.gitignore` host file, and never turns an upstream deletion into automatic project-file deletion. Any conflict without `--force` makes apply mode fail closed after producing the complete conflict report.
-
-An apply run updates managed files atomically, updates the managed `BUILDBEAT.md` version marker only under the same ownership rule, writes the updated schema 2 manifest last, runs `doctor`, and points the user to `bus-check`. A failed run uses the same in-process rollback boundary as Wave 1. Conflict output explicitly recommends opening an AI session to compare the current file with the new template and perform a semantic merge when appropriate.
-
-There is no project `uninstall` engine in the approved command set. `buildbeat uninstall` and its legacy alias remain reserved `command_not_available` responses. A manual removal guide may use the manifest as an inventory, but it must instruct the user to compare hashes, remove only explicitly selected unchanged managed files, edit only the owned `.gitignore` fragment, preserve every `project-owned` path, and delete the manifest only after reviewing what remains. No recursive purge shortcut is permitted.
-
-## Security and privacy boundary
-
-- The legacy npm v0 is read-only. BuildBeat 1.20 Wave 1/2 commands perform only the documented local writes and make no network request. Lifecycle mechanics use only bundled templates and local Git/filesystem facts; package-manager download or publication is outside the project-lifecycle command.
-- Project scans stop at four directory levels or 5,000 entries, skip common build/vendor directories, and never follow symlinks.
-- JSON output contains paths, counts, capability/version metadata, finding codes, bounded placeholder tokens, and one bounded project-name candidate from `package.json`, the first README heading, or the directory name. It does not emit arbitrary source contents, dependency values, environment values, or secrets.
-- Command availability and worktree checks execute only fixed `--version` or read-only Git calls with argument arrays and no shell interpolation.
-
-Package publication remains a separate release action. Every published version must be tied to one immutable Git tag, pass the repository and packed-artifact checks, be read back from the official registry, and pass a clean-directory install plus executable smoke test. See [`RELEASING.md`](RELEASING.md). Documentation must not claim that a new `npx` version is available before those registry checks pass.

package/docs/LEGACY-V1.16-MIGRATION.md

@@ -1,54 +0,0 @@
-# v1.16 legacy 拷出项目迁移指南
-
-> 适用于已把 BuildBeat/Solobaton v1.16 模板拷进业务仓、但没有真实 schema 2 `.buildbeat/manifest.json` 基线的项目。本页是迁移手册，不是执行授权。
-
-## 先判定你在哪条路
-
-| 现状 | 路径 | 结果 |
-|---|---|---|
-| 只有 `SOLOBATON.md` / `BUILDBEAT.md`，无真实 schema 2 manifest | **A. 继续 legacy 手工维护（默认推荐）** | 不改变所有权；以后继续按 CHANGELOG 手工合并 |
-| 已确认要让后续版本进入机械 `upgrade` | **B. 受控重建 schema 2 基线** | 专用 Git 分支上重走 `adopt`，审查后才合并 |
-| 已有 CLI 真实写入的有效 schema 2 manifest | 不属本页 | 待有更新且已验证的 bundle 时才可按 [`CLI.md`](CLI.md) 运行 `upgrade` |
-
-已发布的 `solobaton@1.16.3` v0 仍只读。scoped BuildBeat `1.20.0` 已完成“真实旧 schema 2 版本 → 新 bundle”的独立项目试点，见 [`PHASE4-V1.20-PILOT-2026-08-25.md`](PHASE4-V1.20-PILOT-2026-08-25.md)；但该试点不把没有真实 manifest 的 v1.16 legacy 项目自动变成可升级项目，registry artifact 也仍须独立回读。
-
-## 红线：不猜历史所有权
-
-- 不得把 `.solobaton/manifest.json` 直接改名为 `.buildbeat/manifest.json`；历史 schema/namespace 不会因改名变成新基线。
-- 不得手写 manifest、复制 `example/.buildbeat/manifest.json`，或把当前已改过的文件 hash 当成“安装时 baseline”。
-- 不得同时保留 BuildBeat 与 Solobaton 两份 marker/manifest；混合安装必须 fail-closed。
-- 不把 `doctor`、绿测试、manifest 或 `bus-check --strict` 单独当成人工 Gate、部署或线上健康证据。
-
-## A. 继续 legacy 手工维护
-
-1. 保留现有 marker 与项目文件，不生成 manifest。
-2. 从已安装版本往后逐版阅读 `CHANGELOG.md` 的“拷出项目升级”，按下表处理。
-3. 更改前保留 clean Git checkpoint；更改后运行项目自身测试、`bus-check --format=json --strict` 与人工 Gate。
-4. 将“无 manifest，后续机械 upgrade 不可用”作为明示边界，而不是待修的假阻塞。
-
-| 类别 | legacy 迁移动作 |
-|---|---|
-| `replace-if-unmodified` | 只有确认项目从未修改时才可整文件替换；无法证明就停下做语义合并 |
-| `project-owned` | 只人工合并必要的新字段/规则；不覆盖项目事实、契约、看板、决策、status 和已配置验证命令 |
-| `merge-only` | 只审查并维护 `.gitignore` 中唯一明确标记的片段；不覆盖 host 文件 |
-| optional standards / ADR | 未启用保持缺失；启用时只复制选中模板并填项目事实，已有同名文件不覆盖 |
-| Hook | 始终在 manifest 之外；检查并保留既有 Hook 链后手工安装 |
-
-## B. 受控重建 schema 2 基线
-
-只在项目所有者明确批准“重建基线”后执行；这不是 `upgrade` 的自动降级路径。
-
-1. 确认目标仓已有可回退的 clean commit，新建专用迁移分支；记录旧 marker、布局、协调文件、脚本改写、`.gitignore` 片段、Hook 链和未验证范围。
-2. 将旧协调层的规划目标路径从原位移出，保留在 Git 历史或明确备份位置。`.gitignore` 只在 marker 唯一且边界可确认时移除旧的 BuildBeat/Solobaton 片段，逐字节保留片段外内容；marker 重复/不完整就停下人工核对。把这些变更形成一个单独可审查、worktree clean 的 checkpoint；不删业务代码，不清空未知目录。
-3. 仅从已锁定的 BuildBeat checkout 运行 `node <verified-buildbeat-checkout>/bin/buildbeat.js adopt <project-root> --dry-run --json`；若 scoped registry artifact 已独立回读，也可锁定 `@haiyangbg/buildbeat` 的精确版本。复核 layout、全部 collision/blocker、Git 状态、`.gitignore` 与 `pendingPlaceholders`。不将 `npx solobaton@latest` 当成可写命令。
-4. 同一屏计划获明确确认且 dry-run 无 blocker 后，才在该分支执行交互 apply；非交互 `--yes` 只能复用这次确认。CLI 最后写入 schema 2 manifest，不安装 Hook，不跨 Gate。
-5. 从迁移前 checkpoint 人工回灌项目事实、契约、决策、status、已配置测试和必要的自定义脚本。被项目改写的 `replace-if-unmodified` 文件以后可能进入冲突报告，这是正常的所有权保护。
-6. 可选 standards/ADR 按需手工恢复；填完 `pendingPlaceholders`，配置真实 `verify-status.sh` 与保留既有链的 pre-commit Hook。
-7. 运行项目自身验证、`buildbeat doctor`、`bus-check --format=json --strict`、manifest/hash 回读和 Git diff 审查。`coverage.complete=false` 时保留未验证边界，不得报“全绿”。
-8. 只在同一候选、人工 Gate 和回退方案都齐备后合并迁移分支。本流程不授权部署、push、tag、GitHub Release、npm publish 或远端改名。
-
-## 回退与完成口径
-
-- 回退优先放弃未合并的迁移分支，或用新的 revert 提交撤销已合并变更；不用破坏性 reset 覆盖其他人工作。
-- “建立 schema 2 基线”只表示生命周期所有权可被机械读取。它不证明业务正确、L3/L4 足够、Gate 已批、已部署或线上正常。
-- 后续只有在“真实 schema 2 基线 + 更新且已验证的 bundle + clean Git”同时成立时，才进入机械 `upgrade`；跨 major 仍需额外显式确认。

package/docs/v2/guide/08-migration-v1.md

@@ -1,72 +0,0 @@
-# v1 → v2 迁移指南（手工 runbook）
-
-按收尾修正三：装机量 N=1，**不做 importer 工具**，人工走完。各步括号里的耗时是作者一次迁移的估算，不是承诺。
-
-先分清两件事：**升级 CLI** 与 **迁移项目状态**。`npm install --global @haiyangbg/buildbeat@latest` 只是前者——它把 `buildbeat-v2` 装到机器上，对项目文件零改动；v1 的 `buildbeat doctor / init / adopt / upgrade` 原样保留，schema 仍是 2，`buildbeat upgrade` 对 1.21 骨架报 up-to-date。后者才是本文：把"哪些工作在途"从 v1 看板搬进 `delivery/work/`，并冻结旧入口。三条铁律全程有效：
-
-1. **不猜旧状态有效性**——v1 看板/状态文件里没有证据支撑的行，一律当"待人工确认"，不自动翻译成 v2 状态；
-2. **单向迁移**——v1 只冻结不删除，历史归档可查；
-3. **禁止双写**——切换日之后新工作只进 v2，任何"两边都记一下"都是回退。
-
-## 前提（约 30 分钟）
-
-- [ ] 安装稳定版（`npm install --global @haiyangbg/buildbeat@latest`，2.0.0 起 `latest` 即 v2；`buildbeat-v2` 无参运行能打印用法）；
-- [ ] 读完 [快速开始](01-quickstart.md) 与 [Approval 指南](07-approval-guide.md)；
-- [ ] 目标仓库工作树干净、基线已提交。
-
-## 第 1 步：只读分析 v1（约 1 小时）
-
-盘点现有 v1 资产，只读不改：
-
-- 看板/状态文件（`pm/status/*.md` 或等价物）：列出**声称在途**的工作项；
-- 提案与决策台账（`pm/changes/`、`pm/decisions.md`）：找出已批准未完成的事项；
-- 契约（`contracts/*.md`）与探测器（`drift-check.sh` / `live-status.sh`）：记录现状与调用方式。
-
-产出一张三栏清单：`确认在途 / 疑似过期 / 已完成未归档`。判断依据只认证据（提交、部署记录、生产事实），不认状态文件自述。
-
-## 第 2 步：生成 v2 Work 草稿（约 1 小时）
-
-只为"确认在途"的事项建 v2 工作项：
-
-```bash
-mkdir -p delivery/work/WORK-<名字>
-# intent.md：这件事为什么存在（从 v1 提案摘录+核对）
-# plan.md：接下来真实要做的步骤（不是 v1 计划的搬运——过期部分当场砍掉）
-```
-
-"疑似过期"的行**不迁移**，在清单上标注理由留档；"已完成未归档"的补归档到 v1 历史区。
-
-## 第 3 步：人工确认当前活动 Work（约 30 分钟）
-
-项目所有者逐项过草稿清单，拍板哪些 Work 开（accept intent/plan 即 digest 绑定确认）。没被拍板的草稿删掉或留在未接受状态——**未接受的草稿不产生任何义务**。
-
-## 第 4 步：冻结旧看板（约 15 分钟）
-
-在 v1 看板/状态文件顶部加冻结声明（日期 + "新工作见 delivery/，本文件停止更新"），提交。不删除、不再写入。
-
-## 第 5 步：探测器重挂到 observe（约 30 分钟，可选先行）
-
-把 drift-check/live-status 挂为 observe Provider（[Evidence 指南 §observe](06-evidence-guide.md)）：
-
-```bash
-cp <buildbeat>/src/v2/presets/observe.yaml .buildbeat/observe.yaml   # 改 command/subject
-buildbeat-v2 observe run --config .buildbeat/observe.yaml            # 跑一个周期验证
-```
-
-v1 脚本本体不用改——它们的权威边界（各查什么、不证什么）原样保留。
-
-## 第 6 步：真实 Run 验收（约 1 小时）
-
-选一个已确认的 Work，用 v2 跑完一个真实 Run 到 `WAITING_HUMAN` 并完成决定。**这个 Run 成功之前不算切换完成**——期间发现的问题修完再宣布切换。
-
-人批习惯迁移：v1 四 Gate 用户可先用 `riskPreset: legacy-four-gates`（四 Gate 完整形态），跑顺后再降到 `standard`。
-
-## 完成定义
-
-- 冻结声明已提交；所有新工作走 `delivery/` + v2 Runner；
-- 至少一个真实 Run 走完 Build→Verify→Review→人批闭环；
-- 三栏清单与拍板结果留档（就是迁移的证据）。
-
-迁移前后可核对的目录：迁移前 `pm/NOW.md`、`pm/status/*`、`pm/changes/*` 可写；迁移后它们只读并带冻结声明，`delivery/work/<ID>/` 每个在途事项一个目录，`buildbeat-v2 overview --repo .` 能列出全部活动 Work 且没有重复。旧文件不删，任何时候可读；不要为旧 Run 伪造 run-record 或 manifest。
-
-回退：v1 全部原样在 Git 里，去掉冻结声明即可回去——但双写永远禁止，回去就是整个回去。已经跑出的 v2 Run 台账保留在 `delivery/work/*/runs/`，回退不需要删它。

package/example/.buildbeat/manifest.json

@@ -1,45 +0,0 @@
-{
-  "schemaVersion": 2,
-  "scaffoldVersion": "v1.21",
-  "cliVersion": "2.0.2",
-  "layout": "default",
-  "installedAt": "2026-08-25T00:00:00.000Z",
-  "files": {
-    "AGENTS.md": {
-      "policy": "replace-if-unmodified",
-      "baselineSha256": "b88c3a8f2763933ab7f3c2ebf983fb41f0b2fd4fe878983b94832774854d0e0d"
-    },
-    "ARCHITECTURE.md": {
-      "policy": "project-owned",
-      "baselineSha256": "4c9149a3af00c62f7b588501cf6325aea5be9e96051021c5cffc36d7c5d119b6"
-    },
-    "BUILDBEAT.md": {
-      "policy": "replace-if-unmodified",
-      "baselineSha256": "d411b53917a12e9d53f2b02e8a16292a90570d743943b183316ab0b4c69b254f"
-    },
-    "CLAUDE.md": {
-      "policy": "replace-if-unmodified",
-      "baselineSha256": "1947d9d2c20ce3ede4e24d4f28cedbde0298af53ab5b0e212163d966d28a7a0b"
-    },
-    "contracts/PROTOCOL.md": {
-      "policy": "project-owned",
-      "baselineSha256": "3c970768bed43fa42e4397e703bec4ecedff3a61509d3abcc7ad707e91df8eff"
-    },
-    "pm/NOW.md": {
-      "policy": "project-owned",
-      "baselineSha256": "e0404e1202d9f290d7c97273fc618b7f99f4448a7587898e06500fa0b5c72698"
-    },
-    "pm/decisions.md": {
-      "policy": "project-owned",
-      "baselineSha256": "fff21c36afbdd83132365f0657f54bca9efc5f1a7380c9478e0145ddbd0c8b60"
-    },
-    "pm/一期-看板.md": {
-      "policy": "project-owned",
-      "baselineSha256": "2b74f8a02d0cbdd5710300b2b2a99b101f5e336680edfbd8e30c2c37b542d0b8"
-    }
-  },
-  "integrations": {
-    "gitignore": null,
-    "hooks": null
-  }
-}

package/example/AGENTS.md

@@ -1,19 +0,0 @@
-# AGENTS.md — 简账 工作区 · 工作包路由 + 协作总线
-
-> 沙盘说明:真项目此文件是完整版(路由表 + §1.5 审美红线 + 十条规则 + 红线,见 [templates/AGENTS.md](../templates/AGENTS.md));沙盘只展示**填好占位符的路由表**,其余段落与模板一致、此处从略。简账的同一 Builder 端到端拥有一期工作包,产品/全栈/测试只是 AI 视角。
-> 根上另有一份 `CLAUDE.md`,只是指向本文件的一行指针(见 [templates/CLAUDE.md](../templates/CLAUDE.md))。
-
-## 1. 工作包路由 —— Builder 端到端负责,会话按 AI 视角隔离
-
-| AI 视角 | cwd | 可写(拥有) | 只读 | 开工先读 | 状态写回 |
-|---|---|---|---|---|---|
-| **产品**(规格/编排) | `pm/` | `pm/**` | 全仓 | `pm/NOW.md` | 当期看板 + `pm/status/产品.md` |
-| **全栈**(实现,含运维) | 工作区根(同持 jz-web、jz-api 两仓) | `jz-web/**` + `jz-api/**`(**按仓分别 stage,不 `git add -A`**) | `pm/*` 当期文件、契约 | 各代码仓自己的 `AGENTS.md` + `pm/NOW.md` | `pm/status/全栈.md`(带 hash)+ 各仓 `CHANGELOG.md` + `contracts/PROTOCOL.md` |
-| **测试**(E2E·走查) | `jz-web/` | `tests/**` · 视觉基线 · 走查报告 | 实现 + spec + 设计稿 + 契约 | `pm/NOW.md` + `tests/README.md` | `pm/status/测试.md` + 核查门证据(E2E 报告/视觉 diff/对比图,**落 `pm/archive/<期>/evidence/`,换期零搬运**) |
-
-> 🔴 同一 Builder 合并多视角的补偿控制:一期候选满足 review-ready(两仓 `HEAD=candidate`、工作树干净、L3/渲染证据绿、无待修)后由 reviewer 全核一次 + 测试视角独立核两端;首次 milestone 前写者自发现问题先自行收敛,只有修改冻结对外语义/不可逆副作用才提前 `risk-delta`。写者≠审者不变,但不边改边审。
-> 开工/收工护栏:任意会话开工先跑 `bash scripts/bus-check.sh` + 各仓 `git pull`;收工前回写证据/状态并再跑 `bus-check --strict`,warning/unverified 仍需说明。
-
-## 1.5 UI 规范摘要 / 2. 十条规则 / 2.5 任务包与人批节奏 / 3. 红线
-
-(与 [templates/AGENTS.md](../templates/AGENTS.md) 一致,沙盘从略。完整 UI 规范单点见 `standards/DESIGN.md`;规则⑥采用「机器闸常驻 + review-ready 后一次 milestone + P0/P1 合并 closure」;§2.5 规定会话按用户级工作包持续推进,审批分 `STOP_NOW / BATCH_AT_GATE / NO_APPROVAL`,不因每个小任务交还接力棒。)

package/example/ARCHITECTURE.md

@@ -1,39 +0,0 @@
-# ARCHITECTURE.md — 简账 全栈总图(AI 会话接手按需读这份)
-
-> 一句话:极简个人记账 Web 应用,单用户,先跑通「记一笔 → 看列表 → 月度报表」。
-> 🔴 凭据一律**只标位置、不写值**。
-
-## 0. 架构链路
-
-```
-浏览器
-  ▼
-jz-web(React + Vite,静态托管)
-  ▼
-jz-api(Node + Express + SQLite,示例 PaaS 单实例)
-```
-
-## 1. 文件夹
-
-```
-简账/
-├── AGENTS.md / ARCHITECTURE.md / 指挥台.md / contracts/ / design/ / pm/ / scripts/
-├── jz-web/        # ★ 前端;详见其自己的 AGENTS.md
-└── jz-api/        # ★ 后端 API + SQLite;详见其自己的 AGENTS.md
-```
-
-## 2. 基础设施标识(资源变动时更新本节)
-
-| 项 | 值 | 说明 |
-|---|---|---|
-| 部署平台 | 示例 PaaS(沙盘虚构) | 真项目写平台/区域/应用 ID |
-| 入口 | `https://jz.example.com` | 示意域名 |
-| 数据库 | SQLite(随 jz-api 数据卷) | 每日备份挂账二期(看板挂账 #2) |
-
-### 凭据位置(🔴 只读取,不外泄、不写值)
-- 示例 PaaS 部署 token → 本机 `~/.config/example-paas/token`(600 权限)
-- jz-api 运行时 env 实查 → `paas env list jz-api`(示意命令)
-
-## 3. 红线 / 4. 子项目文档索引
-
-(与 [templates/ARCHITECTURE.md](../templates/ARCHITECTURE.md) 一致,沙盘从略;改 jz-web 先读其自己的 `AGENTS.md`,改契约先读 `contracts/PROTOCOL.md`。)

package/example/BUILDBEAT.md

@@ -1,17 +0,0 @@
-# BUILDBEAT.md — 本项目的协作骨架版本标记
-
-**本项目使用 BuildBeat `v1.21`**(2026-06-10 初次拷入;2026-08-22 升级;2026-08-25 scoped 分发迁移与域回复格式升级;2026-08-28 起随 v2 beta 包分发,v1 脚手架冻结于 v1.21,沙盘示意)
-**协调层布局:`默认`**(脚本在 `scripts/`;简账是从零起的项目,根上本来没别的东西 —— 接管存量项目才用紧凑布局)
-来源:<https://github.com/HaiYangBG1/BuildBeat>
-
-## 升级
-
-对照上游 [CHANGELOG.md](https://github.com/HaiYangBG1/BuildBeat/blob/main/CHANGELOG.md),从本文件记录的版本**往后**逐版看「拷出项目升级」标注的文件,同步后更新上面的版本行。拿不准就让 AI 会话对比上游 `templates/` 与本项目对应文件的差异。
-
-## 教学 manifest
-
-`.buildbeat/manifest.json` 是为本仓文档回归维护的 schema 2 合成快照，它的 hash 锁定当前示例字节。它不证明 npm artifact 或真实 CLI 完成过写入，不是真实项目的安装证据，也不得作为 legacy 项目的复制/重命名来源。真实迁移见 [v1.16 legacy 迁移指南](../docs/LEGACY-V1.16-MIGRATION.md)。
-
-## 回灌(比升级更重要)
-
-本项目踩到 BuildBeat **没覆盖的新坑** → 回上游 `lessons.md` 登记一条(症状→根因→解药)。换期压缩仪式 checklist 里有"回灌一问",别跳过。

package/example/CLAUDE.md

@@ -1,7 +0,0 @@
-# CLAUDE.md — 指针(🔴 勿在此处写内容)
-
-本工作区的会话路由、协作总线十条规则、红线,**单点在同目录的 [`AGENTS.md`](AGENTS.md)** —— 请立即读取那份。
-
-> 本文件只为兼容「只认 `CLAUDE.md` 这个文件名的工具」而存在,**永远保持这几行**。
-> 往这里复制任何规则 = 两份文档必然漂移(上游 `lessons.md` 第 1 条:SSOT 腐烂)。
-> 也不要改成符号链接:Windows 上 git 默认 `core.symlinks=false`,clone 出来会静默退化成一个内容是路径字符串的普通文件,装载即失效。

package/example/README.md

@@ -1,75 +0,0 @@
-# example/ —— 教学沙盘:虚构项目「简账」跑完一期的快照
-
-> 这里的协议骨架文件展示 `templates/` 对应模板**填好项目事实之后的样子**，status/evidence 则是虚构一期的教学产物；沙盘也刻意启用了可选 standards 与一个 ADR，用来展示“默认不生成、选择后由项目拥有”的完成态。
-> 🔴 项目、数据、人物、决策全部虚构(已脱敏);commit hash 均为示意值——真项目里 hash 必须真实可查(`git cat-file -t <hash>`,见 [lessons.md](../lessons.md) 第 11 条)。
-> [`.buildbeat/manifest.json`](.buildbeat/manifest.json) 是 schema 2 的**合成教学快照**：其 baseline hash 会由本仓机器检查锁定到当前示例字节，但它不证明 npm artifact 或真实 CLI 写过这些文件，也不是可复制到真实项目的受管基线。
-
-## 沙盘设定
-
-- **项目**:「简账」—— 网页记账应用(就是主 README §2 举例的那个)
-- **仓**:`jz-web`(前端 React)+ `jz-api`(后端 Node + SQLite),各自独立 git
-- **工作包所有权**:同一 Builder 端到端负责;产品 / 全栈 / 测试是 AI 专业视角;**轨道**:标准轨;**部署**:示例 PaaS(沙盘不接真平台)
-- **进度**:一期(记账主流程 + 月度报表)已跑完 Gate1→Gate4 上线,尚未换期
-
-## 怎么读(建议顺序)
-
-1. [pm/NOW.md](pm/NOW.md) —— 任何会话开工第一眼:当前期是什么、去看哪些文件
-2. [pm/一期-看板.md](pm/一期-看板.md) —— 当前工作包如何覆盖多个子项、决策收件箱如何批量收敛,以及阶段门/分工/挂账
-3. [pm/decisions.md](pm/decisions.md) —— 拍板台账:收敛后的真实决策包 + BuildBeat 升级记录(注意部分回答不单独记行)
-4. [pm/status/](pm/status/) —— 三个 AI 视角各写各的状态:带 hash、带证据指针,按工作包/里程碑更新而非每个子任务一条
-5. [pm/archive/一期/evidence/](pm/archive/一期/evidence/) —— 完成工作包和 Gate 令牌引用的可核验证据落点
-6. [contracts/PROTOCOL.md](contracts/PROTOCOL.md) —— 跨仓契约:快照 + 关键对齐点 + 变更记录(含"独立核查"列)
-7. [AGENTS.md](AGENTS.md) / [ARCHITECTURE.md](ARCHITECTURE.md) —— 路由表和全栈总图填好后的样子(根上另有 [CLAUDE.md](CLAUDE.md),只是指向 `AGENTS.md` 的一行指针)
-8. [standards/](standards/) —— 已确认的 STACK/CODE/REVIEW/DESIGN；普通项目可以完全没有此目录
-9. [pm/adr/](pm/adr/) —— 长期技术决定与替代链；普通拍板仍只进 decisions.md
-10. [.buildbeat/manifest.json](.buildbeat/manifest.json) —— schema 2 字段、所有权策略与 baseline hash 的教学快照
-
-## Gate 四态怎么写
-
-`pm/一期-看板.md` 是已完成一期的 live 快照，因此四行都是 `passed`。下面只是语法对照，不要再追加到同一份看板：
-
-```md
-- Gate1: pending
-- Gate2: passed | 决策: `pm/decisions.md:16` | 证据: `pm/archive/一期/evidence/gate2.md`
-- Gate3: blocked | 理由: `实现候选尚有 P1 待修`
-- Gate4: n/a | 理由: `本工作包无部署或生产发布交付`
-```
-
-`n/a` 必须同行带非占位的 `理由:`；`passed` 应同行指向已存在的决策表行或归档证据。`blocked` 也应说明真实阻塞，不把“还没做”包装成审批。
-
-## 域回复示例
-
-下面展示一期实现候选形成时,全栈视角如何面向人收口。这是回复格式示例,status 和证据文件仍是持久事实。
-
-```md
-## 全栈视角｜✅ 已完成
-
-### 已做
-
-1. 记账主流程和月度报表已形成可验收候选。
-   - 证据：`pm/archive/一期/evidence/implementation.md`
-
-### 未做
-
-1. 黑盒 E2E 和带图走查。
-   - 原因：需要测试视角独立验收当前候选。
-
-### 下一步
-
-- **本域已完成：** 下一棒是测试视角，负责黑盒 E2E 和带图走查。
-```
-
-## Manifest 的教学边界
-
-- `files` 只记录这份合成快照声明的 8 个基线路径；当前文档字节与 `baselineSha256` 一致，是为了防止教材漂移，不是为 legacy 项目追认历史所有权。
-- 可选 `standards/`、`pm/adr/`、业务 status 与 evidence 是基线后的 project-owned 教学内容，不进 manifest。
-- 为避免复制可执行 SSOT，沙盘仍从上游引用 scripts/指挥台/Hook；所以这不是可用 `doctor` 证明健康的完整 CLI 安装。
-- 真实 v1.16 拷出项目必须按 [legacy 迁移指南](../docs/LEGACY-V1.16-MIGRATION.md) 处理；不得复制本 manifest、重命名 `.solobaton` 文件，或把当前已改过的文件 hash 伪装成安装基线。
-
-## 拿它练手(公司内训用法)
-
-开一个 AI 会话,把本目录当项目根,说「你是当前工作包的产品视角,开工」——看它能否从 NOW 顺藤摸瓜讲清当前状态;再说「换期到二期」,对照 NOW.md 底部的压缩仪式 checklist,检查它做没做全。
-
-若把模板脚本复制进本目录运行 `bus-check --strict`,示意 commit 会按设计触发 `sync.ghost_hash`：这是给教学沙盘保留的负例,不是可发布候选的绿灯。真项目必须换成仓库中可解析的真实 hash；删除或豁免检查都不算修复。
-
-> scripts/ 不在沙盘里:开工护栏等脚本直接用 [templates/scripts/](../templates/scripts/);指挥台操作卡见 [templates/指挥台.md](../templates/指挥台.md)。