@haiyangbg/buildbeat 1.21.0 → 2.0.0-beta.2

package/src/v2/policy/policy.js

@@ -0,0 +1,302 @@
+// Policy engine per docs/v2/RFC-0003-workflow-policy.md §4. Policies are
+// declarative YAML documents; rules evaluate under three-valued logic
+// (true / false / "unverified") and UNVERIFIED is never treated as PASS.
+// Parsing is fail-closed: unknown operators, types, or fields are rejected.
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export class PolicyError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PolicyError";
+  }
+}
+
+const POLICY_TYPES = ["pre", "post", "transition", "action"];
+const ENFORCEMENTS = ["ADVISORY", "LOCAL_ENFORCED", "SERVER_ENFORCED"];
+const ON_FAIL = ["WAIT_HUMAN", "BLOCK"];
+const POLICY_FIELDS = new Set([
+  "kind",
+  "version",
+  "name",
+  "type",
+  "appliesTo",
+  "enforcement",
+  "onFail",
+  "rule",
+]);
+const GRADE_RANK = { L0: 0, L1: 1, L2: 2, L3: 3, L4: 4 };
+const SEVERITY_RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
+
+const OPERATORS = new Set([
+  "all",
+  "any",
+  "not",
+  "evidence.exists",
+  "artifact.accepted",
+  "attempts.lt",
+  "budget.remaining",
+  "candidate.clean",
+  "human.approved",
+  "finding.maxSeverity",
+]);
+
+function validateRule(rule, path = "rule") {
+  if (!rule || typeof rule !== "object" || Array.isArray(rule)) {
+    throw new PolicyError(`${path} must be a map with exactly one operator`);
+  }
+  const keys = Object.keys(rule);
+  if (keys.length !== 1) {
+    throw new PolicyError(`${path} must have exactly one operator, got: ${keys.join(", ")}`);
+  }
+  const op = keys[0];
+  if (!OPERATORS.has(op)) {
+    throw new PolicyError(`${path}: unknown operator "${op}"`);
+  }
+  const arg = rule[op];
+  if (op === "all" || op === "any") {
+    if (!Array.isArray(arg) || arg.length === 0) {
+      throw new PolicyError(`${path}.${op} requires a non-empty list of rules`);
+    }
+    arg.forEach((child, index) => validateRule(child, `${path}.${op}[${index}]`));
+  } else if (op === "not") {
+    validateRule(arg, `${path}.not`);
+  }
+  return rule;
+}
+
+export function parsePolicyDoc(doc) {
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+    throw new PolicyError("policy document must be a map");
+  }
+  for (const key of Object.keys(doc)) {
+    if (!POLICY_FIELDS.has(key)) {
+      throw new PolicyError(`unknown field "${key}" in policy ${doc.name ?? "(unnamed)"}`);
+    }
+  }
+  if (doc.kind !== "policy") {
+    throw new PolicyError(`kind must be "policy", got: ${JSON.stringify(doc.kind)}`);
+  }
+  if (doc.version !== 1) {
+    throw new PolicyError(`unsupported policy version: ${JSON.stringify(doc.version)}`);
+  }
+  if (typeof doc.name !== "string" || doc.name.length === 0) {
+    throw new PolicyError("policy needs a name");
+  }
+  if (!POLICY_TYPES.includes(doc.type)) {
+    throw new PolicyError(`policy ${doc.name}: type must be one of ${POLICY_TYPES.join("|")}`);
+  }
+  if (typeof doc.appliesTo !== "string" || doc.appliesTo.length === 0) {
+    throw new PolicyError(`policy ${doc.name}: appliesTo is required`);
+  }
+  if (!ENFORCEMENTS.includes(doc.enforcement)) {
+    throw new PolicyError(
+      `policy ${doc.name}: enforcement must be one of ${ENFORCEMENTS.join("|")}`,
+    );
+  }
+  if (doc.onFail !== undefined && !ON_FAIL.includes(doc.onFail)) {
+    throw new PolicyError(`policy ${doc.name}: onFail must be one of ${ON_FAIL.join("|")}`);
+  }
+  validateRule(doc.rule, `policy ${doc.name} rule`);
+  return {
+    name: doc.name,
+    type: doc.type,
+    appliesTo: doc.appliesTo,
+    enforcement: doc.enforcement,
+    onFail: doc.onFail ?? "WAIT_HUMAN",
+    rule: doc.rule,
+  };
+}
+
+function combine(values, mode) {
+  // Three-valued logic: false dominates all(), true dominates any(),
+  // otherwise any "unverified" makes the result unverified.
+  if (mode === "all") {
+    if (values.some((value) => value.ok === false)) {
+      return values.find((value) => value.ok === false);
+    }
+    if (values.some((value) => value.ok === "unverified")) {
+      return values.find((value) => value.ok === "unverified");
+    }
+    return { ok: true, why: "all conditions hold" };
+  }
+  if (values.some((value) => value.ok === true)) {
+    return { ok: true, why: "a condition holds" };
+  }
+  if (values.some((value) => value.ok === "unverified")) {
+    return values.find((value) => value.ok === "unverified");
+  }
+  return { ok: false, why: values.map((value) => value.why).join("; ") };
+}
+
+export function sha256Text(text) {
+  return `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`;
+}
+
+// ctx: { state, workDir, worktreePath, readWorktree() -> {head, dirty} | null }
+export function evaluateRule(rule, ctx) {
+  const op = Object.keys(rule)[0];
+  const arg = rule[op];
+  switch (op) {
+    case "all":
+      return combine(arg.map((child) => evaluateRule(child, ctx)), "all");
+    case "any":
+      return combine(arg.map((child) => evaluateRule(child, ctx)), "any");
+    case "not": {
+      const inner = evaluateRule(arg, ctx);
+      if (inner.ok === "unverified") {
+        return inner;
+      }
+      return { ok: !inner.ok, why: `not(${inner.why})` };
+    }
+    case "evidence.exists": {
+      const minRank = arg.minGrade !== undefined ? GRADE_RANK[arg.minGrade] : 0;
+      if (minRank === undefined) {
+        return { ok: "unverified", why: `unknown grade ${arg.minGrade}` };
+      }
+      // When the context names a candidate (e.g. a merge approval), only
+      // evidence about that candidate counts — facts about superseded
+      // candidates must not satisfy a gate for the current one.
+      const scoped = ctx.candidate
+        ? ctx.state.evidence.filter((item) => item.subject === ctx.candidate)
+        : ctx.state.evidence;
+      const hit = scoped.some(
+        (item) =>
+          item.kind === arg.kind &&
+          item.status === "passed" &&
+          (GRADE_RANK[item.grade] ?? -1) >= minRank,
+      );
+      return hit
+        ? { ok: true, why: `evidence ${arg.kind} present` }
+        : {
+            ok: false,
+            why: `no passed evidence of kind ${arg.kind}${arg.minGrade ? ` at grade >= ${arg.minGrade}` : ""}${ctx.candidate ? " for the current candidate" : ""}`,
+          };
+    }
+    case "artifact.accepted": {
+      const artifact = arg.artifact;
+      const filePath = join(ctx.workDir, `${artifact}.md`);
+      if (!existsSync(filePath)) {
+        return { ok: "unverified", why: `artifact file missing: ${artifact}.md` };
+      }
+      const decisionsPath = join(ctx.workDir, "decisions.jsonl");
+      if (!existsSync(decisionsPath)) {
+        return { ok: false, why: `artifact ${artifact} has never been accepted` };
+      }
+      const accepts = readFileSync(decisionsPath, "utf8")
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => JSON.parse(line))
+        .filter(
+          (line) => line.transition === `accept-${artifact}` && line.decision === "approved",
+        );
+      if (accepts.length === 0) {
+        return { ok: false, why: `artifact ${artifact} has never been accepted` };
+      }
+      const latest = accepts[accepts.length - 1];
+      const currentDigest = sha256Text(readFileSync(filePath, "utf8"));
+      if (latest.subject?.digest !== currentDigest) {
+        return {
+          ok: false,
+          why: `artifact ${artifact} changed after its acceptance (stale acceptance)`,
+        };
+      }
+      return { ok: true, why: `artifact ${artifact} accepted at current digest` };
+    }
+    case "attempts.lt": {
+      const attempts = ctx.state.steps[arg.step]?.attempts ?? 0;
+      return attempts < arg.max
+        ? { ok: true, why: `${arg.step} attempts ${attempts} < ${arg.max}` }
+        : { ok: false, why: `${arg.step} attempts ${attempts} reached ${arg.max}` };
+    }
+    case "budget.remaining": {
+      const budget = ctx.state.budgets[arg.kind];
+      if (!budget) {
+        return { ok: true, why: `budget ${arg.kind} untouched` };
+      }
+      return budget.remaining > 0
+        ? { ok: true, why: `budget ${arg.kind} remaining ${budget.remaining}` }
+        : { ok: false, why: `budget ${arg.kind} exhausted` };
+    }
+    case "candidate.clean": {
+      const tree = ctx.readWorktree();
+      if (!tree) {
+        return { ok: "unverified", why: "worktree not available for readback" };
+      }
+      return tree.dirty
+        ? { ok: false, why: "worktree is dirty" }
+        : { ok: true, why: "worktree is clean" };
+    }
+    case "human.approved": {
+      const hit = ctx.state.approvals.some(
+        (approval) => !approval.stale && approval.transition === arg.transition,
+      );
+      return hit
+        ? { ok: true, why: `transition ${arg.transition} approved` }
+        : { ok: false, why: `no active approval for transition ${arg.transition}` };
+    }
+    case "finding.maxSeverity": {
+      const atMostRank = SEVERITY_RANK[arg.atMost];
+      if (atMostRank === undefined) {
+        return { ok: "unverified", why: `unknown severity ${arg.atMost}` };
+      }
+      // Findings against superseded candidates are history, not verdicts:
+      // a blocked round-1 review that the fix loop already addressed must
+      // not poison the gate for the final candidate. When the context
+      // names a candidate, judge only reviews of that candidate.
+      const reviews = ctx.state.evidence.filter(
+        (item) =>
+          item.kind === "review" && (!ctx.candidate || item.subject === ctx.candidate),
+      );
+      if (reviews.length === 0) {
+        return {
+          ok: "unverified",
+          why: ctx.candidate
+            ? "no review evidence for the current candidate"
+            : "no review evidence to judge findings",
+        };
+      }
+      const findings = reviews.flatMap((item) => item.findings ?? []);
+      const tooSevere = findings.filter(
+        (finding) => (SEVERITY_RANK[finding.severity] ?? 0) < atMostRank,
+      );
+      return tooSevere.length === 0
+        ? { ok: true, why: `no findings above ${arg.atMost}` }
+        : {
+            ok: false,
+            why: `${tooSevere.length} finding(s) more severe than ${arg.atMost}`,
+          };
+    }
+    default:
+      return { ok: "unverified", why: `unknown operator ${op}` };
+  }
+}
+
+// Evaluates every policy of `type` whose appliesTo matches; returns rows of
+// { policy, result, reason, enforcement } where result is a GateResult.
+export function evaluatePolicies(policies, { type, appliesTo }, ctx) {
+  const rows = [];
+  for (const policy of policies ?? []) {
+    if (policy.type !== type || policy.appliesTo !== appliesTo) {
+      continue;
+    }
+    const verdict = evaluateRule(policy.rule, ctx);
+    let result;
+    if (verdict.ok === true) {
+      result = "PASS";
+    } else if (verdict.ok === "unverified") {
+      result = "UNVERIFIED";
+    } else {
+      result = policy.onFail;
+    }
+    rows.push({
+      policy: policy.name,
+      result,
+      reason: verdict.why,
+      enforcement: policy.enforcement,
+    });
+  }
+  return rows;
+}

package/src/v2/presets/observe.yaml

@@ -0,0 +1,45 @@
+# observe workflow preset per docs/v2/RFC-0003-workflow-policy.md §8 (frozen
+# shape; block form — the strict YAML subset has no inline {}/[]).
+# One `observe run` invocation = one cycle; scheduling is host-level in v0
+# (cron/CI invoking the CLI). Copy to <repo>/.buildbeat/observe.yaml and
+# point commands at the project's real probes.
+kind: workflow
+version: 1
+name: observe
+providers:
+  - id: drift-check
+    command: bash
+    args:
+      - scripts/drift-check.sh
+    schedule: manual
+    evidence:
+      kind: drift
+      subject: deploy-unit
+    severity:
+      failed: error
+      unverified: warn
+    diagnose:
+      command: bash
+      args:
+        - scripts/live-status.sh
+  - id: live-status
+    command: bash
+    args:
+      - scripts/live-status.sh
+    schedule: manual
+    evidence:
+      kind: runtime-health
+      subject: deploy-unit
+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/presets/policies/ui-render-gate.yaml

@@ -0,0 +1,13 @@
+# Invariant 22 (v1 lessons #3, machine form): a UI delivery's spec approval
+# subject must include renderable proof — a screenshot with a digest —
+# before a human may stamp it. Static prose is not an approvable design.
+kind: policy
+version: 1
+name: ui-render-gate
+type: transition
+appliesTo: enter-spec
+enforcement: LOCAL_ENFORCED
+rule:
+  evidence.exists:
+    kind: screenshot
+    minGrade: L2

package/src/v2/presets/risk/controlled.yaml

@@ -0,0 +1,39 @@
+# Controlled lane: intent AND plan must be accepted artifacts before build;
+# merge stays human behind a stricter evidence floor. The release gate from
+# the controlled track is out of MVP scope (no deploy capability exists) and
+# returns with observe/release work in M5.
+kind: risk-preset
+version: 1
+name: controlled
+policies:
+  - kind: policy
+    version: 1
+    name: intent-accepted
+    type: pre
+    appliesTo: build
+    enforcement: LOCAL_ENFORCED
+    rule:
+      artifact.accepted:
+        artifact: intent
+  - kind: policy
+    version: 1
+    name: plan-accepted
+    type: pre
+    appliesTo: build
+    enforcement: LOCAL_ENFORCED
+    rule:
+      artifact.accepted:
+        artifact: plan
+  - kind: policy
+    version: 1
+    name: merge-evidence-floor
+    type: transition
+    appliesTo: enter-wait-merge
+    enforcement: LOCAL_ENFORCED
+    rule:
+      all:
+        - evidence.exists:
+            kind: command
+            minGrade: L2
+        - finding.maxSeverity:
+            atMost: P3

package/src/v2/presets/risk/fast.yaml

@@ -0,0 +1,19 @@
+# Fast lane: automatic plan/build/verify/review, human merge decision only.
+# The merge gate still demands read-back evidence and a clean review.
+kind: risk-preset
+version: 1
+name: fast
+policies:
+  - kind: policy
+    version: 1
+    name: merge-evidence-floor
+    type: transition
+    appliesTo: enter-wait-merge
+    enforcement: LOCAL_ENFORCED
+    rule:
+      all:
+        - evidence.exists:
+            kind: command
+            minGrade: L2
+        - finding.maxSeverity:
+            atMost: P2

package/src/v2/presets/risk/legacy-four-gates.yaml

@@ -0,0 +1,44 @@
+# Migration preset mapping BuildBeat v1's four fixed gates:
+#   Gate1 (requirements) -> intent acceptance (digest-bound)
+#   Gate2 (design)       -> plan acceptance + human boundary before build
+#   Gate3 (merge)        -> the built-in final merge decision
+#   Gate4 (release)      -> out of MVP scope (no deploy capability exists)
+# The extra human boundary before review preserves v1's late review gate.
+kind: risk-preset
+version: 1
+name: legacy-four-gates
+stopAt:
+  - build
+  - review
+policies:
+  - kind: policy
+    version: 1
+    name: intent-accepted
+    type: pre
+    appliesTo: build
+    enforcement: LOCAL_ENFORCED
+    rule:
+      artifact.accepted:
+        artifact: intent
+  - kind: policy
+    version: 1
+    name: plan-accepted
+    type: pre
+    appliesTo: build
+    enforcement: LOCAL_ENFORCED
+    rule:
+      artifact.accepted:
+        artifact: plan
+  - kind: policy
+    version: 1
+    name: merge-evidence-floor
+    type: transition
+    appliesTo: enter-wait-merge
+    enforcement: LOCAL_ENFORCED
+    rule:
+      all:
+        - evidence.exists:
+            kind: command
+            minGrade: L2
+        - finding.maxSeverity:
+            atMost: P2

package/src/v2/presets/risk/standard.yaml

@@ -0,0 +1,28 @@
+# Standard lane: the plan must be an accepted artifact (digest-bound) before
+# build starts; merge stays a human decision behind the evidence floor.
+kind: risk-preset
+version: 1
+name: standard
+policies:
+  - kind: policy
+    version: 1
+    name: plan-accepted
+    type: pre
+    appliesTo: build
+    enforcement: LOCAL_ENFORCED
+    rule:
+      artifact.accepted:
+        artifact: plan
+  - kind: policy
+    version: 1
+    name: merge-evidence-floor
+    type: transition
+    appliesTo: enter-wait-merge
+    enforcement: LOCAL_ENFORCED
+    rule:
+      all:
+        - evidence.exists:
+            kind: command
+            minGrade: L2
+        - finding.maxSeverity:
+            atMost: P2

package/src/v2/presets/software-delivery.yaml

@@ -0,0 +1,39 @@
+# Official software-delivery preset per docs/v2/RFC-0003-workflow-policy.md §2.
+# Step order defines the happy path (each step chains to the next on
+# "succeeded"); fix sits off-path at the end and is reached only via the
+# explicit failure/findings transitions.
+kind: workflow
+version: 1
+name: software-delivery
+entry: intent
+steps:
+  - id: intent
+    worker: planner
+  - id: spec
+    worker: planner
+    optional: true
+    requiredWhen: ui-delivery
+  - id: plan
+    worker: planner
+  - id: build
+    worker: builder
+  - id: verify
+    worker: verifier
+  - id: review
+    worker: reviewer
+    readonly: true
+  - id: wait-merge
+  - id: fix
+    worker: fixer
+transitions:
+  - from: verify
+    on: failed
+    to: fix
+  - from: fix
+    on: succeeded
+    to: verify
+  - from: review
+    on: findings-blocking
+    to: fix
+terminal:
+  - wait-merge