@mmerterden/multi-agent-pipeline 20.28.0 → 20.30.0

package/pipeline/scripts/run-results.mjs

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+/**
+ * @file run-results.mjs  -  what a run produced, read from its own files: the
+ * diff summary, the review findings, the test outcome, the screenshots and,
+ * for an analysis run, the documents it wrote.
+ *
+ * Every source is a file or a state field the phases already write; nothing is
+ * computed here that a phase did not record:
+ *
+ *   diff      agent-state `diffRisk` (diff-risk-score.mjs, Phase 3), else the
+ *             file and line counts of `.review-diff.txt`
+ *   findings  `triage-output.json` (Phase 3 triage), else agent-state
+ *             `review.findings` (a standalone /multi-agent:review)
+ *   tests     agent-state `uiTest` and the `test-summary` gate entries
+ *             (test-summary.mjs)
+ *   evidence  `.pipeline/evidence/*.png|jpg` and agent-state `visualEvidence`
+ *   analysis  agent-state `analysisSpec.outputs` (the documents' text) and
+ *             `analysis.docPath[]`
+ *
+ * Each file is looked for in the run's log directory, its `artifacts/` copy
+ * (worktree-finalize.sh salvages there) and, while the run is live, its
+ * worktree. The state's worktreePath is used only when git lists it as a
+ * worktree of the state's projectRoot. A part with no source is null, never
+ * an empty success.
+ *
+ * An analysis document is read only when its real path sits inside one of
+ * those roots and it is Markdown or HTML; any other path in the state keeps
+ * its name with `text: null`, so a state file cannot point the reader at an
+ * arbitrary file.
+ *
+ * Text a person or tool wrote (finding text, test names, document bodies) is
+ * scrubbed and run through the credential redactor; paths are reduced to file
+ * names.
+ *
+ * Usage:
+ *   run-results.mjs <task-id> [--json]
+ *   run-results.mjs <task-id> --evidence <name>      one image, base64, as JSON
+ *
+ * Exit: 0 printed, 2 usage, 3 no such run or image.
+ *
+ * @module pipeline/scripts/run-results
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { basename, join, sep } from "node:path";
+import { selectRuns } from "./runs-index.mjs";
+import { createRedactor } from "./transcript-index.mjs";
+import { readRegularJson } from "../lib/regular-file.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+export const EVIDENCE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.(?:png|jpe?g)$/i;
+const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+const MAX_DOC_CHARS = 200_000;
+const MAX_FINDINGS = 200;
+const DOC_EXT = /\.(?:md|markdown|html?)$/i;
+
+export class ResultsError extends Error {}
+
+function readState(dir) {
+  for (const p of [join(dir, "agent-state.json"), join(dir, "artifacts", "agent-state.json")]) {
+    if (existsSync(p)) return readRegularJson(p, null) ?? {};
+  }
+  return {};
+}
+
+const realOrNull = (p) => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The state's worktreePath when git lists it as a worktree of the state's
+ * projectRoot, else null.
+ */
+export function verifiedWorktree(state) {
+  const wt = typeof state.worktreePath === "string" ? realOrNull(state.worktreePath) : null;
+  const root = typeof state.projectRoot === "string" ? realOrNull(state.projectRoot) : null;
+  if (!wt || !root) return null;
+  let listing;
+  try {
+    listing = execFileSync("git", ["-C", root, "worktree", "list", "--porcelain"], {
+      encoding: "utf8",
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    return null;
+  }
+  for (const line of listing.split("\n")) {
+    if (line.startsWith("worktree ") && realOrNull(line.slice(9)) === wt) return wt;
+  }
+  return null;
+}
+
+/** The directories a run's files may be in, most durable first. */
+function roots(run, state) {
+  const out = [run.dir, join(run.dir, "artifacts")];
+  const wt = verifiedWorktree(state);
+  if (wt) out.push(wt);
+  return out;
+}
+
+/** The real path of `p` when it is a Markdown or HTML file inside one of `dirs`. */
+function containedDoc(p, dirs) {
+  const real = realOrNull(p);
+  if (!real || !DOC_EXT.test(real)) return null;
+  for (const d of dirs) {
+    const rd = realOrNull(d);
+    if (rd && real.startsWith(rd + sep)) return real;
+  }
+  return null;
+}
+
+function firstExisting(dirs, rel) {
+  for (const d of dirs) {
+    const p = join(d, rel);
+    try {
+      if (statSync(p).isFile()) return p;
+    } catch {
+      // Not in this root.
+    }
+  }
+  return null;
+}
+
+function diffPart(state, dirs) {
+  const r = state.diffRisk;
+  if (r && typeof r === "object" && Number.isInteger(r.files)) {
+    return {
+      files: r.files,
+      added: Number.isInteger(r.loc_added) ? r.loc_added : null,
+      removed: Number.isInteger(r.loc_removed) ? r.loc_removed : null,
+      maxScore: typeof r.max_score === "number" ? r.max_score : null,
+      signals: Array.isArray(r.signals) ? r.signals.map(String) : [],
+      changed: [],
+      source: "diffRisk",
+    };
+  }
+  const p = firstExisting(dirs, ".review-diff.txt");
+  if (!p) return null;
+  const files = new Set();
+  let added = 0;
+  let removed = 0;
+  for (const line of readFileSync(p, "utf8").split("\n")) {
+    const m = /^\+\+\+ b\/(.+)$/.exec(line);
+    if (m) files.add(m[1]);
+    else if (line.startsWith("+") && !line.startsWith("+++")) added++;
+    else if (line.startsWith("-") && !line.startsWith("---")) removed++;
+  }
+  return {
+    files: files.size,
+    added,
+    removed,
+    maxScore: null,
+    signals: [],
+    changed: [...files].slice(0, 200).map((f) => basename(f)),
+    source: ".review-diff.txt",
+  };
+}
+
+function findingsPart(state, dirs, R) {
+  const p = firstExisting(dirs, "triage-output.json");
+  const triage = p ? readRegularJson(p, null) : null;
+  const shape = (f, verdict) => ({
+    severity: String(f?.severity ?? "unknown"),
+    file: f?.file ? basename(String(f.file)) : null,
+    line: Number.isInteger(f?.line) ? f.line : null,
+    issue: R.excerpt(f?.issue ?? f?.title ?? f?.message ?? "", 400),
+    fix: f?.fix ? R.excerpt(f.fix, 400) : null,
+    reviewer: f?.reviewer ? String(f.reviewer) : null,
+    verdict,
+  });
+  if (triage && typeof triage === "object") {
+    const items = [];
+    for (const v of ["accepted", "deferred", "rejected"]) {
+      for (const f of Array.isArray(triage[v]) ? triage[v] : []) items.push(shape(f, v));
+    }
+    return {
+      approved: typeof triage.approved === "boolean" ? triage.approved : null,
+      items: items.slice(0, MAX_FINDINGS),
+      total: items.length,
+      source: "triage-output.json",
+    };
+  }
+  const review = state.review;
+  if (review && Array.isArray(review.findings)) {
+    const items = review.findings.map((f) => shape(f, f?.status ?? f?.verdict ?? "accepted"));
+    return {
+      approved: null,
+      items: items.slice(0, MAX_FINDINGS),
+      total: items.length,
+      source: "agent-state review",
+    };
+  }
+  return null;
+}
+
+function testsPart(state, R) {
+  const gates = Array.isArray(state.gates) ? state.gates : [];
+  const summaries = gates.filter(
+    (g) => g && (g.gate === "test-summary" || g.name === "test-summary"),
+  );
+  const last = summaries.at(-1) ?? null;
+  const ui = state.uiTest && typeof state.uiTest === "object" ? state.uiTest : null;
+  if (!last && !ui) return null;
+  const count = (k) => {
+    const v = last?.counts?.[k] ?? last?.[k];
+    return Number.isInteger(v) ? v : null;
+  };
+  return {
+    status: last?.status ?? last?.verdict ?? ui?.status ?? null,
+    passed: count("passed"),
+    failed: count("failed"),
+    skipped: count("skipped"),
+    uiTest: ui
+      ? {
+          ran: ui.ran === true,
+          status: ui.status ?? null,
+          notRunReason: ui.notRunReason ? R.excerpt(ui.notRunReason, 200) : null,
+        }
+      : null,
+    source: last ? "test-summary gate" : "agent-state uiTest",
+  };
+}
+
+function evidenceDirs(dirs) {
+  return dirs.map((d) => join(d, ".pipeline", "evidence")).filter((d) => existsSync(d));
+}
+
+function evidencePart(state, dirs) {
+  const names = new Map();
+  for (const d of evidenceDirs(dirs)) {
+    let list;
+    try {
+      list = readdirSync(d);
+    } catch {
+      continue;
+    }
+    for (const f of list) if (EVIDENCE_NAME.test(f) && !names.has(f)) names.set(f, null);
+  }
+  const ve = state.visualEvidence;
+  for (const side of ["before", "after"]) {
+    for (const e of Array.isArray(ve?.[side]) ? ve[side] : []) {
+      const f = typeof e?.file === "string" ? basename(e.file) : null;
+      if (f && names.has(f)) names.set(f, side);
+    }
+  }
+  return [...names.entries()].sort().map(([name, phase]) => ({ name, phase }));
+}
+
+function analysisPart(state, dirs, R) {
+  const outputs = state.analysisSpec?.outputs;
+  const paths = [
+    ...(Array.isArray(outputs?.localPaths) ? outputs.localPaths : []),
+    ...(Array.isArray(state.analysis?.docPath) ? state.analysis.docPath : []),
+  ].filter((p) => typeof p === "string");
+  if (!paths.length && !outputs) return null;
+  const documents = [];
+  for (const p of [...new Set(paths)]) {
+    const real = containedDoc(p, dirs);
+    try {
+      if (!real || !statSync(real).isFile()) throw new Error("not readable here");
+      const text = readFileSync(real, "utf8").slice(0, MAX_DOC_CHARS);
+      documents.push({ name: basename(p), text: R.clean(text) });
+    } catch {
+      documents.push({ name: basename(p), text: null });
+    }
+  }
+  return {
+    documents,
+    confluencePages: Array.isArray(outputs?.confluencePageUrls)
+      ? outputs.confluencePageUrls.length
+      : 0,
+    jiraIssueKey:
+      typeof outputs?.jiraIssueKey === "string" &&
+      /^[A-Z][A-Z0-9_]*-[0-9]+$/.test(outputs.jiraIssueKey)
+        ? outputs.jiraIssueKey
+        : null,
+  };
+}
+
+function runFor(taskId) {
+  const { found, records } = selectRuns({ taskId });
+  if (!found || !records.length) throw new ResultsError("no such run");
+  return records[0];
+}
+
+/** Everything a run produced, as one document. */
+export function runResults(taskId) {
+  const run = runFor(taskId);
+  const state = readState(run.dir);
+  const dirs = roots(run, state);
+  const R = createRedactor();
+  return {
+    contractVersion: CONTRACT_VERSION,
+    taskId: run.taskId,
+    diff: diffPart(state, dirs),
+    findings: findingsPart(state, dirs, R),
+    tests: testsPart(state, R),
+    evidence: evidencePart(state, dirs),
+    analysis: analysisPart(state, dirs, R),
+  };
+}
+
+/**
+ * One screenshot as base64. The name must be a bare image file name found in
+ * one of the run's evidence directories; its real path must stay inside it.
+ */
+export function runEvidence(taskId, name) {
+  if (typeof name !== "string" || !EVIDENCE_NAME.test(name))
+    throw new ResultsError("no such image");
+  const run = runFor(taskId);
+  const state = readState(run.dir);
+  for (const d of evidenceDirs(roots(run, state))) {
+    const p = join(d, name);
+    let real;
+    let realDir;
+    try {
+      real = realpathSync(p);
+      realDir = realpathSync(d);
+    } catch {
+      continue;
+    }
+    if (!real.startsWith(realDir + sep)) continue;
+    const st = statSync(real);
+    if (!st.isFile() || st.size > MAX_IMAGE_BYTES) continue;
+    const mime = /\.png$/i.test(name) ? "image/png" : "image/jpeg";
+    return {
+      contractVersion: CONTRACT_VERSION,
+      taskId: run.taskId,
+      name,
+      mime,
+      data: readFileSync(real).toString("base64"),
+    };
+  }
+  throw new ResultsError("no such image");
+}
+
+function main(argv) {
+  const [taskId, ...rest] = argv;
+  if (!taskId) {
+    process.stderr.write("usage: run-results.mjs <task-id> [--json] | --evidence <name>\n");
+    return 2;
+  }
+  try {
+    if (rest[0] === "--evidence") {
+      process.stdout.write(JSON.stringify(runEvidence(taskId, rest[1])) + "\n");
+      return 0;
+    }
+    if (rest.some((a) => a !== "--json")) {
+      process.stderr.write("usage: run-results.mjs <task-id> [--json] | --evidence <name>\n");
+      return 2;
+    }
+    process.stdout.write(JSON.stringify(runResults(taskId), null, 2) + "\n");
+    return 0;
+  } catch (err) {
+    if (!(err instanceof ResultsError)) throw err;
+    process.stderr.write(`run-results: ${err.message}\n`);
+    return 3;
+  }
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("run-results", () => {
+    process.exitCode = main(process.argv.slice(2));
+  });
+}

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