forgedock 1.30.0 → 1.32.0

package/bin/lean/ledger.mjs

@@ -48,9 +48,11 @@ export function dockerLabels({ batch, lane, issue, expires } = {}) {
   return [`forgedock.owner=1`, `forgedock.batch=${v(batch)}`, `forgedock.lane=${v(lane)}`, `forgedock.issue=${v(issue)}`, `forgedock.expires=${v(expires)}`];
 }
 
-export function makeLedger({ root = ledgerRoot(), batch = "adhoc", lane, owner, issue, host = hostname(), pid = process.pid, now = () => Date.now(), ttlMs = LEDGER_TTL_MS, fs = nodeFs } = {}) {
+/** #4432: with a `repo`, the lane file is `<batch>/<owner>__<repo>__<lane>.json` (issue numbers, hence lane names, are per repo). */
+export function makeLedger({ root = ledgerRoot(), batch = "adhoc", lane, owner, issue, repo = null, host = hostname(), pid = process.pid, now = () => Date.now(), ttlMs = LEDGER_TTL_MS, fs = nodeFs } = {}) {
   const dir = join(root, safeSegment(batch));
-  const path = join(dir, `${safeSegment(lane ?? `lane-${issue}`)}.json`);
+  const repoPrefix = repo ? `${String(repo).split("/").map(safeSegment).join("__")}__` : "";
+  const path = join(dir, `${repoPrefix}${safeSegment(lane ?? `lane-${issue}`)}.json`);
   const read = () => { try { const j = JSON.parse(fs.readFileSync(path, "utf8")); return j && typeof j === "object" && Array.isArray(j.resources) ? j : null; } catch { return null; } };
   const write = (j) => {
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -58,7 +60,7 @@ export function makeLedger({ root = ledgerRoot(), batch = "adhoc", lane, owner,
     fs.writeFileSync(tmp, JSON.stringify(j, null, 2) + "\n");
     fs.renameSync(tmp, path);
   };
-  const fresh = () => { const c = now(); return { v: 1, owner, batch: String(batch), lane: String(lane ?? `lane-${issue}`), issue, host, pid, created: c, expires: c + ttlMs, resources: [] }; };
+  const fresh = () => { const c = now(); return { v: 1, owner, batch: String(batch), lane: String(lane ?? `lane-${issue}`), issue, ...(repo ? { repo: String(repo) } : {}), host, pid, created: c, expires: c + ttlMs, resources: [] }; };
   const same = (r, kind, value) => r.kind === kind && String(r.value) === String(value);
   return {
     path,

package/bin/lean/ledger.test.mjs

@@ -54,6 +54,24 @@ describe("lane resource ledger (#4179)", () => {
   });
 });
 
+describe("repo-scoped lane files (#4432)", () => {
+  it("ledgers of two repos with the same lane are separate files", () => {
+    const root = tmpDir("ledger-");
+    const one = makeLedger({ root, batch: "adhoc", lane: "lean-2", owner: "core_1", issue: 2, repo: "acme/one" });
+    const two = makeLedger({ root, batch: "adhoc", lane: "lean-2", owner: "core_2", issue: 2, repo: "acme/two" });
+    assert.equal(one.path, join(root, "adhoc", "acme__one__lean-2.json"));
+    assert.notEqual(one.path, two.path);
+    one.register("worktree", "/one/.claude/worktrees/lean-2");
+    two.register("worktree", "/two/.claude/worktrees/lean-2");
+    one.release("worktree", "/one/.claude/worktrees/lean-2");
+    assert.deepEqual(two.entries().map((r) => r.value), ["/two/.claude/worktrees/lean-2"], "one repo's teardown leaves the other's resources");
+    assert.equal(JSON.parse(readFileSync(two.path, "utf8")).repo, "acme/two");
+    assert.equal(JSON.parse(readFileSync(two.path, "utf8")).lane, "lean-2", "the lane field is unchanged");
+    const legacy = makeLedger({ root, batch: "adhoc", lane: "lean-2", issue: 2 });
+    assert.equal(legacy.path, join(root, "adhoc", "lean-2.json"), "no repo: unchanged path");
+  });
+});
+
 describe("live lane count (#4182)", () => {
   it("counts only live, same-host, unexpired lane files across batches, and deletes nothing", async () => {
     const { mkdirSync, writeFileSync } = await import("node:fs");

package/bin/lean/light.mjs

@@ -0,0 +1,135 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Light-lane eligibility and upgrade triggers (#4448, parent #4442). Rules first: an issue is eligible for the light
+ * lane (one builder session, deterministic gates) when it has a concrete repro or expected behaviour, predicts 1..max_files
+ * non-test files, is size S, touches no risk path and is not an investigation, post-deploy or decision issue. A missing
+ * repro or file prediction is `ambiguous` (the caller's cheap classifier decides). During a light lane, any upgrade
+ * trigger (oversized diff, repro not red on base, two test failures, risk path, public-API-shape change from #4449)
+ * moves the lane to the full pipeline. forge.yaml `lean.light` {mode: off|shadow (default)|on, max_lines: 40,
+ * max_files: 2}: off is never eligible, shadow reports the verdict without changing the lane shape, on lets an eligible
+ * issue run light (lane wiring: #4450). Pure: no I/O, no model call.
+ */
+import { riskClassOf, riskPathHits } from "./review-trigger.mjs";
+import { classifyPath } from "./routing.mjs";
+import { laneSize } from "./budget.mjs";
+import { isInvestigation } from "./conformance.mjs";
+import { postDeployOnly } from "./prefilter.mjs";
+
+export const LIGHT_MODES = Object.freeze(["off", "shadow", "on"]);
+export const LIGHT_DEFAULTS = Object.freeze({ mode: "shadow", maxLines: 40, maxFiles: 2 });
+
+const posInt = (v) => { const s = String(v ?? "").trim(); return /^\d+$/.test(s) && Number(s) > 0 ? Number(s) : null; };
+
+/**
+ * forge.yaml lean section -> {mode, maxLines, maxFiles}. The one-level parser flattens a nested `light:` block to
+ * `lean.mode|max_lines|max_files`; flat `lean.light_mode|light_max_lines|light_max_files` also work and win.
+ * An unknown mode is shadow; a limit that is not a positive integer keeps its default.
+ */
+export function parseLightConfig(lean = {}) {
+  const l = lean && typeof lean === "object" ? lean : {};
+  const m = String(l.light_mode ?? l.mode ?? "").trim().toLowerCase();
+  return {
+    mode: LIGHT_MODES.includes(m) ? m : LIGHT_DEFAULTS.mode,
+    maxLines: posInt(l.light_max_lines) ?? posInt(l.max_lines) ?? LIGHT_DEFAULTS.maxLines,
+    maxFiles: posInt(l.light_max_files) ?? posInt(l.max_files) ?? LIGHT_DEFAULTS.maxFiles,
+  };
+}
+
+/** A parsed config, or the defaults merged with whatever valid fields `cfg` carries. */
+const cfgOf = (cfg) => {
+  const c = cfg && typeof cfg === "object" ? cfg : {};
+  return {
+    mode: LIGHT_MODES.includes(c.mode) ? c.mode : LIGHT_DEFAULTS.mode,
+    maxLines: posInt(c.maxLines) ?? LIGHT_DEFAULTS.maxLines,
+    maxFiles: posInt(c.maxFiles) ?? LIGHT_DEFAULTS.maxFiles,
+  };
+};
+
+const uniquePaths = (xs) => [...new Set((Array.isArray(xs) ? xs : []).map((p) => String(p ?? "").trim().replace(/^\.\//, "")).filter(Boolean))].sort();
+const labelNames = (labels) => (Array.isArray(labels) ? labels : []).map((l) => String(l?.name ?? l ?? "").trim()).filter(Boolean);
+const sortReasons = (rs) => rs.sort((a, b) => a.code.localeCompare(b.code) || a.detail.localeCompare(b.detail));
+
+const REPRO_RE = /steps to reproduce|\brepro(duction|duce)?\b|\bexpected[ _-]+(behaviou?r|result|output)\b|\bactual[ _-]+(behaviou?r|result|output)\b/i;
+const FENCE_RE = /^\s*(```|~~~)/m;
+const DECISION_LABEL_RE = /^(type[:/]\s*)?(decision|needs-decision|product-decision|rfc|adr)$/i;
+const DECISION_TITLE_RE = /^\s*(decision|rfc|adr)[(:]/i;
+const POST_DEPLOY_LABELS = new Set(["post-deploy", "awaiting-promotion"]);
+
+/** Risk details for `files`: a built-in risk word or a declared review.risk_paths glob. */
+function riskDetails(files, riskPaths) {
+  const declared = new Set(riskPathHits(files, riskPaths));
+  const out = [];
+  for (const f of files) {
+    const cls = riskClassOf(f);
+    if (cls) out.push(`${f} (${cls})`);
+    else if (declared.has(f)) out.push(`${f} (review.risk_paths)`);
+  }
+  return out;
+}
+
+/**
+ * Light-lane eligibility of one issue: {mode, verdict, eligible, light, reasons:[{code, detail}]}.
+ * verdict: off | eligible | ineligible (a hard reason: files, size, risk_path, investigate, post_deploy, decision) |
+ * ambiguous (only soft reasons: no_repro, files_unknown). `light` is the lane shape: true only in mode on when eligible.
+ */
+export function lightEligibility({ title = "", body = "", labels = [], predictedFiles = [], riskPaths = [], cfg = {} } = {}) {
+  const c = cfgOf(cfg);
+  if (c.mode === "off") return { mode: "off", verdict: "off", eligible: false, light: false, reasons: [] };
+  const hard = [], soft = [];
+  const text = String(body ?? "").replace(/<!--[\s\S]*?-->/g, " ");
+  if (!FENCE_RE.test(text) && !REPRO_RE.test(text)) soft.push({ code: "no_repro", detail: "no repro, expected behaviour or code block in the body" });
+
+  const files = uniquePaths(predictedFiles);
+  const nonTest = files.filter((f) => classifyPath(f) !== "test");
+  if (nonTest.length > c.maxFiles) hard.push({ code: "files", detail: `${nonTest.length} predicted non-test files (max ${c.maxFiles})` });
+  else if (!nonTest.length) soft.push({ code: "files_unknown", detail: "no predicted non-test files" });
+
+  const names = labelNames(labels);
+  const size = laneSize({ labels: names });
+  if (size && size !== "S") hard.push({ code: "size", detail: `size:${size}` });
+
+  for (const d of riskDetails(files, riskPaths)) hard.push({ code: "risk_path", detail: d });
+
+  if (isInvestigation(title)) hard.push({ code: "investigate", detail: "investigate( issue" });
+  const pdLabel = names.find((n) => POST_DEPLOY_LABELS.has(n.toLowerCase()));
+  if (pdLabel) hard.push({ code: "post_deploy", detail: `label ${pdLabel}` });
+  else if (postDeployOnly(body)) hard.push({ code: "post_deploy", detail: "every checklist item is a post-deploy check" });
+  const decLabel = names.find((n) => DECISION_LABEL_RE.test(n));
+  if (decLabel) hard.push({ code: "decision", detail: `label ${decLabel}` });
+  else if (DECISION_TITLE_RE.test(String(title ?? ""))) hard.push({ code: "decision", detail: "decision title" });
+
+  const verdict = hard.length ? "ineligible" : soft.length ? "ambiguous" : "eligible";
+  const eligible = verdict === "eligible";
+  return { mode: c.mode, verdict, eligible, light: c.mode === "on" && eligible, reasons: sortReasons([...hard, ...soft]) };
+}
+
+const lineCount = (v) => { const n = Number(v); return Number.isFinite(n) && n > 0 ? n : 0; };
+
+/**
+ * Upgrade triggers of a light lane: {upgrade, reasons:[{code, detail}]}. diff: {files:[{path, added, deleted}]}
+ * (git numstat; "-" binary counts 0). repro: {base, head} words of scripts/acceptance-red-green.sh. testFailures: count
+ * of failed targeted-test runs. apiShape: public-API-shape changes from #4449 (strings or {symbol, kind}).
+ * Codes: diff_lines, diff_files (non-test files only), repro_not_red, tests_failed_twice, risk_path (every path), api_shape.
+ */
+export function upgradeTriggers({ diff = null, repro = null, testFailures = 0, riskPaths = [], apiShape = [], cfg = {} } = {}) {
+  const c = cfgOf(cfg);
+  const reasons = [];
+  const rows = (Array.isArray(diff?.files) ? diff.files : []).filter((f) => f && String(f.path ?? "").trim());
+  const nonTest = rows.filter((f) => classifyPath(String(f.path).trim()) !== "test");
+  const lines = nonTest.reduce((n, f) => n + lineCount(f.added) + lineCount(f.deleted), 0);
+  if (lines > c.maxLines) reasons.push({ code: "diff_lines", detail: `${lines} non-test lines (max ${c.maxLines})` });
+  const nFiles = uniquePaths(nonTest.map((f) => f.path)).length;
+  if (nFiles > c.maxFiles) reasons.push({ code: "diff_files", detail: `${nFiles} non-test files (max ${c.maxFiles})` });
+  const base = repro && typeof repro === "object" ? String(repro.base ?? "") : "";
+  if (base !== "FAILED") reasons.push({ code: "repro_not_red", detail: base ? `repro on base: ${base}` : "no repro result" });
+  const fails = Number(testFailures);
+  if (Number.isFinite(fails) && fails >= 2) reasons.push({ code: "tests_failed_twice", detail: `${fails} failed test runs` });
+  for (const d of riskDetails(uniquePaths(rows.map((f) => f.path)), riskPaths)) reasons.push({ code: "risk_path", detail: d });
+  for (const a of Array.isArray(apiShape) ? apiShape : []) {
+    const d = typeof a === "string" ? a.trim() : a && typeof a === "object" ? [a.symbol, a.kind].filter(Boolean).map(String).join(": ") : "";
+    if (d) reasons.push({ code: "api_shape", detail: d });
+  }
+  sortReasons(reasons);
+  return { upgrade: reasons.length > 0, reasons };
+}

package/bin/lean/light.test.mjs

@@ -0,0 +1,173 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { LIGHT_MODES, LIGHT_DEFAULTS, parseLightConfig, lightEligibility, upgradeTriggers } from "./light.mjs";
+import { readLight } from "../engine-cli.mjs";
+
+const ON = { mode: "on", maxLines: 40, maxFiles: 2 };
+const BODY = "## Steps to reproduce\n```js\nchunk([1, 2], 0)\n```\nExpected behaviour: a ValueError.";
+/** A fully eligible issue; override one field to break one rule. */
+const issue = (o = {}) => ({ title: "fix(chunk): reject n=0", body: BODY, labels: ["bug", "size:S"], predictedFiles: ["src/chunk.py", "tests/test_chunk.py"], riskPaths: [], cfg: ON, ...o });
+const codes = (r) => r.reasons.map((x) => x.code);
+const numstat = (...rows) => ({ files: rows.map(([path, added, deleted = 0]) => ({ path, added, deleted })) });
+const RED = { base: "FAILED", head: "RAN" };
+
+describe("parseLightConfig (#4448)", () => {
+  it("defaults to shadow, 40 lines, 2 files", () => {
+    assert.deepEqual(LIGHT_MODES, ["off", "shadow", "on"]);
+    assert.deepEqual(parseLightConfig(), LIGHT_DEFAULTS);
+    assert.deepEqual(parseLightConfig(null), { mode: "shadow", maxLines: 40, maxFiles: 2 });
+  });
+  it("reads the flattened nested keys; flat light_* keys win; junk keeps the default", () => {
+    assert.deepEqual(parseLightConfig({ mode: "ON", max_lines: "60", max_files: "3" }), { mode: "on", maxLines: 60, maxFiles: 3 });
+    assert.deepEqual(parseLightConfig({ mode: "on", light_mode: "off", max_lines: "60", light_max_lines: "80", light_max_files: "1" }), { mode: "off", maxLines: 80, maxFiles: 1 });
+    assert.deepEqual(parseLightConfig({ mode: "enforce", max_lines: "0", max_files: "-1" }), LIGHT_DEFAULTS);
+    assert.deepEqual(parseLightConfig({ light_max_lines: "4x" }), LIGHT_DEFAULTS);
+  });
+  it("readLight reads forge.yaml lean.light; absent forge.yaml is the defaults", () => {
+    const d = tmpDir("light-yaml-");
+    assert.deepEqual(readLight(d), LIGHT_DEFAULTS);
+    writeFileSync(join(d, "forge.yaml"), "lean:\n  light:\n    mode: on\n    max_lines: 50\n    max_files: 3\n");
+    assert.deepEqual(readLight(d), { mode: "on", maxLines: 50, maxFiles: 3 });
+    writeFileSync(join(d, "forge.yaml"), "lean:\n  light_mode: off\n");
+    assert.equal(readLight(d).mode, "off");
+  });
+});
+
+describe("lightEligibility rules (#4448)", () => {
+  it("accepts a well-specified size:S issue with 1-2 predicted files", () => {
+    const r = lightEligibility(issue());
+    assert.deepEqual(r, { mode: "on", verdict: "eligible", eligible: true, light: true, reasons: [] });
+  });
+  it("repro or expected behaviour: present accepts, absent is ambiguous (never a model call)", () => {
+    for (const body of ["Repro: `x()` throws", "Expected result: 3", "```\nboom\n```", "actual output differs"]) assert.equal(lightEligibility(issue({ body })).verdict, "eligible", body);
+    const r = lightEligibility(issue({ body: "It is broken. <!-- steps to reproduce -->" }));
+    assert.equal(r.verdict, "ambiguous");
+    assert.equal(r.eligible, false);
+    assert.equal(r.light, false);
+    assert.deepEqual(codes(r), ["no_repro"]);
+  });
+  it("predicted files: 1 or 2 non-test files accept, 3 reject, tests do not count, none is ambiguous", () => {
+    assert.equal(lightEligibility(issue({ predictedFiles: ["src/a.py"] })).verdict, "eligible");
+    assert.equal(lightEligibility(issue({ predictedFiles: ["src/a.py", "src/b.py", "tests/test_a.py", "src/c.test.ts"] })).verdict, "eligible");
+    const r = lightEligibility(issue({ predictedFiles: ["src/a.py", "src/b.py", "src/c.py"] }));
+    assert.equal(r.verdict, "ineligible");
+    assert.deepEqual(codes(r), ["files"]);
+    assert.deepEqual(codes(lightEligibility(issue({ predictedFiles: [] }))), ["files_unknown"]);
+    assert.equal(lightEligibility(issue({ predictedFiles: ["tests/test_a.py"] })).verdict, "ambiguous");
+    assert.equal(lightEligibility(issue({ predictedFiles: ["src/a.py", "src/b.py", "src/c.py"], cfg: { ...ON, maxFiles: 3 } })).verdict, "eligible");
+  });
+  it("size: size:S accepts, size:M and size:L reject", () => {
+    assert.equal(lightEligibility(issue({ labels: [{ name: "size:S" }] })).verdict, "eligible");
+    assert.equal(lightEligibility(issue({ labels: [] })).verdict, "eligible");
+    for (const s of ["size:M", "size:L"]) {
+      const r = lightEligibility(issue({ labels: ["bug", s] }));
+      assert.equal(r.verdict, "ineligible", s);
+      assert.deepEqual(codes(r), ["size"]);
+    }
+  });
+  it("risk path: a built-in risk word or a declared review.risk_paths glob rejects; a clean path accepts", () => {
+    const w = lightEligibility(issue({ predictedFiles: ["src/auth/login.ts"] }));
+    assert.deepEqual(codes(w), ["risk_path"]);
+    assert.match(w.reasons[0].detail, /src\/auth\/login\.ts \(auth\)/);
+    const g = lightEligibility(issue({ predictedFiles: ["src/detect/rules.ts"], riskPaths: "src/detect/**" }));
+    assert.deepEqual(codes(g), ["risk_path"]);
+    assert.match(g.reasons[0].detail, /review\.risk_paths/);
+    assert.equal(lightEligibility(issue({ predictedFiles: ["src/chunk.py"], riskPaths: ["src/detect/**"] })).verdict, "eligible");
+  });
+  it("kind: investigate(, post-deploy and decision issues reject; a plain bug accepts", () => {
+    assert.deepEqual(codes(lightEligibility(issue({ title: "investigate(lean): why lanes stall" }))), ["investigate"]);
+    assert.deepEqual(codes(lightEligibility(issue({ labels: ["awaiting-promotion"] }))), ["post_deploy"]);
+    assert.deepEqual(codes(lightEligibility(issue({ labels: ["post-deploy"] }))), ["post_deploy"]);
+    const pd = "Post-deploy checks.\n```\nx\n```\n- [ ] `R3: verify in prod` — post-deploy: needs a deploy\n";
+    assert.deepEqual(codes(lightEligibility(issue({ body: pd }))), ["post_deploy"]);
+    for (const labels of [["decision"], ["needs-decision"], ["type:decision"], ["product-decision"], ["RFC"], ["adr"]]) assert.deepEqual(codes(lightEligibility(issue({ labels }))), ["decision"], labels[0]);
+    for (const title of ["decision(lean): pick a queue", "RFC: light lanes", "adr(engine): leases"]) assert.deepEqual(codes(lightEligibility(issue({ title }))), ["decision"], title);
+    assert.equal(lightEligibility(issue({ title: "fix: decision table off by one", labels: ["bug"] })).verdict, "eligible");
+  });
+  it("hard reasons win over soft ones; reasons are sorted and deterministic", () => {
+    const o = issue({ body: "broken", labels: ["size:L", "decision"], predictedFiles: ["src/billing.ts", "a.py", "b.py"] });
+    const r = lightEligibility(o);
+    assert.equal(r.verdict, "ineligible");
+    assert.deepEqual(codes(r), ["decision", "files", "no_repro", "risk_path", "size"]);
+    assert.deepEqual(lightEligibility({ ...o, predictedFiles: [...o.predictedFiles].reverse() }), r);
+  });
+  it("tolerates missing and junk input", () => {
+    assert.equal(lightEligibility().verdict, "ambiguous");
+    assert.doesNotThrow(() => lightEligibility({ title: null, body: null, labels: "x", predictedFiles: "y", riskPaths: 3, cfg: null }));
+  });
+});
+
+describe("lightEligibility modes (#4448)", () => {
+  it("off never returns eligible, even for a fully eligible issue", () => {
+    assert.deepEqual(lightEligibility(issue({ cfg: { mode: "off" } })), { mode: "off", verdict: "off", eligible: false, light: false, reasons: [] });
+  });
+  it("shadow returns the verdict without changing the lane shape", () => {
+    const r = lightEligibility(issue({ cfg: { mode: "shadow" } }));
+    assert.equal(r.verdict, "eligible");
+    assert.equal(r.eligible, true);
+    assert.equal(r.light, false);
+    assert.equal(lightEligibility(issue({ cfg: {} })).mode, "shadow", "default mode");
+    assert.equal(lightEligibility(issue({ cfg: { mode: "shadow" }, labels: ["size:M"] })).verdict, "ineligible");
+  });
+  it("on runs an eligible issue light and never an ineligible one", () => {
+    assert.equal(lightEligibility(issue()).light, true);
+    assert.equal(lightEligibility(issue({ labels: ["size:M"] })).light, false);
+    assert.equal(lightEligibility(issue({ body: "broken" })).light, false);
+  });
+});
+
+describe("upgradeTriggers (#4448)", () => {
+  const quiet = { diff: numstat(["src/chunk.py", 30, 10], ["tests/test_chunk.py", 200]), repro: RED, testFailures: 1, cfg: ON };
+  it("no trigger on a small red-green diff", () => {
+    assert.deepEqual(upgradeTriggers(quiet), { upgrade: false, reasons: [] });
+  });
+  it("oversized diff by lines: 41 non-test lines fire, 40 do not, test lines are ignored, max_lines is honoured", () => {
+    const r = upgradeTriggers({ ...quiet, diff: numstat(["src/chunk.py", 31, 10], ["tests/test_chunk.py", 500]) });
+    assert.equal(r.upgrade, true);
+    assert.deepEqual(codes(r), ["diff_lines"]);
+    assert.match(r.reasons[0].detail, /41 non-test lines \(max 40\)/);
+    assert.equal(upgradeTriggers({ ...quiet, diff: numstat(["src/a.py", 41], ["src/b.py", "-", "-"]), cfg: { ...ON, maxLines: 41 } }).upgrade, false);
+  });
+  it("oversized diff by files: 3 non-test files fire, 2 do not", () => {
+    assert.deepEqual(codes(upgradeTriggers({ ...quiet, diff: numstat(["src/a.py", 1], ["src/b.py", 1], ["src/c.py", 1]) })), ["diff_files"]);
+    assert.equal(upgradeTriggers({ ...quiet, diff: numstat(["src/a.py", 1], ["src/b.py", 1], ["tests/test_a.py", 1]) }).upgrade, false);
+  });
+  it("non-red repro: anything but FAILED on base fires, a missing repro included", () => {
+    for (const base of ["RAN", "RAN_NOTHING", "UNRUNNABLE", "SKIPPED"]) assert.deepEqual(codes(upgradeTriggers({ ...quiet, repro: { base, head: "RAN" } })), ["repro_not_red"], base);
+    assert.deepEqual(codes(upgradeTriggers({ ...quiet, repro: null })), ["repro_not_red"]);
+    assert.equal(upgradeTriggers({ ...quiet, repro: RED }).upgrade, false);
+  });
+  it("tests fail twice: 2 failures fire, 1 does not", () => {
+    assert.deepEqual(codes(upgradeTriggers({ ...quiet, testFailures: 2 })), ["tests_failed_twice"]);
+    assert.equal(upgradeTriggers({ ...quiet, testFailures: 1 }).upgrade, false);
+  });
+  it("risk path: a risk word or declared glob on any diff path fires, tests included; a clean diff does not", () => {
+    assert.deepEqual(codes(upgradeTriggers({ ...quiet, diff: numstat(["src/session.ts", 2]) })), ["risk_path"]);
+    assert.deepEqual(codes(upgradeTriggers({ ...quiet, diff: numstat(["src/a.py", 2], ["tests/test_payments.py", 2]) })), ["risk_path"]);
+    assert.deepEqual(codes(upgradeTriggers({ ...quiet, diff: numstat(["lib/detect.py", 2]), riskPaths: "lib/detect.py" })), ["risk_path"]);
+    assert.equal(upgradeTriggers({ ...quiet, riskPaths: ["lib/**"] }).upgrade, false);
+  });
+  it("public-API-shape changes (#4449) plug in as one more input", () => {
+    const r = upgradeTriggers({ ...quiet, apiShape: ["ichunked: generator -> function", { symbol: "chunk", kind: "signature" }, "", null] });
+    assert.deepEqual(r.reasons, [{ code: "api_shape", detail: "chunk: signature" }, { code: "api_shape", detail: "ichunked: generator -> function" }]);
+  });
+  it("reasons are sorted and deterministic; junk input does not throw", () => {
+    const o = { diff: numstat(["src/z.py", 30], ["src/auth.py", 30], ["src/m.py", 1]), repro: null, testFailures: 3, cfg: ON };
+    const r = upgradeTriggers(o);
+    assert.deepEqual(codes(r), ["diff_files", "diff_lines", "repro_not_red", "risk_path", "tests_failed_twice"]);
+    assert.deepEqual(upgradeTriggers({ ...o, diff: { files: [...o.diff.files].reverse() } }), r);
+    assert.doesNotThrow(() => upgradeTriggers({ diff: { files: [null, { path: "" }, { path: 3, added: "x" }] }, testFailures: "nan", apiShape: "x", cfg: null }));
+  });
+});
+
+describe("light.mjs purity (#4448)", () => {
+  it("imports no filesystem, process or network module", () => {
+    const src = readFileSync(new URL("./light.mjs", import.meta.url), "utf8");
+    for (const m of ["node:fs", "node:child_process", "node:net", "node:http", "node:https"]) assert.equal(src.includes(`"${m}"`), false, m);
+  });
+});

package/bin/lean/lightlane.mjs

@@ -0,0 +1,219 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Light-lane execution (#4450, parent #4442). An eligible issue (light.mjs, mode on) runs ONE builder session: failing
+ * test first, then the fix, then the targeted tests. No plan session, no pre-frozen contract: the contract record is
+ * derived afterwards from the diff and the test (deriveLightContract) and checked by the same validateContract as a
+ * planned one. The deterministic gates are kept (targeted tests, red/green repro, the API-shape detector of #4449);
+ * any upgrade trigger hands the lane to the full plan -> freeze -> implement path, with the light work kept on the
+ * branch and carried over as a digest (#4400). runLightStep takes every effect as a callback, so lean.mjs only wires it.
+ */
+import { classifyPath } from "./routing.mjs";
+import { upgradeTriggers } from "./light.mjs";
+import { inIssue } from "./conformance.mjs";
+import { runChecks } from "./precheck.mjs";
+import { LEAN_DIR, RESULT_FILE, IMPLEMENTATION_FILE, FORGEDOCK_CLI, hostRules } from "./prompts.mjs";
+
+const UPGRADE_NOTE_MAX = 10;
+const DETAIL_MAX = 200;
+const one = (s, max = DETAIL_MAX) => {
+  const t = String(s ?? "").replace(/<!--|--!?>/g, " ").replace(/\s+/g, " ").trim().replace(/</g, "&lt;");
+  return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+};
+
+/** The one builder session of a light lane: failing test, fix, targeted tests, result.json with what the contract is derived from. */
+export function lightBuildPrompt(n, opts = {}) {
+  return `Resolve issue #${n} (read it with gh issue view ${n} --comments) in ONE session; this is a light lane for a small, well-specified issue. There is no plan step and no frozen contract: the engine derives the contract from your diff and your test.
+
+${hostRules(opts)}
+
+1. Write the failing regression test first and run it: it must fail on the current code for the reason the issue describes.
+2. Make the smallest fix that makes it pass. Keep the public API shape unchanged (signatures, sync/async, generator/function, exported names); the engine checks it.
+3. Run the targeted tests (the new test plus the existing tests of the files you changed), run the repo's formatter on the files you changed, and commit. Do not push or touch GitHub.
+4. Run \`node ${FORGEDOCK_CLI} check\` in the worktree and fix until it passes.
+
+When done and committed, write ${IMPLEMENTATION_FILE} (markdown, no HTML comments):
+### Approach
+### Changes   (file: what)
+### Verification   (each test command, its result, and whether the new test fails without the fix)
+
+Finally write ${RESULT_FILE}: {"status":"fixed","summary":"one line","requirement":"<one sentence of the issue, verbatim, that this fix delivers>","repro_test":{"path":"<test file>","id":"<test name>","command":"<exact command that runs only that test>"},"tests":[{"command":"<targeted test command>","result":"pass|fail: ...","fails_without_fix":true|false|"unknown"}]}
+If the issue is invalid, already fixed, blocked, or bigger than a small fix (more than a couple of files, a design decision), do not grind: write {"status":"upgrade","summary":"<why>"} and stop. The engine then runs the full lane, keeping what you committed.`;
+}
+
+/** "-" (binary) and junk count 0. */
+const count = (v) => (/^\d+$/.test(String(v ?? "")) ? Number(v) : 0);
+/** A numstat path, rename forms resolved to the new path: `a => b`, `dir/{a => b}/f`. */
+const newPath = (p) => {
+  const s = String(p ?? "").trim();
+  const brace = /^(.*)\{(.*) => (.*)\}(.*)$/.exec(s);
+  if (brace) return `${brace[1]}${brace[3]}${brace[4]}`.replace(/\/\/+/g, "/");
+  const arrow = s.indexOf(" => ");
+  return arrow >= 0 ? s.slice(arrow + 4) : s;
+};
+/** `git diff --numstat` output -> {files:[{path, added, deleted}]} for upgradeTriggers; the engine's own dir is skipped. */
+export function parseNumstat(out) {
+  const files = [];
+  for (const line of String(out ?? "").split("\n")) {
+    const m = /^(\S+)\t(\S+)\t(.+)$/.exec(line.trim() ? line : "");
+    if (!m) continue;
+    const path = newPath(m[3]);
+    if (!path || path === LEAN_DIR || path.startsWith(`${LEAN_DIR}/`)) continue;
+    files.push({ path, added: count(m[1]), deleted: count(m[2]) });
+  }
+  return { files };
+}
+
+/** detectApiShape output (apishape.mjs) -> upgradeTriggers apiShape strings; a missing or unreadable result is `unknown` (#4449). */
+export function apiShapeReasons(r) {
+  if (!r || typeof r !== "object" || !["none", "changed", "unknown"].includes(r.status)) return ["api shape: no detector result (unknown)"];
+  const out = [];
+  for (const c of Array.isArray(r.changes) ? r.changes : []) out.push(one(`${c?.file ?? "?"}: ${c?.symbol ?? "?"} ${c?.change ?? "changed"}`));
+  for (const u of Array.isArray(r.unknown) ? r.unknown : []) out.push(one(`${u?.file ?? "?"}: unknown${u?.lang ? ` (${u.lang})` : ""}${u?.reason ? `, ${u.reason}` : ""}`));
+  if (r.status !== "none" && !out.length) out.push(`api shape: ${r.status}`);
+  return out;
+}
+
+/**
+ * The contract record of a light lane, from the diff and the builder's test (pure). requirement: the builder's verbatim
+ * issue sentence, else the issue title; deliverables: the changed non-test files; validate: the repro command plus each
+ * targeted test command; repro_test: the builder's, else "none" with a reason. validateContract judges it like any other.
+ */
+export function deriveLightContract({ title = "", issueText = "", result = null, files = [] } = {}) {
+  const r = result && typeof result === "object" ? result : {};
+  const said = typeof r.requirement === "string" ? r.requirement.trim() : "";
+  const quote = said && inIssue(said, issueText) ? said : String(title ?? "").trim();
+  const paths = [...new Set((Array.isArray(files) ? files : []).map((f) => String(f ?? "").trim()).filter((f) => f && f !== LEAN_DIR && !f.startsWith(`${LEAN_DIR}/`)))];
+  const code = paths.filter((f) => classifyPath(f) !== "test");
+  const t = r.repro_test;
+  const repro = t && typeof t === "object" && !Array.isArray(t) && String(t.path ?? "").trim() && String(t.command ?? "").trim()
+    ? { path: String(t.path).trim(), id: String(t.id ?? "").trim(), command: String(t.command).trim() } : null;
+  const commands = [...new Set([repro?.command, ...(Array.isArray(r.tests) ? r.tests : []).map((x) => (x && typeof x === "object" ? String(x.command ?? "").trim() : ""))].filter(Boolean))];
+  return {
+    requirements: [{ id: "R1", quote, disposition: "deliver" }],
+    deliverables: code.map((path, i) => ({ id: `D${i + 1}`, path, change: "light-lane fix (derived from the diff)", requirements: ["R1"] })),
+    validate: commands.map((command, i) => ({ id: `V${i + 1}`, command })),
+    ...(repro ? { repro_test: repro } : { repro_test: "none", repro_test_reason: "the light-lane builder named no repro test" }),
+  };
+}
+
+/** The full lane's prompt addition after an upgrade: why the light lane stopped (bounded, one line per reason). */
+export function upgradeNote(reasons) {
+  const rs = (Array.isArray(reasons) ? reasons : []).filter((x) => x && x.code);
+  if (!rs.length) return "";
+  const lines = rs.slice(0, UPGRADE_NOTE_MAX).map((x) => `- ${one(x.code, 40)}: ${one(x.detail)}`);
+  if (rs.length > UPGRADE_NOTE_MAX) lines.push(`- … ${rs.length - UPGRADE_NOTE_MAX} more`);
+  return `\n\nLight-lane upgrade: a single light builder session already worked on this issue and its commits are on the branch. The engine moved the issue to the full lane because:\n${lines.join("\n")}\nKeep the committed work that fits the issue; plan and fix what these reasons show.`;
+}
+
+/**
+ * #4451: the light targeted tests, concurrently through precheck.mjs runChecks (one heavy slot per running command, the
+ * worker cap `parallelism` divided among them) with no round budget: every command runs, none is deferred to CI.
+ * run({command, workers}) -> {rc, output}. Returns [{command, rc, output}] in input order.
+ */
+export async function runLightTests({ commands, parallelism = 1, run, acquire, now = () => Date.now() }) {
+  // the per-command limit stays far below the budget, so runChecks never sees a budget cut: a timeout (rc 124) stays a failure
+  const { results } = await runChecks({ commands, parallelism, budgetMs: Number.MAX_SAFE_INTEGER, perCommandMs: 2 ** 40, now, acquire, run: ({ command, workers }) => run({ command, workers }) });
+  return results.map(({ command, rc, output }) => ({ command, rc, output }));
+}
+
+/**
+ * One light lane step. ctx callbacks (all async unless noted): build() runs the one builder session; readResult();
+ * checkpoint() commits uncommitted work; changedFiles(); numstat() -> `git diff --numstat` text; runTests(commands) ->
+ * [{command, rc, output}] or null (no runner); fixTests(failed) resumes the builder once; reproOf(contract) -> {base, head}
+ * or null; apiShape() -> detectApiShape output or null; validate(contract) -> {ok, problems} (sync). Plus title, issueText,
+ * riskPaths, cfg. Returns {upgrade:false, contract, files, repro, testFailures} or {upgrade:true, reasons, files, ...}, plus the
+ * gate inputs of the FORGE:LITE receipt (#4452): diff (parseNumstat), apiShape (apiShapeReasons), testCommands, testRuns.
+ * Never throws: an internal error is the upgrade reason light_error.
+ */
+export async function runLightStep(ctx) {
+  const up = (reasons, extra = {}) => ({ upgrade: true, reasons, contract: null, files: [], repro: null, testFailures: 0, diff: null, apiShape: null, testCommands: [], testRuns: null, ...extra });
+  try {
+    await ctx.build();
+    const result = await ctx.readResult();
+    await ctx.checkpoint();
+    const files = await ctx.changedFiles();
+    if (!files.length) return up([{ code: "no_commit", detail: `the light builder made no commit (status ${one(result?.status ?? "none", 40)})` }]);
+    if (result?.status !== "fixed") return up([{ code: "not_fixed", detail: `light builder status ${one(result?.status ?? "none", 40)}${result?.summary ? `: ${one(result.summary)}` : ""}` }], { files });
+    const contract = deriveLightContract({ title: ctx.title, issueText: ctx.issueText, result, files });
+    const vc = ctx.validate(contract);
+    if (!vc?.ok) return up([{ code: "contract_invalid", detail: `derived contract: ${one((vc?.problems ?? [])[0] ?? "invalid")}` }], { files });
+
+    let testFailures = 0;
+    const commands = contract.validate.map((v) => v.command);
+    let runs = await ctx.runTests(commands);
+    let failed = (runs ?? []).filter((x) => x?.rc !== 0);
+    if (failed.length) {
+      testFailures = 1;
+      await ctx.fixTests(failed);
+      runs = await ctx.runTests(commands);
+      failed = (runs ?? []).filter((x) => x?.rc !== 0);
+      if (failed.length) testFailures = 2;
+    }
+    const now = await ctx.changedFiles();
+    // #4451: the three deterministic gates are independent, so they run concurrently
+    const [repro, numstat, shape] = await Promise.all([ctx.reproOf(contract), ctx.numstat(), ctx.apiShape()]);
+    const diff = parseNumstat(numstat), apiShape = apiShapeReasons(shape);
+    const t = upgradeTriggers({ diff, repro, testFailures, riskPaths: ctx.riskPaths ?? [], apiShape, cfg: ctx.cfg ?? {} });
+    const latest = deriveLightContract({ title: ctx.title, issueText: ctx.issueText, result: (await ctx.readResult()) ?? result, files: now });
+    return { upgrade: t.upgrade, reasons: t.reasons, contract: t.upgrade ? null : (ctx.validate(latest)?.ok ? latest : contract), files: now, repro, testFailures,
+      diff, apiShape, testCommands: commands, testRuns: runs == null ? null : (runs ?? []).length };
+  } catch (e) {
+    return up([{ code: "light_error", detail: one(e?.message ?? e) }]);
+  }
+}
+
+const usd = (x) => (typeof x === "number" && Number.isFinite(x) ? `$${x.toFixed(4)}` : "n/a");
+const RECEIPT_ROWS_MAX = 10;
+const bullets = (xs) => {
+  const lines = xs.slice(0, RECEIPT_ROWS_MAX).map((x) => `  - ${x}`);
+  if (xs.length > RECEIPT_ROWS_MAX) lines.push(`  - … ${xs.length - RECEIPT_ROWS_MAX} more`);
+  return lines;
+};
+
+/**
+ * The FORGE:LITE receipt of a light lane (#4452, parent #4442), without the marker (pure): outcome, diff stat, red/green
+ * repro, gates (targeted tests, API shape, derived contract), cost and eligibility, plus the upgrade reasons when the lane
+ * moved to the full pipeline. `costUsd` is the lane's true cost so far: the sum of #4407 per-session deltas, never a
+ * running session total. `lr` is runLightStep's return; `eligibility` is lightEligibility's.
+ */
+export function renderLiteReceipt({ lr = {}, eligibility = null, costUsd = null, contractHash = null } = {}) {
+  const r = lr && typeof lr === "object" ? lr : {};
+  const upgraded = !!r.upgrade;
+  const rows = Array.isArray(r.diff?.files) ? r.diff.files : null;
+  const nonTest = rows ? rows.filter((f) => classifyPath(String(f.path ?? "")) !== "test") : [];
+  const add = (xs) => xs.reduce((n, f) => n + (Number(f.added) || 0), 0), del = (xs) => xs.reduce((n, f) => n + (Number(f.deleted) || 0), 0);
+  const diff = rows
+    ? `${rows.length} file(s), +${add(rows)}/-${del(rows)} (non-test: ${nonTest.length} file(s), ${add(nonTest) + del(nonTest)} line(s))`
+    : `n/a${Array.isArray(r.files) && r.files.length ? ` (${r.files.length} changed file(s))` : ""}`;
+  const rp = r.repro && typeof r.repro === "object" ? r.repro : null;
+  const repro = rp ? `base ${one(rp.base || "?", 40)} → head ${one(rp.head || "?", 40)}${rp.base === "FAILED" ? " (red on base)" : " (not red on base)"}` : "n/a";
+  const cmds = Array.isArray(r.testCommands) ? r.testCommands : [];
+  const fails = Number(r.testFailures) || 0;
+  const tests = r.testRuns == null ? (cmds.length ? `${cmds.length} command(s), no runner` : "not run")
+    : `${cmds.length} command(s), ${fails ? (fails >= 2 ? "failed twice" : "failed once, passed after one fix") : "passed"}`;
+  const api = Array.isArray(r.apiShape) ? (r.apiShape.length ? `${r.apiShape.length} change(s)/unknown` : "unchanged") : "not checked";
+  const contract = upgraded ? "not derived (upgraded)" : contractHash ? `derived, valid (\`${one(contractHash, 20)}\`)` : "derived, valid";
+  const e = eligibility && typeof eligibility === "object" ? eligibility : {};
+  const eReasons = (Array.isArray(e.reasons) ? e.reasons : []).filter((x) => x && x.code).map((x) => `${one(x.code, 40)}: ${one(x.detail)}`);
+  const lines = [
+    `## Light lane ${upgraded ? "upgraded to the full lane" : "receipt"}`,
+    `**Outcome:** ${upgraded ? "upgraded" : "light"}`,
+    `**Diff:** ${diff}`,
+    `**Red/green:** ${repro}`,
+    "**Gates:**",
+    `  - targeted tests: ${tests}`,
+    ...bullets(cmds.map((c) => `\`${one(c, 120)}\``)).map((x) => `  ${x}`),
+    `  - API shape: ${api}`,
+    ...(Array.isArray(r.apiShape) ? bullets(r.apiShape.map((x) => one(x))).map((x) => `  ${x}`) : []),
+    `  - contract: ${contract}`,
+    `**Cost:** ${usd(costUsd)} (true per-session cost, #4407 deltas)`,
+    `**Eligibility:** ${one(e.verdict ?? "unknown", 20)} (mode ${one(e.mode ?? "?", 10)})${e.verdict === "eligible" && !eReasons.length ? ": repro or expected behaviour, predicted files within limits, size S, no risk path" : ""}`,
+    ...bullets(eReasons),
+  ];
+  if (upgraded) {
+    const ups = (Array.isArray(r.reasons) ? r.reasons : []).filter((x) => x && x.code).map((x) => `${one(x.code, 40)}: ${one(x.detail)}`);
+    lines.push("**Upgrade reasons:**", ...bullets(ups.length ? ups : ["unknown"]));
+  }
+  return lines.join("\n");
+}