@mmerterden/multi-agent-pipeline 20.28.0 → 20.29.0

package/pipeline/scripts/gate-ledger.mjs

@@ -15,7 +15,8 @@
  *
  * 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
+ * that is neither writes only the gates in ATTENDED_RECORDED, each entry marked
+ * `attended: true`, and checkCommit never counts those. 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.
  *
@@ -32,6 +33,9 @@
  *   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 evidence [--state <path>] [--repo <dir>] [--sha <sha>] [--json]
+ *     the attended commit check: build/test evidence for HEAD, per
+ *     prefs.global.attendedCommitGate.mode (exit 0 fine, 1 warn, 4 block)
  *   gate-ledger.mjs park   --outcome awaiting-answer|verification-failed
  *                  [--waiting-for <step>] [--gate <id>] [--reason <text>] [--state <path>]
  *
@@ -49,12 +53,21 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { basename, dirname } from "node:path";
 
 import { decisionEntry, withDecision } from "../lib/decisions.mjs";
 import { invokedDirectly } from "../lib/invoked-directly.mjs";
 import { readRegularFile, readRegularJson } from "../lib/regular-file.mjs";
+import { globalPref } from "../lib/prefs-value.mjs";
+import { modeEntry } from "../lib/run-completion.mjs";
 import { attendedVerdict, gatesActive } from "../lib/unattended.mjs";
 import { listRuns, resolveRunFile } from "./_run-paths.mjs";
 import { acquireLock, releaseLock, stillOurs } from "./write-state.mjs";
@@ -80,6 +93,41 @@ export const MANDATORY_AT_COMMIT = [
   "plan-coverage",
 ];
 
+/**
+ * Gates whose verdict is recorded in an attended run too, marked
+ * `attended: true`. `plan-coverage` is what lib/run-completion.mjs reads
+ * before a run may write `status: complete`. One locked append per verdict;
+ * every other gate writes nothing while the gates are off.
+ */
+export const ATTENDED_RECORDED = new Set([
+  "plan-coverage",
+  "evidence-gate/build",
+  "evidence-gate/test",
+]);
+
+/** What an attended commit is checked for (pre-commit-check.sh, `evidence`). */
+export const ATTENDED_COMMIT_EVIDENCE = ["evidence-gate/build", "evidence-gate/test"];
+
+/** prefs.global.attendedCommitGate.mode values; `warn` is the default. */
+export const ATTENDED_COMMIT_MODES = ["off", "warn", "block"];
+
+/**
+ * The build/test evidence an attended commit on `sha` lacks: every gate in
+ * ATTENDED_COMMIT_EVIDENCE whose latest entry for that sha, attended or not,
+ * is missing or not passing.
+ *
+ * @param {object} state
+ * @param {string} sha
+ * @returns {string[]}
+ */
+export function attendedEvidenceGaps(state, sha) {
+  const latest = latestByGate(state?.gates, sha);
+  return ATTENDED_COMMIT_EVIDENCE.filter((g) => {
+    const e = latest.get(g);
+    return !e || !PASSING.has(e.verdict);
+  });
+}
+
 const QUESTION_ID = /^[a-z][a-z0-9-]*$/;
 const OPTION_ID = /^[a-z0-9][a-z0-9+_-]*$/;
 const QUESTION_KEYS = ["id", "stepId", "text", "kind", "options"];
@@ -201,6 +249,59 @@ export function resolveStatePath({ statePath = null, repo = null, env = process.
   }
 }
 
+export const TREE_MATCH_MAX_AGE_MS = 6 * 60 * 60 * 1000;
+
+/**
+ * The in-progress run an attended commit in `repo` belongs to, or null.
+ *
+ * Only a run still in progress counts: a finished local-mode run keeps the
+ * project root as its worktree forever and would otherwise judge every later
+ * commit there. Of several, the one bound to the hook's session (`sessionId`
+ * = MULTI_AGENT_SESSION_ID, or `hostSessionId` = the payload's session_id)
+ * wins, then the most recently written. A run matched only by its worktree
+ * counts while its state was written in the last six hours.
+ *
+ * @param {{repo: string, session?: string, env?: Record<string,string|undefined>}} opts
+ * @returns {string|null}
+ */
+export function liveRunFor({ repo, session = "", env = process.env }) {
+  const prevRoot = process.env.LOGS_ROOT;
+  if (env.LOGS_ROOT !== undefined) process.env.LOGS_ROOT = env.LOGS_ROOT;
+  try {
+    const top = toplevel(repo);
+    const want = top ? real(top) : null;
+    const launched = env.MULTI_AGENT_SESSION_ID || "";
+    const hits = [];
+    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" || doc.status !== "in_progress") continue;
+      const bound =
+        (launched && doc.sessionId === launched) || (session && doc.hostSessionId === session);
+      const onTree =
+        want && typeof doc.worktreePath === "string" && real(doc.worktreePath) === want;
+      if (!bound && !onTree) continue;
+      let t = 0;
+      try {
+        t = statSync(p).mtimeMs;
+      } catch {
+        t = 0;
+      }
+      // A run that crashed keeps status in_progress forever. Matched only by
+      // its worktree, it judges commits there while its state is still being
+      // written; once it has gone quiet the tree is the user's again.
+      if (!bound && Date.now() - t > TREE_MATCH_MAX_AGE_MS) continue;
+      hits.push({ p, bound: bound ? 1 : 0, t });
+    }
+    hits.sort((a, b) => b.bound - a.bound || b.t - a.t);
+    return hits.length ? hits[0].p : null;
+  } 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?
  *
@@ -274,9 +375,17 @@ export async function record(
     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 attended = !ctx.active;
+  if (attended && !ATTENDED_RECORDED.has(gate)) {
+    return { written: false, reason: attendedVerdict(gate).reason };
+  }
   const path = ctx.statePath;
-  if (!path) return { written: false, reason: "no run state found for this repository" };
+  if (!path) {
+    // Attended with no run to write into is the ordinary case outside the
+    // pipeline, not a ledger problem worth a line on stderr.
+    if (attended) return { written: false, reason: attendedVerdict(gate).reason };
+    return { written: false, reason: "no run state found for this repository" };
+  }
   let shaRepo = repo;
   if (!shaRepo) {
     const wt = ctx.state?.worktreePath;
@@ -288,6 +397,7 @@ export async function record(
     at: new Date().toISOString(),
     sha: headSha(shaRepo),
     detail: detail && typeof detail === "object" ? detail : { value: detail },
+    ...(attended ? { attended: true } : {}),
   };
   await updateState(path, (s) => ({
     ...s,
@@ -403,7 +513,12 @@ export function latestByGate(gates, sha) {
  * @returns {{ok: boolean, missing: string[], failing: object[], sha: string}}
  */
 export function checkCommit(state, sha, { mandatory = MANDATORY_AT_COMMIT } = {}) {
-  const latest = latestByGate(state?.gates, sha);
+  // An entry written while the gates were off says what an attended run
+  // observed; it never stands in for a verdict the unattended contract requires.
+  const gated = (Array.isArray(state?.gates) ? state.gates : []).filter(
+    (e) => !(e && e.attended === true),
+  );
+  const latest = latestByGate(gated, sha);
   const missing = [];
   const failing = [];
   for (const g of mandatory) {
@@ -499,6 +614,47 @@ async function main(argv) {
       );
     return 0;
   }
+  if (mode === "evidence") {
+    // The attended commit check: exit 0 nothing to say (no run, mode off, a
+    // mode that commits nothing, evidence present), 1 warn, 4 block. Never 2
+    // or 3 for a missing run: outside the pipeline a commit is none of this
+    // hook's business.
+    const pref = globalPref("attendedCommitGate.mode", "warn");
+    const gateMode = ATTENDED_COMMIT_MODES.includes(pref) ? pref : "warn";
+    if (gateMode === "off") return 0;
+    let session = "";
+    if (opts["hook-input"] === "-") {
+      try {
+        session = String(JSON.parse(readFileSync(0, "utf8"))?.session_id || "");
+      } catch {
+        session = "";
+      }
+    }
+    const path = opts.state || liveRunFor({ repo, session });
+    if (!path) return 0;
+    const state = readJson(path);
+    if (!state || typeof state !== "object") return 0;
+    if (state.status !== "in_progress") return 0;
+    if (modeEntry(state)?.commits === false) return 0;
+    const sha = opts.sha || headSha(repo);
+    if (!sha) return 0;
+    const missing = attendedEvidenceGaps(state, sha);
+    if (opts.json)
+      writeFileSync(1, `${JSON.stringify({ statePath: path, sha, gateMode, missing })}\n`);
+    if (!missing.length) return 0;
+    const verb = gateMode === "block" ? "BLOCKED" : "warning";
+    writeFileSync(
+      2,
+      `${[
+        `pre-commit-check: ${verb}: the run's gate ledger (${path}) has no passing ${missing.join(" / ")} for HEAD ${sha.slice(0, 12)}.`,
+        "  Run the build and the tests through evidence-gate.mjs (Phase 2 Gate 1) so the commit rests on recorded evidence.",
+        gateMode === "block"
+          ? "  prefs.global.attendedCommitGate.mode is block; set it to warn to commit anyway."
+          : "  The commit goes ahead; prefs.global.attendedCommitGate.mode block refuses it instead.",
+      ].join("\n")}\n`,
+    );
+    return gateMode === "block" ? 4 : 1;
+  }
   if (mode === "park") {
     const path = resolveStatePath({ statePath: opts.state, repo });
     let pendingQuestion;
@@ -523,7 +679,7 @@ async function main(argv) {
     });
     return 0;
   }
-  throw new LedgerError("usage", "mode must be append, check or park");
+  throw new LedgerError("usage", "mode must be append, check, evidence or park");
 }
 
 if (invokedDirectly(import.meta.url)) {
@@ -533,7 +689,7 @@ if (invokedDirectly(import.meta.url)) {
       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",
+          "usage: gate-ledger.mjs append|check|evidence|park [--gate g] [--verdict v] [--detail json] [--state p] [--repo d] [--sha s] [--json]\n",
         );
         process.exit(2);
       }

package/pipeline/scripts/plan-coverage-gate.mjs

@@ -220,15 +220,16 @@ async function main(args) {
   const UNREADABLE = gatesOn ? 3 : 2;
   const ZERO_STEPS = gatesOn ? 1 : 2;
 
+  // Recorded attended too (gate-ledger.mjs ATTENDED_RECORDED, marked
+  // `attended: true`): lib/run-completion.mjs reads the verdict before a run
+  // may write `status: complete`.
   const finish = async (code, result, detail = {}) => {
-    if (gatesOn) {
-      await recordQuietly(
-        "plan-coverage",
-        LEDGER[result.verdict] ?? "fail",
-        { verdict: result.verdict, ...detail },
-        { repo: root, statePath: statePath ?? null },
-      );
-    }
+    await recordQuietly(
+      "plan-coverage",
+      LEDGER[result.verdict] ?? "fail",
+      { verdict: result.verdict, ...detail },
+      { repo: root, statePath: statePath ?? null },
+    );
     return code;
   };
 

package/pipeline/scripts/pre-commit-check.sh

@@ -715,6 +715,18 @@ if [ "$IS_COMMIT_HOOK" = "1" ]; then
   owned_path_gate || exit 2
 fi
 
+# Attended commit inside a pipeline run: the run's gate ledger should hold a
+# passing build and test verdict for HEAD (evidence-gate.mjs records both in an
+# attended run too). prefs.global.attendedCommitGate.mode: warn (default) says so
+# on stderr and lets the commit through, block refuses it, off skips the check.
+# Outside a run gate-ledger.mjs says nothing; any error of its own is not a
+# reason to refuse a commit a person is watching.
+if [ "$IS_COMMIT_HOOK" = "1" ] && ! ma_unattended && command -v node >/dev/null 2>&1; then
+  printf '%s' "${HOOK_INPUT:-}" \
+    | node "$PRE_COMMIT_DIR/gate-ledger.mjs" evidence --repo "${REPO_ROOT:-$PWD}" --hook-input - >/dev/null
+  [ "$?" = "4" ] && exit 2
+fi
+
 # Unattended commit: the verification gates must have passed for this HEAD.
 # The environment is the hook's own, inherited from the process the launcher
 # started, so the run cannot talk its way past it by editing its state. An

package/pipeline/scripts/run-scope-guard.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * run-scope-guard.mjs  -  PreToolUse rules that depend on the active run.
+ *
+ * Figma (matcher `mcp__.*[Ff]igma.*`): the design is read in the analysis
+ * part of a run and nowhere after it (rules/figma-pipeline.md, "No MCP outside
+ * analysis phase"). For a run bound to this session by `sessionId` or
+ * `hostSessionId` (never by a worktree match) whose status is `in_progress` or
+ * `awaiting_input`:
+ *
+ *   - mode `analysis`: allowed at every phase; the analysis command is the
+ *     design fetch.
+ *   - any other mode: allowed through Phase `thresholds.mcpAllowedThroughPhase`
+ *     of schemas/phases.json (Phase 1 Step 1.4 captures the Figma evidence
+ *     record), denied above it with a reason that says to re-run analysis.
+ *
+ * An allowed call is appended to `telemetry.mcpCalls[]` by this hook, so the
+ * record smoke-no-mcp-in-dev-phases.sh audits no longer depends on the model
+ * remembering to write it. A denied call never ran and is not recorded.
+ *
+ * Worktree boundary (matcher `Edit|Write|NotebookEdit|MultiEdit`), attended
+ * only: a file write outside the bound run's worktree (or its other projects'
+ * worktrees, its run directory, the log root, the temp directories and
+ * ~/.claude) is let through with a warning: `additionalContext` tells the model
+ * the target is outside the run, `systemMessage` tells the user. A run with
+ * no worktree (`localMode`, `worktreePath: null`) is not checked. The
+ * containment test is the one unattended_policy.py applies to its run's
+ * worktree, a real-path prefix match; unattended, that policy and its
+ * protected paths decide instead, so this rule stays silent there.
+ *
+ * No run bound to the session: no output, the call proceeds. Any internal
+ * error: no output, a line in <log root>/hook-failures.log.
+ *
+ * Output: the PreToolUse hook JSON (a Figma deny, a boundary warning) or nothing.
+ * Exit 0 always.
+ *
+ * @module pipeline/scripts/run-scope-guard
+ */
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { isUnattended } from "../lib/unattended.mjs";
+import { findActiveRun, logHookFailure, modeOf, phaseContract } from "./_active-run.mjs";
+import { logsRoot } from "./_run-paths.mjs";
+
+const HOOK = "run-scope-guard";
+const FIGMA_TOOL = /^mcp__.*figma/i;
+const SESSION_BOUND = new Set(["session", "host-session"]);
+const LIVE = new Set(["in_progress", "awaiting_input"]);
+const FILE_TOOLS = new Set(["Edit", "Write", "NotebookEdit", "MultiEdit"]);
+
+const deny = (reason) => ({
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    permissionDecision: "deny",
+    permissionDecisionReason: `run-scope-guard: ${reason}`,
+  },
+});
+
+/** The last phase a Figma call is allowed in outside an analysis run. */
+export function figmaThroughPhase() {
+  const n = Number(phaseContract().thresholds?.mcpAllowedThroughPhase);
+  return Number.isInteger(n) ? n : 1;
+}
+
+async function recordMcpCall(statePath, tool, phase) {
+  const { updateState } = await import("./gate-ledger.mjs");
+  const entry = { tool, phase, timestamp: new Date().toISOString(), recordedBy: HOOK };
+  await updateState(statePath, (s) => {
+    const telemetry = s.telemetry && typeof s.telemetry === "object" ? s.telemetry : {};
+    const calls = Array.isArray(telemetry.mcpCalls) ? telemetry.mcpCalls : [];
+    return { ...s, telemetry: { ...telemetry, mcpCalls: [...calls, entry] } };
+  });
+}
+
+async function figmaDecision(payload, run) {
+  const tool = payload.tool_name;
+  const state = run.state;
+  // A finished, failed or abandoned run governs nothing and records nothing.
+  if (!LIVE.has(state.status)) return null;
+  const phase = Number(state.currentPhase);
+  const at = Number.isInteger(phase) ? phase : 0;
+  if (modeOf(state) !== "analysis" && at > figmaThroughPhase()) {
+    return deny(
+      `${tool} is a Figma call at Phase ${at} of run ${state.taskId || run.statePath}. The design is read during analysis only (through Phase ${figmaThroughPhase()}); later phases work from the analysis document and the repo's Code Connect mappings. If a variant or value is missing, halt and re-run /multi-agent:analysis.`,
+    );
+  }
+  await recordMcpCall(run.statePath, tool, Math.min(5, Math.max(0, at)));
+  return null;
+}
+
+/** The real path of `p`, resolving the nearest existing ancestor. */
+function realish(p) {
+  let cur = p;
+  const tail = [];
+  while (!existsSync(cur)) {
+    const up = dirname(cur);
+    if (up === cur) return p;
+    tail.unshift(basename(cur));
+    cur = up;
+  }
+  try {
+    return join(realpathSync(cur), ...tail);
+  } catch {
+    return p;
+  }
+}
+
+const under = (path, root) =>
+  path === root || path.startsWith(root.endsWith(sep) ? root : root + sep);
+
+/** The directories a file write of this run may land in without a warning. */
+export function allowedRoots(run, env = process.env) {
+  const s = run.state;
+  const roots = [s.worktreePath, s.artifactsPath, dirname(run.statePath)];
+  for (const p of Array.isArray(s.projects) ? s.projects : []) roots.push(p?.worktreePath);
+  roots.push(env.LOGS_ROOT || logsRoot(), tmpdir(), "/tmp", "/private/tmp", "/var/folders");
+  roots.push(join(env.HOME || homedir(), ".claude"));
+  return roots.filter((r) => typeof r === "string" && r).map((r) => realish(resolve(r)));
+}
+
+function boundaryDecision(payload, run, env) {
+  const s = run.state;
+  if (isUnattended(env)) return null;
+  if (s.status !== "in_progress" || s.localMode === true) return null;
+  if (typeof s.worktreePath !== "string" || !s.worktreePath) return null;
+  const ti = payload.tool_input || {};
+  const raw = ti.file_path || ti.notebook_path;
+  if (typeof raw !== "string" || !raw) return null;
+  const base = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
+  const target = realish(isAbsolute(raw) ? raw : resolve(base, raw));
+  if (allowedRoots(run, env).some((r) => under(target, r))) return null;
+  const msg = `${raw} is outside the worktree of pipeline run ${s.taskId || run.statePath} (${s.worktreePath}). Edits for the run belong in its worktree; if this file really is part of the task, say why before continuing.`;
+  return {
+    systemMessage: `run-scope-guard: ${msg}`,
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      additionalContext: `run-scope-guard: ${msg}`,
+    },
+  };
+}
+
+/**
+ * The hook's answer for one payload, or null for no output.
+ *
+ * @param {object} payload
+ * @param {Record<string,string|undefined>} [env]
+ */
+export async function decide(payload, env = process.env) {
+  if (!payload || typeof payload !== "object") return null;
+  const tool = typeof payload.tool_name === "string" ? payload.tool_name : "";
+  const figma = FIGMA_TOOL.test(tool);
+  if (!figma && !FILE_TOOLS.has(tool)) return null;
+  const run = findActiveRun({
+    sessionId: typeof payload.session_id === "string" ? payload.session_id : null,
+    cwd: typeof payload.cwd === "string" ? payload.cwd : null,
+    env,
+  });
+  // Only a run bound to this session: an old local-mode run matched by its
+  // worktree (the project root) must not govern every later session there.
+  if (!run || !SESSION_BOUND.has(run.matchedBy)) return null;
+  return figma ? figmaDecision(payload, run) : boundaryDecision(payload, run, env);
+}
+
+async function main() {
+  let payload;
+  try {
+    payload = JSON.parse(readFileSync(0, "utf8"));
+  } catch {
+    logHookFailure(HOOK, "the hook payload is not JSON; allowed the call");
+    return;
+  }
+  try {
+    const out = await decide(payload);
+    if (out) process.stdout.write(`${JSON.stringify(out)}\n`);
+  } catch (err) {
+    logHookFailure(HOOK, `${err?.message || err}; allowed the call`);
+  }
+}
+
+const onFatal = (err) => logHookFailure(HOOK, `${err?.message || err}; allowed the call`);
+
+// Exit 0 on every path: nothing above sets a non-zero code, and a failure
+// is logged and allowed.
+if (invokedDirectly(import.meta.url)) main().catch(onFatal);

package/pipeline/scripts/run-scope-guard.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# run-scope-guard.sh  -  PreToolUse rules that depend on the active pipeline run.
+#
+# The decisions are in run-scope-guard.mjs; this wrapper exists because every
+# hook the pipeline registers is a `bash "$HOME/.<host>/scripts/<name>"`
+# command.
+#
+# Contract (Claude Code PreToolUse hook):
+#   - Reads the tool-call JSON on stdin.
+#   - Prints the hook JSON the host reads (a deny with its reason, or context
+#     for the model) or nothing.
+#   - Exits 0 on every path. A missing node or an internal error means no
+#     output, and the call proceeds.
+
+set -u
+
+HERE="$(cd "$(dirname "$0")" 2>/dev/null && pwd || true)"
+CORE="$HERE/run-scope-guard.mjs"
+[ -f "$CORE" ] || exit 0
+command -v node >/dev/null 2>&1 || exit 0
+
+node "$CORE" 2>/dev/null || true
+exit 0