@haiyangbg/buildbeat 3.3.1 → 4.0.0

package/docs/v2/skill/07-templates-and-lessons.md

@@ -1,24 +0,0 @@
-# BuildBeat 方法论 · 模板索引与实战教训（原 §9–§10）
-
-> 从 [`SKILL.md`](../../../SKILL.md) 移出的正文，原文与原节号不变，只调整了相对链接；入口、驾驶手册与红线摘要仍在 `SKILL.md`。
-
-## 9. 模板索引(templates/,直接拷贝后改占位符)
-
-| 模板 | 用途 |
-|---|---|
-| [templates/v2/AGENTS.md](../../../templates/v2/AGENTS.md) / [templates/v2/指挥台.md](../../../templates/v2/指挥台.md) | **项目装载入口**:一页流程 + 视角路由 + 十一条规则(含可见命名进决策卡)+ 红线;指挥台是"用户一句话 → 会话调什么"的操作卡 |
-| [templates/v2/CLAUDE.md](../../../templates/v2/CLAUDE.md) / [templates/v2/BUILDBEAT.md](../../../templates/v2/BUILDBEAT.md) | 一行指针与版本标记(运行时版本、装载方式、升级 = 升级 CLI、回灌通道) |
-| [templates/v2/run-config.example.yaml](../../../templates/v2/run-config.example.yaml) | 可原样解析的 run 配置样板(含 fixer、reviewTriage、budgets、cache、envelope、redact);机器验证见 `tests/v2-templates-firstrun.test.js` |
-| [templates/v2/envelope/worker.sh](../../../templates/v2/envelope/worker.sh) + [prompts/](../../../templates/v2/envelope/prompts/builder.md) | worker 包装(工具缺失 exit 75、喂 prompt、写入步机械 commit、只读步落信封)与 builder / reviewer / fixer 三份 prompt;拷到仓级 `delivery/envelope/` |
-| [templates/pm/decisions.md](../../../templates/pm/decisions.md) | 平台级决策包台账(全工作区唯一决策单点;Run 级批准由内核落 `decisions.jsonl`) |
-| [templates/pm/adr/README.md](../../../templates/pm/adr/README.md) / [ADR 模板](../../../templates/pm/adr/ADR-0000-template.md) | 可选 ADR 判据、四态 Status 与替代链;默认不生成 |
-| [templates/contracts/PROTOCOL.md](../../../templates/contracts/PROTOCOL.md) | 跨边界契约唯一入口骨架(多仓项目) |
-| [templates/ARCHITECTURE.md](../../../templates/ARCHITECTURE.md) | 全栈总图骨架(架构/基础设施/凭据位置/子项目索引;多仓项目) |
-| [templates/standards/STACK.md](../../../templates/standards/STACK.md) / [CODE](../../../templates/standards/CODE.md) / [REVIEW](../../../templates/standards/REVIEW.md) / [DESIGN](../../../templates/standards/DESIGN.md) | 可选 project-owned 规范(Policy 输入工件);缺失跳过,Draft 显式待确认,DESIGN 仅 UI 项目 |
-| [templates/gitignore.template](../../../templates/gitignore.template) | 工作区 .gitignore 模板(排除子仓、*.env、`.buildbeat/runtime/`、`.buildbeat/worktrees/`;拷入后改名) |
-
-> 运行时命令面(`accept / start / resume / status / inbox / overview / approve / reject / findings / doctor / preflight / gc / metrics / observe / watch`)见 [docs/v2/guide/README.md](../guide/README.md);Skill-only 手工路径 / 运行时 / Claude 插件各自的可用面见 [docs/CAPABILITY-MATRIX.md](../../CAPABILITY-MATRIX.md)。
-
-## 10. 反模式与实战教训
-
-血泪清单(每条都真实发生过)见 [lessons.md](../../../lessons.md)——SSOT 腐烂、读过期 race、静态稿拍板返工螺旋、视角过细收敛史、"当前版本"声明漂移、走查漏独立弹窗、构建产物混入他人 WIP、平台侧配置漂移、UI 元注释复发、核查门吞掉交付、追踪项当任务边界、等待找不到人、预算是刹车不是墙、基础设施故障当候选失败、台账说的和人看到的不是一回事等。**搭完骨架后建议通读一遍,大部分零件就是为这些坑而生。**

package/example/.buildbeat/observe.yaml

@@ -1,31 +0,0 @@
-# observe 配置样例：一次 `buildbeat observe run --config .buildbeat/observe.yaml` = 一轮只读体检。
-# 简账没有线上环境，这里只挂一个"测试还绿吗"的探针，示范 provider 的形状；真实项目换成部署平台的只读查询。
-kind: workflow
-version: 1
-name: observe
-providers:
-  - id: tests-green
-    command: bash
-    args:
-      - -lc
-      - npm test
-    schedule: manual
-    evidence:
-      kind: health
-      subject: jianzhang-tests
-    severity:
-      failed: error
-      unverified: warn
-bands:
-  - level: log
-    when: "severity >= info"
-  - level: diagnose
-    when: "severity >= error"
-  - level: intent
-    when: "severity >= error"
-triage:
-  actions:
-    - fix_now
-    - schedule
-    - dismiss
-  dismissFeedback: bands

package/src/v2/observe/observe-config.js

@@ -1,194 +0,0 @@
-// observe.yaml loader per docs/v2/RFC-0003-workflow-policy.md §8 (frozen
-// shape, block form — the strict YAML subset rejects inline {}/[]). Fail
-// closed: any shape violation is an error, never a default.
-
-import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
-import { basename, dirname, resolve } from "node:path";
-
-import {
-  OBSERVE_BAND_LEVELS,
-  OBSERVE_SEVERITIES,
-  TRIAGE_ACTIONS,
-} from "../domain/model.js";
-import { parseYamlSubset } from "../engine/yaml-subset.js";
-
-export class ObserveConfigError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ObserveConfigError";
-  }
-}
-
-const WHEN_PATTERN = /^severity\s*>=\s*(info|warn|error|critical)$/;
-
-export function severityRank(severity) {
-  const rank = OBSERVE_SEVERITIES.indexOf(severity);
-  if (rank === -1) {
-    throw new ObserveConfigError(`unknown severity: ${severity}`);
-  }
-  return rank;
-}
-
-function requireString(value, label) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new ObserveConfigError(`${label} must be a non-empty string`);
-  }
-  return value;
-}
-
-function parseSeverityMap(raw, providerId) {
-  const map = { failed: "error", unverified: "warn" };
-  if (raw === undefined) {
-    return map;
-  }
-  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
-    throw new ObserveConfigError(`provider ${providerId}: severity must be a map`);
-  }
-  for (const [key, value] of Object.entries(raw)) {
-    if (key !== "failed" && key !== "unverified") {
-      throw new ObserveConfigError(`provider ${providerId}: severity.${key} is not a known key`);
-    }
-    if (!OBSERVE_SEVERITIES.includes(value)) {
-      throw new ObserveConfigError(
-        `provider ${providerId}: severity.${key} must be one of ${OBSERVE_SEVERITIES.join("|")}`,
-      );
-    }
-    map[key] = value;
-  }
-  return map;
-}
-
-function parseProvider(raw, index) {
-  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
-    throw new ObserveConfigError(`providers[${index}] must be a map`);
-  }
-  const id = requireString(raw.id, `providers[${index}].id`);
-  const command = requireString(raw.command, `provider ${id}: command`);
-  const args = raw.args ?? [];
-  if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string" && typeof arg !== "number")) {
-    throw new ObserveConfigError(`provider ${id}: args must be a list of scalars`);
-  }
-  if (raw.evidence === null || typeof raw.evidence !== "object" || Array.isArray(raw.evidence)) {
-    throw new ObserveConfigError(`provider ${id}: evidence must be a map with kind and subject`);
-  }
-  const evidence = {
-    kind: requireString(raw.evidence.kind, `provider ${id}: evidence.kind`),
-    subject: requireString(raw.evidence.subject, `provider ${id}: evidence.subject`),
-  };
-  let diagnose = null;
-  if (raw.diagnose !== undefined) {
-    if (raw.diagnose === null || typeof raw.diagnose !== "object" || Array.isArray(raw.diagnose)) {
-      throw new ObserveConfigError(`provider ${id}: diagnose must be a map with command`);
-    }
-    const diagnoseArgs = raw.diagnose.args ?? [];
-    if (!Array.isArray(diagnoseArgs)) {
-      throw new ObserveConfigError(`provider ${id}: diagnose.args must be a list`);
-    }
-    diagnose = {
-      command: requireString(raw.diagnose.command, `provider ${id}: diagnose.command`),
-      args: diagnoseArgs.map((arg) => String(arg)),
-      timeoutMs: raw.diagnose.timeoutMs,
-    };
-  }
-  return {
-    id,
-    command,
-    args: args.map((arg) => String(arg)),
-    schedule: raw.schedule === undefined ? "manual" : String(raw.schedule),
-    evidence,
-    severity: parseSeverityMap(raw.severity, id),
-    diagnose,
-    timeoutMs: raw.timeoutMs,
-  };
-}
-
-function parseBands(raw) {
-  if (!Array.isArray(raw) || raw.length !== OBSERVE_BAND_LEVELS.length) {
-    throw new ObserveConfigError(
-      `bands must list exactly the three levels ${OBSERVE_BAND_LEVELS.join(", ")} in order`,
-    );
-  }
-  return raw.map((band, index) => {
-    const expectedLevel = OBSERVE_BAND_LEVELS[index];
-    if (band === null || typeof band !== "object" || Array.isArray(band)) {
-      throw new ObserveConfigError(`bands[${index}] must be a map`);
-    }
-    if (band.level !== expectedLevel) {
-      throw new ObserveConfigError(
-        `bands[${index}].level must be ${expectedLevel} (levels are fixed), got: ${band.level}`,
-      );
-    }
-    const when = requireString(band.when, `band ${expectedLevel}: when`);
-    const match = WHEN_PATTERN.exec(when.trim());
-    if (!match) {
-      throw new ObserveConfigError(
-        `band ${expectedLevel}: when must match "severity >= <level>", got: ${when}`,
-      );
-    }
-    return { level: expectedLevel, minSeverity: match[1] };
-  });
-}
-
-function parseTriage(raw) {
-  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
-    throw new ObserveConfigError("triage must be a map");
-  }
-  const actions = raw.actions;
-  if (
-    !Array.isArray(actions) ||
-    actions.length !== TRIAGE_ACTIONS.length ||
-    TRIAGE_ACTIONS.some((action, index) => actions[index] !== action)
-  ) {
-    throw new ObserveConfigError(
-      `triage.actions must be exactly [${TRIAGE_ACTIONS.join(", ")}] (closed set)`,
-    );
-  }
-  if (raw.dismissFeedback !== "bands") {
-    throw new ObserveConfigError('triage.dismissFeedback must be "bands"');
-  }
-  return { actions: [...TRIAGE_ACTIONS], dismissFeedback: "bands" };
-}
-
-export function loadObserveConfig(configPath) {
-  const absolutePath = resolve(configPath);
-  const text = readFileSync(absolutePath, "utf8");
-  const raw = parseYamlSubset(text);
-  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
-    throw new ObserveConfigError("observe config must be a YAML map");
-  }
-  if (raw.kind !== "workflow") {
-    throw new ObserveConfigError(`kind must be workflow, got: ${raw.kind}`);
-  }
-  if (raw.version !== 1) {
-    throw new ObserveConfigError(`unsupported observe config version: ${raw.version}`);
-  }
-  if (raw.name !== "observe") {
-    throw new ObserveConfigError(`name must be observe, got: ${raw.name}`);
-  }
-  if (!Array.isArray(raw.providers) || raw.providers.length === 0) {
-    throw new ObserveConfigError("providers must be a non-empty list");
-  }
-  const providers = raw.providers.map((provider, index) => parseProvider(provider, index));
-  const ids = new Set();
-  for (const provider of providers) {
-    if (ids.has(provider.id)) {
-      throw new ObserveConfigError(`duplicate provider id: ${provider.id}`);
-    }
-    ids.add(provider.id);
-  }
-  const configDir = dirname(absolutePath);
-  const repoRoot = raw.repo
-    ? resolve(configDir, String(raw.repo))
-    : basename(configDir) === ".buildbeat"
-      ? dirname(configDir)
-      : configDir;
-  return {
-    configPath: absolutePath,
-    configDigest: `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`,
-    repoRoot,
-    providers,
-    bands: parseBands(raw.bands),
-    triage: parseTriage(raw.triage),
-  };
-}

package/src/v2/observe/observe-reducer.js

@@ -1,117 +0,0 @@
-// Deterministic reducer for the observe ledger (RFC-0003 §8, implemented M5).
-// Shares envelope/chain rules with the run ledger via EventLedger's pluggable
-// reducer; state here is a runtime view only — triage terminal state lives in
-// the Git-plane intent draft files (invariant 23: runtime is deletable).
-
-export class IllegalObserveEventError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "IllegalObserveEventError";
-  }
-}
-
-export function observeInitialState() {
-  return {
-    seq: 0,
-    cycles: 0,
-    activeCycle: null,
-    providers: {},
-    evidence: [],
-    bands: [],
-    intents: {},
-    triage: [],
-  };
-}
-
-export function applyObserveEvent(state, event) {
-  if (event.seq !== state.seq + 1) {
-    throw new IllegalObserveEventError(`expected seq ${state.seq + 1}, got ${event.seq}`);
-  }
-  const { type, data } = event;
-  const next = structuredClone(state);
-  next.seq = event.seq;
-
-  switch (type) {
-    case "OBSERVE_CYCLE_STARTED": {
-      if (state.activeCycle !== null) {
-        // A crashed cycle never finished; the new cycle supersedes it. Facts
-        // already appended stand; nothing is repaired.
-        next.activeCycle = null;
-      }
-      if (data.cycle !== state.cycles + 1) {
-        throw new IllegalObserveEventError(
-          `expected cycle ${state.cycles + 1}, got ${data.cycle}`,
-        );
-      }
-      next.activeCycle = { cycle: data.cycle, configDigest: data.configDigest, ts: event.ts };
-      next.cycles = data.cycle;
-      break;
-    }
-    case "OBSERVE_CYCLE_FINISHED": {
-      if (!state.activeCycle || state.activeCycle.cycle !== data.cycle) {
-        throw new IllegalObserveEventError(`no active cycle ${data.cycle} to finish`);
-      }
-      next.activeCycle = null;
-      break;
-    }
-    case "EVIDENCE_RECORDED": {
-      next.evidence.push({
-        ref: data.evidenceRef,
-        kind: data.kind,
-        subject: data.subject,
-        digest: data.digest,
-        status: data.status,
-        grade: data.grade,
-        ...(data.provider ? { provider: data.provider } : {}),
-        ...(data.cycle !== undefined ? { cycle: data.cycle } : {}),
-      });
-      if (data.provider) {
-        next.providers[data.provider] = {
-          lastStatus: data.status,
-          lastKind: data.kind,
-          lastSubject: data.subject,
-          lastEvidenceRef: data.evidenceRef,
-          lastTs: event.ts,
-        };
-      }
-      break;
-    }
-    case "BAND_TRIGGERED": {
-      next.bands.push({
-        provider: data.provider,
-        band: data.band,
-        severity: data.severity,
-        fingerprint: data.fingerprint,
-        ts: event.ts,
-      });
-      break;
-    }
-    case "INTENT_DRAFTED": {
-      next.intents[data.fingerprint] = {
-        intentRef: data.intentRef,
-        provider: data.provider,
-        severity: data.severity,
-        ts: event.ts,
-      };
-      break;
-    }
-    case "TRIAGE_RECORDED": {
-      next.triage.push({
-        intentRef: data.intentRef,
-        action: data.action,
-        fingerprint: data.fingerprint,
-        ts: event.ts,
-      });
-      break;
-    }
-    default:
-      // Unknown type written by a newer version: preserved, skipped.
-      break;
-  }
-  return next;
-}
-
-export const OBSERVE_REDUCER = {
-  initialState: observeInitialState,
-  applyEvent: applyObserveEvent,
-};