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

package/src/v2/runtime/overview.js

@@ -0,0 +1,301 @@
+// Work-level overview (iteration 08, C5): "where is this thing, and who
+// moves next" — the question the owner opened three sessions with
+// ("X 上线了吗 / 离上线还差多远 / 从每个系统说待办") and that inbox,
+// which only knows about runs waiting on a human, cannot answer.
+//
+// Everything here is derived: work directories and decision ledgers in the
+// Git plane, run ledgers in the runtime plane (run-records fill in for runs
+// whose runtime was wiped), and git ancestry for "merged". Nothing is
+// written.
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { EventLedger } from "../storage/event-ledger.js";
+import { latestAdjudications, readFindingsAccount } from "./findings.js";
+import { nextReply } from "./notify.js";
+import { computeWorkCost, renderWorkCost } from "./work-cost.js";
+
+function sha256File(path) {
+  return `sha256:${createHash("sha256").update(readFileSync(path, "utf8"), "utf8").digest("hex")}`;
+}
+
+export function readJsonl(path) {
+  if (!existsSync(path)) {
+    return [];
+  }
+  return readFileSync(path, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+export function artifactStatus(workDir, decisions, artifact) {
+  const path = join(workDir, `${artifact}.md`);
+  if (!existsSync(path)) {
+    return { exists: false, accepted: false, stale: false };
+  }
+  const digest = sha256File(path);
+  const accepts = decisions.filter((row) => row.transition === `accept-${artifact}` && row.decision === "approved");
+  const latest = accepts[accepts.length - 1];
+  if (!latest) {
+    return { exists: true, accepted: false, stale: false };
+  }
+  const stale = latest.subject?.digest !== digest;
+  return { exists: true, accepted: !stale, stale, by: latest.by, at: latest.ts };
+}
+
+function isAncestor(repoRoot, sha, ref) {
+  try {
+    execFileSync("git", ["-C", repoRoot, "merge-base", "--is-ancestor", sha, ref], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function headRef(repoRoot) {
+  try {
+    return execFileSync("git", ["-C", repoRoot, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "HEAD";
+  }
+}
+
+// Runs for a work: runtime ledgers first, run-records for the rest.
+function runsFor(repoRoot, workId) {
+  const runs = new Map();
+  const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
+  if (existsSync(runsDir)) {
+    for (const entry of readdirSync(runsDir)) {
+      const path = join(runsDir, entry, "events.jsonl");
+      if (!existsSync(path)) {
+        continue;
+      }
+      const ledger = EventLedger.open(path);
+      const state = ledger.state;
+      if (!state.run || state.run.work !== workId) {
+        continue;
+      }
+      runs.set(state.run.id, {
+        id: state.run.id,
+        status: state.run.status,
+        terminal: state.terminal,
+        pendingHuman: state.pendingHuman,
+        candidate: state.workspaces[state.run.id]?.candidate ?? null,
+        createdAt: ledger.events[0]?.ts ?? null,
+        lastAt: ledger.events[ledger.events.length - 1]?.ts ?? null,
+        workflow: state.run.workflowRef ?? null,
+        steps: Object.keys(state.steps),
+        state,
+        source: "runtime",
+      });
+    }
+  }
+  const recordsDir = join(repoRoot, "delivery", "work", workId, "runs");
+  if (existsSync(recordsDir)) {
+    for (const entry of readdirSync(recordsDir)) {
+      if (runs.has(entry)) {
+        continue;
+      }
+      const path = join(recordsDir, entry, "run-record.json");
+      if (!existsSync(path)) {
+        continue;
+      }
+      try {
+        const record = JSON.parse(readFileSync(path, "utf8"));
+        runs.set(entry, {
+          id: entry,
+          status: record.terminal?.status ?? "UNKNOWN",
+          terminal: record.terminal ?? null,
+          pendingHuman: null,
+          candidate: record.workspaces?.[entry]?.candidate ?? null,
+          createdAt: record.startedAt ?? null,
+          lastAt: record.finishedAt ?? null,
+          workflow: record.workflow ?? null,
+          steps: Object.keys(record.attempts ?? {}),
+          state: null,
+          source: "run-record",
+        });
+      } catch {
+        // an unreadable record is reported as absent, not guessed
+      }
+    }
+  }
+  return [...runs.values()].sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
+}
+
+export function computeOverview(repoRoot, { work = null, repoLabel = "." } = {}) {
+  const workRoot = join(repoRoot, "delivery", "work");
+  const rows = [];
+  if (!existsSync(workRoot)) {
+    return rows;
+  }
+  const mainRef = headRef(repoRoot);
+  for (const workId of readdirSync(workRoot).sort()) {
+    if (work && workId !== work) {
+      continue;
+    }
+    const workDir = join(workRoot, workId);
+    if (!existsSync(join(workDir, "intent.md")) && !existsSync(join(workDir, "plan.md")) && !existsSync(join(workDir, "decisions.jsonl")) && !existsSync(join(workDir, "runs"))) {
+      continue;
+    }
+    const decisions = readJsonl(join(workDir, "decisions.jsonl"));
+    const intent = artifactStatus(workDir, decisions, "intent");
+    const plan = artifactStatus(workDir, decisions, "plan");
+    const envFacts = existsSync(join(workDir, "env-facts.md"));
+    const findingRows = readFindingsAccount(repoRoot, workId);
+    const adjudicated = latestAdjudications(findingRows);
+    const openFindings = findingRows.filter(
+      (row) => row.kind === "finding" && (row.severity === "P0" || row.severity === "P1") && !adjudicated.has(row.fingerprint),
+    ).length;
+    const runs = runsFor(repoRoot, workId);
+    const live = runs.filter((run) => run.status !== "SUPERSEDED");
+    const latest = live[live.length - 1] ?? null;
+    // "Merged" is a fact about any candidate of the work, not only the
+    // latest run's: a pilot's shipped candidate sat behind a CANCELLED run
+    // (its in-run review budget ran out and closure happened elsewhere) and
+    // overview reported the shipped work as STOPPED_CANCELLED.
+    const mergedRun =
+      [...runs].reverse().find((run) => run.candidate && isAncestor(repoRoot, run.candidate, mainRef)) ?? null;
+    const merged = Boolean(mergedRun);
+    const RELEASE_STEPS = ["preflight", "apply-readback", "observe"];
+    const isReleaseLane = (run) =>
+      Boolean(run) && (run.workflow === "release-readback" || run.steps.some((step) => RELEASE_STEPS.includes(step)));
+
+    // A Work is closed by an explicit row in decisions.jsonl:
+    //   {"transition":"close-work","decision":"closed"|"cancelled","subject":{"result":"..."}}
+    // A live run (RUNNING / WAITING_HUMAN) contradicts a closure and wins, so a
+    // stale close row can never hide something that still needs a human.
+    const closure = [...decisions].reverse().find((row) => row.transition === "close-work");
+    const liveRun = latest && (latest.status === "RUNNING" || latest.status === "WAITING_HUMAN");
+
+    let stage;
+    let next;
+    if (closure && !liveRun) {
+      stage = closure.decision === "cancelled" ? "CANCELLED" : "CLOSED";
+      const result = typeof closure.subject?.result === "string" && closure.subject.result.length > 0 ? closure.subject.result : "see decisions.jsonl";
+      next = `${stage.toLowerCase()} @ ${closure.ts ?? "?"}: ${result.slice(0, 160)}`;
+    } else if (!intent.exists) {
+      stage = "NO_INTENT";
+      next = `write delivery/work/${workId}/intent.md (what and why), then plan.md`;
+    } else if (!latest) {
+      if (!plan.exists) {
+        stage = intent.accepted ? "INTENT_ACCEPTED" : "INTENT_DRAFT";
+        next = intent.accepted
+          ? `write delivery/work/${workId}/plan.md, then accept it`
+          : `buildbeat-v2 accept --repo ${repoLabel} --work ${workId} --artifact intent --by <you>`;
+      } else if (!plan.accepted) {
+        stage = plan.stale ? "PLAN_STALE" : "PLAN_DRAFT";
+        next = `buildbeat-v2 accept --repo ${repoLabel} --work ${workId} --artifact plan --by <you>${plan.stale ? "   # plan changed since acceptance" : ""}`;
+      } else {
+        stage = "READY_TO_RUN";
+        const configs = readdirSync(workDir).filter((name) => /^run-config.*\.ya?ml$/.test(name));
+        next =
+          configs.length > 0
+            ? `buildbeat-v2 start --config delivery/work/${workId}/${configs[0]} --attempt new`
+            : `no run-config in delivery/work/${workId}: write one, or close it with a decisions.jsonl row {"transition":"close-work","decision":"closed","subject":{"result":"..."}} if it was doc-only`;
+      }
+    } else if (latest.status === "RUNNING") {
+      stage = "RUNNING";
+      next = `buildbeat-v2 status --repo ${repoLabel} --run ${latest.id}`;
+    } else if (latest.status === "WAITING_HUMAN") {
+      stage = latest.pendingHuman?.kind === "final-decision" ? "MERGE_DECISION" : "WAITING_HUMAN";
+      const replies = latest.state ? nextReply({ repoLabel, state: latest.state }) : [];
+      next = replies[0] ?? `buildbeat-v2 inbox --repo ${repoLabel}`;
+    } else if (latest.status === "SUCCEEDED" && isReleaseLane(latest)) {
+      // A release-readback lane that reached wait-close and was approved is
+      // a closed release window, not "nothing to merge".
+      stage = "RELEASED";
+      next = `release window closed by ${latest.id}; close the work with a decisions.jsonl row {"transition":"close-work","decision":"closed","subject":{"result":"released"}}`;
+    } else if (merged) {
+      stage = "MERGED";
+      next =
+        `candidate ${mergedRun.candidate.slice(0, 7)} (${mergedRun.id}) is on ${mainRef}; release/deploy stays a human action; then buildbeat-v2 gc --repo ${repoLabel}` +
+        (latest.status !== "SUCCEEDED" ? `   # latest run ${latest.id} ended ${latest.status} after the merge` : "");
+    } else if (latest.status === "SUCCEEDED") {
+      stage = "MERGE_READY";
+      next = latest.candidate
+        ? `merge ${latest.candidate.slice(0, 7)} (run/${latest.id}) into ${mainRef} — manual, then push`
+        : "run succeeded without a candidate; nothing to merge";
+    } else {
+      stage = `STOPPED_${latest.status}`;
+      next = plan.accepted
+        ? `decide: retry (buildbeat-v2 start ... --attempt new) or close the work`
+        : `plan not accepted (${plan.exists ? "draft" : "missing"}); fix that before another run`;
+    }
+    rows.push({
+      work: workId,
+      stage,
+      intent,
+      plan,
+      envFacts,
+      openFindings,
+      runs: runs.length,
+      cost: runs.length > 0 ? computeWorkCost(repoRoot, workId) : null,
+      latest: latest
+        ? { id: latest.id, status: latest.status, candidate: latest.candidate, at: latest.lastAt, source: latest.source, terminalReason: latest.terminal?.reason ?? null, waiting: latest.pendingHuman?.transition ?? null }
+        : null,
+      merged,
+      mergedCandidate: mergedRun?.candidate ?? null,
+      next,
+    });
+  }
+  return rows;
+}
+
+function mark(status) {
+  if (!status.exists) {
+    return "–";
+  }
+  if (status.stale) {
+    return "stale";
+  }
+  return status.accepted ? "✓" : "draft";
+}
+
+export function renderOverview(rows) {
+  if (rows.length === 0) {
+    return "overview: no work items under delivery/work";
+  }
+  const lines = [];
+  for (const row of rows) {
+    lines.push(`${row.work}  ${row.stage}`);
+    const parts = [`intent ${mark(row.intent)}`, `plan ${mark(row.plan)}`, `runs ${row.runs}`];
+    const settled = ["MERGED", "RELEASED", "CLOSED", "CANCELLED"].includes(row.stage);
+    if (row.openFindings > 0 && !settled) {
+      // Unadjudicated, not necessarily unresolved: a fixer may have closed
+      // them without anyone recording a verdict. The number says "nobody
+      // ruled on these", which is exactly what a human should know.
+      parts.push(`unadjudicated P0/P1 findings ${row.openFindings}`);
+    }
+    if (row.envFacts) {
+      parts.push("env-facts ✓");
+    }
+    lines.push(`  ${parts.join(" · ")}`);
+    if (row.cost) {
+      // What this work has already consumed across every run, superseded
+      // ones included: the number a "continue or cut" decision needs.
+      lines.push(`  cost: ${renderWorkCost(row.cost)}`);
+    }
+    if (row.latest) {
+      const cand = row.latest.candidate
+        ? ` candidate ${row.latest.candidate.slice(0, 7)}${row.latest.candidate === row.mergedCandidate ? " (merged)" : ""}`
+        : "";
+      const wait = row.latest.waiting ? ` waiting ${row.latest.waiting}` : "";
+      const why = row.latest.terminalReason ? ` — ${row.latest.terminalReason.slice(0, 100)}` : "";
+      lines.push(`  latest ${row.latest.id} ${row.latest.status}${cand}${wait} @ ${row.latest.at ?? "?"}${why}`);
+    }
+    lines.push(`  next: ${row.next}`);
+  }
+  return lines.join("\n");
+}

package/src/v2/runtime/run-record.js

@@ -9,6 +9,7 @@ import { join, relative } from "node:path";
 
 import { canonicalJson } from "../storage/event-ledger.js";
 import { normalizeRepoRef } from "./repo-ref.js";
+import { ledgerCost } from "./work-cost.js";
 
 const KERNEL = { kind: "kernel", id: "orchestrator" };
 
@@ -40,12 +41,14 @@ export function writeRunRecord({ repoRoot, ledger, ts }) {
   const record = {
     run: first.run,
     work: first.work,
+    workflow: state.run?.workflowRef ?? null,
     terminal: state.terminal,
     events: { from: first.seq, to: last.seq, lastDigest: last.digest },
     startedAt: first.ts,
     finishedAt: last.ts,
     attempts,
     budgets: state.budgets,
+    cost: ledgerCost(ledger),
     workspaces,
     evidence,
     decisions: state.decisions,

package/src/v2/runtime/work-cost.js

@@ -0,0 +1,147 @@
+// Work-level cost (iteration 09): what a work has already consumed across
+// every run of it, superseded ones included. Per-run budgets were bypassed
+// by "one run per review round" (a pilot work ran 21 runs and 9 review
+// rounds while the preset's two-round cap never fired), and a work that ate
+// ten runs and a day was cut by the owner as "cost > benefit" with no
+// number in front of them. Derived only: runtime ledgers first, run-records
+// for runs whose runtime was wiped. Nothing is written.
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { EventLedger } from "../storage/event-ledger.js";
+import { readFindingsAccount } from "./findings.js";
+
+function emptyCost() {
+  return {
+    runs: 0,
+    reviewRounds: 0,
+    findings: 0,
+    humanWaits: 0,
+    infraFailures: 0,
+    workerMs: 0,
+    firstAt: null,
+    lastAt: null,
+  };
+}
+
+// Cost facts of one ledger: review rounds, human waits, infra failures and
+// worker wall time (STEP_STARTED → STEP_FINISHED per attempt).
+export function ledgerCost(ledger) {
+  const cost = { reviewRounds: 0, humanWaits: 0, infraFailures: 0, workerMs: 0 };
+  const open = new Map();
+  for (const event of ledger.events) {
+    if (event.type === "STEP_STARTED") {
+      open.set(`${event.data.step}#${event.data.attempt}`, Date.parse(event.ts));
+    } else if (event.type === "STEP_FINISHED") {
+      const key = `${event.data.step}#${event.data.attempt}`;
+      const startedAt = open.get(key);
+      if (startedAt !== undefined) {
+        const ms = Date.parse(event.ts) - startedAt;
+        if (Number.isFinite(ms) && ms > 0) {
+          cost.workerMs += ms;
+        }
+        open.delete(key);
+      }
+      if (event.data.step === "review") {
+        cost.reviewRounds += 1;
+      }
+      if (event.data.infra === true) {
+        cost.infraFailures += 1;
+      }
+    } else if (event.type === "HUMAN_REQUESTED") {
+      cost.humanWaits += 1;
+    }
+  }
+  return cost;
+}
+
+export function computeWorkCost(repoRoot, workId, { excludeRun = null } = {}) {
+  const cost = emptyCost();
+  const seen = new Set();
+  const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
+  if (existsSync(runsDir)) {
+    for (const entry of readdirSync(runsDir)) {
+      const path = join(runsDir, entry, "events.jsonl");
+      if (!existsSync(path)) {
+        continue;
+      }
+      const ledger = EventLedger.open(path);
+      const state = ledger.state;
+      if (ledger.corruption || !state.run || state.run.work !== workId) {
+        continue;
+      }
+      seen.add(state.run.id);
+      if (state.run.id === excludeRun) {
+        continue;
+      }
+      const row = ledgerCost(ledger);
+      cost.runs += 1;
+      cost.reviewRounds += row.reviewRounds;
+      cost.humanWaits += row.humanWaits;
+      cost.infraFailures += row.infraFailures;
+      cost.workerMs += row.workerMs;
+      track(cost, ledger.events[0]?.ts, ledger.events[ledger.events.length - 1]?.ts);
+    }
+  }
+  const recordsDir = join(repoRoot, "delivery", "work", workId, "runs");
+  if (existsSync(recordsDir)) {
+    for (const entry of readdirSync(recordsDir)) {
+      if (seen.has(entry) || entry === excludeRun) {
+        continue;
+      }
+      const path = join(recordsDir, entry, "run-record.json");
+      if (!existsSync(path)) {
+        continue;
+      }
+      let record;
+      try {
+        record = JSON.parse(readFileSync(path, "utf8"));
+      } catch {
+        continue;
+      }
+      cost.runs += 1;
+      // Records written before iteration 09 carry attempts and decisions
+      // only; the cost block is preferred when present.
+      cost.reviewRounds += record.cost?.reviewRounds ?? record.attempts?.review ?? 0;
+      cost.humanWaits += record.cost?.humanWaits ?? record.decisions?.length ?? 0;
+      cost.infraFailures += record.cost?.infraFailures ?? 0;
+      cost.workerMs += record.cost?.workerMs ?? 0;
+      track(cost, record.startedAt, record.finishedAt);
+    }
+  }
+  cost.findings = readFindingsAccount(repoRoot, workId).filter((row) => row.kind === "finding").length;
+  return cost;
+}
+
+function track(cost, firstAt, lastAt) {
+  if (firstAt && (!cost.firstAt || firstAt < cost.firstAt)) {
+    cost.firstAt = firstAt;
+  }
+  if (lastAt && (!cost.lastAt || lastAt > cost.lastAt)) {
+    cost.lastAt = lastAt;
+  }
+}
+
+export function formatWorkerMs(ms) {
+  if (!ms || ms < 1000) {
+    return "0s";
+  }
+  if (ms < 60000) {
+    return `${Math.round(ms / 1000)}s`;
+  }
+  const totalMinutes = Math.round(ms / 60000);
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  return hours > 0 ? `${hours}h${String(minutes).padStart(2, "0")}m` : `${minutes}m`;
+}
+
+export function renderWorkCost(cost) {
+  return [
+    `review rounds ${cost.reviewRounds}`,
+    `findings ${cost.findings}`,
+    `human waits ${cost.humanWaits}`,
+    ...(cost.infraFailures > 0 ? [`infra failures ${cost.infraFailures}`] : []),
+    `worker ${formatWorkerMs(cost.workerMs)}`,
+  ].join(" · ");
+}

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"