@haiyangbg/buildbeat 2.0.2 → 3.0.1

package/docs/CHECKS.md

@@ -1,326 +0,0 @@
-# BuildBeat file-bus check specification
-
-Status: **BuildBeat 1.20 / WP3.4 implementation baseline** · normative bus-check schema: `1` · canonical scoped package metadata is `@haiyangbg/buildbeat@1.20.0`; legacy `solobaton@1.16.3` remains the read-only v0 distribution. CLI output/manifest schema 2 and mechanical upgrade are specified separately in [`CLI.md`](CLI.md); the genuine version-increment and real multi-repository refresh evidence is archived in [`PHASE4-V1.20-PILOT-2026-08-25.md`](PHASE4-V1.20-PILOT-2026-08-25.md). None of those facts changes this bus-check schema or proves registry publication.
-
-This document is the single semantic source for `templates/scripts/bus-check.sh` and the same-directory scripts it orchestrates. It defines what a result means, not merely how output is colored. `SKILL.md`, board templates, fixtures, and script tests must use the same tokens and finding codes.
-
-The Node CLI does not reimplement these synchronous file-bus checks. `doctor` keeps its existing inspection taxonomy; the relationship is documented in the appendix.
-
-## 1. Authority and evidence boundary
-
-The check layers are:
-
-| Layer | Authority | Boundary |
-|---|---|---|
-| `bus-check.sh` | one synchronous report for file-bus, Gate, evidence, reference, stack, standards, and ADR findings | may aggregate sibling scripts, but must not invent facts they did not return |
-| `verify-status.sh` | configured L3-suite state | an unconfigured suite is `unverified`, never green evidence; `--run` exits non-zero when any configured suite fails |
-| `drift-check.sh` | configured production-fact comparison | missing adapters, failed queries, or truncated data are `unverified`, never “no drift” |
-| `pre-commit.sh` | consumes `bus-check --strict` plus commit-local guards | a local hook is not server-side enforcement and can be absent on another clone |
-| `doctor` | scaffold/install inspection | does not approve Gates or duplicate the bus result taxonomy |
-
-The scripts may confirm only repository-visible facts and configured adapter results. They cannot prove that documentation matches arbitrary source code, that a human really approved a Gate, that a deployment is healthy, or that an unscanned path is clean. Those limits must appear as `unverified` findings or coverage reasons.
-
-## 2. File-bus invariants
-
-The eight invariant IDs are stable. New implementations extend the registry rather than renumbering it.
-
-| ID | Normative rule | Machine-verifiable part | Must remain `unverified` without extra evidence | Implementation route |
-|---|---|---|---|---|
-| INV-1 | `pm/NOW.md` points to exactly one valid current board | NOW exists; one parseable current-period line and one board pointer; target is a live regular file under `pm/`, not `pm/archive/` | whether the named period is semantically the real current priority | current script partially checks existence/rot; Phase 1 adds stable codes |
-| INV-2 | current board, status, and actual work state do not contradict one another | parseable work-package state; resolvable candidate hashes; configured L3 freshness; explicit contradictions between machine tokens | arbitrary prose status, uncommitted work, product truth, or live runtime state with no adapter | `bus-check` + `verify-status`; unresolved scope emits `sync.unverified` |
-| INV-3 | a completed work package has evidence | every `✅完成` work-package block has one non-empty `**证据**:` line; local paths exist; hashes resolve | external URLs, screenshots not present locally, human statements, or commands whose output was not persisted | Phase 1 `evidence.missing`; external-only evidence also emits `sync.unverified` |
-| INV-4 | a cross-boundary change is reflected in the contract | configured provider-path hints, contract file existence/version token, and project adapters when present | a generic script cannot infer all API/schema/public-behavior changes from arbitrary code | pre-commit hint + contract section; absence of a hint is never proof of synchronization |
-| INV-5 | a passed Gate is traceable | Gate token parses; referenced decision/evidence path or hash is syntactically valid and locally resolvable | whether the named person actually approved or the evidence is sufficient | Phase 1 `gate.pass_untraceable`; human confirmation remains authoritative |
-| INV-6 | a Gate marked `n/a` has a reason | exact `n/a` token and a non-placeholder `理由:` value on the same line | whether the reason is substantively correct for the project | Phase 1 `gate.na_without_reason`; later project-type checks may warn |
-| INV-7 | pointers and references resolve safely | scoped Markdown/local references stay inside the root; regular-file targets exist; Git hashes resolve in the meta repo or discovered subrepos | remote-link availability or semantic correctness of an anchor | Phase 1 `ref.broken`; network is not used |
-| INV-8 | an incomplete check is exposed | scan truncation, skipped directories, missing tools/adapters, permission errors, and failed child checks set incomplete coverage | anything outside the observed scope | `sync.unverified` or a narrower `*.unverified` code; never a confirmed all-clear |
-
-INV-2 and INV-4 are intentionally not reducible to a single green boolean. When only part of an invariant is observable, report the confirmed subfact and the remaining `unverified` scope separately.
-
-## 3. Machine-readable tokens
-
-### 3.1 Gate state lines
-
-The board contains one list item for each fixed Gate. The canonical form is:
-
-```md
-- Gate1: pending
-- Gate2: n/a | 理由: `本期无 UI 或交互面`
-- Gate3: passed | 决策: `pm/decisions.md:42` | 证据: `pm/archive/一期/evidence/gate3.md`
-- Gate4: blocked | 理由: `尚无获批发布窗口`
-```
-
-Parser rules:
-
-1. Accept optional leading whitespace, then the exact list marker `- `, `Gate1` through `Gate4`, one colon, and one lowercase state: `pending`, `passed`, `blocked`, or `n/a`.
-2. Each Gate appears exactly once. Missing lines in a legacy board produce `gate.line_missing` at `warning`; duplicates or an unknown state are protocol `error` findings.
-3. `n/a` requires a same-line `理由:` field whose backticked value is non-empty and contains no canonical `<...>` placeholder. Otherwise emit `gate.na_without_reason` at `conflict`.
-4. `passed` should provide at least one `决策:` or `证据:` field. A present `决策:` must be exactly `pm/decisions.md:<positive-line-number>` and that line must exist as a dated decision-table row; naming the ledger file alone is not enough. A missing or invalid trace emits `gate.pass_untraceable` at `warning`.
-5. Gate2 `n/a` is compared only with positive UI signals: a regular `standards/DESIGN.md`, an `index.html`, a known UI package dependency, or a browser-extension UI manifest. A detected signal emits `gate.na_inconsistent` at `warning`; no signal is merely inconclusive and is never proof that the project has no UI.
-6. `blocked` should carry `理由:`. Phase 1 may warn when it is absent, but this is not a strict blocker until a stable finding code is added here.
-7. Natural-language Gate tables may remain for readers, but only these four canonical lines drive machine conclusions.
-
-### 3.2 Work-package evidence lines
-
-Within each `### WP-...` block, the canonical state and evidence fields are:
-
-```md
-- **状态**: ✅完成
-- **证据**: `pm/archive/一期/evidence/report.md` · candidate `deadbee1`
-```
-
-The parser scopes a block from its `### WP-...` heading to the next heading of the same or higher level. A block containing `**状态**:` and `✅完成` must contain exactly one non-empty `**证据**:` line. Missing, duplicate, placeholder-only, or locally invalid evidence emits `evidence.missing` at `conflict`.
-
-Machine-verifiable reference forms are:
-
-- a backticked repository-relative regular-file path, optionally followed by `:<positive-line-number>`;
-- a backticked 7–40 character lowercase hexadecimal Git token containing at least one letter and one digit, resolvable in the meta repo or a discovered subrepo;
-- an `https://` reference, which is recorded but remains `unverified` unless a project adapter supplies a verified result.
-
-Paths must not be absolute, contain traversal segments, or resolve through a symlink outside the coordination root. A valid local Gate/work-package evidence path outside `pm/archive/<期>/evidence/` remains traceable but emits `evidence.outside_archive` at `warning`; Git hashes and remote URLs have no local archive-location claim. A command name or prose claim by itself is not machine-verifiable evidence; retain it for humans and emit `sync.unverified` when no local evidence token exists.
-
-### 3.3 Scoped reference scan
-
-Phase 1 checks Markdown links and backticked `.md` paths in `pm/NOW.md`, the current board, and the latest three dated rows of `pm/decisions.md`. It also checks paths/hashes on canonical Gate and evidence lines. The three-row decision window keeps the live synchronization guard from retroactively blocking on historical paths that were intentionally archived; the full repository linker remains a separate source-checkout gate in `tests/check_docs.py`.
-
-Canonical Gate/evidence paths are repository-root relative and may not contain traversal segments. For scoped legacy prose, the scanner accepts an existing source-file-relative path first, including `../` or `./` segments only when the resolved regular file remains inside the coordination root, then an existing repository-root path (and bare contract filenames under `contracts/`). Absolute paths, paths that resolve outside the root, wildcards/placeholders, overlong table fragments, and prose-only tokens are never treated as valid local evidence. Wildcards/placeholders/prose are ignored rather than mislabeled as broken regular-file references; a real path-shaped token that stays in scope but does not resolve emits `ref.broken`.
-
-### 3.4 Optional standards
-
-`standards/STACK.md`, `CODE.md`, `REVIEW.md`, and UI-only `DESIGN.md` are independent, project-owned optional files. If none exists, `bus-check` emits no standards finding. Every file that does exist must contain exactly once:
-
-```md
-> **Optional**: ...
-> **AI write boundary**: ...
-> **Status**: Draft
-```
-
-Status is exactly `Draft` or `Confirmed`. A Draft is structurally valid but emits `standards.unconfirmed` at `unverified`; it never becomes green by implication. A Confirmed file must contain no `<...>` placeholder.
-
-Each present file contains at least one stable, unique Rule ID whose prefix matches the filename, for example `STACK-MUST-001`, `CODE-SHOULD-002`, or `DESIGN-MAY-003`. Levels are `MUST / SHOULD / MAY`; the numeric suffix is exactly three digits. Missing metadata, illegal/duplicate/wrong-prefix Rule IDs, a placeholder in a Confirmed file, or a broken repository-local backticked reference emits one `standards.invalid` error for that file. Remote references are not fetched. This structural check never infers machine values from the standards prose; a structurally valid Confirmed STACK enters the separate observation check below.
-
-### 3.5 Confirmed STACK observable baseline
-
-Only a structurally valid `standards/STACK.md` with `Status: Confirmed` enters stack observation. Draft or structurally invalid files retain their existing standards finding and are not compared, so an unconfirmed declaration cannot manufacture a drift conclusion. Absence of STACK remains a legal zero-finding state.
-
-The Confirmed file contains exactly one v1 comment block:
-
-```md
-<!-- buildbeat-stack-baseline:v1
-nodeConstraint=22
-nodeConstraint=>=22 <23
-lockfileKind=package-lock.json
-dockerFromImage=node:22-alpine
--->
-```
-
-The three keys are exact and each must occur at least once. Repeating a key declares a set. Values are trimmed, case-sensitive strings of at most 200 characters; exact duplicates collapse. A dimension with no applicable source uses one sole `n/a` value, never `n/a` plus another value. A missing/duplicated/malformed block, an unknown or missing key, or an ambiguous `n/a` set emits `stack.unverified`, not `standards.invalid`: the standards document is structurally readable, but its observable baseline is not. A canonical `<...>` placeholder in any Confirmed standard remains the earlier `standards.invalid` structural error, so the observation step is skipped.
-
-The scanner recursively observes regular files below the coordination root, pruning `.git`, `.claude`, `.codex`, canonical `.buildbeat`, legacy `.solobaton`, dependency, coverage, build, and generated-output directories. New STACK files use `buildbeat-stack-baseline:v1`; the parser also accepts exactly one legacy `solobaton-stack-baseline:v1` block. The default bound is 200 relevant files/symlinks and can be lowered or raised with positive-integer `BUS_STACK_MAX`. It compares these exact sets:
-
-| Dimension | Observed source | Normalization |
-|---|---|---|
-| Node constraints | every `.nvmrc`; every string `package.json` `engines.node` | one trimmed non-empty `.nvmrc` line; JSON value preserved after outer trim |
-| lockfile kinds | `package-lock.json`, `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `bun.lockb` | basename only; duplicate kinds collapse |
-| Docker FROM images | `Dockerfile` and `Dockerfile.*` FROM instructions | optional `--platform=...` removed; image token preserved; stage aliases ignored |
-
-Observed and declared non-empty sets must match exactly. A declared `n/a` plus an observed source, or two non-empty sets that differ, emits `stack.drift` at `conflict`. A declared non-`n/a` set with no observable source emits `stack.unverified` rather than drift. Invalid JSON, a non-string Node engine, an empty/multi-line `.nvmrc`, an unreadable file, an unresolved variable in a Docker image token, missing Python needed for JSON parsing, an over-limit scan, a find/permission error, a relevant file symlink, or an unpruned directory symlink also leaves the affected scope `stack.unverified`. A definite mismatch and an incomplete remaining scope may emit both codes.
-
-The check is report-only: it never edits STACK, version files, package manifests, lockfiles, or Dockerfiles. Findings name dimensions but do not echo raw source/config values into JSON. Matching only confirms these three observed dimensions inside the scanned regular-file scope; it says nothing about frameworks, databases, deployment health, CI, licensing, remote repositories not present below the root, or semantic compatibility.
-
-### 3.6 Explicit multi-repository version joins
-
-Multi-repository drift is checked only through one explicit project-owned map in `contracts/PROTOCOL.md`; directory names, architecture prose, package metadata, and live output are never guessed into version equality:
-
-```md
-<!-- buildbeat-multirepo-map:v1
-repo=service-web|contract=contracts/PROTOCOL.md|deployment=web
-repo=service-api|contract=contracts/api.md|deployment=n/a
--->
-```
-
-Each non-empty row has exactly `repo=<path>|contract=<path>|deployment=<app-or-n/a>` with no surrounding whitespace. `repo` is a safe coordination-root-relative path expected to match the existing `SUBREPOS` discovery (independent Git repositories one or two levels below the root). `contract` is a safe `contracts/**/*.md` path containing exactly one `契约快照对应版本` line with one backticked release token. `deployment` is either an app key in the same-directory `bus-baseline.json` used by `drift-check.sh`, or the exact value `n/a` when that repository has no deployment source.
-
-The repository version comes only from the first non-`Unreleased` H2 in `<repo>/CHANGELOG.md`. Accepted headings are Keep-a-Changelog forms such as `## [1.2.3] - 2026-08-25` or `## v1.2`; accepted source tokens have two or three numeric components plus optional SemVer prerelease/build suffixes. One leading `v`/`V` is ignored for equality. Free-form release prose, package versions, Git tags, commit hashes, and a later convenient heading are not substituted for an invalid head source.
-
-For each mapped repository, every successfully observed source is compared pairwise. A definite mismatch emits `sync.multirepo_drift` at `conflict` and identifies the repository, `CHANGELOG.md`, mapped contract file, and `bus-baseline.json#apps.<app>.imageTag` fact source. A missing/out-of-root repository or source, invalid/duplicate/empty map, unparseable version, missing `jq`, missing app, missing deployment baseline, mapped repository outside the bounded discovery, or discovered repository absent from the map emits `sync.unverified`; a present source skipped for symlink or permission safety emits `sync.scan_truncated` under §3.8. A definite mismatch and an incomplete third source may emit both.
-
-No discovered repositories plus no map is a legal zero-finding state. A present map is the expected inventory, so a mapped-but-undiscovered repository remains explicitly unverified even when no nested repository was found. `deployment=n/a` compares CHANGELOG and contract only. This check is read-only and compares a local deployment baseline; it does not query production or prove that the baseline is current. `live-status.sh` and `drift-check.sh` retain those separate authority boundaries.
-
-### 3.7 Optional ADRs
-
-ADR files are named `pm/adr/ADR-NNNN-*.md`. The directory and all ADR files are optional; absence emits no ADR finding. Every present ADR contains exactly one canonical status line:
-
-```md
-- Status: Proposed
-```
-
-The only legal values are `Proposed`, `Accepted`, `Rejected`, and `Superseded`. Missing, duplicated, or unknown status emits `adr.status_invalid` at `error`.
-
-A Superseded ADR must contain exactly one root-relative target such as:
-
-```md
-- Superseded by: `pm/adr/ADR-0002-new-choice.md`
-```
-
-The target must exist, must itself have a legal status, and the chain must terminate without self-reference or cycles. Otherwise emit `adr.superseded_broken` at `conflict`. The script checks link integrity only; it cannot prove the architectural decision is correct or genuinely approved.
-
-### 3.8 Mechanical scan boundaries
-
-`sync.scan_truncated` is the common non-blocking result when a relevant local source is present or a bounded scan started, but the checker deliberately did not inspect the entire scope. Its message contains one stable reason token and its `path` names the skipped repository-relative source when known:
-
-| Reason | Condition | Operator response |
-|---|---|---|
-| `reason=limit` | scoped-reference or STACK observation count exceeds `BUS_REF_MAX` / `BUS_STACK_MAX` | inspect what was omitted; raise the relevant limit only when the larger scope is intentional, then rerun |
-| `reason=symlink` | a relevant coordination, evidence, standards, ADR, STACK, contract, repository, or deployment-baseline path traverses an in-root symbolic link | independently inspect the target or materialize the required fact as an in-root regular file; the checker does not follow it |
-| `reason=permission` | the current process cannot read a relevant file, search a mapped repository directory, or complete filesystem traversal | restore only the minimum read/search access needed for the check, or provide a readable evidence artifact, then rerun |
-
-This finding means “coverage stopped here,” not “the source is missing” and not “the source is valid.” A completed-work evidence reference that resolves only through a symlink or unreadable file therefore remains unverified and does not additionally become `evidence.missing`; an absent or unsafe path still follows its narrower missing/broken rule. Domain findings may coexist: for example, a Confirmed STACK scan can emit both `sync.scan_truncated` for the exact mechanical boundary and `stack.unverified` for the affected comparison dimensions.
-
-Intentional exclusions such as `.git`, `node_modules`, build output, and vendor directories do not each produce findings because those trees are outside the declared observation scope. Raw OS error text and temporary absolute paths are not copied into JSON; an unlocatable traversal failure uses `path="."`. Any `sync.scan_truncated` sets `coverage.complete=false` but does not block strict mode. It must be reported in handoff evidence and cannot be converted into an all-clear by exit 0.
-
-## 4. Result levels
-
-Every finding has exactly one level:
-
-| Level | Meaning | Strict by default |
-|---|---|---|
-| `confirmed` | a positive or neutral fact was directly observed | no |
-| `warning` | a risk or traceability weakness exists, but no invariant conflict is established | no |
-| `unverified` | the tool cannot reliably decide within the observed scope | no; must stay visible |
-| `conflict` | a project declaration contradicts an observed fact or omits support required by an invariant | yes |
-| `error` | protocol structure is malformed or the requested check cannot produce a trustworthy report | yes |
-
-Levels are not a cosmetic mapping from legacy emoji or from `error/warning/info`. The implementation must construct the semantic finding first, then render human or JSON output from that same finding.
-
-`confirmed` never means “the whole project is healthy.” If `coverage.complete` is false, the report cannot print or encode an unqualified all-clear.
-
-## 5. Finding-code registry
-
-Namespaces are reserved as follows:
-
-| Namespace | Scope |
-|---|---|
-| `sync.` | NOW/status/L3/scan/remote and general coordination state |
-| `gate.` | four-Gate tokens and traceability |
-| `evidence.` | work-package evidence requirements |
-| `contract.` | cross-boundary contract synchronization |
-| `ref.` | local path, Markdown, and Git reference integrity |
-| `stack.` | optional `STACK.md` observation and drift |
-| `standards.` | optional standards structure/rules |
-| `adr.` | optional ADR structure and supersession links |
-
-The initial registry is:
-
-| Code | Level | Condition | Phase |
-|---|---|---|---|
-| `sync.now_bloated` | `conflict` | NOW/status live coordination layer exceeds the configured rot limits | legacy behavior; code in Phase 1 |
-| `sync.ghost_hash` | `conflict` | a canonical status hash cannot resolve in any known repo | legacy behavior; code in Phase 1 |
-| `sync.production_drift` | `conflict` | configured drift adapter confirms a changed production fact | legacy behavior; code in Phase 1 |
-| `sync.multirepo_drift` | `conflict` | explicitly mapped CHANGELOG, contract, and/or deployment-baseline versions disagree | Phase 3 / WP3.3 |
-| `sync.l3_stale` | `warning` | configured suite evidence is absent, unreadable, or older than `BUS_L3_MAX_AGE_DAYS` (default `7`) | Phase 1 |
-| `sync.l3_unconfigured` | `unverified` | no real L3 suite is configured | Phase 1 |
-| `sync.scan_truncated` | `unverified` | limit, permission, or symlink boundary leaves relevant declared scope unchecked | Phase 1; consolidated path/reason handling in Phase 3 / WP3.4 |
-| `sync.unverified` | `unverified` | a material check boundary has no narrower registered code | Phase 1 |
-| `gate.line_missing` | `warning` | a legacy board lacks one or more canonical Gate lines | Phase 1 |
-| `gate.invalid` | `error` | a Gate state line is duplicated, malformed, or uses an unknown state | Phase 1 |
-| `gate.na_without_reason` | `conflict` | `n/a` lacks a valid same-line reason | Phase 1 |
-| `gate.na_inconsistent` | `warning` | Gate2 is `n/a` while a positive UI signal is present | Phase 3 / WP3.2 |
-| `gate.pass_untraceable` | `warning` | `passed` lacks a resolvable decision/evidence reference | Phase 1 |
-| `evidence.missing` | `conflict` | a completed work package lacks one valid canonical evidence line | Phase 1 |
-| `evidence.outside_archive` | `warning` | a valid local Gate/work-package evidence path is outside `pm/archive/<期>/evidence/` | Phase 3 / WP3.2 |
-| `ref.broken` | `conflict` | a scoped local path/hash reference is syntactically unsafe or does not resolve | Phase 1 |
-| `standards.invalid` | `error` | a present optional standard has invalid metadata, Rule IDs, confirmed placeholders, or local references | Phase 2-A |
-| `standards.unconfirmed` | `unverified` | a present optional standard is structurally valid but remains Draft | Phase 2-A |
-| `stack.drift` | `conflict` | a Confirmed v1 STACK baseline contradicts an observed Node, lockfile, or Docker FROM set | Phase 2-B / WP2.5 |
-| `stack.unverified` | `unverified` | a Confirmed STACK baseline or relevant observation scope cannot be compared reliably | Phase 2-B / WP2.5 |
-| `adr.status_invalid` | `error` | a present ADR lacks exactly one legal canonical Status | Phase 2-A |
-| `adr.superseded_broken` | `conflict` | a Superseded ADR points to a missing/invalid ADR or creates a self-reference/cycle | Phase 2-A |
-
-New codes require this document, positive/negative fixtures, human rendering, JSON rendering, and strict behavior to change together. A code must not silently change level between releases; that is a user-visible compatibility change.
-
-## 6. JSON report schema
-
-`bus-check --format=json` emits one JSON document to stdout and no human dashboard text. Diagnostics that prevent a report go to stderr.
-
-```json
-{
-  "schemaVersion": 1,
-  "command": "bus-check",
-  "ok": false,
-  "target": ".",
-  "findings": [
-    {
-      "code": "gate.na_without_reason",
-      "level": "conflict",
-      "message": "Gate2 is n/a without a non-placeholder reason.",
-      "path": "pm/一期-看板.md"
-    }
-  ],
-  "summary": {
-    "confirmed": 0,
-    "warning": 0,
-    "unverified": 0,
-    "conflict": 1,
-    "error": 0
-  },
-  "coverage": {
-    "complete": true,
-    "reasons": []
-  },
-  "strict": {
-    "enabled": true,
-    "blocked": true
-  }
-}
-```
-
-Schema rules:
-
-1. `target` and `path` are normalized repository-relative display paths; fixture output must not contain temporary absolute paths.
-2. Findings are ordered by the registry/check order, then path, so repeated runs on unchanged facts are byte-stable apart from messages whose documented fact changed.
-3. `ok` is true only when there is no `conflict` or `error`. Warnings and explicit unverified coverage do not change `ok`, but remain in the report.
-4. `coverage.complete` is false when any relevant scope was truncated, skipped, unavailable, or failed. `reasons` contains stable finding codes, not secrets or raw command output.
-5. Counts equal the findings array exactly. Unknown levels/codes are schema errors in fixtures and consumers.
-6. JSON never includes credential values, environment values, arbitrary source contents, private messages, or live configuration values.
-
-Exit behavior:
-
-| Invocation | Exit 0 | Exit 1 | Exit 2 |
-|---|---|---|---|
-| default human or `--format=json` | a report was produced, even with findings | not used for findings | invalid arguments or failure to produce a trustworthy report |
-| `--strict` with either format | no `conflict`/`error` | at least one `conflict`/`error` | invalid arguments or failure to produce a trustworthy report |
-
-`warning` and `unverified` never block strict by implication. Promoting either level into the strict set requires an explicit code-level change in this specification and the changelog.
-
-## 7. Current versus planned implementation
-
-The current worktree candidate implements Phase 1, the Phase 2-A structural checks, WP2.5 STACK observation, WP3.2 Gate/evidence joins, WP3.3 explicit multi-repository version joins, and WP3.4 consolidated mechanical-boundary reporting from one finding collection: human rendering, schema 1 JSON, strict blocking, canonical Gate/evidence parsing, scoped reference scanning, L3 machine findings, explicit incomplete coverage, the three legacy strict checks, optional standards metadata/Rule-ID validation, exact Node/lockfile/Docker baseline comparison, ADR status/supersession integrity, mapped CHANGELOG/contract/deployment-baseline comparison, and precise `limit`/`symlink`/`permission` reasons. Default human and JSON report modes still return exit 0 after producing a trustworthy report; `--strict` returns exit 1 only for `conflict` or `error`.
-
-Fixtures now execute both renderings. They compare finding codes, registered levels, counts, relative paths, coverage reasons, and strict status; retained human text assertions protect operator-facing compatibility. Matching, definite-conflict, and missing-observation STACK fixtures lock the WP2.5 result boundary. Runtime-generated nested Git repositories cover WP3.3 matching, definite drift, spaces in repository paths, and unmapped coverage without checking nested `.git` metadata into this source repository. WP3.4 additionally covers reference-limit, symlinked evidence, and permission-denied evidence paths, including non-blocking strict behavior, incomplete coverage, and exact relative paths; the Shell suite currently has 221 assertions. WP1.6 has also completed the earlier example, active multi-repo projection, and real single-repo code-tree projection documented in [`PHASE1-PILOT-2026-08-24.md`](PHASE1-PILOT-2026-08-24.md). Current Phase 3 evidence remains disposable local fixtures, not a refreshed real-project pilot. Without separate release authorization and installed-project migration evidence, this remains an Unreleased candidate rather than released behavior.
-
-WP2.5 does not extend beyond its three explicit regular-file dimensions. WP3.2–WP3.4 add separately mapped checks and honest boundary reporting, but a green STACK or multi-repository comparison still cannot be extrapolated into deployment health, semantic contract correctness, human approval, or any path outside the declared observation scope.
-
-## 8. Three retained compatibility files
-
-These files stay for distinct consumers and do not create a second semantic authority:
-
-| File | Purpose | Schema 2 ownership |
-|---|---|---|
-| `CLAUDE.md` | thin compatibility pointer to `AGENTS.md` | `replace-if-unmodified` |
-| `指挥台.md` | one-page human operator card | `replace-if-unmodified` |
-| `.claude/agents/reviewer.md` | tool-specific read-only reviewer increment | `replace-if-unmodified` |
-
-Project facts remain in AGENTS/NOW/board/contracts/status/evidence. These three files may point to those facts but must not copy them into competing SSOTs.
-
-## Appendix: doctor comparison
-
-`doctor` keeps `error / warning / info` and `ok = no error`; it does not migrate to the five bus levels in Phase 1.
-
-| Doctor level | Closest display concept | Caveat |
-|---|---|---|
-| `error` | `error` | only within scaffold/install inspection |
-| `warning` | `warning` | may include incomplete setup such as pending placeholders |
-| `info` | `confirmed` when it reports an observed fact | not every info message is a project-wide confirmation |
-
-No automated Gate or release decision may be made by mechanically converting doctor levels into bus-check levels.

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.