@mmerterden/multi-agent-pipeline 20.15.0 → 20.16.0

package/pipeline/scripts/valven-gate.mjs

@@ -0,0 +1,788 @@
+#!/usr/bin/env node
+
+/**
+ * @file valven-gate.mjs  -  measure a change set against the valven-rules
+ * registry (skills/.../valven-rules/references/rules.yml, block `gate_rules`).
+ *
+ * Usage:
+ *   valven-gate.mjs --mode dev|commit|review
+ *                   [--repo <dir>] [--base <ref>] [--head <ref> | --worktree] [--branch <name>]
+ *                   [--diff-file <patch>] [--commits-file <path>] [--pr-body-file <path>]
+ *                   [--rules <rules.yml>] [--prefs <prefs.json>] [--now <ISO date>]
+ *                   [--out <file>]
+ *
+ * Two input shapes:
+ *   - a checkout: --repo plus --base (and --head, default HEAD; --worktree measures
+ *     the working tree instead, untracked files included). Sizes come from
+ *     `git diff --numstat -M`, commit subjects from `git log`, the rework ratio
+ *     from `git blame` of the removed lines at the merge-base.
+ *   - no checkout (a PR fetched over an API): --diff-file, with --commits-file
+ *     (one subject per line), --branch and --pr-body-file when known. The rework
+ *     ratio needs history, so it is reported `not-measured`.
+ *
+ * A rule that cannot be measured is `not-measured` with the reason, never a pass.
+ * Generated output, lockfiles and snapshots are removed with the same pattern
+ * list the reviewers use (review-file-filter.mjs), so no budget counts them.
+ *
+ * Findings are reviewer-shaped: a PR-level finding carries `line: 0` and the
+ * changed file with the largest churn, so post-pr-review.sh posts it as a
+ * top-level comment and verify-citations.mjs accepts it (criteriaSource
+ * `valven-rules` only).
+ *
+ * Exit codes:
+ *   0   -  no important or blocking finding (or the gate is disabled by prefs)
+ *   1   -  at least one important or blocking finding
+ *   2   -  setup error: bad arguments, rules file not found or unreadable, git failure
+ *
+ * @module pipeline/scripts/valven-gate
+ */
+
+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 { unquotePathIfNeeded } from "./git-path.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { messages, outputLanguage, prefsPath } from "../lib/user-facing.mjs";
+
+export const CRITERIA_SOURCE = "valven-rules";
+export const TAG = "valven";
+const MODES = new Set(["dev", "commit", "review"]);
+const SOURCE_EXT_RE = /\.(swift|kt|kts|java|m|mm|ts|tsx|js|jsx|mjs|py|go|rb|cs)$/;
+const TEST_PATH_RE =
+  /(^|\/)(Tests?|tests?|__tests__|androidTest|UITests?|spec)\/|(Tests?|Spec|\.test|\.spec|_test)\.[a-z]+$/;
+const SPLIT_RULES = new Set(["VLV-SIZE-01", "VLV-SIZE-02", "VLV-SCOPE-01"]);
+const DEFAULT_PATTERNS = join(import.meta.dirname, "..", "schemas", "review-file-exclusions.json");
+
+/**
+ * Candidate locations of rules.yml relative to this script, installed layouts
+ * first: Claude Code and Copilot (`<root>/skills`), Codex
+ * (`<root>/multi-agent-refs/skills`), then the source checkout.
+ */
+export function rulesCandidates(dir = import.meta.dirname) {
+  const rel = ["valven-rules", "references", "rules.yml"];
+  return [
+    join(dir, "..", "skills", ...rel),
+    join(dir, "..", "multi-agent-refs", "skills", ...rel),
+    join(dir, "..", "skills", "shared", "core", ...rel),
+  ];
+}
+
+function parseScalar(raw) {
+  const v = raw.trim();
+  if (v.startsWith("[") && v.endsWith("]")) {
+    return v
+      .slice(1, -1)
+      .split(",")
+      .map((s) => parseScalar(s))
+      .filter((s) => s !== "");
+  }
+  if (/^".*"$/.test(v)) return JSON.parse(v);
+  if (/^'.*'$/.test(v)) return v.slice(1, -1);
+  if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v);
+  return v;
+}
+
+/**
+ * Read the `gate_rules` block. Fixed indentation, same convention the
+ * skill-conformance reader uses: a rule starts at two spaces with `- id:`, its
+ * fields sit at four spaces.
+ *
+ * @param {string} text
+ * @returns {{version: string|null, rules: object[]}}
+ */
+export function parseGateRules(text) {
+  const rules = [];
+  let version = null;
+  let inBlock = false;
+  let cur = null;
+  for (const raw of text.split("\n")) {
+    const line = raw.replace(/\s+$/, "");
+    if (!line || /^\s*#/.test(line)) continue;
+    const top = /^([a-z_]+):(.*)$/.exec(line);
+    if (top) {
+      if (top[1] === "version") version = top[2].trim() || null;
+      inBlock = top[1] === "gate_rules";
+      if (cur) rules.push(cur);
+      cur = null;
+      continue;
+    }
+    if (!inBlock) continue;
+    const id = /^ {2}- id:\s*(.+)$/.exec(line);
+    if (id) {
+      if (cur) rules.push(cur);
+      cur = { id: id[1].trim() };
+      continue;
+    }
+    const field = /^ {4}([a-z_]+):\s*(.*)$/.exec(line);
+    if (cur && field) cur[field[1]] = parseScalar(field[2]);
+  }
+  if (cur) rules.push(cur);
+  return { version, rules };
+}
+
+/**
+ * Apply `prefs.global.valven.thresholds` on top of the registry defaults. Only
+ * keys the rule already has are taken, so a typo cannot add a threshold the
+ * evaluator never reads and leave the default silently in force.
+ */
+export function applyOverrides(rules, overrides) {
+  if (!overrides || typeof overrides !== "object") return rules;
+  return rules.map((r) => {
+    const o = overrides[r.id];
+    if (!o || typeof o !== "object") return r;
+    const next = { ...r };
+    for (const [k, v] of Object.entries(o)) {
+      if (Object.hasOwn(r, k) && k !== "id") next[k] = v;
+    }
+    return next;
+  });
+}
+
+/**
+ * Parse `git diff --numstat -z -M` output.
+ *
+ * @param {string} out
+ * @returns {{path: string, oldPath: string|null, added: number, deleted: number, binary: boolean}[]}
+ */
+export function parseNumstatZ(out) {
+  const parts = out.split("\0");
+  const files = [];
+  for (let i = 0; i < parts.length; i++) {
+    const rec = parts[i];
+    if (!rec) continue;
+    const m = /^(-|\d+)\t(-|\d+)\t(.*)$/s.exec(rec.replace(/^\n/, ""));
+    if (!m) continue;
+    const binary = m[1] === "-";
+    const added = binary ? 0 : Number(m[1]);
+    const deleted = binary ? 0 : Number(m[2]);
+    if (m[3] === "") {
+      const oldPath = parts[++i];
+      const path = parts[++i];
+      files.push({ path, oldPath, added, deleted, binary });
+    } else {
+      files.push({ path: m[3], oldPath: null, added, deleted, binary });
+    }
+  }
+  return files;
+}
+
+/**
+ * Derive the same per-file stats from a unified patch, for the no-checkout path.
+ *
+ * @param {string} patch
+ */
+export function parsePatch(patch) {
+  const files = [];
+  let cur = null;
+  let inHunk = false;
+  for (const line of patch.split("\n")) {
+    const head = /^diff --git a\/(.+) b\/(.+)$/.exec(line);
+    if (head) {
+      if (cur) files.push(cur);
+      cur = {
+        path: unquotePathIfNeeded(head[2]),
+        oldPath: null,
+        added: 0,
+        deleted: 0,
+        binary: false,
+        deletedFile: false,
+      };
+      inHunk = false;
+      continue;
+    }
+    if (!cur) continue;
+    if (!inHunk) {
+      const from = /^rename from (.+)$/.exec(line);
+      if (from) cur.oldPath = unquotePathIfNeeded(from[1]);
+      const to = /^rename to (.+)$/.exec(line);
+      if (to) cur.path = unquotePathIfNeeded(to[1]);
+      if (/^deleted file mode/.test(line)) cur.deletedFile = true;
+      if (/^Binary files /.test(line)) cur.binary = true;
+      if (line.startsWith("@@")) inHunk = true;
+      continue;
+    }
+    if (line.startsWith("+") && !line.startsWith("+++ ")) cur.added++;
+    else if (line.startsWith("-") && !line.startsWith("--- ")) cur.deleted++;
+    else if (line.startsWith("@@")) inHunk = true;
+  }
+  if (cur) files.push(cur);
+  return files;
+}
+
+export const isTestPath = (p) => TEST_PATH_RE.test(p);
+export const isSourcePath = (p) => SOURCE_EXT_RE.test(p) && !isTestPath(p);
+export const isPureRename = (f) => Boolean(f.oldPath) && f.added === 0 && f.deleted === 0;
+
+/** Size and shape metrics over the human-authored files only. */
+export function measure(files, patterns) {
+  const { reviewed, excluded } = partition(
+    files.map((f) => f.path),
+    patterns,
+  );
+  const keep = new Set(reviewed);
+  const human = files.filter((f) => keep.has(f.path));
+  const renames = human.filter(isPureRename);
+  const content = human.filter((f) => !isPureRename(f));
+  const changedLines = human.reduce((n, f) => n + f.added + f.deleted, 0);
+  return {
+    human,
+    excluded,
+    changedLines,
+    fileCount: human.length,
+    renameCount: renames.length,
+    contentLines: content.reduce((n, f) => n + f.added + f.deleted, 0),
+    sourceFiles: human.filter((f) => isSourcePath(f.path) && !f.deletedFile).map((f) => f.path),
+    testFiles: human.filter((f) => isTestPath(f.path)).map((f) => f.path),
+  };
+}
+
+/** The file a PR-level finding is anchored to: the largest surviving change. */
+export function anchorFile(human) {
+  const live = human.filter((f) => !f.deletedFile);
+  const pool = live.length ? live : human;
+  if (!pool.length) return ".";
+  return [...pool].sort((a, b) => b.added + b.deleted - (a.added + a.deleted))[0].path;
+}
+
+const TEXT = {
+  en: {
+    size: (n, max) =>
+      `This pull request changes ${n} lines (budget ${max}). Split it into stacked PRs.`,
+    files: (n, max) =>
+      `This pull request touches ${n} files (budget ${max}). Split it into stacked PRs.`,
+    scope: (r, c) =>
+      `${r} pure renames/moves ship together with ${c} lines of content changes. Ship the renames as their own PR.`,
+    test: (n) => `${n} source file(s) changed and no test file changed.`,
+    branch: (b) => `Branch "${b}" carries no issue key.`,
+    commitKey: (s) => `Commit subject without an issue key: "${s}".`,
+    wip: (s) => `WIP/fixup commit in the branch: "${s}".`,
+    rework: (pct, max, days) =>
+      `${pct}% of the removed lines were written in the last ${days} days (budget ${max}%). This is rework.`,
+    prBody: (n, min) =>
+      n === 0 ? "The PR body is empty." : `The PR body is ${n} characters (minimum ${min}).`,
+    prTest: "The PR body does not say how the change was tested.",
+    hotfix: (n, max) => `Hotfix branch changes ${n} lines (budget ${max}).`,
+    age: (d, max) =>
+      `The oldest commit in this pull request is ${d} days old (budget ${max}). Start a fresh branch from the current base and carry the change over with valven-port.`,
+    behind: (n, d) =>
+      `The branch is ${n} commits behind its base and its merge-base is ${d} days old. Carry the change onto a fresh branch with valven-port.`,
+    foreign: (s, key) =>
+      `Commit "${s}" belongs to another issue (branch key ${key}). Move it to its own PR.`,
+  },
+  tr: {
+    size: (n, max) =>
+      `Bu PR ${n} satır değiştiriyor (sınır ${max}). PR'ı zincirleme küçük PR'lara böl.`,
+    files: (n, max) =>
+      `Bu PR ${n} dosyaya dokunuyor (sınır ${max}). PR'ı zincirleme küçük PR'lara böl.`,
+    scope: (r, c) =>
+      `${r} saf rename/taşıma, ${c} satırlık içerik değişikliğiyle aynı PR'da. Rename'leri ayrı PR olarak gönder.`,
+    test: (n) => `${n} kaynak dosya değişmiş ama hiçbir test dosyası değişmemiş.`,
+    branch: (b) => `"${b}" branch adında Jira ID'si yok.`,
+    commitKey: (s) => `Jira ID'si olmayan commit: "${s}".`,
+    wip: (s) => `Branch'te WIP/fixup commit var: "${s}".`,
+    rework: (pct, max, days) =>
+      `Silinen satırların %${pct}'i son ${days} günde yazılmış (sınır %${max}). Bu rework.`,
+    prBody: (n, min) =>
+      n === 0 ? "PR açıklaması boş." : `PR açıklaması ${n} karakter (en az ${min}).`,
+    prTest: "PR açıklaması değişikliğin nasıl test edildiğini söylemiyor.",
+    hotfix: (n, max) => `Hotfix branch'i ${n} satır değiştiriyor (sınır ${max}).`,
+    age: (d, max) =>
+      `Bu PR'daki en eski commit ${d} günlük (sınır ${max}). Güncel base'den yeni bir branch aç, değişikliği valven-port ile taşı, yeni PR aç ve bunu kapat.`,
+    behind: (n, d) =>
+      `Branch base'in ${n} commit gerisinde ve merge-base'i ${d} günlük. Değişikliği valven-port ile güncel base'den açılan yeni bir branch'e taşı.`,
+    foreign: (s, key) =>
+      `"${s}" commit'i başka bir işe ait (branch ID'si ${key}). Onu ayrı bir PR'a taşı.`,
+  },
+};
+
+/**
+ * Evaluate every gate rule. Pure: all I/O results arrive in `input`.
+ *
+ * @param {object} input
+ * @param {"dev"|"commit"|"review"} input.mode
+ * @param {object[]} input.rules       parsed gate_rules, overrides applied
+ * @param {ReturnType<typeof measure>} input.metrics
+ * @param {string|null} input.branch
+ * @param {string[]|null} input.commits  subjects, null when unknown
+ * @param {string|null} input.prBody     null when unknown
+ * @param {{ratio:number, recent:number, removed:number}|{reason:string}|null} input.rework
+ * @param {{oldestDays:number|null, behind:number|null, baseDays:number|null}|null} [input.history]
+ * @param {string} [input.lang]
+ */
+export function evaluate({
+  mode,
+  rules,
+  metrics,
+  branch,
+  commits,
+  prBody,
+  rework,
+  history = null,
+  lang = "en",
+}) {
+  const t = messages(TEXT, lang);
+  const anchor = anchorFile(metrics.human);
+  const results = [];
+  const findings = [];
+  const add = (rule, severity, issue, file = anchor) =>
+    findings.push({
+      severity,
+      file,
+      line: 0,
+      issue,
+      fix: rule.fix,
+      ruleId: rule.id,
+      criteriaSource: CRITERIA_SOURCE,
+      tag: TAG,
+    });
+  const record = (rule, status, detail) => results.push({ ruleId: rule.id, status, detail });
+
+  for (const rule of rules) {
+    const modes = Array.isArray(rule.modes) ? rule.modes : [];
+    if (!modes.includes(mode)) {
+      record(rule, "not-applicable", `not run in ${mode} mode`);
+      continue;
+    }
+    switch (rule.id) {
+      case "VLV-SIZE-01": {
+        const n = metrics.changedLines;
+        if (n > rule.blocking_over) {
+          add(rule, "blocking", t.size(n, rule.important_over));
+          record(rule, "violated", `${n} > ${rule.blocking_over}`);
+        } else if (n > rule.important_over) {
+          add(rule, rule.severity, t.size(n, rule.important_over));
+          record(rule, "violated", `${n} > ${rule.important_over}`);
+        } else record(rule, "pass", `${n} <= ${rule.important_over}`);
+        break;
+      }
+      case "VLV-SIZE-02": {
+        const n = metrics.fileCount;
+        if (n > rule.important_over) {
+          add(rule, rule.severity, t.files(n, rule.important_over));
+          record(rule, "violated", `${n} > ${rule.important_over}`);
+        } else record(rule, "pass", `${n} <= ${rule.important_over}`);
+        break;
+      }
+      case "VLV-SCOPE-01": {
+        const { renameCount: r, contentLines: c } = metrics;
+        if (r >= rule.renames_at_least && c > rule.content_lines_over) {
+          add(rule, rule.severity, t.scope(r, c));
+          record(rule, "violated", `${r} renames + ${c} content lines`);
+        } else record(rule, "pass", `${r} renames, ${c} content lines`);
+        break;
+      }
+      case "VLV-TEST-01": {
+        const src = metrics.sourceFiles;
+        if (src.length && !metrics.testFiles.length) {
+          add(rule, rule.severity, t.test(src.length), src[0]);
+          record(rule, "violated", `${src.length} source, 0 test`);
+        } else if (!src.length) record(rule, "not-applicable", "no source file changed");
+        else record(rule, "pass", `${metrics.testFiles.length} test file(s) changed`);
+        break;
+      }
+      case "VLV-TRACE-01": {
+        if (!branch || branch === "HEAD") {
+          record(rule, "not-measured", "branch name unknown");
+          break;
+        }
+        if (new RegExp(rule.key_pattern).test(branch)) record(rule, "pass", branch);
+        else {
+          add(rule, rule.severity, t.branch(branch));
+          record(rule, "violated", branch);
+        }
+        break;
+      }
+      case "VLV-TRACE-02": {
+        if (!commits) {
+          record(rule, "not-measured", "commit subjects unknown");
+          break;
+        }
+        const re = new RegExp(rule.key_pattern);
+        const bad = commits.filter((s) => !re.test(s));
+        for (const s of bad) add(rule, rule.severity, t.commitKey(s));
+        record(
+          rule,
+          bad.length ? "violated" : "pass",
+          `${bad.length}/${commits.length} without key`,
+        );
+        break;
+      }
+      case "VLV-COMMIT-01": {
+        if (!commits) {
+          record(rule, "not-measured", "commit subjects unknown");
+          break;
+        }
+        const re = new RegExp(rule.subject_pattern, "i");
+        const bad = commits.filter((s) => re.test(s.trim()));
+        for (const s of bad) add(rule, rule.severity, t.wip(s));
+        record(rule, bad.length ? "violated" : "pass", `${bad.length} WIP/fixup commit(s)`);
+        break;
+      }
+      case "VLV-REWORK-01": {
+        if (!rework || "reason" in rework) {
+          record(rule, "not-measured", rework?.reason ?? "no history");
+          break;
+        }
+        if (rework.removed < rule.min_removed_lines) {
+          record(rule, "pass", `${rework.removed} removed lines, below ${rule.min_removed_lines}`);
+        } else if (rework.ratio > rule.ratio_over) {
+          const pct = Math.round(rework.ratio * 100);
+          add(
+            rule,
+            rule.severity,
+            t.rework(pct, Math.round(rule.ratio_over * 100), rule.window_days),
+          );
+          record(rule, "violated", `${rework.recent}/${rework.removed}`);
+        } else record(rule, "pass", `${rework.recent}/${rework.removed}`);
+        break;
+      }
+      case "VLV-PRDESC-01": {
+        if (prBody === null || prBody === undefined) {
+          record(rule, "not-measured", "no PR body (branch mode)");
+          break;
+        }
+        const body = prBody.trim();
+        const short = body.length < rule.min_chars;
+        const untested = !new RegExp(rule.test_pattern, "i").test(body);
+        if (short) add(rule, rule.severity, t.prBody(body.length, rule.min_chars));
+        if (untested) add(rule, rule.severity, t.prTest);
+        record(rule, short || untested ? "violated" : "pass", `${body.length} chars`);
+        break;
+      }
+      case "VLV-AGE-01": {
+        const d = history?.oldestDays;
+        if (d === null || d === undefined) {
+          record(rule, "not-measured", "commit dates unknown");
+        } else if (d > rule.days_over) {
+          add(rule, rule.severity, t.age(d, rule.days_over));
+          record(rule, "violated", `${d} days`);
+        } else record(rule, "pass", `${d} days`);
+        break;
+      }
+      case "VLV-BEHIND-01": {
+        const n = history?.behind;
+        const d = history?.baseDays;
+        if (n === null || n === undefined || d === null || d === undefined) {
+          record(rule, "not-measured", "base history unknown (no checkout)");
+        } else if (n > rule.behind_over || d > rule.base_days_over) {
+          add(rule, rule.severity, t.behind(n, d));
+          record(rule, "violated", `${n} behind, merge-base ${d} days`);
+        } else record(rule, "pass", `${n} behind, merge-base ${d} days`);
+        break;
+      }
+      case "VLV-TRACE-03": {
+        const re = new RegExp(rule.key_pattern, "g");
+        const own = branch ? (branch.match(re) ?? [])[0] : undefined;
+        if (!commits || !own) {
+          record(
+            rule,
+            "not-measured",
+            !commits ? "commit subjects unknown" : "branch carries no key",
+          );
+          break;
+        }
+        const foreign = commits.filter((c) => {
+          const keys = c.match(re) ?? [];
+          return keys.length > 0 && !keys.includes(own);
+        });
+        for (const c of foreign) add(rule, rule.severity, t.foreign(c, own));
+        record(rule, foreign.length ? "violated" : "pass", `${foreign.length} foreign commit(s)`);
+        break;
+      }
+      case "VLV-HOTFIX-01": {
+        if (!branch || !new RegExp(rule.branch_pattern).test(branch)) {
+          record(rule, "not-applicable", "not a hotfix branch");
+          break;
+        }
+        const n = metrics.changedLines;
+        if (n > rule.important_over) {
+          add(rule, rule.severity, t.hotfix(n, rule.important_over));
+          record(rule, "violated", `${n} > ${rule.important_over}`);
+        } else record(rule, "pass", `${n} <= ${rule.important_over}`);
+        break;
+      }
+      default:
+        record(rule, "not-measured", "rule has no evaluator in this version of the gate");
+    }
+  }
+
+  const splitRequired = results.some((r) => SPLIT_RULES.has(r.ruleId) && r.status === "violated");
+  const failing = findings.some((f) => f.severity === "blocking" || f.severity === "important");
+  return { results, findings, splitRequired, failing };
+}
+
+// ---------------------------------------------------------------------------
+// I/O
+// ---------------------------------------------------------------------------
+
+function git(repo, args) {
+  return execFileSync("git", ["-C", repo, ...args], {
+    encoding: "utf-8",
+    maxBuffer: 64 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+/**
+ * One commit line: `<ISO date>\t<subject>` or a bare subject. The dated form is
+ * what `git log --format=%aI%x09%s` prints and what a PR caller writes from the
+ * provider API; author dates are used so a rebase does not make old work look new.
+ */
+export function parseCommitLine(line) {
+  const m = /^(\d{4}-\d{2}-\d{2}T[^\t]+)\t(.*)$/.exec(line);
+  if (!m) return { date: null, subject: line };
+  const date = new Date(m[1]);
+  return { date: Number.isNaN(date.getTime()) ? null : date, subject: m[2] };
+}
+
+/** Whole days from `from` to `to`, never negative. */
+export function daysBetween(from, to) {
+  return Math.max(0, Math.floor((to.getTime() - from.getTime()) / 86400000));
+}
+
+/** Removed-line hunks of one file, as [start, count] pairs on the old side. */
+export function removedRanges(unifiedZero) {
+  const out = [];
+  for (const line of unifiedZero.split("\n")) {
+    const m = /^@@ -(\d+)(?:,(\d+))? \+/.exec(line);
+    if (!m) continue;
+    const count = m[2] === undefined ? 1 : Number(m[2]);
+    if (count > 0) out.push([Number(m[1]), count]);
+  }
+  return out;
+}
+
+/** Committer times (epoch seconds) from `git blame --line-porcelain`. */
+export function blameTimes(porcelain) {
+  const times = [];
+  for (const line of porcelain.split("\n")) {
+    const m = /^committer-time (\d+)$/.exec(line);
+    if (m) times.push(Number(m[1]));
+  }
+  return times;
+}
+
+/**
+ * Share of the removed lines that were committed inside the window, blamed at
+ * the merge-base so the branch's own commits never count against it.
+ */
+function measureRework(repo, mergeBase, range, human, windowDays, now) {
+  const cutoff = Math.floor(now.getTime() / 1000) - windowDays * 86400;
+  let removed = 0;
+  let recent = 0;
+  for (const f of human) {
+    if (f.deleted === 0 || f.binary) continue;
+    const old = f.oldPath ?? f.path;
+    if (f.untracked) continue;
+    const diff = git(repo, ["diff", "-U0", "-M", ...range, "--", old, f.path]);
+    for (const [start, count] of removedRanges(diff)) {
+      const porcelain = git(repo, [
+        "blame",
+        "--line-porcelain",
+        "-L",
+        `${start},+${count}`,
+        mergeBase,
+        "--",
+        old,
+      ]);
+      const times = blameTimes(porcelain);
+      removed += times.length;
+      recent += times.filter((s) => s >= cutoff).length;
+    }
+  }
+  return { removed, recent, ratio: removed ? recent / removed : 0 };
+}
+
+/** Untracked, not ignored files, counted as fully added. A file holding a NUL byte is binary. */
+function untrackedFiles(repo) {
+  return git(repo, ["ls-files", "--others", "--exclude-standard", "-z"])
+    .split("\0")
+    .filter(Boolean)
+    .map((path) => {
+      let text;
+      try {
+        text = readFileSync(join(repo, path), "utf-8");
+      } catch {
+        text = "";
+      }
+      const binary = text.includes("\0");
+      const added = binary || !text ? 0 : text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+      return {
+        path,
+        oldPath: null,
+        added,
+        deleted: 0,
+        binary,
+        deletedFile: false,
+        untracked: true,
+      };
+    });
+}
+
+function readPrefs(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"))?.global?.valven ?? {};
+  } catch {
+    return {};
+  }
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--worktree") {
+      args.worktree = true;
+      continue;
+    }
+    if (!a.startsWith("--")) throw new Error(`unexpected argument ${a}`);
+    const key = a.slice(2);
+    const val = argv[i + 1];
+    if (val === undefined || val.startsWith("--")) throw new Error(`${a} needs a value`);
+    args[key] = val;
+    i++;
+  }
+  return args;
+}
+
+function fail(msg) {
+  process.stderr.write(`valven-gate: ${msg}\n`);
+  process.exitCode = 2;
+}
+
+async function main() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    return fail(err.message);
+  }
+  if (!MODES.has(args.mode)) return fail("--mode must be dev, commit or review");
+
+  const prefsFile = args.prefs ?? prefsPath();
+  const prefs = readPrefs(prefsFile);
+  if (prefs.enabled === false) {
+    process.stderr.write("valven: disabled by prefs\n");
+    const report = { mode: args.mode, enabled: false, results: [], findings: [] };
+    if (args.out) writeFileSync(args.out, `${JSON.stringify(report, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  const rulesPath = args.rules ?? rulesCandidates().find((p) => existsSync(p));
+  if (!rulesPath || !existsSync(rulesPath)) {
+    return fail(`rules.yml not found (searched ${rulesCandidates().join(", ")})`);
+  }
+  const { version, rules: parsed } = parseGateRules(readFileSync(rulesPath, "utf-8"));
+  if (!parsed.length) return fail(`${rulesPath} has no gate_rules`);
+  const rules = applyOverrides(parsed, prefs.thresholds);
+
+  const { patterns, error: patternError } = loadPatterns(args.patterns ?? DEFAULT_PATTERNS);
+  if (patternError) process.stderr.write(`valven-gate: ${patternError}; counting every file\n`);
+
+  const repo = args.repo ?? process.cwd();
+  const head = args.head ?? "HEAD";
+  let files;
+  let commits = null;
+  let branch = args.branch ?? null;
+  let rework = { reason: "no checkout (--diff-file input)" };
+  let commitDates = [];
+  let history = { behind: null, baseDays: null };
+  const now = args.now ? new Date(args.now) : new Date();
+
+  try {
+    if (args["diff-file"]) {
+      files = parsePatch(readFileSync(args["diff-file"], "utf-8"));
+    } else {
+      if (!args.base) return fail("--base is required without --diff-file");
+      const mergeBase = git(repo, ["merge-base", args.base, head]).trim();
+      const range = args.worktree ? [mergeBase] : [mergeBase, head];
+      files = parseNumstatZ(git(repo, ["diff", "--numstat", "-z", "-M", ...range]));
+      const deleted = new Set(
+        git(repo, ["diff", "--name-only", "-z", "--diff-filter=D", ...range])
+          .split("\0")
+          .filter(Boolean),
+      );
+      for (const f of files) f.deletedFile = deleted.has(f.path);
+      if (args.worktree) files.push(...untrackedFiles(repo));
+      const log = git(repo, ["log", "--no-merges", "--format=%aI%x09%s", `${mergeBase}..${head}`])
+        .split("\n")
+        .filter(Boolean)
+        .map(parseCommitLine);
+      commits = log.map((c) => c.subject);
+      commitDates = log.map((c) => c.date).filter(Boolean);
+      const behind = Number(git(repo, ["rev-list", "--count", `${head}..${args.base}`]).trim());
+      const baseDate = git(repo, ["log", "-1", "--format=%cI", mergeBase]).trim();
+      history = { behind, baseDays: daysBetween(new Date(baseDate), now) };
+      if (!branch) branch = git(repo, ["rev-parse", "--abbrev-ref", head]).trim();
+      const reworkRule = rules.find((r) => r.id === "VLV-REWORK-01");
+      if (reworkRule) {
+        const metricsForRework = measure(files, patterns);
+        rework = measureRework(
+          repo,
+          mergeBase,
+          range,
+          metricsForRework.human,
+          reworkRule.window_days,
+          now,
+        );
+      }
+    }
+  } catch (err) {
+    return fail(`git failed: ${String(err.stderr || err.message).trim()}`);
+  }
+
+  if (args["commits-file"]) {
+    const log = readFileSync(args["commits-file"], "utf-8")
+      .split("\n")
+      .map((s) => s.trim())
+      .filter(Boolean)
+      .map(parseCommitLine);
+    commits = log.map((c) => c.subject);
+    commitDates = log.map((c) => c.date).filter(Boolean);
+  }
+  const oldest = commitDates.length ? Math.min(...commitDates.map((d) => d.getTime())) : null;
+  history.oldestDays = oldest === null ? null : daysBetween(new Date(oldest), now);
+  const prBody = args["pr-body-file"] ? readFileSync(args["pr-body-file"], "utf-8") : null;
+
+  const metrics = measure(files, patterns);
+  const verdict = evaluate({
+    mode: args.mode,
+    rules,
+    metrics,
+    branch,
+    commits,
+    prBody,
+    rework,
+    history,
+    lang: args.lang ?? outputLanguage(prefsFile),
+  });
+
+  const report = {
+    mode: args.mode,
+    enabled: true,
+    rulesVersion: version,
+    rulesPath,
+    metrics: {
+      changedLines: metrics.changedLines,
+      fileCount: metrics.fileCount,
+      renameCount: metrics.renameCount,
+      contentLines: metrics.contentLines,
+      sourceFiles: metrics.sourceFiles.length,
+      testFiles: metrics.testFiles.length,
+      excludedFiles: metrics.excluded.length,
+      rework: "reason" in rework ? null : rework,
+    },
+    results: verdict.results,
+    findings: verdict.findings,
+    splitRequired: verdict.splitRequired,
+  };
+  const json = `${JSON.stringify(report, null, 2)}\n`;
+  if (args.out) writeFileSync(args.out, json);
+  process.stdout.write(json);
+  if (verdict.failing) process.exitCode = 1;
+}
+
+if (invokedDirectly(import.meta.url)) runMain("valven-gate", main, { code: 2 });