@mmerterden/multi-agent-pipeline 20.15.0 → 20.16.0

package/pipeline/scripts/valven-port.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+/**
+ * @file valven-port.mjs  -  carry a branch's net change onto a fresh branch cut
+ * from the current tip of its base (valven-rules VLV-AGE-01, VLV-BEHIND-01).
+ *
+ * Usage:
+ *   valven-port.mjs --base <ref> [--repo <dir>] [--head <ref>] [--branch <name>]
+ *                   [--to <new-branch>] [--subject <commit subject>] [--apply] [--out <file>]
+ *
+ * Without --apply it reports what would move: the merge-base, how far the base
+ * has moved since, the changed paths, and the paths the base also touched (the
+ * ones a 3-way apply may have to merge). Nothing changes.
+ *
+ * With --apply it creates `--to` (default `<branch>-v2`, or the next free
+ * `-vN`) at the tip of --base, applies the diff merge-base..head with
+ * `git apply --3way --index`, commits it as one commit and returns to the
+ * branch it started on. Old commit history does not move: the new branch holds
+ * the change, not the path that led to it. On a conflict nothing is left
+ * behind: the new branch is deleted, the conflicted paths are reported, and
+ * the exit code is 1. Nothing is pushed.
+ *
+ * Exit codes:
+ *   0   -  plan printed, or applied cleanly
+ *   1   -  applied with conflicts; rolled back, `conflicts[]` names the paths
+ *   2   -  setup error: bad arguments, dirty worktree on --apply, git failure, empty change
+ *
+ * @module pipeline/scripts/valven-port
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+function git(repo, args) {
+  return execFileSync("git", ["-C", repo, ...args], {
+    encoding: "utf-8",
+    maxBuffer: 256 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+/** `feature/X-1-login` -> `feature/X-1-login-v2`; `...-v2` -> `...-v3`. */
+export function nextName(branch, exists) {
+  const m = /^(.*)-v(\d+)$/.exec(branch);
+  const stem = m ? m[1] : branch;
+  let n = m ? Number(m[2]) + 1 : 2;
+  while (exists(`${stem}-v${n}`)) n++;
+  return `${stem}-v${n}`;
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--apply") {
+      args.apply = true;
+      continue;
+    }
+    if (!a.startsWith("--")) throw new Error(`unexpected argument ${a}`);
+    const val = argv[i + 1];
+    if (val === undefined || val.startsWith("--")) throw new Error(`${a} needs a value`);
+    args[a.slice(2)] = val;
+    i++;
+  }
+  return args;
+}
+
+function fail(msg) {
+  process.stderr.write(`valven-port: ${msg}\n`);
+  process.exitCode = 2;
+}
+
+const lines = (out) => out.split("\n").filter(Boolean);
+
+async function main() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    return fail(err.message);
+  }
+  if (!args.base) return fail("--base is required");
+  const repo = args.repo ?? process.cwd();
+  const head = args.head ?? "HEAD";
+
+  let plan;
+  try {
+    const mergeBase = git(repo, ["merge-base", args.base, head]).trim();
+    const headSha = git(repo, ["rev-parse", head]).trim();
+    const baseSha = git(repo, ["rev-parse", args.base]).trim();
+    const branch = args.branch ?? git(repo, ["rev-parse", "--abbrev-ref", head]).trim();
+    const changed = lines(git(repo, ["diff", "--name-only", "-M", mergeBase, headSha]));
+    if (!changed.length) return fail(`no change between ${args.base} and ${head}`);
+    const baseTouched = new Set(lines(git(repo, ["diff", "--name-only", mergeBase, baseSha])));
+    const exists = (name) => git(repo, ["branch", "--list", name]).trim() !== "";
+    const to = args.to ?? nextName(branch, exists);
+    const subject =
+      args.subject ??
+      lines(
+        git(repo, ["log", "--no-merges", "--reverse", "--format=%s", `${mergeBase}..${headSha}`]),
+      )[0] ??
+      branch;
+    plan = {
+      branch,
+      to,
+      base: args.base,
+      baseSha,
+      mergeBase,
+      head: headSha,
+      behind: Number(git(repo, ["rev-list", "--count", `${headSha}..${baseSha}`]).trim()),
+      commitsDropped: Number(
+        git(repo, ["rev-list", "--count", "--no-merges", `${mergeBase}..${headSha}`]).trim(),
+      ),
+      subject,
+      changedPaths: changed,
+      sharedWithBase: changed.filter((p) => baseTouched.has(p)),
+      applied: false,
+    };
+  } catch (err) {
+    return fail(`git failed: ${String(err.stderr || err.message).trim()}`);
+  }
+
+  if (args.apply) {
+    if (git(repo, ["status", "--porcelain"]).trim()) return fail("worktree is not clean");
+    if (git(repo, ["branch", "--list", plan.to]).trim())
+      return fail(`branch ${plan.to} already exists`);
+    const original = git(repo, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+    const back = original === "HEAD" ? plan.head : original;
+    const tmp = mkdtempSync(join(tmpdir(), "valven-port-"));
+    const patch = join(tmp, "change.patch");
+    try {
+      writeFileSync(patch, git(repo, ["diff", "--binary", "-M", plan.mergeBase, plan.head]));
+      git(repo, ["checkout", "-q", "-b", plan.to, plan.baseSha]);
+      const r = spawnSync("git", ["-C", repo, "apply", "--3way", "--index", patch], {
+        encoding: "utf-8",
+      });
+      if (r.status !== 0) {
+        const unmerged = lines(git(repo, ["diff", "--name-only", "--diff-filter=U"]));
+        plan.conflicts = unmerged.length ? unmerged : lines(r.stderr).slice(0, 20);
+        git(repo, ["reset", "-q", "--hard"]);
+        git(repo, ["checkout", "-q", back]);
+        git(repo, ["branch", "-q", "-D", plan.to]);
+        process.exitCode = 1;
+      } else {
+        git(repo, ["commit", "-q", "-m", plan.subject]);
+        plan.applied = true;
+        plan.portedSha = git(repo, ["rev-parse", "HEAD"]).trim();
+        plan.differsFromHead = lines(
+          git(repo, ["diff", "--name-only", plan.head, "HEAD", "--", ...plan.changedPaths]),
+        );
+        git(repo, ["checkout", "-q", back]);
+      }
+    } catch (err) {
+      return fail(`git failed while applying: ${String(err.stderr || err.message).trim()}`);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  }
+
+  const json = `${JSON.stringify(plan, null, 2)}\n`;
+  if (args.out) writeFileSync(args.out, json);
+  process.stdout.write(json);
+}
+
+if (invokedDirectly(import.meta.url)) runMain("valven-port", main, { code: 2 });

package/pipeline/scripts/valven-split.mjs

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+
+/**
+ * @file valven-split.mjs  -  split one branch into stacked pull requests that
+ * each fit the valven-rules size budget (VLV-SIZE-01, VLV-SIZE-02, VLV-SCOPE-01).
+ *
+ * Usage:
+ *   valven-split.mjs --base <ref> [--repo <dir>] [--head <ref>] [--branch <name>]
+ *                    [--budget <lines>] [--max-files <n>] [--rules <rules.yml>]
+ *                    [--prefs <prefs.json>] [--apply] [--out <file>]
+ *
+ * Without --apply it prints the plan and changes nothing. With --apply it
+ * creates `<branch>-p1` .. `<branch>-pN`: p1 from the merge-base, each next one
+ * from the previous, one commit per slice, then checks that the top of the
+ * stack has exactly the tree of the original branch and returns to it. Nothing
+ * is pushed.
+ *
+ * Slicing:
+ *   1. Pure renames and moves form the first slice.
+ *   2. Every test file travels with the source file it pairs with by name.
+ *   3. Groups are ordered by layer: data (models, services, repositories), then
+ *      domain (view models, use cases, state), then UI, then everything else.
+ *   4. Groups are packed greedily up to the budget. A group larger than the
+ *      budget becomes its own slice and is marked `oversized`; it is never cut.
+ *   5. Generated output, lockfiles and snapshots (review-file-exclusions.json)
+ *      count toward no budget and ride with the first content slice, since the
+ *      code in every later slice may compile against them.
+ *
+ * Exit codes:
+ *   0   -  plan printed, or applied and the stack's top matches the branch
+ *   1   -  applied, but the top of the stack differs from the branch (left in place for inspection)
+ *   2   -  setup error: bad arguments, dirty worktree on --apply, git failure, a target branch already exists
+ *
+ * @module pipeline/scripts/valven-split
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadPatterns, partition } from "./review-file-filter.mjs";
+import {
+  applyOverrides,
+  isPureRename,
+  isTestPath,
+  parseGateRules,
+  parseNumstatZ,
+  rulesCandidates,
+} from "./valven-gate.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { prefsPath } from "../lib/user-facing.mjs";
+
+const DEFAULT_PATTERNS = join(import.meta.dirname, "..", "schemas", "review-file-exclusions.json");
+
+const LAYERS = [
+  {
+    name: "data",
+    re: /(model|entity|dto|service|repository|repo\b|network|api|endpoint|mapper|schema|migration|request|response|client|datasource|dao)/i,
+  },
+  {
+    name: "domain",
+    re: /(viewmodel|view_model|usecase|use_case|interactor|presenter|store|reducer|state|coordinator|router|formstate)/i,
+  },
+  {
+    name: "ui",
+    re: /(view|screen|scene|component|composable|fragment|activity|controller|cell|sheet|\/ui\/)/i,
+  },
+];
+
+/**
+ * Match order differs from rank order: `ViewModel` contains both `model` and
+ * `view`, so the domain pattern is tried first.
+ */
+const MATCH_ORDER = [1, 0, 2];
+
+/** Layer rank of a path: 0 data, 1 domain, 2 ui, 3 other. File name first, then the path. */
+export function layerOf(path) {
+  const name = path.split("/").pop() ?? path;
+  for (const subject of [name, path]) {
+    for (const i of MATCH_ORDER) {
+      if (LAYERS[i].re.test(subject)) return i;
+    }
+  }
+  return LAYERS.length;
+}
+
+export const LAYER_NAMES = [...LAYERS.map((l) => l.name), "other"];
+
+/** File stem without the test suffix: `LoginViewModelTests.swift` -> `LoginViewModel`. */
+export function stemOf(path) {
+  const file = path.split("/").pop() ?? path;
+  return file
+    .replace(/\.[^.]+$/, "")
+    .replace(/(\.test|\.spec|_test|Tests|Test|Spec)$/, "")
+    .toLowerCase();
+}
+
+const churn = (f) => f.added + f.deleted;
+
+/**
+ * Build the slice plan. Pure.
+ *
+ * @param {{path:string, oldPath:string|null, added:number, deleted:number}[]} files
+ * @param {{budget:number, maxFiles:number, patterns:object[]}} opts
+ */
+export function planSlices(files, { budget, maxFiles, patterns }) {
+  const { reviewed } = partition(
+    files.map((f) => f.path),
+    patterns,
+  );
+  const keep = new Set(reviewed);
+  const human = files.filter((f) => keep.has(f.path));
+  const riders = files.filter((f) => !keep.has(f.path));
+
+  const renames = human.filter(isPureRename);
+  const content = human.filter((f) => !isPureRename(f));
+
+  const tests = content.filter((f) => isTestPath(f.path));
+  const sources = content.filter((f) => !isTestPath(f.path));
+  const groups = sources.map((f) => ({ files: [f], layer: layerOf(f.path), key: f.path }));
+  const byStem = new Map();
+  for (const g of groups) {
+    const s = stemOf(g.key);
+    if (!byStem.has(s)) byStem.set(s, g);
+  }
+  for (const t of tests) {
+    const g = byStem.get(stemOf(t.path));
+    if (g) g.files.push(t);
+    else groups.push({ files: [t], layer: layerOf(t.path), key: t.path });
+  }
+  groups.sort((a, b) => a.layer - b.layer || a.key.localeCompare(b.key));
+
+  const slices = [];
+  if (renames.length) {
+    slices.push({ kind: "renames", files: renames, lines: 0, layers: [], oversized: false });
+  }
+  let cur = null;
+  const close = () => {
+    if (cur && cur.files.length) slices.push(cur);
+    cur = null;
+  };
+  for (const g of groups) {
+    const lines = g.files.reduce((n, f) => n + churn(f), 0);
+    const layer = LAYER_NAMES[g.layer];
+    if (lines > budget || g.files.length > maxFiles) {
+      close();
+      slices.push({ kind: "content", files: g.files, lines, layers: [layer], oversized: true });
+      continue;
+    }
+    if (cur && (cur.lines + lines > budget || cur.files.length + g.files.length > maxFiles))
+      close();
+    if (!cur) cur = { kind: "content", files: [], lines: 0, layers: [], oversized: false };
+    cur.files.push(...g.files);
+    cur.lines += lines;
+    if (!cur.layers.includes(layer)) cur.layers.push(layer);
+  }
+  close();
+
+  if (riders.length) {
+    const target = slices.find((s) => s.kind === "content") ?? slices[0];
+    if (target) target.riders = riders;
+    else
+      slices.push({ kind: "generated", files: [], riders, lines: 0, layers: [], oversized: false });
+  }
+  return slices.map((s, i) => ({ index: i + 1, riders: [], ...s }));
+}
+
+/** Subject for slice k of n, keeping a trailing `[KEY-1]` at the end. */
+export function sliceSubject(base, k, n) {
+  const m = /^(.*?)(\s*\[[A-Z][A-Z0-9]+-\d+\])\s*$/.exec(base);
+  return m ? `${m[1]} (${k}/${n})${m[2]}` : `${base} (${k}/${n})`;
+}
+
+// ---------------------------------------------------------------------------
+// I/O
+// ---------------------------------------------------------------------------
+
+function git(repo, args) {
+  return execFileSync("git", ["-C", repo, ...args], {
+    encoding: "utf-8",
+    maxBuffer: 64 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--apply") {
+      args.apply = true;
+      continue;
+    }
+    if (!a.startsWith("--")) throw new Error(`unexpected argument ${a}`);
+    const val = argv[i + 1];
+    if (val === undefined || val.startsWith("--")) throw new Error(`${a} needs a value`);
+    args[a.slice(2)] = val;
+    i++;
+  }
+  return args;
+}
+
+function fail(msg) {
+  process.stderr.write(`valven-split: ${msg}\n`);
+  process.exitCode = 2;
+}
+
+function readThresholds(args) {
+  let overrides;
+  try {
+    overrides =
+      JSON.parse(readFileSync(args.prefs ?? prefsPath(), "utf-8"))?.global?.valven?.thresholds ??
+      {};
+  } catch {
+    overrides = {};
+  }
+  const rulesPath = args.rules ?? rulesCandidates().find((p) => existsSync(p));
+  const rules =
+    rulesPath && existsSync(rulesPath)
+      ? applyOverrides(parseGateRules(readFileSync(rulesPath, "utf-8")).rules, overrides)
+      : [];
+  const size = rules.find((r) => r.id === "VLV-SIZE-01");
+  const files = rules.find((r) => r.id === "VLV-SIZE-02");
+  return {
+    budget: Number(args.budget ?? size?.important_over ?? 250),
+    maxFiles: Number(args["max-files"] ?? files?.important_over ?? 25),
+  };
+}
+
+function applySlice(repo, head, slice) {
+  const touch = [...slice.files, ...slice.riders];
+  for (const f of touch) {
+    if (f.oldPath && f.oldPath !== f.path)
+      git(repo, ["rm", "-q", "--cached", "--ignore-unmatch", "--", f.oldPath]);
+    if (f.deletedFile) git(repo, ["rm", "-q", "--cached", "--ignore-unmatch", "--", f.path]);
+    else git(repo, ["checkout", head, "--", f.path]);
+  }
+  git(repo, ["checkout", "--", "."]);
+  git(repo, ["clean", "-fdq"]);
+}
+
+async function main() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    return fail(err.message);
+  }
+  if (!args.base) return fail("--base is required");
+  const repo = args.repo ?? process.cwd();
+  const head = args.head ?? "HEAD";
+  const { budget, maxFiles } = readThresholds(args);
+  if (!(budget > 0) || !(maxFiles > 0))
+    return fail("budget and max-files must be positive numbers");
+  const { patterns, error } = loadPatterns(args.patterns ?? DEFAULT_PATTERNS);
+  if (error) process.stderr.write(`valven-split: ${error}; counting every file\n`);
+
+  let mergeBase;
+  let headSha;
+  let branch;
+  let files;
+  let firstSubject;
+  try {
+    mergeBase = git(repo, ["merge-base", args.base, head]).trim();
+    headSha = git(repo, ["rev-parse", head]).trim();
+    branch = args.branch ?? git(repo, ["rev-parse", "--abbrev-ref", head]).trim();
+    files = parseNumstatZ(git(repo, ["diff", "--numstat", "-z", "-M", mergeBase, headSha]));
+    const deleted = new Set(
+      git(repo, ["diff", "--name-only", "-z", "--diff-filter=D", mergeBase, headSha])
+        .split("\0")
+        .filter(Boolean),
+    );
+    for (const f of files) f.deletedFile = deleted.has(f.path);
+    firstSubject =
+      git(repo, ["log", "--no-merges", "--reverse", "--format=%s", `${mergeBase}..${headSha}`])
+        .split("\n")
+        .find(Boolean) ?? branch;
+  } catch (err) {
+    return fail(`git failed: ${String(err.stderr || err.message).trim()}`);
+  }
+
+  const slices = planSlices(files, { budget, maxFiles, patterns });
+  const n = slices.length;
+  const plan = {
+    branch,
+    base: args.base,
+    mergeBase,
+    head: headSha,
+    budget,
+    maxFiles,
+    sliceCount: n,
+    slices: slices.map((s) => ({
+      index: s.index,
+      branch: `${branch}-p${s.index}`,
+      parent: s.index === 1 ? args.base : `${branch}-p${s.index - 1}`,
+      kind: s.kind,
+      lines: s.lines,
+      layers: s.layers,
+      oversized: s.oversized,
+      subject: sliceSubject(firstSubject, s.index, n),
+      files: s.files.map((f) => f.path),
+      riders: s.riders.map((f) => f.path),
+    })),
+    applied: false,
+  };
+
+  if (args.apply && n > 1) {
+    try {
+      if (git(repo, ["status", "--porcelain"]).trim()) return fail("worktree is not clean");
+      for (const s of plan.slices) {
+        if (git(repo, ["branch", "--list", s.branch]).trim())
+          return fail(`branch ${s.branch} already exists`);
+      }
+      const original = git(repo, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+      let parent = mergeBase;
+      for (const [i, s] of slices.entries()) {
+        const name = plan.slices[i].branch;
+        git(repo, ["checkout", "-q", "-b", name, parent]);
+        applySlice(repo, headSha, s);
+        git(repo, ["commit", "-q", "--allow-empty", "-m", plan.slices[i].subject]);
+        parent = name;
+      }
+      const drift = git(repo, ["diff", "--name-only", parent, headSha]).trim();
+      git(repo, ["checkout", "-q", original === "HEAD" ? headSha : original]);
+      plan.applied = true;
+      plan.topMatchesBranch = drift === "";
+      if (drift) {
+        plan.drift = drift.split("\n");
+        process.exitCode = 1;
+      }
+    } catch (err) {
+      return fail(`git failed while applying: ${String(err.stderr || err.message).trim()}`);
+    }
+  }
+
+  const json = `${JSON.stringify(plan, null, 2)}\n`;
+  if (args.out) writeFileSync(args.out, json);
+  process.stdout.write(json);
+}
+
+if (invokedDirectly(import.meta.url)) runMain("valven-split", main, { code: 2 });

package/pipeline/scripts/verify-citations.mjs

@@ -199,7 +199,7 @@ export function extract(raw, { nested = true, quotes = true } = {}) {
       for (const [i, item] of (Array.isArray(doc[key]) ? doc[key] : []).entries()) {
         if (!item || typeof item !== "object") continue;
         const f = nested && item.finding && typeof item.finding === "object" ? item.finding : item;
-        push(f.file, Number(f.line), `${key}[${i}]`, f.quote);
+        push(f.file, citedLine(f), `${key}[${i}]`, f.quote);
       }
     }
     const repoEvidence = doc?.evidence?.repoEvidence || doc?.analysisSpec?.evidence?.repoEvidence;
@@ -256,6 +256,19 @@ export function extract(raw, { nested = true, quotes = true } = {}) {
   return out;
 }
 
+/**
+ * The line a finding cites. A valven-rules finding judges the pull request as a
+ * whole and carries `line: 0`; only its file is resolved. Every other source
+ * keeps the strict check, so line 0 is not a way around it.
+ *
+ * @param {{line?: unknown, criteriaSource?: unknown}} f
+ * @returns {number}
+ */
+export function citedLine(f) {
+  if (f.criteriaSource === "valven-rules" && Number(f.line) === 0) return Number.NaN;
+  return Number(f.line);
+}
+
 /**
  * Resolve one citation at a commit, or in the checkout when `rev` is null.
  *

package/pipeline/skills/.skill-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-10-02T08:26:22Z",
-  "skillCount": 220,
+  "generatedAt": "2026-10-02T10:19:25Z",
+  "skillCount": 221,
   "entries": [
     {
       "path": "shared/core/apple-archive-compliance/SKILL.md",
@@ -161,7 +161,7 @@
     },
     {
       "path": "shared/core/multi-agent-review/SKILL.md",
-      "sha256": "1cbe44b2ec63e0e158ded35825876e7dc9c45732fc9b067f0655e68823188efb"
+      "sha256": "cd500e32efdf6c8f36da5bb2e43d2558d096e33cd3274aead5118dd2c14f118a"
     },
     {
       "path": "shared/core/multi-agent-route-off/SKILL.md",
@@ -267,6 +267,10 @@
       "path": "shared/core/multi-agent/SKILL.md",
       "sha256": "3dd44ccc00e41c09e59ad223900a391f80158bd3f69e45d67c684285bc42418d"
     },
+    {
+      "path": "shared/core/valven-rules/SKILL.md",
+      "sha256": "274299b75e36991941b8402ae025967ce553878100c1a3878a955d27f5b7db9e"
+    },
     {
       "path": "shared/external/accessibility-compliance-accessibility-audit/SKILL.md",
       "sha256": "0508b6e832b43d54c6ed5f57d42c292925b81e4df1c132ba1786860385ea2838"