@haiyangbg/buildbeat 2.0.0-beta.4 → 2.0.0-beta.5

package/src/v2/workspace/workspace-manager.js

@@ -4,7 +4,7 @@
 // deleted here — the pinned candidate must stay reachable for evidence.
 
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 
 export class WorkspaceError extends Error {
@@ -44,6 +44,19 @@ export function acquireLock(repoRoot, runId) {
   return lockPath;
 }
 
+// Run ids currently holding a lock in this repository (the repository-wide
+// active-run marker excluded): who a blocked `start` is queued behind.
+export function listHeldRunLocks(repoRoot) {
+  const lockDir = join(repoRoot, ".buildbeat", "runtime", "locks");
+  if (!existsSync(lockDir)) {
+    return [];
+  }
+  return readdirSync(lockDir)
+    .filter((entry) => entry.endsWith(".lock") && entry !== "active-run.lock")
+    .map((entry) => entry.slice(0, -".lock".length))
+    .sort();
+}
+
 export function releaseLock(repoRoot, runId) {
   const lockPath = join(repoRoot, ".buildbeat", "runtime", "locks", `${runId}.lock`);
   rmSync(lockPath, { recursive: true, force: true });

package/templates/contracts/PROTOCOL.md

@@ -13,6 +13,10 @@
 <!-- buildbeat-multirepo-map:v1
 repo=<代码子仓1>|contract=contracts/PROTOCOL.md|deployment=<bus-baseline.json app 名或 n/a>
 -->
+<!-- map 行格式:repo=<子仓路径>|contract=<contracts/*.md 或 n/a>|deployment=<bus-baseline.json app 名或 n/a>[|changelog=<该仓内模块 CHANGELOG 路径>]
+     · changelog= 给多模块仓用(根下没有 CHANGELOG,由某个模块 CHANGELOG 承载契约版本);缺省 <repo>/CHANGELOG.md。
+     · contract=n/a 表示该仓没有契约版本域(如只读存量前端、npm 包 semver 与契约版本不同域),只登记不核对;不得拿它掩盖真实的契约关系。
+     · 被核对的 CHANGELOG 首个已发布 H2 须以契约快照版本开头,如 `## [v1.3 · Deployed 2026-09-05 · <sha> · <流水线>]`。 -->
 
 ---
 

package/templates/gitignore.template

@@ -14,6 +14,11 @@
 # verify-status 的「上次全绿」标记(本地实查产物,不入 git)
 .last-green-*
 
+# BuildBeat v2 运行时面与隔离工作树(可随时整删重建;不入 git)
+# 同时让 rg / 尊重 .gitignore 的工具不再走进旧工作树;vitest / jest 等要另配 exclude,见 docs/v2/guide/02-workflow-guide.md
+.buildbeat/runtime/
+.buildbeat/worktrees/
+
 # 代码子仓(各自独立 git,meta 仓不跟踪;按实际仓名替换)
 /<代码仓1>/
 /<代码仓2>/

package/templates/scripts/bus-check.sh

@@ -438,14 +438,18 @@ check_multirepo_drift() {
     multirepo_line="${multirepo_line%$'\r'}"
     [ -n "$multirepo_line" ] || continue
     if ! printf '%s\n' "$multirepo_line" \
-        | grep -Eq '^repo=[^|]+\|contract=[^|]+\|deployment=[^|]+$'; then
+        | grep -Eq '^repo=[^|]+\|contract=[^|]+\|deployment=[^|]+(\|changelog=[^|]+)?$'; then
       multirepo_map_invalid=1
       continue
     fi
-    IFS='|' read -r multirepo_repo_field multirepo_contract_field multirepo_deployment_field <<< "$multirepo_line"
+    IFS='|' read -r multirepo_repo_field multirepo_contract_field multirepo_deployment_field multirepo_changelog_field <<< "$multirepo_line"
     multirepo_repo="${multirepo_repo_field#repo=}"
     multirepo_contract="${multirepo_contract_field#contract=}"
     multirepo_deployment="${multirepo_deployment_field#deployment=}"
+    # 可选第 4 字段 changelog=<repo 内的 CHANGELOG 路径>:多模块仓没有根 CHANGELOG 时,
+    # 由 map 显式指定承载契约版本的模块 CHANGELOG;缺省仍为 <repo>/CHANGELOG.md。
+    multirepo_changelog_override="${multirepo_changelog_field#changelog=}"
+    [ -n "$multirepo_changelog_field" ] || multirepo_changelog_override=""
     multirepo_repo_trimmed="$(printf '%s' "$multirepo_repo" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"
     multirepo_contract_trimmed="$(printf '%s' "$multirepo_contract" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"
     multirepo_deployment_trimmed="$(printf '%s' "$multirepo_deployment" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"
@@ -454,12 +458,23 @@ check_multirepo_drift() {
         || [ "$multirepo_deployment" != "$multirepo_deployment_trimmed" ] \
         || ! multirepo_repo_path_safe "$multirepo_repo" \
         || ! multirepo_map_value_safe "$multirepo_contract" 240 \
-        || ! printf '%s\n' "$multirepo_contract" | grep -Eq '^contracts/[^/].*\.md$' \
+        || ! { [ "$multirepo_contract" = "n/a" ] \
+          || printf '%s\n' "$multirepo_contract" | grep -Eq '^contracts/[^/].*\.md$'; } \
         || ! multirepo_map_value_safe "$multirepo_deployment" 100; then
       multirepo_map_invalid=1
       continue
     fi
-    printf '%s\t%s\t%s\n' "$multirepo_repo" "$multirepo_contract" "$multirepo_deployment" >> "$multirepo_records"
+    # contract=n/a 表示该仓没有契约版本域(如只读存量前端、npm 包 semver 与契约版本不同域),
+    # 只登记入 inventory、不做版本核对;不得用它掩盖真实存在的契约版本关系。
+    if [ -n "$multirepo_changelog_override" ]; then
+      if ! multirepo_repo_path_safe "$multirepo_changelog_override" \
+          || [ "${#multirepo_changelog_override}" -gt 240 ] \
+          || ! printf '%s\n' "$multirepo_changelog_override" | grep -Eq "^$(printf '%s' "$multirepo_repo" | sed 's/[.[\*^$]/\\&/g')/.+/CHANGELOG\.md$"; then
+        multirepo_map_invalid=1
+        continue
+      fi
+    fi
+    printf '%s\t%s\t%s\t%s\n' "$multirepo_repo" "$multirepo_contract" "$multirepo_deployment" "$multirepo_changelog_override" >> "$multirepo_records"
     printf '%s\n' "$multirepo_repo" >> "$multirepo_expected"
   done < "$multirepo_map_raw"
 
@@ -485,9 +500,9 @@ check_multirepo_drift() {
     add_finding "sync.unverified" "unverified" "Discovered repo=$multirepo_repo is absent from buildbeat-multirepo-map:v1." "$multirepo_repo"
   done < "$multirepo_discovered"
 
-  while IFS=$'\t' read -r multirepo_repo multirepo_contract multirepo_deployment; do
+  while IFS=$'\t' read -r multirepo_repo multirepo_contract multirepo_deployment multirepo_changelog_override; do
     [ -n "$multirepo_repo" ] || continue
-    multirepo_changelog="$multirepo_repo/CHANGELOG.md"
+    multirepo_changelog="${multirepo_changelog_override:-$multirepo_repo/CHANGELOG.md}"
     multirepo_issue=0
     multirepo_drift=0
     multirepo_changelog_ok=0
@@ -544,6 +559,10 @@ check_multirepo_drift() {
         ;;
     esac
 
+    if [ "$multirepo_contract" = "n/a" ] && [ "$multirepo_deployment" = "n/a" ]; then
+      echo "  · $multirepo_repo 已登记,无契约/部署版本域(contract=n/a, deployment=n/a),不做版本核对"
+      continue
+    fi
     if [ -L "$multirepo_changelog" ] \
         || { [ -e "$multirepo_changelog" ] \
           && path_uses_symlink_component "$ROOT_PHYS/$multirepo_changelog"; }; then
@@ -557,8 +576,8 @@ check_multirepo_drift() {
         "the mapped CHANGELOG version source was not readable"
       multirepo_issue=1
     elif [ ! -f "$multirepo_changelog" ]; then
-      echo "  ⚠️  $multirepo_repo 缺少可读 regular CHANGELOG.md"
-      add_finding "sync.unverified" "unverified" "Repo=$multirepo_repo has no readable regular CHANGELOG.md version source." "$multirepo_changelog"
+      echo "  ⚠️  $multirepo_repo 缺少可读 regular $multirepo_changelog"
+      add_finding "sync.unverified" "unverified" "Repo=$multirepo_repo has no readable regular CHANGELOG version source: $multirepo_changelog." "$multirepo_changelog"
       multirepo_issue=1
     else
       multirepo_changelog_version="$(read_changelog_head_version "$multirepo_changelog" || true)"
@@ -572,8 +591,14 @@ check_multirepo_drift() {
     fi
 
     multirepo_contract_rc=0
-    validate_reference "$multirepo_contract" "$multirepo_map_path" || multirepo_contract_rc=$?
-    if [ "$multirepo_contract_rc" -ne 0 ]; then
+    if [ "$multirepo_contract" = "n/a" ]; then
+      multirepo_contract_rc=0
+    else
+      validate_reference "$multirepo_contract" "$multirepo_map_path" || multirepo_contract_rc=$?
+    fi
+    if [ "$multirepo_contract" = "n/a" ]; then
+      :
+    elif [ "$multirepo_contract_rc" -ne 0 ]; then
       echo "  ⚠️  $multirepo_repo 的契约版本来源不可读:$multirepo_contract"
       if [ "$multirepo_contract_rc" -eq 4 ]; then
         add_scan_boundary "symlink" "$multirepo_contract" \
@@ -672,9 +697,9 @@ check_multirepo_drift() {
       add_finding "sync.multirepo_drift" "conflict" "Version sources disagree for repo=$multirepo_repo: $multirepo_changelog=$multirepo_changelog_fact; $multirepo_contract=$multirepo_contract_fact; $multirepo_deployment_fact." "$multirepo_changelog"
     elif [ "$multirepo_issue" -eq 0 ]; then
       if [ "$multirepo_deployment" = "n/a" ]; then
-        echo "  ✅ $multirepo_repo 多仓版本一致: CHANGELOG.md ↔ $multirepo_contract (deployment=n/a)"
+        echo "  ✅ $multirepo_repo 多仓版本一致: $multirepo_changelog ↔ $multirepo_contract (deployment=n/a)"
       else
-        echo "  ✅ $multirepo_repo 多仓版本一致: CHANGELOG.md ↔ $multirepo_contract ↔ $multirepo_baseline#apps.$multirepo_deployment.imageTag"
+        echo "  ✅ $multirepo_repo 多仓版本一致: $multirepo_changelog ↔ $multirepo_contract ↔ $multirepo_baseline#apps.$multirepo_deployment.imageTag"
       fi
     fi
   done < "$multirepo_records"

package/templates/v2/AGENTS.md

@@ -7,14 +7,15 @@
 
 ## 0. v2 下工作怎么发生（一页流程）
 
-1. **工作项**：每件事一个 `delivery/work/<WORK-ID>/`（`intent.md` 为什么做 + `plan.md` 怎么做，可选 `env-facts.md` 记踩出来的环境事实）；被 digest 绑定接受（`buildbeat-v2 accept`）前只是草稿、不产生义务。
+1. **工作项**：每件事一个 `delivery/work/<WORK-ID>/`（`intent.md` 为什么做 + **止损线**（最多几个 Run / 几轮 review / 几小时，越线先问所有者"继续还是砍"）+ `plan.md` 怎么做，可选 `env-facts.md` 记踩出来的环境事实）；被 digest 绑定接受（`buildbeat-v2 accept`）前只是草稿、不产生义务。`overview` 的 `cost:` 行就是止损线的读数。
 2. **代码工作跑 Run**：`buildbeat-v2 start --config <run-config.yaml> --attempt new` → 隔离 worktree 内 Build→Verify→Fix→Review 自动闭环 → **停在合并决定**。push、合并、部署永远是人批之后的人类动作。
 3. **人怎么知道该做什么**：`buildbeat-v2 overview --repo .` 回答「每件事走到哪、下一步该谁」；`inbox` 只列等人批的 Run，每条后面附可复制的下一句命令；`status --run <RUN>` 回答「还在动吗、动了多久、卡没卡」。
 4. **上线**：生产动作是人的；`release-readback` 预设 + `release` 风险预设把「做之前回读 → 人做 → 做之后回读 → 观察 → 人关窗」记成 L4 证据，任一步失败即停人批。
 5. **observe 盯生产**：`buildbeat-v2 observe run --config .buildbeat/observe.yaml` 一次=一轮只读体检；异常分层（落账→只读诊断→intent 草稿入队 `delivery/observe/intents/`），草稿**绝不自动执行**，人用 `observe triage` 分诊。
 6. **拍板台账**：平台级真实决策包一行进 `pm/decisions.md`；Run 级批准落各 Work 的 `decisions.jsonl`；finding 裁决落 `review-findings.jsonl`。契约在 `contracts/`。
 7. **通知**：`.buildbeat/notify.yaml` 配一条通道（URL 只能来自环境变量），Run 停在人批 / 终态 / 疑似卡住会来找人。
-8. **打扫**：终态 Run 留下的工作树用 `buildbeat-v2 gc --repo .` 清（默认只出计划）。
+8. **打扫**：终态 Run 留下的工作树用 `buildbeat-v2 gc --repo .` 清（默认只出计划）。工作树在仓内 `.buildbeat/worktrees/`：`.gitignore` 排除 `.buildbeat/runtime/` 与 `.buildbeat/worktrees/`，测试框架的收集范围也要排除 `**/.buildbeat/**`（vitest `exclude`、jest `testPathIgnorePatterns`、pytest `norecursedirs`），否则主干测试会把旧候选的用例一起跑。
+9. **worker 环境事实（写进 worker prompt / 信封）**：worker 的沙箱通常**不能监听端口**，需要起服务或绑定 loopback 的集成测试交给 verify 步，worker 只跑单测与静态检查，不要反复尝试；PATH 只认 POSIX 工具（`grep -E` 不用 `rg`，`find` 不用 `fd`）或在 `requires:` 里声明；verify / 包装脚本发现环境不满足（命令不在 PATH、端口被占、后端 404）就 `exit 75`，内核会当基础设施故障停人、不派 fixer、不扣预算。
 
 ## 1. 工作包路由 —— Builder 端到端负责，会话按 AI 视角隔离