forgedock 1.36.0 → 1.37.0

package/bin/lean/guardgate.mjs

@@ -0,0 +1,170 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Guard gate (#4693): execution-based, no pattern matching on diff text. A lane whose diff changes lines a merged fix
+ * protected (git blame on the lane's merge base names the guard's merge commit, or a later commit that kept the lines), or
+ * edits/deletes a guard's test file, reruns that guard's test files *as they exist on base* against the lane's tree. A
+ * failure is `conformance.guard_broken` (builder resumed once). The only override is a `supersedes` amendment (conformance.mjs).
+ * Deterministic, 0 LLM calls; a lane touching nothing guarded does one local index read and no git work.
+ */
+import * as nodeFs from "node:fs";
+import { dirname, extname, join } from "node:path";
+import { OUTCOME_CODES } from "../engine/outcome-codes.mjs";
+import { collectGuards, guardsIndexPath, readIndex, writeIndex } from "./guards.mjs";
+import { isTestPath } from "./enumerating.mjs";
+
+export const GUARD_CAP_MS = 120000;
+export const INDEX_MAX_AGE_MS = 6 * 3600000;
+const TIMEOUT_RC = 124;
+const SLACK = 10; // lines a guarded hunk may have drifted since its merge when only a later commit kept it
+const SHA_RE = /^[0-9a-f]{40}$/;
+const ok = async (fn) => { try { await fn(); return true; } catch { return false; } };
+const norm = (p) => String(p ?? "").replace(/^\.\//, "");
+
+/** Guards from the local index; rebuilt from the GitHub register when absent or older than INDEX_MAX_AGE_MS (a stale index is still used when GitHub is unreachable). */
+export async function loadGuards({ repo, gh, root, fs = nodeFs, now = Date.now() }) {
+  const cached = readIndex(repo, { root, fs });
+  let age = Infinity;
+  try { age = now - fs.statSync(guardsIndexPath(repo, root)).mtimeMs; } catch { /* no index yet */ }
+  if (cached && age < INDEX_MAX_AGE_MS) return cached;
+  try { const g = await collectGuards({ gh, repo }); writeIndex(repo, g, { root, fs }); return g; } catch { return cached ?? []; }
+}
+
+/** Old-side line ranges of a `git diff -U0` text for non-test files: {file: [[start, end]]}. Pure insertions touch no old line. */
+export function oldRanges(diff) {
+  const out = {};
+  let file = null;
+  for (const line of String(diff ?? "").split("\n")) {
+    if (line.startsWith("--- ")) { file = line === "--- /dev/null" ? null : line.replace(/^--- a\//, ""); continue; }
+    if (line.startsWith("+++ ")) { if (line === "+++ /dev/null") continue; continue; }
+    const m = /^@@ -(\d+)(?:,(\d+))? \+/.exec(line);
+    if (!m || !file || isTestPath(file)) continue;
+    const start = Number(m[1]), len = m[2] === undefined ? 1 : Number(m[2]);
+    if (len > 0) (out[file] ??= []).push([start, start + len - 1]);
+  }
+  return out;
+}
+
+/** Commit shas that last touched lines a..b of `file` at `rev` (git blame --porcelain). */
+export function blameShas(text) {
+  const shas = new Set();
+  for (const l of String(text ?? "").split("\n")) { const s = l.split(" ")[0]; if (SHA_RE.test(s)) shas.add(s); }
+  return shas;
+}
+
+/**
+ * The guards a lane's diff intersects, each with why it was selected: {guard, reason}. `files` are the lane's changed paths.
+ * Guards whose hunk files and test files the lane does not touch are never looked at (no git calls).
+ */
+export async function selectGuards({ guards, files, git, base }) {
+  const changed = new Set((files ?? []).map(norm));
+  const cands = (guards ?? []).filter((g) => (g.hunks ?? []).some((h) => changed.has(norm(h.file))) || (g.tests ?? []).some((t) => changed.has(norm(t.path))));
+  if (!cands.length) return { selected: [], mergeBase: null };
+  const mergeBase = String(await git(["merge-base", base, "HEAD"])).trim();
+  const hunkFiles = [...new Set(cands.flatMap((g) => (g.hunks ?? []).map((h) => norm(h.file))).filter((f) => changed.has(f)))];
+  const ranges = hunkFiles.length ? oldRanges(String(await git(["diff", "-U0", "--no-renames", `${base}...HEAD`, "--", ...hunkFiles]))) : {};
+  const blamed = new Map(); // `${file}:${a}-${b}` -> Set(sha)
+  const shasOf = async (file, [a, b]) => {
+    const k = `${file}:${a}-${b}`;
+    if (!blamed.has(k)) blamed.set(k, blameShas(await git(["blame", "--porcelain", "-L", `${a},${b}`, mergeBase, "--", file]).catch(() => "")));
+    return blamed.get(k);
+  };
+  const selected = [];
+  for (const g of cands) {
+    const sha = String(g.merge_sha ?? "");
+    const known = SHA_RE.test(sha) || sha.length >= 7 ? await ok(() => git(["cat-file", "-e", `${sha}^{commit}`])) : false;
+    let reason = null;
+    for (const h of g.hunks ?? []) {
+      const f = norm(h.file);
+      for (const r of ranges[f] ?? []) {
+        const near = r[0] <= h.end + SLACK && r[1] >= h.start - SLACK;
+        if (!known) { if (near) reason = `lines ${r[0]}-${r[1]} of ${f} overlap the protected hunk (merge commit not local)`; }
+        else if (near) {
+          for (const s of await shasOf(f, r)) {
+            if (s === sha || (s.startsWith(sha) && sha.length >= 7) || sha.startsWith(s) || await ok(() => git(["merge-base", "--is-ancestor", sha, s]))) { reason = `lines ${r[0]}-${r[1]} of ${f} last changed by ${s.slice(0, 10)}, which carries the fix`; break; }
+          }
+        }
+        if (reason) break;
+      }
+      if (reason) break;
+    }
+    if (!reason) { const t = (g.tests ?? []).find((x) => changed.has(norm(x.path))); if (t) reason = `the lane edits or deletes its test ${t.path}`; }
+    if (reason) selected.push({ guard: g, reason });
+  }
+  return { selected, mergeBase };
+}
+
+/** The command that runs one test file: the contract's own validate command with that path substituted, else a per-extension default; null when unknown. */
+export function commandFor(path, contract) {
+  const ext = extname(path);
+  for (const v of contract?.validate ?? []) {
+    const cmd = String(v?.command ?? "");
+    if (/(?:^|\s)(?:-k|-t|--grep|--test-name-pattern|--testNamePattern)(?:\s|=)|::/.test(cmd)) continue;
+    const toks = cmd.match(/[^\s"']+/g) ?? [];
+    const tests = toks.filter((t) => extname(t) === ext && isTestPath(t));
+    if (tests.length === 1 && /\b(?:node|pytest|python3?|vitest|jest|npx|pnpm|npm|yarn|bun)\b/.test(cmd)) return cmd.replace(tests[0], path);
+  }
+  if ([".mjs", ".cjs", ".js"].includes(ext)) return `node --test ${path}`;
+  if (ext === ".py") return `python -m pytest -q ${path}`;
+  return null;
+}
+
+/** Sibling path for the base copy of a test file, so its relative imports resolve against the lane's tree. */
+export const basePathOf = (path) => { const e = extname(path); return `${path.slice(0, path.length - e.length)}__guardbase${e}`; };
+
+const tailOf = (out) => String(out ?? "").split("\n").filter((l) => l.trim()).slice(-40).join("\n").slice(-1500);
+
+/**
+ * Rerun the selected guards' base test files against the lane tree, in a small pool, under one wall-time cap.
+ * Returns {failures, runs, skipped[], ms}. A test that cannot be run (no base copy, unknown runner, over the cap) is skipped, never a failure.
+ */
+export async function runGuards({ selected, mergeBase, contract, git, runCommand, cwd, env, capMs = GUARD_CAP_MS, parallelism = 2, fs = nodeFs, now = Date.now }) {
+  const t0 = now(), skipped = [], runs = [], jobs = [];
+  for (const { guard } of selected) {
+    for (const t of guard.tests ?? []) {
+      const path = norm(t.path), copy = basePathOf(path), command = commandFor(copy, contract);
+      if (!command) { skipped.push(`#${guard.issue} ${path}: no runner known for ${extname(path) || "this file"}`); continue; }
+      jobs.push({ guard, path, copy, command });
+    }
+  }
+  const made = [];
+  try {
+    const queue = jobs.slice();
+    const work = async () => {
+      for (let j = queue.shift(); j; j = queue.shift()) {
+        const left = capMs - (now() - t0);
+        if (left <= 0) { skipped.push(`#${j.guard.issue} ${j.path}: over the ${Math.round(capMs / 1000)}s guard cap`); continue; }
+        let body;
+        try { body = await git(["show", `${mergeBase}:${j.path}`]); } catch { skipped.push(`#${j.guard.issue} ${j.path}: not on base`); continue; }
+        const abs = join(cwd, j.copy);
+        try { fs.mkdirSync(dirname(abs), { recursive: true }); fs.writeFileSync(abs, body); made.push(abs); } catch (e) { skipped.push(`#${j.guard.issue} ${j.path}: ${String(e?.message ?? e).slice(0, 80)}`); continue; }
+        let r;
+        try { r = await runCommand({ command: j.command, cwd, timeoutMs: left, env }); } catch (e) { r = { rc: 127, output: String(e?.message ?? e) }; }
+        if (r?.rc === TIMEOUT_RC) { skipped.push(`#${j.guard.issue} ${j.path}: over the ${Math.round(capMs / 1000)}s guard cap`); continue; }
+        if (r?.rc === 127) { skipped.push(`#${j.guard.issue} ${j.path}: runner unavailable`); continue; }
+        runs.push({ issue: j.guard.issue, why: j.guard.why, test: j.path, command: j.command, rc: Number.isInteger(r?.rc) ? r.rc : 1, output: String(r?.output ?? "") });
+      }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(parallelism, jobs.length)) }, work));
+  } finally {
+    for (const p of made) { try { fs.rmSync(p, { force: true }); } catch { /* best effort */ } }
+  }
+  return { failures: guardFailures(runs), runs, skipped, ms: now() - t0 };
+}
+
+/** conformance.guard_broken rows (one per failing guard test): the guard's issue, its one-line why, the failing test and its output tail. */
+export function guardFailures(runs) {
+  return (runs ?? []).filter((r) => r.rc !== 0).map((r) => ({
+    code: OUTCOME_CODES.CONFORMANCE_GUARD_BROKEN, kind: "guard_broken", guard: `#${r.issue}`, test: r.test,
+    detail: `guard #${r.issue} broken (${String(r.why ?? "").slice(0, 200)}): base test ${r.test} fails against your tree (\`${r.command}\`, exit ${r.rc}):\n${tailOf(r.output)}`,
+  }));
+}
+
+/** The comment the engine posts on a guarded issue once its guard is superseded. */
+export const supersessionComment = ({ guard, pr, why }) => `The fix guard from ${guard} was superseded by PR #${pr}: ${String(why ?? "").trim()}\n\nThe lane's contract carried a \`supersedes\` amendment the reviewer accepted; this guard's test no longer describes current behaviour.`;
+
+/** Guard ids the effective contract's accepted supersedes amendments retire, limited to guards the gate selected. */
+export function supersededIds(contract, selected) {
+  const sel = new Set((selected ?? []).map((s) => `#${s.guard.issue}`));
+  return (contract?.supersedes ?? []).filter((s) => sel.has(s.guard));
+}

package/bin/lean/guardgate.test.mjs

@@ -0,0 +1,153 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import test from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { oldRanges, selectGuards, runGuards, commandFor, basePathOf, guardFailures, supersessionComment, supersededIds, loadGuards } from "./guardgate.mjs";
+import { applyAmendments, precheck } from "./conformance.mjs";
+import { tmpDir } from "../tests/_tmp.mjs";
+
+const sh = (cwd, ...a) => execFileSync("git", a, { cwd, encoding: "utf8", env: { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" } });
+const gitIn = (cwd) => async (args) => sh(cwd, ...args);
+const { NODE_TEST_CONTEXT: _ctx, ...CLEAN_ENV } = process.env; // the fixture runs node --test inside a test
+const runCommand = async ({ command, cwd }) => { const r = spawnSync("sh", ["-c", command], { cwd, encoding: "utf8", env: CLEAN_ENV }); return { rc: r.status ?? 1, output: `${r.stdout}${r.stderr}` }; };
+const put = (cwd, p, body) => { mkdirSync(join(cwd, p, ".."), { recursive: true }); writeFileSync(join(cwd, p), body); };
+
+const TEST_SRC = (v) => `import test from "node:test";\nimport assert from "node:assert/strict";\nimport { price } from "./a.mjs";\ntest("price is ${v}", () => assert.equal(price(), ${v}));\n`;
+
+/** A repo whose fix commit (merge_sha) made price() return 2, guarded by src/a.test.mjs; the lane starts from it. */
+function fixture() {
+  const d = tmpDir("guardgate-");
+  sh(d, "init", "-q", "-b", "main");
+  put(d, "src/a.mjs", "export function price() {\n  return 1;\n}\n");
+  sh(d, "add", "-A"); sh(d, "commit", "-qm", "init");
+  put(d, "src/a.mjs", "export function price() {\n  return 2;\n}\n");
+  put(d, "src/a.test.mjs", TEST_SRC(2));
+  sh(d, "add", "-A"); sh(d, "commit", "-qm", "fix: price");
+  const sha = sh(d, "rev-parse", "HEAD").trim();
+  put(d, "src/other.mjs", "export const x = 1;\n");
+  sh(d, "add", "-A"); sh(d, "commit", "-qm", "later");
+  sh(d, "update-ref", "refs/remotes/origin/main", "HEAD");
+  sh(d, "checkout", "-qb", "lane");
+  const guard = { v: 1, issue: 7, pr: 9, merge_sha: sha, tests: [{ path: "src/a.test.mjs", ids: [] }], hunks: [{ file: "src/a.mjs", start: 2, end: 2, symbol: "price" }], why: "price must be 2" };
+  return { d, guard };
+}
+const commit = (d, m) => { sh(d, "add", "-A"); sh(d, "commit", "-qm", m); };
+const files = (d) => sh(d, "diff", "--name-only", "origin/main...HEAD").split("\n").filter(Boolean);
+const gate = async (d, guard, contract = {}) => {
+  const git = gitIn(d);
+  const { selected, mergeBase } = await selectGuards({ guards: [guard], files: files(d), git, base: "origin/main" });
+  const r = selected.length ? await runGuards({ selected, mergeBase, contract, git, runCommand, cwd: d, env: process.env }) : null;
+  return { selected, r };
+};
+
+test("a lane that reverts a guarded fix fails guard_broken even when it also edits the guard's test to pass", async () => {
+  const { d, guard } = fixture();
+  put(d, "src/a.mjs", "export function price() {\n  return 1;\n}\n"); // reverts the fix
+  put(d, "src/a.test.mjs", TEST_SRC(1)); // and weakens the test so the lane's own copy passes
+  commit(d, "revert");
+  assert.equal((await runCommand({ command: "node --test src/a.test.mjs", cwd: d })).rc, 0, "the lane's own edited test passes");
+  const { selected, r } = await gate(d, guard);
+  assert.equal(selected.length, 1);
+  assert.match(selected[0].reason, /src\/a\.mjs/);
+  assert.equal(r.failures.length, 1, JSON.stringify({ runs: r.runs, skipped: r.skipped }));
+  assert.equal(r.failures[0].code, "conformance.guard_broken");
+  assert.equal(r.failures[0].guard, "#7");
+  assert.match(r.failures[0].detail, /price must be 2/);
+  assert.match(r.failures[0].detail, /src\/a\.test\.mjs/);
+  assert.deepEqual(readdirSync(join(d, "src")).filter((f) => f.includes("__guardbase")), [], "base copies are removed");
+  const pc = precheck({ contract: { requirements: [], deliverables: [{ id: "D1", path: "src/a.mjs" }, { id: "D2", path: "src/a.test.mjs" }], validate: [] }, result: {}, changedFiles: files(d), guardFailures: r.failures });
+  assert.deepEqual(pc.failures.filter((f) => f.kind === "guard_broken").map((f) => f.guard), ["#7"]);
+  assert.equal(pc.ok, false);
+});
+
+test("an accepted supersedes amendment passes the precheck and names the superseded guard for the issue comment", async () => {
+  const { d, guard } = fixture();
+  put(d, "src/a.mjs", "export function price() {\n  return 3;\n}\n");
+  commit(d, "change");
+  const { selected, r } = await gate(d, guard);
+  assert.equal(r.failures.length, 1);
+  const frozen = { requirements: [], deliverables: [{ id: "D1", path: "src/a.mjs" }], validate: [] };
+  const a = applyAmendments(frozen, [{ kind: "supersedes", guard: "#7", why: "price is now 3 by product decision" }]);
+  assert.deepEqual(a.problems, []);
+  assert.deepEqual(a.applied, [{ kind: "supersedes", target: "#7", why: "price is now 3 by product decision" }]);
+  const pc = precheck({ contract: a.contract, result: {}, changedFiles: ["src/a.mjs"], guardFailures: r.failures });
+  assert.equal(pc.ok, true, JSON.stringify(pc.failures));
+  const sup = supersededIds(a.contract, selected);
+  assert.deepEqual(sup.map((s) => s.guard), ["#7"]);
+  assert.match(supersessionComment({ guard: "#7", pr: 12, why: sup[0].why }), /#7 was superseded by PR #12: price is now 3/);
+  assert.deepEqual(supersededIds(a.contract, []), [], "only selected guards are retired");
+});
+
+test("a supersedes amendment without a guard id is rejected", () => {
+  const a = applyAmendments({ requirements: [], deliverables: [] }, [{ kind: "supersedes", why: "x" }, { kind: "supersedes", guard: "abc", why: "x" }]);
+  assert.equal(a.problems.length, 2);
+  assert.match(a.problems[0], /needs guard/);
+});
+
+test("a lane touching no guarded hunk selects nothing and runs no git or test", async () => {
+  const { d, guard } = fixture();
+  put(d, "src/other.mjs", "export const x = 2;\n");
+  commit(d, "unrelated");
+  const calls = [];
+  const git = async (a) => { calls.push(a[0]); return gitIn(d)(a); };
+  const r = await selectGuards({ guards: [guard], files: files(d), git, base: "origin/main" });
+  assert.deepEqual(r.selected, []);
+  assert.deepEqual(calls, [], "no git call at all");
+  // same file as the guard but lines far from the hunk, with the guard's commit not the blamed one
+  const big = { ...guard, hunks: [{ file: "src/a.mjs", start: 200, end: 210 }] };
+  assert.deepEqual((await selectGuards({ guards: [big], files: files(d).concat("src/a.mjs"), git: gitIn(d), base: "origin/main" })).selected, []);
+});
+
+test("deleting or editing a guard's test selects it even when no guarded line changed", async () => {
+  const { d, guard } = fixture();
+  sh(d, "rm", "-q", "src/a.test.mjs");
+  commit(d, "drop test");
+  const { selected, r } = await gate(d, guard);
+  assert.equal(selected.length, 1);
+  assert.match(selected[0].reason, /edits or deletes its test/);
+  assert.deepEqual(r.failures, [], "the base test still passes against the unchanged code");
+  assert.equal(r.runs.length, 1);
+});
+
+test("a base test that cannot run in the cap, or has no known runner, is skipped and never blocks", async () => {
+  const { d, guard } = fixture();
+  put(d, "src/a.mjs", "export function price() {\n  return 1;\n}\n");
+  commit(d, "revert");
+  const git = gitIn(d);
+  const { selected, mergeBase } = await selectGuards({ guards: [guard], files: files(d), git, base: "origin/main" });
+  const slow = await runGuards({ selected, mergeBase, contract: {}, git, runCommand: async () => ({ rc: 124, output: "" }), cwd: d, env: {} });
+  assert.deepEqual(slow.failures, []);
+  assert.match(slow.skipped[0], /guard cap/);
+  const none = await runGuards({ selected: [{ guard: { ...guard, tests: [{ path: "src/a.test.rb" }] }, reason: "" }], mergeBase, contract: {}, git, runCommand, cwd: d, env: {} });
+  assert.match(none.skipped[0], /no runner/);
+  assert.equal(existsSync(join(d, basePathOf("src/a.test.mjs"))), false);
+});
+
+test("pytest-style guards run through the contract's own validate command with the path substituted", () => {
+  assert.equal(commandFor("tests/test_a__guardbase.py", { validate: [{ command: "pytest -q tests/test_a.py" }] }), "pytest -q tests/test_a__guardbase.py");
+  assert.equal(commandFor("tests/test_a__guardbase.py", {}), "python -m pytest -q tests/test_a__guardbase.py");
+  assert.equal(commandFor("src/a.test__guardbase.mjs", { validate: [{ command: "node --test src/a.test.mjs -t x" }] }), "node --test src/a.test__guardbase.mjs");
+  assert.equal(commandFor("a.rb", {}), null);
+  assert.equal(basePathOf("src/a.test.mjs"), "src/a.test__guardbase.mjs");
+});
+
+test("oldRanges reads old-side lines of non-test files and skips pure insertions", () => {
+  const diff = "--- a/src/a.mjs\n+++ b/src/a.mjs\n@@ -3,2 +3 @@\n-a\n-b\n+c\n@@ -9,0 +9,2 @@\n+x\n+y\n@@ -20 +19,0 @@\n-z\n--- a/src/a.test.mjs\n+++ b/src/a.test.mjs\n@@ -1 +1 @@\n";
+  assert.deepEqual(oldRanges(diff), { "src/a.mjs": [[3, 4], [20, 20]] });
+});
+
+test("guardFailures keeps only failing runs and loadGuards falls back to a stale index when GitHub is down", async () => {
+  assert.deepEqual(guardFailures([{ issue: 1, rc: 0 }]), []);
+  const root = tmpDir("guardgate-idx-");
+  const fs = await import("node:fs");
+  const { writeIndex } = await import("./guards.mjs");
+  writeIndex("o/r", [{ issue: 3 }], { root });
+  const old = new Date(Date.now() - 48 * 3600000);
+  fs.utimesSync(join(root, "o_r.json"), old, old);
+  const down = await loadGuards({ repo: "o/r", gh: async () => { throw new Error("offline"); }, root });
+  assert.deepEqual(down, [{ issue: 3 }]);
+  assert.deepEqual(await loadGuards({ repo: "o/none", gh: async () => "[]", root }), []);
+});

package/bin/lean/guards.mjs

@@ -0,0 +1,243 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Fix guards (#4692): a merged lane whose frozen contract names a regression/repro test records a guard on its issue as
+ * `<!-- FORGE:GUARD {json} -->`: {v, issue, pr, merge_sha, tests:[{path, ids}], hunks:[{file, start, end, symbol}], why}.
+ * GitHub is the register; `~/.forge/guards/<repo>.json` is a cache rebuilt from those comments. Codebase-agnostic and
+ * deterministic (0 LLM calls): test identity comes from the contract's repro_test and validate commands, never from a
+ * language parser; without per-test ids a guard is file-granular (ids: []). Protected hunks come from the merged diff
+ * against the merge commit's first parent, which is the base for both merge-commit and squash merges.
+ */
+import * as nodeFs from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { isTestPath } from "./enumerating.mjs";
+import { parseContractComment } from "./render.mjs";
+
+export const GUARD_MARKER = "FORGE:GUARD";
+const GUARD_RE = /<!-- FORGE:GUARD (\{[\s\S]*?\}) -->/;
+const PATHISH = /^[\w@.+/-]+\.[A-Za-z0-9]+$/;
+const hasMarker = (b) => GUARD_RE.test(String(b ?? ""));
+
+export const guardsIndexPath = (repo, root = join(homedir(), ".forge", "guards")) => join(root, `${String(repo).replace(/[^A-Za-z0-9._-]/g, "_")}.json`);
+
+/** Test ids a validate/repro command names: `-k expr`, `--test-name-pattern x`, `-t x`, `--grep x`, and `file::name` pytest ids. */
+function idsOf(command, path) {
+  const toks = String(command ?? "").match(/(?:[^\s"']|"[^"]*"|'[^']*')+/g) ?? [];
+  const unq = (t) => t.replace(/^(["'])(.*)\1$/, "$2");
+  const ids = [];
+  toks.forEach((t, i) => {
+    const v = unq(t);
+    if (/^(?:-k|-t|--grep|--test-name-pattern|--testNamePattern)$/.test(v) && toks[i + 1]) ids.push(unq(toks[i + 1]));
+    else if (/^--(?:k|grep|test-name-pattern|testNamePattern)=/.test(v)) ids.push(unq(v.split("=").slice(1).join("=")));
+    else if (v.startsWith(`${path}::`)) ids.push(v.slice(path.length + 2));
+  });
+  return ids;
+}
+
+/** Test files (and ids) from the contract's repro_test and validate commands. [] when the contract names no test. */
+export function guardTests(contract) {
+  const by = new Map();
+  const add = (path, ids) => { const e = by.get(path) ?? new Set(); ids.filter(Boolean).forEach((i) => e.add(i)); by.set(path, e); };
+  const t = contract?.repro_test;
+  const cmds = [];
+  if (t && typeof t === "object") {
+    if (t.path) add(String(t.path), t.id ? [String(t.id)] : []);
+    cmds.push(t.command);
+  }
+  for (const v of contract?.validate ?? []) cmds.push(v?.command);
+  for (const c of cmds) {
+    for (const tok of String(c ?? "").match(/[^\s"']+/g) ?? []) {
+      const p = tok.split("::")[0];
+      if (PATHISH.test(p) && isTestPath(p)) add(p, idsOf(c, p));
+    }
+  }
+  if (t && typeof t === "object" && t.path) add(String(t.path), []);
+  return [...by].map(([path, ids]) => ({ path, ids: [...ids] }));
+}
+
+/** Hunks of a `git diff -U0` text for non-test files: [{file, start, end, symbol}] in post-image lines (deletions anchor at the line after). */
+export function parseHunks(diff) {
+  const out = [];
+  let file = null;
+  for (const line of String(diff ?? "").split("\n")) {
+    if (line.startsWith("+++ ")) { file = line === "+++ /dev/null" ? null : line.replace(/^\+\+\+ b\//, ""); continue; }
+    if (line.startsWith("--- ")) { if (line === "--- /dev/null") file = null; continue; }
+    const m = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@ ?(.*)$/.exec(line);
+    if (!m || !file || isTestPath(file)) continue;
+    const delOnly = m[4] === "0", start = Number(m[3]) + (delOnly ? 1 : 0), len = m[4] === undefined ? 1 : Number(m[4]);
+    out.push({ file, start, end: delOnly ? start : start + len - 1, symbol: m[5].trim().slice(0, 120) || null });
+  }
+  return out;
+}
+
+/** The guard for a merged lane, or {skipped, reason} when its contract names no regression/repro test. */
+export function buildGuard({ issue, title = "", pr = null, mergeSha = null, contract, diff = "" }) {
+  const tests = guardTests(contract);
+  if (!tests.length) {
+    const why = contract?.repro_test === "none" ? `repro_test none (${String(contract.repro_test_reason ?? "").slice(0, 120)})` : "contract names no test file";
+    return { skipped: true, reason: `no guard for #${issue}: ${why}` };
+  }
+  return { guard: { v: 1, issue, pr, merge_sha: mergeSha, tests, hunks: parseHunks(diff), why: String(title).replace(/\s+/g, " ").trim().slice(0, 200) } };
+}
+
+export const renderGuard = (g) => `<!-- ${GUARD_MARKER} ${JSON.stringify(g).replace(/</g, "\\u003c").replace(/>/g, "\\u003e")} -->`;
+export function parseGuard(body) {
+  const m = GUARD_RE.exec(String(body ?? ""));
+  if (!m) return null;
+  try { const g = JSON.parse(m[1]); return g && g.v === 1 && Number.isInteger(g.issue) ? g : null; } catch { return null; }
+}
+
+const json = (s, d) => { try { return JSON.parse(String(s) || "null") ?? d; } catch { return d; } };
+
+/**
+ * Build the guard for one merged issue from GitHub alone (its FORGE:CONTRACT comment, merged PR and merge commit) and post it
+ * once. Idempotent: an issue that already has a FORGE:GUARD comment is left alone. Returns {posted|exists|skipped, ...}.
+ */
+export async function guardIssue({ gh, git, repo, issue, pr = null, post = null, dryRun = false }) {
+  const iss = json(await gh(["issue", "view", String(issue), "-R", repo, "--json", "number,title,comments"]), null);
+  if (!iss) return { skipped: true, reason: `#${issue}: issue not readable` };
+  const bodies = (iss.comments ?? []).map((c) => c?.body ?? "");
+  const existing = bodies.map(parseGuard).find(Boolean);
+  if (existing) return { exists: true, guard: existing };
+  const cb = [...bodies].reverse().find((b) => b.startsWith("<!-- FORGE:CONTRACT -->") && parseContractComment(b));
+  if (!cb) return { skipped: true, reason: `no guard for #${issue}: no frozen FORGE:CONTRACT comment` };
+  const contract = parseContractComment(cb).contract;
+  let prn = pr, sha = null;
+  const view = prn
+    ? json(await gh(["pr", "view", String(prn), "-R", repo, "--json", "number,state,mergeCommit"]), null)
+    : json(await gh(["pr", "list", "-R", repo, "--state", "merged", "--search", `#${issue} in:body`, "--limit", "5", "--json", "number,mergeCommit,body"]), []).find((p) => new RegExp(`(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\\s+#${issue}\\b`, "i").test(p.body ?? "")) ?? null;
+  if (view) { prn = view.number ?? prn; sha = view.mergeCommit?.oid ?? null; }
+  if (!sha) return { skipped: true, reason: `no guard for #${issue}: no merged PR with a merge commit` };
+  let diff = "";
+  const getDiff = async () => String(await git(["diff", "-U0", "--no-color", "--no-renames", `${sha}^1`, sha]));
+  try {
+    try { diff = await getDiff(); } catch { await git(["fetch", "origin", sha]); diff = await getDiff(); } // merge commit not local yet: fetch it by sha
+  } catch (e) {
+    return { skipped: true, reason: `no guard for #${issue}: merge commit ${sha.slice(0, 10)} not available locally (${String(e?.message ?? e).split("\n")[0].slice(0, 100)})` };
+  }
+  const built = buildGuard({ issue, title: iss.title, pr: prn, mergeSha: sha, contract, diff });
+  if (built.skipped) return built;
+  if (!dryRun) await (post ?? ((b) => gh(["issue", "comment", String(issue), "-R", repo, "--body", b])))(renderGuard(built.guard));
+  return { posted: true, guard: built.guard };
+}
+
+/** Guards read from a repo's issue comments (the register of record). */
+export async function collectGuards({ gh, repo, limit = 500 }) {
+  const rows = json(await gh(["issue", "list", "-R", repo, "--state", "all", "--search", `${GUARD_MARKER} in:comments`, "--limit", String(limit), "--json", "number,comments"]), []);
+  const guards = [];
+  for (const r of rows) for (const c of r.comments ?? []) { const g = hasMarker(c?.body) ? parseGuard(c.body) : null; if (g) { guards.push(g); break; } }
+  return guards;
+}
+
+/** Rewrite the local cache from the guards found on GitHub. */
+export function writeIndex(repo, guards, { root, fs = nodeFs } = {}) {
+  const p = guardsIndexPath(repo, root);
+  fs.mkdirSync(dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify({ v: 1, repo, guards }, null, 1));
+  return p;
+}
+export function readIndex(repo, { root, fs = nodeFs } = {}) {
+  try { const j = JSON.parse(fs.readFileSync(guardsIndexPath(repo, root), "utf8")); return Array.isArray(j?.guards) ? j.guards : null; } catch { return null; }
+}
+
+/** Guards covering `path` (a protected hunk file or a guarding test file; a directory prefix matches too). No path: all. */
+export function listGuards(guards, { path = null } = {}) {
+  if (!path) return guards;
+  const p = String(path).replace(/^\.\//, "").replace(/\/$/, "");
+  const hit = (f) => f === p || f.startsWith(`${p}/`);
+  return guards.filter((g) => (g.hunks ?? []).some((h) => hit(h.file)) || (g.tests ?? []).some((t) => hit(t.path)));
+}
+
+const H_ROW = /^H\d+$/;
+const dirOf = (f) => String(f).split("/").slice(0, -1).join("/");
+
+/**
+ * History preserve rows (#4694): at most `cap` `{id:"H<n>", what, source:"guard"}` rows for the guards covering the deliverable
+ * paths. Pure and deterministic: score 3 = a protected hunk file is a deliverable, 2 = a guarding test file is, 1 = either sits
+ * under a deliverable's directory; ties go to the newest issue. The lane's own issue is skipped.
+ */
+export function historyPreserve({ guards, deliverables, issue = null, cap = 5 }) {
+  const paths = [...new Set((deliverables ?? []).map((d) => String(d?.path ?? d ?? "").replace(/^\.\//, "")).filter(Boolean))];
+  if (!paths.length || !Array.isArray(guards) || !guards.length) return [];
+  const dirs = paths.map(dirOf).filter(Boolean);
+  const under = (f) => dirs.some((d) => f.startsWith(`${d}/`));
+  const scored = [];
+  for (const g of guards) {
+    if (!g || g.issue == null || String(g.issue) === String(issue)) continue;
+    const hunks = (g.hunks ?? []).map((h) => String(h.file)), tests = (g.tests ?? []).map((t) => String(t.path));
+    const score = hunks.some((f) => paths.includes(f)) ? 3 : tests.some((f) => paths.includes(f)) ? 2 : [...hunks, ...tests].some(under) ? 1 : 0;
+    if (score) scored.push({ g, score });
+  }
+  scored.sort((a, b) => b.score - a.score || Number(b.g.issue) - Number(a.g.issue) || (Number(a.g.pr) || 0) - (Number(b.g.pr) || 0));
+  const seen = new Set();
+  return scored.filter(({ g }) => !seen.has(String(g.issue)) && seen.add(String(g.issue))).slice(0, cap).map(({ g }, i) => ({
+    id: `H${i + 1}`,
+    what: `${String(g.why ?? "").replace(/\s+/g, " ").trim().slice(0, 160) || "guarded fix"} (#${g.issue}${g.pr ? `, PR #${g.pr}` : ""})`,
+    source: "guard",
+  }));
+}
+
+/** The contract with H-rows from the local guards index appended to preserve; the same object when nothing applies. Never throws. */
+export function withHistoryRows(contract, { repo, issue, root, fs = nodeFs } = {}) {
+  try {
+    const guards = readIndex(repo, { root, fs });
+    if (!guards?.length) return contract;
+    const rows = historyPreserve({ guards, deliverables: contract?.deliverables, issue });
+    if (!rows.length) return contract;
+    return { ...contract, preserve: [...(contract.preserve ?? []).filter((p) => !(H_ROW.test(p?.id) && p?.source === "guard")), ...rows] };
+  } catch { return contract; }
+}
+
+/**
+ * Backfill guards for issues closed since `since` (ISO date) that ran through the lean lane (a FORGE:CONTRACT comment and a
+ * merged PR). Lanes without a test yield no guard; the reason is reported in `logs`. Idempotent.
+ */
+export async function backfill({ gh, git, repo, since, dryRun = false, log = () => {} }) {
+  const rows = json(await gh(["issue", "list", "-R", repo, "--state", "closed", "--search", `closed:>=${since}`, "--limit", "500", "--json", "number"]), []);
+  const res = { posted: [], exists: [], skipped: [] };
+  for (const { number } of rows) {
+    let r;
+    try { r = await guardIssue({ gh, git, repo, issue: number, dryRun }); } catch (e) { r = { skipped: true, reason: `#${number}: ${String(e?.message ?? e).split("\n")[0].slice(0, 160)}` }; }
+    if (r.posted) res.posted.push(number); else if (r.exists) res.exists.push(number);
+    else { res.skipped.push({ issue: number, reason: r.reason }); log(r.reason); }
+  }
+  return res;
+}
+
+/** Lane hook: after a merge, fetch the base so the merge commit is local, then guard the issue. Best effort: never throws. */
+export async function guardAfterMerge({ io, repo, issue, pr, cwd, base = null, root }) {
+  try {
+    const branch = base ? String(base).replace(/^(?:refs\/remotes\/)?origin\//, "") : null; // lean.mjs passes `origin/<lane>`
+    if (branch) { try { await io.git(["fetch", "origin", branch], { cwd }); } catch { /* offline: use the local ref */ } }
+    const r = await guardIssue({ gh: (a) => io.gh(a), git: (a) => io.git(a, { cwd }), repo, issue, pr });
+    if (r.posted) { // #4694: keep the local cache current so the next lane's freeze sees this guard; only extend an existing index
+      try { const cur = readIndex(repo, { root }); if (cur) writeIndex(repo, [...cur.filter((g) => g.issue !== r.guard.issue), r.guard], { root }); } catch { /* cache only */ }
+    }
+    return r;
+  } catch (e) { return { skipped: true, reason: `guard failed: ${String(e?.message ?? e).split("\n")[0].slice(0, 160)}` }; }
+}
+
+/** `forgedock guards list [--path p] [--json] | backfill --since <date> [--dry-run]`. Returns the exit code. */
+export async function guardsCli(argv, { gh, git, repo, print = console.log, root, fs = nodeFs } = {}) {
+  const sub = argv[0];
+  const flag = (n) => { const i = argv.indexOf(n); return i >= 0 ? argv[i + 1] : null; };
+  if (sub === "list") {
+    let guards = null;
+    try { guards = await collectGuards({ gh, repo }); writeIndex(repo, guards, { root, fs }); } catch { guards = readIndex(repo, { root, fs }); }
+    if (!guards) throw new Error("guards list: GitHub is unreachable and there is no local index");
+    const hits = listGuards(guards, { path: flag("--path") });
+    if (argv.includes("--json")) print(JSON.stringify(hits, null, 1));
+    else if (!hits.length) print("No guards" + (flag("--path") ? ` cover ${flag("--path")}` : "") + ".");
+    else for (const g of hits) print(`#${g.issue} (PR ${g.pr ?? "?"}, ${String(g.merge_sha ?? "").slice(0, 10)}): ${g.why}\n  tests: ${g.tests.map((t) => t.path + (t.ids.length ? ` [${t.ids.join(", ")}]` : "")).join(", ")}\n  hunks: ${(g.hunks ?? []).map((h) => `${h.file}:${h.start}-${h.end}${h.symbol ? ` (${h.symbol})` : ""}`).join(", ") || "none"}`);
+    return 0;
+  }
+  if (sub === "backfill") {
+    const since = flag("--since");
+    if (!since || Number.isNaN(Date.parse(since))) throw new Error("usage: forgedock guards backfill --since <YYYY-MM-DD> [--dry-run]");
+    const r = await backfill({ gh, git, repo, since, dryRun: argv.includes("--dry-run"), log: (m) => print(m) });
+    print(`guards backfill: ${r.posted.length} ${argv.includes("--dry-run") ? "would be posted" : "posted"}, ${r.exists.length} already guarded, ${r.skipped.length} skipped`);
+    return 0;
+  }
+  throw new Error("usage: forgedock guards list [--path p] [--json] | backfill --since <date> [--dry-run]");
+}