@mmerterden/multi-agent-pipeline 20.15.1 → 20.17.0

package/pipeline/scripts/valven-gate.mjs

@@ -0,0 +1,1069 @@
+#!/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>]
+ *                   [--pr-meta-file <json>]
+ *                   [--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`.
+ *
+ * --pr-meta-file adds the pull request's timing (`gh pr view --json
+ * author,closedAt,createdAt,isDraft,mergedAt,reviewRequests,reviews`, or the normalized
+ * shape normalizePrMeta() documents). Without it the pickup and review durations
+ * are `not-measured`; coding time is measured up to now in commit mode, where the
+ * pull request is about to open.
+ *
+ * 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 { homedir } from "node:os";
+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 { pluginSkillRootCandidates } from "../lib/plugin-skill-roots.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. The gate reads the registry that was
+ * installed with it, so its evaluators and its rules come from one release: on
+ * Claude Code `<root>/multi-agent-refs/registries/valven-rules` (the installer
+ * lays it down there because Claude Code loads the skill itself from the
+ * ai-common-toolkit plugin), on Copilot `<root>/skills`, on Codex
+ * `<root>/multi-agent-refs/skills`, and in a checkout the source. Searching the
+ * registries dir before `<root>/skills` also keeps a `~/.claude/skills/valven-rules`
+ * left by an older install from being read. The plugin copies come last, for a
+ * layout that has none of these.
+ *
+ * @param {string} [dir]  directory of this script
+ * @param {string} [home]
+ */
+export function rulesCandidates(dir = import.meta.dirname, home = homedir()) {
+  const rel = ["valven-rules", "references", "rules.yml"];
+  return [
+    join(dir, "..", "multi-agent-refs", "registries", ...rel),
+    join(dir, "..", "skills", ...rel),
+    join(dir, "..", "multi-agent-refs", "skills", ...rel),
+    join(dir, "..", "skills", "shared", "external", ...rel),
+    ...pluginSkillRootCandidates(home, ["ai-common-toolkit"]).map((root) =>
+      join(root, "knowledge", ...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;
+}
+
+/**
+ * The Valven score band of a duration: 100 under `full_under_minutes`, 75 under
+ * `three_quarter_under_minutes`, 50 under `half_under_minutes`, otherwise 0.
+ * Each bound is exclusive, as in Valven's table ("under 30 min", "30 min - 2.5 hours").
+ *
+ * @param {number} minutes
+ * @param {{full_under_minutes:number, three_quarter_under_minutes:number, half_under_minutes:number}} rule
+ */
+export function bandOf(minutes, rule) {
+  if (minutes < rule.full_under_minutes) return 100;
+  if (minutes < rule.three_quarter_under_minutes) return 75;
+  if (minutes < rule.half_under_minutes) return 50;
+  return 0;
+}
+
+const isoOrNull = (v) => {
+  if (!v) return null;
+  const d = new Date(v);
+  return Number.isNaN(d.getTime()) ? null : d.toISOString();
+};
+
+/** The earliest valid date that is not before `floor`, or null. */
+const earliest = (dates, floor) => {
+  const valid = dates
+    .map(isoOrNull)
+    .filter((d) => d && d >= floor)
+    .sort();
+  return valid[0] ?? null;
+};
+
+/**
+ * Pull request timing in one shape. Accepts `gh pr view --json
+ * author,closedAt,createdAt,isDraft,mergedAt,reviewRequests,reviews` as is, or the
+ * normalized form a Bitbucket caller writes: `{createdAt, readyAt, isDraft,
+ * reviewerCount, firstReviewAt, approvedAt, mergedAt, closedAt}`. Reviews by the pull
+ * request's own author, bots and pending reviews never count, and a review left
+ * before the pull request was ready for review (or before it opened) is not the
+ * first review: pickup and review time start at ready. A reviewer count the input does not carry
+ * stays null, so it reads as unknown rather than as "no reviewer". Returns null
+ * without a valid `createdAt`, because every duration here is anchored to it.
+ *
+ * @param {object|null} raw
+ */
+export function normalizePrMeta(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const createdAt = isoOrNull(raw.createdAt);
+  if (!createdAt) return null;
+  const base = {
+    createdAt,
+    readyAt: isoOrNull(raw.readyAt),
+    isDraft: raw.isDraft === true,
+    mergedAt: isoOrNull(raw.mergedAt),
+    closedAt: isoOrNull(raw.closedAt),
+  };
+  const floor = base.readyAt ?? createdAt;
+  if (Array.isArray(raw.reviews) || Array.isArray(raw.reviewRequests)) {
+    const author = raw.author?.login ?? null;
+    const isBot = (who) => who?.is_bot === true || /\[bot\]$/.test(who?.login ?? "");
+    const reviews = (raw.reviews ?? []).filter(
+      (r) => r?.author?.login !== author && r?.state !== "PENDING" && !isBot(r?.author),
+    );
+    const people = new Set([
+      ...(raw.reviewRequests ?? []).map((r) => r?.login ?? r?.name ?? r?.slug).filter(Boolean),
+      ...reviews.map((r) => r.author?.login).filter(Boolean),
+    ]);
+    return {
+      ...base,
+      reviewerCount: people.size,
+      firstReviewAt: earliest(
+        reviews.map((r) => r.submittedAt),
+        floor,
+      ),
+      approvedAt: earliest(
+        reviews.filter((r) => r.state === "APPROVED").map((r) => r.submittedAt),
+        floor,
+      ),
+    };
+  }
+  return {
+    ...base,
+    reviewerCount: Number.isFinite(raw.reviewerCount) ? raw.reviewerCount : null,
+    firstReviewAt: earliest([raw.firstReviewAt], floor),
+    approvedAt: earliest([raw.approvedAt], floor),
+  };
+}
+
+const minutesBetween = (from, to) =>
+  Math.max(0, Math.floor((new Date(to).getTime() - new Date(from).getTime()) / 60000));
+
+function duration(minutes, lang) {
+  const tr = lang === "tr";
+  if (minutes < 60) return tr ? `${minutes} dakika` : `${minutes} min`;
+  const hours = Math.round((minutes / 60) * 10) / 10;
+  return tr ? `${String(hours).replace(".", ",")} saat` : `${hours} h`;
+}
+
+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.`,
+    coding: (d, band) =>
+      `Coding took ${d} from the first commit to opening the pull request (Valven score ${band}%). Open the pull request as soon as the first slice works, and keep slices small.`,
+    pickup: (d, band, waiting) =>
+      waiting
+        ? `The pull request has waited ${d} for its first review (Valven score ${band}%). Remind the reviewers or ask the team for one.`
+        : `The first review came ${d} after the pull request was ready (Valven score ${band}%).`,
+    review: (d, band, open) =>
+      open
+        ? `The pull request has been in review for ${d} without an approval (Valven score ${band}%). Answer every comment in one round and push the fixes together.`
+        : `Review took ${d} from the first review to approval (Valven score ${band}%). Answer every comment in one round and push the fixes together.`,
+    noReviewer:
+      "The pull request has no reviewer, so nobody is asked to review it. Assign the default reviewers.",
+    draft: (d) =>
+      `The pull request has been a draft for ${d}. Mark it ready for review once its gates pass, or close it.`,
+  },
+  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şı.`,
+    coding: (d, band) =>
+      `İlk commit'ten PR'ın açılmasına kadar ${d} geçmiş (Valven puanı %${band}). İlk dilim çalışır hale gelince PR'ı hemen aç, dilimleri küçük tut.`,
+    pickup: (d, band, waiting) =>
+      waiting
+        ? `PR ${d} süredir ilk review'u bekliyor (Valven puanı %${band}). Reviewer'lara hatırlat ya da takımdan birini iste.`
+        : `İlk review, PR hazır olduktan ${d} sonra geldi (Valven puanı %${band}).`,
+    review: (d, band, open) =>
+      open
+        ? `PR ${d} süredir review'da ve onay almadı (Valven puanı %${band}). Bütün yorumları tek turda yanıtla, düzeltmeleri birlikte push'la.`
+        : `İlk review'dan onaya kadar ${d} geçmiş (Valven puanı %${band}). Bütün yorumları tek turda yanıtla, düzeltmeleri birlikte push'la.`,
+    noReviewer: "PR'da reviewer yok, kimseden review istenmiyor. Varsayılan reviewer'ları ekle.",
+    draft: (d) =>
+      `PR ${d} süredir draft. Gate'leri geçtiyse review'a hazır olarak işaretle ya da kapat.`,
+  },
+};
+
+/**
+ * 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, oldestCommitAt?:Date|null, behind:number|null, baseDays:number|null}|null} [input.history]
+ * @param {ReturnType<typeof normalizePrMeta>} [input.prMeta]  null when no pull request is known
+ * @param {Date} [input.now]
+ * @param {string} [input.lang]
+ */
+export function evaluate({
+  mode,
+  rules,
+  metrics,
+  branch,
+  commits,
+  prBody,
+  rework,
+  history = null,
+  prMeta = null,
+  now = new Date(),
+  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, score) =>
+    results.push(
+      score === undefined
+        ? { ruleId: rule.id, status, detail }
+        : { ruleId: rule.id, status, detail, score },
+    );
+  const scoreDuration = (rule, minutes, issue, detail) => {
+    const band = bandOf(minutes, rule);
+    if (band <= 50) {
+      add(rule, rule.severity, issue(duration(minutes, lang), band));
+      record(rule, "violated", detail, band);
+    } else record(rule, "pass", detail, band);
+  };
+
+  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;
+        }
+        const score = Math.round((1 - rework.ratio) * 100);
+        if (rework.removed < rule.min_removed_lines) {
+          record(
+            rule,
+            "pass",
+            `${rework.removed} removed lines, below ${rule.min_removed_lines}`,
+            score,
+          );
+        } 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}`, score);
+        } else record(rule, "pass", `${rework.recent}/${rework.removed}`, score);
+        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;
+      }
+      case "VLV-CYCLE-01": {
+        const start = history?.oldestCommitAt ?? null;
+        const end = prMeta ? prMeta.createdAt : mode === "commit" ? now : null;
+        if (!start) {
+          record(rule, "not-measured", "commit dates unknown");
+          break;
+        }
+        if (!end) {
+          record(rule, "not-measured", "no pull request opening time (branch input)");
+          break;
+        }
+        const m = minutesBetween(start, end);
+        scoreDuration(rule, m, t.coding, `${m} min to open`);
+        break;
+      }
+      case "VLV-CYCLE-02": {
+        if (!prMeta) {
+          record(rule, "not-measured", "no pull request metadata");
+          break;
+        }
+        const ready = prMeta.readyAt ?? (prMeta.isDraft ? null : prMeta.createdAt);
+        if (!ready) {
+          record(rule, "not-measured", "still a draft; the pickup clock has not started");
+          break;
+        }
+        if (!prMeta.firstReviewAt && (prMeta.mergedAt || prMeta.closedAt)) {
+          record(
+            rule,
+            "not-measured",
+            prMeta.mergedAt ? "merged without a review" : "closed without a review",
+          );
+          break;
+        }
+        const waiting = !prMeta.firstReviewAt;
+        const m = minutesBetween(ready, prMeta.firstReviewAt ?? now);
+        scoreDuration(
+          rule,
+          m,
+          (d, band) => t.pickup(d, band, waiting),
+          waiting ? `${m} min, still waiting` : `${m} min to first review`,
+        );
+        break;
+      }
+      case "VLV-CYCLE-03": {
+        if (!prMeta?.firstReviewAt) {
+          record(rule, "not-measured", prMeta ? "no review yet" : "no pull request metadata");
+          break;
+        }
+        const done = prMeta.approvedAt ?? prMeta.mergedAt ?? prMeta.closedAt;
+        const m = minutesBetween(prMeta.firstReviewAt, done ?? now);
+        scoreDuration(
+          rule,
+          m,
+          (d, band) => t.review(d, band, !done),
+          done ? `${m} min to approval` : `${m} min, still in review`,
+        );
+        break;
+      }
+      case "VLV-PICKUP-01": {
+        if (!prMeta) {
+          record(rule, "not-measured", "no pull request metadata");
+          break;
+        }
+        if (prMeta.mergedAt || prMeta.closedAt) {
+          record(rule, "not-applicable", prMeta.mergedAt ? "already merged" : "closed");
+          break;
+        }
+        const problems = [];
+        const reviewerUnknown =
+          prMeta.reviewerCount === null && !prMeta.firstReviewAt && !prMeta.isDraft;
+        if (prMeta.reviewerCount === 0 && !prMeta.firstReviewAt && !prMeta.isDraft) {
+          add(rule, rule.severity, t.noReviewer);
+          problems.push("no reviewer");
+        }
+        const draftFor = minutesBetween(prMeta.createdAt, now);
+        if (prMeta.isDraft && draftFor > rule.draft_minutes_over) {
+          add(rule, rule.draft_severity ?? rule.severity, t.draft(duration(draftFor, lang)));
+          problems.push(`draft for ${draftFor} min`);
+        }
+        if (problems.length) record(rule, "violated", problems.join(", "));
+        else if (reviewerUnknown) record(rule, "not-measured", "reviewer count unknown");
+        else
+          record(
+            rule,
+            "pass",
+            prMeta.reviewerCount === null
+              ? "already reviewed"
+              : `${prMeta.reviewerCount} reviewer(s)`,
+          );
+        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");
+  const scores = Object.fromEntries(
+    results.filter((r) => r.score !== undefined).map((r) => [r.ruleId, r.score]),
+  );
+  return { results, findings, splitRequired, failing, scores };
+}
+
+// ---------------------------------------------------------------------------
+// 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);
+  history.oldestCommitAt = oldest === null ? null : new Date(oldest);
+  const prBody = args["pr-body-file"] ? readFileSync(args["pr-body-file"], "utf-8") : null;
+  let prMeta = null;
+  if (args["pr-meta-file"]) {
+    let problem = null;
+    try {
+      prMeta = normalizePrMeta(JSON.parse(readFileSync(args["pr-meta-file"], "utf-8")));
+      if (!prMeta) problem = "no valid createdAt";
+    } catch (err) {
+      problem = err.message;
+    }
+    if (problem) {
+      process.stderr.write(
+        `valven-gate: --pr-meta-file ${args["pr-meta-file"]}: ${problem}; the timeline rules report not-measured\n`,
+      );
+    }
+  }
+
+  const metrics = measure(files, patterns);
+  const verdict = evaluate({
+    mode: args.mode,
+    rules,
+    metrics,
+    branch,
+    commits,
+    prBody,
+    rework,
+    history,
+    prMeta,
+    now,
+    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,
+    },
+    prMeta,
+    scores: verdict.scores,
+    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 });