@mmerterden/multi-agent-pipeline 20.27.2 → 20.29.0

package/pipeline/scripts/handle-diff-audit.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * @file handle-diff-audit.mjs  -  did the handle stage add only handles?
+ *
+ * The test-gen handle stage may change product code for one purpose: adding
+ * the automation handles a UI test finds elements by (iOS
+ * accessibilityIdentifier, Compose testTag / semantics, web data-testid). A
+ * prompt that says "only add attributes" is a wish; this measures it.
+ *
+ * Per changed file, the removed lines and the added lines with their handle
+ * constructs stripped are read as ordered code tokens (_handle-patterns.mjs
+ * codeTokens: operators and punctuation kept, whitespace dropped), hunk by
+ * hunk in order. The two sequences must be equal. Re-wrapping a tag over
+ * several lines or moving a modifier onto its own line keeps them equal; a
+ * flipped comparison, a dropped `!`, swapped arguments or a deleted modifier
+ * does not. A difference is reported as:
+ *
+ *   lost       tokens the removed lines had that the added lines lack
+ *   extra      tokens the added lines carry beyond the removed ones
+ *   reordered  the same tokens in another order
+ *   new-file   a file appeared that is not a handle-constants file (string
+ *              constants, the enums or objects grouping them, imports,
+ *              comments, nothing else)
+ *   deleted-file / binary
+ *
+ * Snapshot files are listed apart: a new attribute changes a rendered
+ * snapshot, and its owners should know, but it is not a violation.
+ *
+ * What is read:
+ *   --since <tree> / --baseline <json>  only what changed after the stage-start
+ *                     snapshot (test-gen-gate.mjs baseline records its tree),
+ *                     so uncommitted work the person had before the stage is
+ *                     never read as the stage's change
+ *   --base <ref>      the working tree, untracked files included, against a
+ *                     commit (default HEAD)
+ *   --diff-file <p>   a saved unified diff
+ *
+ * Usage:
+ *   node handle-diff-audit.mjs [--repo <path>] [--since <tree> | --baseline <json> | --base <ref>]
+ *   node handle-diff-audit.mjs --diff-file <unified.diff>
+ *
+ * Output: one JSON object on stdout.
+ * Exit: 0 only handles (or nothing changed), 2 violation, 3 input unreadable
+ * (a missing or option-shaped value, an unknown ref, a failed git call)
+ *
+ * @module pipeline/scripts/handle-diff-audit
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+import {
+  codeTokens,
+  isHandleConstantsFile,
+  isHandleLine,
+  isSnapshotPath,
+  parseUnifiedDiff,
+  stripHandles,
+} from "./_handle-patterns.mjs";
+import {
+  GitError,
+  diffSince,
+  optionValue,
+  snapshotTree,
+  treeDiff,
+  verifyCommit,
+} from "./_worktree-snapshot.mjs";
+
+const VALUE_FLAGS = new Set(["repo", "base", "since", "baseline", "diff-file"]);
+
+function emit(result, code) {
+  writeFileSync(1, `${JSON.stringify({ ...result, code })}\n`);
+  process.exit(code);
+}
+
+function unreadable(reason) {
+  emit({ ok: false, reason }, 3);
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) unreadable(`unexpected argument ${a}`);
+    const key = a.slice(2);
+    if (!VALUE_FLAGS.has(key)) unreadable(`unknown option ${a}`);
+    const v = argv[i + 1];
+    if (v === undefined || v.startsWith("-"))
+      unreadable(`${a} needs a value that does not start with "-"`);
+    out[key] = v;
+    i++;
+  }
+  return out;
+}
+
+function readDiff(args) {
+  if (args["diff-file"]) {
+    try {
+      return readFileSync(args["diff-file"], "utf8");
+    } catch (err) {
+      return unreadable(`cannot read --diff-file: ${err.message}`);
+    }
+  }
+  const repo = args.repo || process.cwd();
+  try {
+    if (args.since || args.baseline) {
+      let tree = args.since;
+      if (!tree) {
+        const doc = JSON.parse(readFileSync(args.baseline, "utf8"));
+        tree = optionValue("baseline tree", doc.tree);
+      }
+      return diffSince(repo, tree);
+    }
+    const base = verifyCommit(repo, args.base || "HEAD");
+    return treeDiff(repo, base, snapshotTree(repo));
+  } catch (err) {
+    if (err instanceof GitError || err instanceof SyntaxError || err.code === "ENOENT") {
+      return unreadable(err.message);
+    }
+    throw err;
+  }
+}
+
+/** Multiset difference: tokens of `a` not covered by `b`. */
+function missing(a, b) {
+  const pool = new Map();
+  for (const t of b) pool.set(t, (pool.get(t) || 0) + 1);
+  const out = [];
+  for (const t of a) {
+    const n = pool.get(t) || 0;
+    if (n > 0) pool.set(t, n - 1);
+    else out.push(t);
+  }
+  return out;
+}
+
+export function audit(diffText) {
+  const files = [];
+  const violations = [];
+  const snapshots = [];
+  let handlesAdded = 0;
+  for (const [file, f] of parseUnifiedDiff(diffText)) {
+    if (isSnapshotPath(file)) {
+      snapshots.push(file);
+      continue;
+    }
+    const handles = f.added.filter((l) => isHandleLine(file, l)).length;
+    handlesAdded += handles;
+    files.push({ file, handles, added: f.added.length, removed: f.removed.length });
+    if (f.binary) {
+      violations.push({ file, kind: "binary", tokens: [] });
+      continue;
+    }
+    if (f.isDeleted) {
+      violations.push({ file, kind: "deleted-file", tokens: [] });
+      continue;
+    }
+    if (f.isNew) {
+      if (!isHandleConstantsFile(f.added)) violations.push({ file, kind: "new-file", tokens: [] });
+      continue;
+    }
+    const before = f.hunks.flatMap((h) => codeTokens(h.removed.map((d) => d.text).join("\n")));
+    const after = f.hunks.flatMap((h) =>
+      codeTokens(h.added.map((d) => stripHandles(file, d.text)).join("\n")),
+    );
+    if (before.length === after.length && before.every((t, i) => t === after[i])) continue;
+    const lost = missing(before, after);
+    const extra = missing(after, before);
+    if (lost.length) violations.push({ file, kind: "lost", tokens: [...new Set(lost)] });
+    if (extra.length) violations.push({ file, kind: "extra", tokens: [...new Set(extra)] });
+    if (!lost.length && !extra.length) {
+      const at = before.findIndex((t, i) => t !== after[i]);
+      violations.push({ file, kind: "reordered", tokens: before.slice(at, at + 6) });
+    }
+  }
+  return { ok: violations.length === 0, handlesAdded, files, snapshots, violations };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const text = readDiff(args);
+  if (!text.trim())
+    emit({ ok: true, handlesAdded: 0, files: [], snapshots: [], violations: [] }, 0);
+  const result = audit(text);
+  emit(result, result.ok ? 0 : 2);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();

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/routine-registry.mjs

@@ -122,6 +122,10 @@ function cmdGet(home, name) {
   process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
 }
 
+// Every saved routine is written with this grant; permission-baseline.mjs
+// freezes it.
+export const ROUTINE_ALLOWED_TOOLS = "Skill, Bash, Read, Edit, Write, AskUserQuestion";
+
 function buildSkill(args) {
   const desc = args.description;
   const descTr = args["description-tr"];
@@ -132,7 +136,7 @@ function buildSkill(args) {
     `description: ${JSON.stringify(desc)}`,
     descTr ? `description-tr: ${JSON.stringify(descTr)}` : null,
     `argument-hint: ${JSON.stringify(hint)}`,
-    "allowed-tools: Skill, Bash, Read, Edit, Write, AskUserQuestion",
+    `allowed-tools: ${ROUTINE_ALLOWED_TOOLS}`,
     "local-only: true",
     "---",
   ].filter(Boolean);

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