@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/scripts/gate-ledger.mjs

@@ -0,0 +1,449 @@
+#!/usr/bin/env node
+/**
+ * gate-ledger.mjs  -  the one writer of `state.gates[]`, and the commit-time
+ * check that reads it.
+ *
+ * In an unattended run every verification gate appends one entry per verdict:
+ *
+ *   { gate, verdict: "pass" | "fail" | "not-applicable", at, sha, detail }
+ *
+ * `sha` is the repository HEAD the gate ran against. The pipeline commits only
+ * in Phase 4, so every gate of a run records the same HEAD, and the commit hook
+ * (pre-commit-check.sh) asks this file whether the latest entry of each
+ * mandatory gate for that HEAD passed. A gate the run skipped leaves no entry,
+ * and a missing entry blocks the commit the same way a failing one does.
+ *
+ * Entries are written while the quality gates are active (lib/unattended.mjs,
+ * gatesActive): MULTI_AGENT_UNATTENDED=1, or a run in autopilot mode. A run
+ * that is neither writes nothing and state.gates[] stays absent. The commit
+ * hook's REQUIREMENT is narrower: it applies only with the variable set, since
+ * it is security enforcement and a terminal autopilot run has a person at it.
+ *
+ * Writes take the same advisory lock as write-state.mjs (acquireLock /
+ * releaseLock / stillOurs), read-modify-write the whole document under it, bump
+ * `rev`, and land through tmpfile + rename. write-state's merge replaces arrays,
+ * so an append cannot go through it without losing a concurrent entry.
+ *
+ * The state is found by, in order: an explicit --state, the run whose
+ * `sessionId` equals MULTI_AGENT_SESSION_ID (the id the runner launched it
+ * with), the run whose `worktreePath` is this repository.
+ *
+ * Usage:
+ *   gate-ledger.mjs append --gate <id> --verdict pass|fail|not-applicable
+ *                  [--detail '<json>'] [--state <path>] [--repo <dir>]
+ *   gate-ledger.mjs check  [--state <path>] [--repo <dir>] [--sha <sha>] [--json]
+ *   gate-ledger.mjs park   --outcome awaiting-answer|verification-failed
+ *                  [--waiting-for <step>] [--gate <id>] [--reason <text>] [--state <path>]
+ *
+ *   `--waiting-for` takes `maturity` or `user-channels-choice` on the command
+ *   line. `question` needs the pendingQuestion it parks on, which the CLI does
+ *   not take, so it is refused (exit 2): a question park is written by the gate
+ *   that asks it, through park() (open-questions-gate.mjs).
+ *
+ * Exit: 0 written / check passed · 1 check failed · 2 usage · 3 no state or I/O error
+ *
+ * @module pipeline/scripts/gate-ledger
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { readRegularFile, readRegularJson } from "../lib/regular-file.mjs";
+import { attendedVerdict, gatesActive } from "../lib/unattended.mjs";
+import { listRuns, resolveRunFile } from "./_run-paths.mjs";
+import { acquireLock, releaseLock, stillOurs } from "./write-state.mjs";
+
+export const VERDICTS = ["pass", "fail", "not-applicable"];
+export const PASSING = new Set(["pass", "not-applicable"]);
+
+/**
+ * Gates whose latest entry for HEAD must pass before an unattended commit.
+ * `verify-citations` covers the pre-existing check too: both run on the triage
+ * output in one invocation. `review-decision` runs on the same output, the
+ * empty one included, and is the only check that refuses a rebuttal round.
+ */
+export const MANDATORY_AT_COMMIT = [
+  "open-questions",
+  "evidence-gate/build",
+  "evidence-gate/test",
+  "test-summary",
+  "test-strength",
+  "symbol-existence",
+  "verify-citations",
+  "review-decision",
+  "plan-coverage",
+];
+
+export class LedgerError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/**
+ * HEAD of the repository at `dir`, or null outside one.
+ * @param {string} dir
+ */
+export function headSha(dir) {
+  const r = spawnSync("git", ["-C", dir, "rev-parse", "HEAD"], {
+    encoding: "utf8",
+    timeout: 20000,
+  });
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+function toplevel(dir) {
+  const r = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
+    encoding: "utf8",
+    timeout: 20000,
+  });
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+function real(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+function readJson(p) {
+  return readRegularJson(p, null);
+}
+
+/**
+ * The run state this invocation belongs to, or null.
+ *
+ * @param {{statePath?: string|null, repo?: string|null, env?: Record<string,string|undefined>}} [opts]
+ * @returns {string|null}
+ */
+export function resolveStatePath({ statePath = null, repo = null, env = process.env } = {}) {
+  if (statePath) return existsSync(statePath) ? statePath : null;
+  const prevRoot = process.env.LOGS_ROOT;
+  if (env.LOGS_ROOT !== undefined) process.env.LOGS_ROOT = env.LOGS_ROOT;
+  try {
+    const session = env.MULTI_AGENT_SESSION_ID || "";
+    const top = repo ? toplevel(repo) : null;
+    const want = top ? real(top) : null;
+    let byWorktree = null;
+    for (const run of listRuns()) {
+      const p = resolveRunFile(run.taskId, "agent-state.json", run.project);
+      if (!p) continue;
+      const doc = readJson(p);
+      if (!doc || typeof doc !== "object") continue;
+      if (session && doc.sessionId === session) return p;
+      if (
+        !byWorktree &&
+        want &&
+        typeof doc.worktreePath === "string" &&
+        real(doc.worktreePath) === want
+      ) {
+        byWorktree = p;
+      }
+    }
+    return byWorktree;
+  } finally {
+    if (prevRoot === undefined) delete process.env.LOGS_ROOT;
+    else process.env.LOGS_ROOT = prevRoot;
+  }
+}
+
+/**
+ * Do the quality gates run here, and against which state?
+ *
+ * @param {{statePath?: string|null, repo?: string|null, env?: Record<string,string|undefined>}} [opts]
+ * @returns {{active: boolean, statePath: string|null, state: object|null}}
+ */
+export function gateContext({ statePath = null, repo = null, env = process.env } = {}) {
+  const path = resolveStatePath({ statePath, repo: repo || process.cwd(), env });
+  const state = path ? readJson(path) : null;
+  return { active: gatesActive(state, env), statePath: path, state };
+}
+
+/**
+ * Read-modify-write one state document under the write-state lock.
+ *
+ * A `mutate` that returns the document it was given has changed nothing, so
+ * nothing is written and `rev` stays where it was.
+ *
+ * @param {string} path
+ * @param {(state: object) => object} mutate  returns the next document
+ */
+export async function updateState(path, mutate) {
+  if (!existsSync(path)) throw new LedgerError("no-state", `no state file at ${path}`);
+  const ino = await acquireLock(path);
+  try {
+    let current;
+    try {
+      current = JSON.parse(readRegularFile(path));
+    } catch (err) {
+      throw new LedgerError("io", `state unreadable: ${err.message}`);
+    }
+    if (!current || typeof current !== "object" || Array.isArray(current)) {
+      throw new LedgerError("io", "state is not a JSON object");
+    }
+    const next = mutate(current);
+    if (next === current) return current;
+    next.rev = (Number.isInteger(current.rev) ? current.rev : 0) + 1;
+    if (!stillOurs(path, ino)) {
+      throw new LedgerError("io", `the lock on ${path} was taken mid-write; nothing written`);
+    }
+    const tmp = `${dirname(path)}/.${basename(path)}.${process.pid}.gates.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`);
+    renameSync(tmp, path);
+    return next;
+  } finally {
+    releaseLock(path, ino);
+  }
+}
+
+/**
+ * Append one gate verdict. A no-op in an attended run.
+ *
+ * `repo` is the checkout the gate judged. A gate that has no checkout argument
+ * of its own (evidence-gate, test-summary) passes none, and the run's
+ * `worktreePath` is used, so the sha is the worktree's HEAD whatever directory
+ * the gate was started from.
+ *
+ * @param {string} gate
+ * @param {"pass"|"fail"|"not-applicable"} verdict
+ * @param {object} [detail]
+ * @param {{repo?: string|null, statePath?: string|null, env?: Record<string,string|undefined>}} [opts]
+ * @returns {Promise<{written: boolean, reason?: string, statePath?: string, entry?: object}>}
+ */
+export async function record(
+  gate,
+  verdict,
+  detail = {},
+  { repo = null, statePath = null, env = process.env } = {},
+) {
+  if (!VERDICTS.includes(verdict)) {
+    throw new LedgerError("usage", `verdict must be one of ${VERDICTS.join(", ")}, got ${verdict}`);
+  }
+  const ctx = gateContext({ statePath, repo, env });
+  if (!ctx.active) return { written: false, reason: attendedVerdict(gate).reason };
+  const path = ctx.statePath;
+  if (!path) return { written: false, reason: "no run state found for this repository" };
+  let shaRepo = repo;
+  if (!shaRepo) {
+    const wt = ctx.state?.worktreePath;
+    shaRepo = typeof wt === "string" && existsSync(wt) ? wt : process.cwd();
+  }
+  const entry = {
+    gate,
+    verdict,
+    at: new Date().toISOString(),
+    sha: headSha(shaRepo),
+    detail: detail && typeof detail === "object" ? detail : { value: detail },
+  };
+  await updateState(path, (s) => ({
+    ...s,
+    gates: [...(Array.isArray(s.gates) ? s.gates : []), entry],
+  }));
+  return { written: true, statePath: path, entry };
+}
+
+/**
+ * Best-effort record for a gate's own CLI: a ledger problem is reported on
+ * stderr and never changes the gate's verdict or exit code.
+ */
+export async function recordQuietly(gate, verdict, detail, opts) {
+  try {
+    const r = await record(gate, verdict, detail, opts);
+    if (!r.written && r.reason !== attendedVerdict(gate).reason) {
+      process.stderr.write(`gate-ledger: ${gate} not recorded: ${r.reason}\n`);
+    }
+    return r;
+  } catch (err) {
+    process.stderr.write(`gate-ledger: ${gate} not recorded: ${err.message}\n`);
+    return { written: false, reason: err.message };
+  }
+}
+
+/**
+ * Park an unattended run for a person. The runner reads `waitingFor` as
+ * awaiting-answer and `verificationFailed` as verification-failed.
+ *
+ * @param {string} path
+ * @param {{outcome: "awaiting-answer"|"verification-failed", waitingFor?: string,
+ *          gate?: string, reason?: string}} opts
+ */
+export async function park(path, { outcome, waitingFor, gate, reason = "", pendingQuestion }) {
+  const at = new Date().toISOString();
+  if (outcome === "awaiting-answer") {
+    if (!waitingFor) throw new LedgerError("usage", "awaiting-answer needs --waiting-for");
+    if (waitingFor === "question" && !pendingQuestion) {
+      throw new LedgerError("usage", "waitingFor question needs a pendingQuestion to answer");
+    }
+    return updateState(path, (s) => ({
+      ...s,
+      waitingFor,
+      ...(pendingQuestion ? { pendingQuestion } : {}),
+      status: "awaiting_input",
+      haltReason: reason || `waiting for ${waitingFor}`,
+    }));
+  }
+  if (outcome === "verification-failed") {
+    if (!gate) throw new LedgerError("usage", "verification-failed needs --gate");
+    return updateState(path, (s) => ({
+      ...s,
+      status: "failed",
+      verificationFailed: { gate, reason, at },
+      haltReason: `verification failed at ${gate}: ${reason}`,
+    }));
+  }
+  throw new LedgerError("usage", `unknown outcome ${outcome}`);
+}
+
+/**
+ * Latest entry per gate for one sha. "Latest" is by `at`, then by position.
+ */
+export function latestByGate(gates, sha) {
+  const out = new Map();
+  (Array.isArray(gates) ? gates : []).forEach((e, i) => {
+    if (!e || typeof e !== "object" || e.sha !== sha || typeof e.gate !== "string") return;
+    const prev = out.get(e.gate);
+    const t = Date.parse(e.at) || 0;
+    if (!prev || t > prev.t || (t === prev.t && i > prev.i)) out.set(e.gate, { e, t, i });
+  });
+  return new Map([...out].map(([k, v]) => [k, v.e]));
+}
+
+/**
+ * Does the ledger allow a commit on top of `sha`?
+ *
+ * @param {object} state
+ * @param {string} sha
+ * @param {{mandatory?: string[]}} [opts]
+ * @returns {{ok: boolean, missing: string[], failing: object[], sha: string}}
+ */
+export function checkCommit(state, sha, { mandatory = MANDATORY_AT_COMMIT } = {}) {
+  const latest = latestByGate(state?.gates, sha);
+  const missing = [];
+  const failing = [];
+  for (const g of mandatory) {
+    const e = latest.get(g);
+    if (!e) missing.push(g);
+    else if (!PASSING.has(e.verdict)) failing.push(e);
+  }
+  return { ok: missing.length === 0 && failing.length === 0, missing, failing, sha };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+
+function parse(argv) {
+  const opts = {};
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") {
+      opts.json = true;
+      continue;
+    }
+    if (!a.startsWith("--")) throw new LedgerError("usage", `unexpected argument ${a}`);
+    const v = argv[++i];
+    if (v === undefined) throw new LedgerError("usage", `${a} needs a value`);
+    opts[a.slice(2)] = v;
+  }
+  return opts;
+}
+
+async function main(argv) {
+  const mode = argv[0];
+  const opts = parse(argv);
+  const repo = opts.repo || process.cwd();
+  if (mode === "append") {
+    if (!opts.gate || !opts.verdict)
+      throw new LedgerError("usage", "append needs --gate and --verdict");
+    let detail = {};
+    if (opts.detail) {
+      try {
+        detail = JSON.parse(opts.detail);
+      } catch (err) {
+        throw new LedgerError("usage", `--detail is not JSON: ${err.message}`);
+      }
+    }
+    const r = await record(opts.gate, opts.verdict, detail, {
+      repo: opts.repo || null,
+      statePath: opts.state,
+    });
+    // Gates off: nothing is written and nothing is said.
+    if (!r.written && r.reason === attendedVerdict(opts.gate).reason) return 0;
+    if (!r.written) process.stderr.write(`gate-ledger: nothing written: ${r.reason}\n`);
+    return r.written ? 0 : 3;
+  }
+  if (mode === "check") {
+    const path = resolveStatePath({ statePath: opts.state, repo });
+    if (!path) {
+      process.stderr.write(
+        "gate-ledger: no run state found for this repository, so the gate ledger cannot be checked\n",
+      );
+      return 3;
+    }
+    const state = readJson(path);
+    const sha =
+      opts.sha ||
+      headSha(
+        opts.repo || !(state?.worktreePath && existsSync(state.worktreePath))
+          ? repo
+          : state.worktreePath,
+      );
+    if (!state || !sha) {
+      process.stderr.write(`gate-ledger: cannot read ${path} or resolve HEAD\n`);
+      return 3;
+    }
+    const r = checkCommit(state, sha);
+    if (opts.json) writeFileSync(1, `${JSON.stringify({ statePath: path, ...r }, null, 2)}\n`);
+    if (!r.ok) {
+      const lines = [
+        `gate-ledger: the unattended commit on ${sha.slice(0, 12)} is not backed by the gate ledger (${path})`,
+        ...r.missing.map((g) => `  missing: ${g} has no entry for this HEAD`),
+        ...r.failing.map(
+          (e) =>
+            `  failing: ${e.gate} -> ${e.verdict}${e.detail?.reason ? ` (${e.detail.reason})` : ""}`,
+        ),
+        "  Run the missing gates (multi-agent-refs/features/unattended-gates.md); a failing one parks the run.",
+      ];
+      writeFileSync(2, `${lines.join("\n")}\n`);
+      return 1;
+    }
+    if (!opts.json)
+      writeFileSync(
+        1,
+        `gate-ledger: ${MANDATORY_AT_COMMIT.length} mandatory gate(s) pass for ${sha.slice(0, 12)}\n`,
+      );
+    return 0;
+  }
+  if (mode === "park") {
+    const path = resolveStatePath({ statePath: opts.state, repo });
+    if (!path) throw new LedgerError("no-state", "no run state found to park");
+    await park(path, {
+      outcome: opts.outcome,
+      waitingFor: opts["waiting-for"],
+      gate: opts.gate,
+      reason: opts.reason,
+    });
+    return 0;
+  }
+  throw new LedgerError("usage", "mode must be append, check or park");
+}
+
+if (invokedDirectly(import.meta.url)) {
+  main(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (err) => {
+      process.stderr.write(`gate-ledger: ${err.message}\n`);
+      if (err.code === "usage") {
+        process.stderr.write(
+          "usage: gate-ledger.mjs append|check|park [--gate g] [--verdict v] [--detail json] [--state p] [--repo d] [--sha s] [--json]\n",
+        );
+        process.exit(2);
+      }
+      process.exit(3);
+    },
+  );
+}