forgedock 1.30.0 → 1.32.0

package/bin/lean/pitfalls.mjs

@@ -0,0 +1,136 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * #4375: learned per-repo pitfalls. When a rework round (fixround.mjs REWORK_TRIGGERS) fixes a failure, i.e. the same gate
+ * passes afterwards, the engine appends one record: trigger, a normalised failure signature, the fix's file globs and a
+ * one-line lesson from the failure output. The context pack carries the top ones for the next lane in the same repo.
+ * Deterministic: no model call. Local only: an append-only JSONL per repo under ~/.forge/pitfalls (FORGE_PITFALLS_DIR),
+ * never posted to GitHub or telemetry. A cache in the NORTHSTAR sense: deleting it only forgets the lessons.
+ * Records: {t:"lane", run, ts} once per lane (the aging clock) and {t:"pitfall", run, ts, sig, trigger, globs, lesson}.
+ */
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, extname, join } from "node:path";
+import { REWORK_TRIGGERS } from "./fixround.mjs";
+import { matchesGlob } from "./verify.mjs";
+
+export const DEFAULT_PITFALL_LANES = 50;
+export const DEFAULT_PITFALL_LIMIT = 5;
+export const LESSON_MAX = 160;
+const MAX_GLOBS = 5;
+const ERROR_LINE_RE = /\b(?:error|errors|fail(?:ed|ure|s)?|not ok|missing|stale|undeclared|collid\w*|cannot|unable|invalid|expected|assert\w*|exception|traceback|panic|denied)\b|✗|✖|×|\b[A-Z]{1,4}\d{3,5}\b/i;
+
+const hash12 = (s) => createHash("sha256").update(String(s)).digest("hex").slice(0, 12);
+// eslint-disable-next-line no-control-regex
+const stripAnsi = (s) => String(s ?? "").replace(/\x1b\[[0-9;]*[A-Za-z]/g, "");
+const squash = (s) => s.replace(/\s+/g, " ").trim();
+
+/** The failure output's first error-like line (ANSI and blank lines skipped), else its first non-empty line, else "". */
+export function failureLine(text) {
+  const lines = stripAnsi(text).split(/\r?\n/).map(squash).filter((l) => l && !/^[-=#*`~>]+$/.test(l));
+  return lines.find((l) => ERROR_LINE_RE.test(l)) ?? lines[0] ?? "";
+}
+
+/**
+ * The repeat-stable form of a failure line: quoted literals, file paths (with :line:col), hex ids and standalone numbers
+ * are replaced, so the same rule on another file or line gives the same signature. Rule codes (F401, TS2345) are kept.
+ */
+export function normaliseFailure(line) {
+  return squash(String(line ?? "")
+    .replace(/"[^"\n]*"|'[^'\n]*'|`[^`\n]*`/g, "<str>")
+    .replace(/(?:[\w.@~-]+[/\\])*[\w.@~-]+\.[A-Za-z][A-Za-z0-9]{0,7}(?::\d+)*/g, "<path>")
+    .replace(/\b[0-9a-f]{7,40}\b/gi, "<hex>")
+    .replace(/\b\d+(?:\.\d+)*\b/g, "<n>")
+    .toLowerCase());
+}
+
+/** `trigger:` + a 12-hex hash of the normalised failure line. */
+export const signatureOf = (trigger, text) => `${trigger}:${hash12(normaliseFailure(failureLine(text)))}`;
+
+/** One line (at most LESSON_MAX chars) from the failure output, prefixed with the trigger. */
+export function lessonOf(trigger, text) {
+  const t = `${trigger}: ${failureLine(text)}`;
+  return t.length > LESSON_MAX ? `${t.slice(0, LESSON_MAX - 1)}…` : t;
+}
+
+/** The fix's changed files as globs: `dir/*.ext` (`dir/*` without an extension), a root file by name; `.forge-lean/` left out. */
+export function fixGlobs(files) {
+  const out = [];
+  for (const f of files ?? []) {
+    const p = String(f ?? "").trim().replace(/^\.?\//, "");
+    if (!p || p.startsWith(".forge-lean/")) continue;
+    const d = dirname(p), base = p.split("/").at(-1);
+    const g = d === "." ? base : `${d}/*${extname(base)}`;
+    if (!out.includes(g)) out.push(g);
+    if (out.length >= MAX_GLOBS) break;
+  }
+  return out;
+}
+
+/** Failure text from a gate's failure list: strings, CI jobs ({job, log}) or conformance rows ({code, detail}). */
+export const failureLog = (failures) => (Array.isArray(failures) ? failures : []).map((f) => (typeof f === "string" ? f
+  : [f?.code, f?.detail, f?.log ? `${f.job ?? ""}\n${f.log}` : f?.job].filter(Boolean).join(" "))).join("\n");
+
+/** A pending pitfall for a rework round, or null (not a rework trigger, or no failure text to learn from). */
+export function pendingPitfall(trigger, text) {
+  if (!REWORK_TRIGGERS.includes(trigger) || !failureLine(text)) return null;
+  return { trigger, sig: signatureOf(trigger, text), lesson: lessonOf(trigger, text) };
+}
+
+/** The ledger record for a pending pitfall whose gate passed; `files` are the files the fix changed. */
+export const pitfallRecord = ({ pending, files, run, ts }) => ({ t: "pitfall", run: String(run), ts, sig: pending.sig, trigger: pending.trigger, globs: fixGlobs(files), lesson: pending.lesson });
+
+const byRank = (a, b) => b.count - a.count || String(b.lastTs ?? "").localeCompare(String(a.lastTs ?? "")) || a.sig.localeCompare(b.sig);
+
+/**
+ * One entry per signature {sig, trigger, globs, lesson, count, lastSeq, lastTs}, ranked by count, then recency. The lane
+ * sequence is the order of distinct `lane` rows; an entry not seen in the last `maxAge` lanes ages out. One lane counts
+ * a signature once.
+ */
+export function foldPitfalls(records, { maxAge = DEFAULT_PITFALL_LANES } = {}) {
+  const lanes = new Map(), bySig = new Map();
+  for (const r of records ?? []) {
+    if (!r || typeof r !== "object") continue;
+    if (r.t === "lane") { if (!lanes.has(String(r.run))) lanes.set(String(r.run), lanes.size); continue; }
+    if (r.t !== "pitfall" || typeof r.sig !== "string" || !r.sig) continue;
+    const seq = lanes.get(String(r.run)) ?? Math.max(0, lanes.size - 1);
+    const e = bySig.get(r.sig) ?? { sig: r.sig, trigger: String(r.trigger ?? ""), globs: [], lesson: "", count: 0, lastSeq: seq, lastTs: null, lastRun: null };
+    if (e.lastRun !== String(r.run)) e.count++;
+    e.lastRun = String(r.run); e.lastSeq = Math.max(e.lastSeq, seq); e.lastTs = r.ts ?? e.lastTs;
+    e.lesson = typeof r.lesson === "string" && r.lesson ? r.lesson : e.lesson;
+    for (const g of Array.isArray(r.globs) ? r.globs : []) if (typeof g === "string" && g && !e.globs.includes(g) && e.globs.length < MAX_GLOBS) e.globs.push(g);
+    bySig.set(r.sig, e);
+  }
+  const total = lanes.size;
+  return [...bySig.values()].filter((e) => total - 1 - e.lastSeq < maxAge).map(({ lastRun, ...e }) => e).sort(byRank);
+}
+
+/** Up to `limit` pitfalls: those whose globs match one of `paths` (match "files") first, then the rest (match "repo"). */
+export function selectPitfalls(folded, { paths = [], limit = DEFAULT_PITFALL_LIMIT } = {}) {
+  const hits = (p) => p.globs.some((g) => paths.some((f) => matchesGlob(f, g)));
+  const files = folded.filter(hits).sort(byRank).map((p) => ({ ...p, match: "files" }));
+  const repo = folded.filter((p) => !hits(p)).sort(byRank).map((p) => ({ ...p, match: "repo" }));
+  return [...files, ...repo].slice(0, limit);
+}
+
+// ---- file store (I/O) ----
+
+export const pitfallsDir = (env = process.env) => env.FORGE_PITFALLS_DIR || join(homedir(), ".forge", "pitfalls");
+const segment = (s) => { const v = String(s ?? "").replace(/[^A-Za-z0-9._-]/g, "_"); return !v || /^\.+$/.test(v) ? "_" : v; };
+export const pitfallsFile = (repo, dir = pitfallsDir()) => join(dir, `${String(repo ?? "").split("/").map(segment).join("__")}.jsonl`);
+
+/** {read(repo) → records (corrupt lines skipped, missing file → []), append(repo, rec)}: one line per append. */
+export function makePitfallStore({ dir = pitfallsDir() } = {}) {
+  return {
+    read(repo) {
+      const f = pitfallsFile(repo, dir);
+      if (!existsSync(f)) return [];
+      return readFileSync(f, "utf8").split("\n").map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter((x) => x && typeof x === "object");
+    },
+    append(repo, rec) {
+      mkdirSync(dir, { recursive: true });
+      appendFileSync(pitfallsFile(repo, dir), `${JSON.stringify(rec)}\n`);
+    },
+  };
+}

package/bin/lean/pitfalls.test.mjs

@@ -0,0 +1,117 @@
+// 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 { existsSync, readFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { failureLine, normaliseFailure, signatureOf, lessonOf, fixGlobs, pendingPitfall, pitfallRecord, foldPitfalls, selectPitfalls, failureLog,
+  makePitfallStore, pitfallsFile, pitfallsDir, DEFAULT_PITFALL_LANES, LESSON_MAX } from "./pitfalls.mjs";
+
+// Two ecosystems' failure output (#4375: the mechanism is generic, the data is each repo's own).
+const NODE_ESLINT = (file, line) => `> app@1.0.0 lint\n> eslint .\n\n/home/u/wt/${file}\n  ${line}:5  error  'unused' is defined but never used  no-unused-vars\n\n✖ 1 problem (1 error, 0 warnings)`;
+const NODE_TSC = "src/api/client.ts(41,7): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.";
+const NODE_DOCS = "devdocs freshness: bin/lean/lean.mjs changed but devdocs/modules/lean.md did not (stale dossier)";
+const PY_RUFF = (file, line) => `${file}:${line}:1: F401 [*] \`os\` imported but unused\nFound 1 error.\n[*] 1 fixable with the \`--fix\` option.`;
+const PY_PYTEST = "============ FAILURES ============\n____ test_create_user ____\nE       AssertionError: assert 404 == 201\ntests/test_users.py:22: AssertionError\n==== 1 failed, 12 passed in 0.91s ====";
+const PY_MIGRATION = "sequence number collision: migrations/0042_add_index.py already taken by migrations/0042_user_email.py";
+
+describe("#4375 pitfall signatures and lessons", () => {
+  it("picks the first error-like line, skipping banners and ANSI codes", () => {
+    assert.match(failureLine(NODE_ESLINT("src/a.ts", 12)), /error 'unused' is defined but never used no-unused-vars/);
+    assert.match(failureLine(`\x1b[31m${PY_RUFF("app/models.py", 3)}\x1b[0m`), /^app\/models\.py:3:1: F401/);
+    assert.match(failureLine(PY_PYTEST), /AssertionError: assert 404 == 201/);
+    assert.equal(failureLine("only info\nmore info"), "only info", "no error-like line: the first line");
+    assert.equal(failureLine("\n \n"), "");
+  });
+
+  it("the same rule on another file or line gives the same signature; another rule or trigger does not", () => {
+    assert.equal(signatureOf("precheck", NODE_ESLINT("src/a.ts", 12)), signatureOf("precheck", NODE_ESLINT("lib/b/c.ts", 380)));
+    assert.equal(signatureOf("precheck", PY_RUFF("app/models.py", 3)), signatureOf("precheck", PY_RUFF("svc/api/views.py", 17)));
+    assert.notEqual(signatureOf("precheck", PY_RUFF("app/models.py", 3)), signatureOf("precheck", PY_RUFF("app/models.py", 3).replace("F401", "E501")), "rule codes are kept");
+    assert.notEqual(signatureOf("precheck", NODE_TSC), signatureOf("ci_red", NODE_TSC));
+    assert.match(signatureOf("ci_red", NODE_TSC), /^ci_red:[0-9a-f]{12}$/);
+    assert.equal(normaliseFailure("Error at src/x.ts:1:2 in deadbeefcafe after 30 s: \"foo\""), "error at <path> in <hex> after <n> s: <str>");
+    assert.equal(signatureOf("sequence", PY_MIGRATION), signatureOf("sequence", PY_MIGRATION.replaceAll("0042", "0107")));
+  });
+
+  it("the lesson is one line from the failure output, prefixed with the trigger and capped", () => {
+    assert.equal(lessonOf("docs", NODE_DOCS), `docs: ${NODE_DOCS}`);
+    const long = lessonOf("precheck", `error ${"x".repeat(400)}\nsecond line`);
+    assert.ok(long.length <= LESSON_MAX && !long.includes("\n") && long.endsWith("…"), long);
+  });
+
+  it("fix globs: dir/*.ext, root files by name, .forge-lean left out, at most five", () => {
+    assert.deepEqual(fixGlobs(["src/a.ts", "src/b.ts", "package.json", ".forge-lean/result.json", "alembic/versions/0003_x.py", "Makefile", "docs/README"]),
+      ["src/*.ts", "package.json", "alembic/versions/*.py", "Makefile", "docs/*"]);
+    assert.equal(fixGlobs(Array.from({ length: 9 }, (_, i) => `d${i}/f.go`)).length, 5);
+  });
+
+  it("only rework triggers with failure text become pending pitfalls", () => {
+    assert.deepEqual(Object.keys(pendingPitfall("precheck", NODE_TSC)), ["trigger", "sig", "lesson"]);
+    for (const t of ["plan", "build", "block_correction", "ci_unavailable", "recovery", "timeout_restart"]) assert.equal(pendingPitfall(t, NODE_TSC), null, t);
+    assert.equal(pendingPitfall("docs", ""), null);
+    assert.match(failureLog([{ job: "lint", log: PY_RUFF("a.py", 1) }, { code: "review.finding", detail: "src/x.ts:3 misses the null check" }, "plain"]), /F401[\s\S]*review\.finding src\/x\.ts:3[\s\S]*plain/);
+  });
+});
+
+describe("#4375 pitfall ledger: dedup, aging, selection", () => {
+  const lane = (run) => ({ t: "lane", run, ts: `2026-10-${String(10 + (Number(String(run).replace(/\D/g, "")) % 20)).padStart(2, "0")}T00:00:00Z` });
+  const pit = (run, trigger, text, files, ts = "2026-10-20T00:00:00Z") => pitfallRecord({ pending: pendingPitfall(trigger, text), files, run, ts });
+
+  it("deduplicates by signature with a count (one per lane), union of globs, latest lesson", () => {
+    const recs = [lane("r1"), pit("r1", "precheck", NODE_ESLINT("src/a.ts", 1), ["src/a.ts"]), pit("r1", "precheck", NODE_ESLINT("src/a.ts", 9), ["src/a.ts"]),
+      lane("r2"), pit("r2", "precheck", NODE_ESLINT("web/b.tsx", 4), ["web/b.tsx"], "2026-10-21T00:00:00Z"), lane("r3"), pit("r3", "docs", NODE_DOCS, ["devdocs/modules/lean.md"])];
+    const f = foldPitfalls(recs);
+    assert.equal(f.length, 2);
+    assert.deepEqual([f[0].trigger, f[0].count, f[0].globs, f[0].lastTs], ["precheck", 2, ["src/*.ts", "web/*.tsx"], "2026-10-21T00:00:00Z"]);
+    assert.deepEqual([f[1].trigger, f[1].count, f[1].globs], ["docs", 1, ["devdocs/modules/*.md"]]);
+    assert.equal(foldPitfalls([{ t: "pitfall" }, null, "x", { t: "pitfall", sig: "" }]).length, 0, "malformed rows are skipped");
+  });
+
+  it("a pitfall not seen in N lanes (default 50) ages out; a recurring one stays", () => {
+    assert.equal(DEFAULT_PITFALL_LANES, 50);
+    const recs = [lane("r0"), pit("r0", "precheck", PY_RUFF("app/m.py", 3), ["app/m.py"]), pit("r0", "ci_red", PY_PYTEST, ["tests/test_users.py"])];
+    for (let i = 1; i <= 49; i++) recs.push(lane(`r${i}`));
+    assert.equal(foldPitfalls(recs).length, 2, "49 lanes since: kept");
+    recs.push(pit("r49", "ci_red", PY_PYTEST, ["tests/test_users.py"]), lane("r50"));
+    const f = foldPitfalls(recs);
+    assert.deepEqual(f.map((p) => p.trigger), ["ci_red"], "50 lanes without a recurrence: aged out; the recurring one stays");
+    assert.equal(foldPitfalls(recs, { maxAge: 100 }).length, 2, "custom N");
+    assert.equal(foldPitfalls(recs, { maxAge: 1 }).length, 0);
+  });
+
+  it("selects file matches first, then repo-wide, each by count then recency, up to the limit", () => {
+    const recs = [lane("a"), pit("a", "docs", NODE_DOCS, ["devdocs/modules/lean.md"]), lane("b"), pit("b", "docs", NODE_DOCS, ["devdocs/modules/lean.md"]),
+      lane("c"), pit("c", "precheck", PY_RUFF("app/models.py", 3), ["app/models.py"], "2026-10-01T00:00:00Z"),
+      lane("d"), pit("d", "ci_red", PY_PYTEST, ["app/views.py"], "2026-10-05T00:00:00Z"), pit("d", "sequence", PY_MIGRATION, ["migrations/0042_add_index.py"])];
+    const f = foldPitfalls(recs);
+    const s = selectPitfalls(f, { paths: ["app/models.py", "app/serializers.py"] });
+    assert.deepEqual(s.map((p) => [p.trigger, p.match]), [["ci_red", "files"], ["precheck", "files"], ["docs", "repo"], ["sequence", "repo"]]);
+    assert.deepEqual(selectPitfalls(f, { paths: [], limit: 2 }).map((p) => p.trigger), ["docs", "sequence"], "no likely files: repo-wide by count, then recency (sequence 10-20 is newer than ci_red 10-05)");
+    assert.equal(selectPitfalls([], { paths: ["x"] }).length, 0);
+  });
+});
+
+describe("#4375 local file store", () => {
+  it("is per repo under the pitfalls dir, appends one line per record and skips corrupt lines", () => {
+    const dir = tmpDir("pitfalls-");
+    const st = makePitfallStore({ dir });
+    assert.deepEqual(st.read("o/r"), [], "missing file: empty");
+    st.append("o/r", { t: "lane", run: "1" });
+    st.append("o/r", { t: "pitfall", run: "1", sig: "docs:abc", trigger: "docs", globs: [], lesson: "docs: x" });
+    st.append("acme/py-app", { t: "lane", run: "9" });
+    appendFileSync(pitfallsFile("o/r", dir), "{not json\n");
+    assert.equal(pitfallsFile("o/r", dir), join(dir, "o__r.jsonl"));
+    assert.deepEqual(st.read("o/r").map((r) => r.t), ["lane", "pitfall"]);
+    assert.deepEqual(st.read("acme/py-app"), [{ t: "lane", run: "9" }]);
+    assert.ok(existsSync(join(dir, "acme__py-app.jsonl")));
+    assert.equal(readFileSync(pitfallsFile("o/r", dir), "utf8").split("\n").filter(Boolean).length, 3);
+    assert.equal(pitfallsFile("../../etc/x", dir).startsWith(dir), true, "the repo name cannot escape the dir");
+  });
+
+  it("defaults to ~/.forge/pitfalls with a FORGE_PITFALLS_DIR override", () => {
+    assert.match(pitfallsDir({}), /[/\\]\.forge[/\\]pitfalls$/);
+    assert.equal(pitfallsDir({ FORGE_PITFALLS_DIR: "/x/p" }), "/x/p");
+  });
+});

package/bin/lean/postmerge.mjs

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Merge-time semantic checks (#4406). Parallel sibling lanes can each add the same name (an export, a registry key) and
+ * git merges both without a conflict: duplicate object keys, or a name-keyed probe map that tests only one of two
+ * same-named actions. Two deterministic pieces, codebase-agnostic (git + fs, no LLM):
+ *  - postMergeCommands: what base-sync runs on the merged tree before the push (forge.yaml verify.post_merge, else the
+ *    lane's scoped typecheck from checks.mjs; ci mode runs no host typecheck unless one is configured);
+ *  - duplicateExports: names the lane newly exports that another module of the same app or package already declares.
+ */
+import fs from "node:fs";
+import { dirname, join, posix } from "node:path";
+import { exportNames, isTestPath } from "./enumerating.mjs";
+
+const SOURCE_RE = /\.(?:[cm]?[jt]sx?|py)$/;
+const SKIP_RE = /(?:^|\/)(?:node_modules|vendor|dist|build|coverage)\//;
+const MANIFESTS = ["package.json", "pyproject.toml", "setup.py", "go.mod", "Cargo.toml"];
+const MIN_NAME = 3, MAX_NAMES = 50, CONVENTION = 3;
+const lines = (s) => String(s ?? "").split("\n").map((x) => x.trim()).filter(Boolean);
+const out = (git) => async (args) => { try { return String(await git(args)); } catch { return ""; } };
+const shq = (s) => (/^[\w./-]+$/.test(s) ? s : `'${String(s).replace(/'/g, "'\\''")}'`);
+
+/**
+ * The commands base-sync runs on the merged tree: [configured] when verify.post_merge is set, else (local/hybrid) the
+ * non-skip typecheck rows of checks.mjs scopedChecks, prefixed with their package dir; [] in ci mode.
+ */
+export function postMergeCommands({ configured = null, scoped = [], mode = "local" } = {}) {
+  const c = String(configured ?? "").trim();
+  if (c) return [c];
+  if (mode === "ci") return [];
+  return (Array.isArray(scoped) ? scoped : [])
+    .filter((r) => r && r.kind === "typecheck" && r.mode !== "skip" && String(r.command ?? "").trim())
+    .map((r) => (r.cwd && r.cwd !== "." ? `cd ${shq(r.cwd)} && ${r.command}` : String(r.command)));
+}
+
+/** Declared exports only: re-exports (`export {..} from`, `export * from`) and default exports (named or not) are not collisions. */
+export function declaredExports(text, path = "") {
+  const t = /\.py$/.test(path) ? String(text ?? "") : String(text ?? "")
+    .replace(/^\s*export\s+(?:type\s+)?\{[^}]*\}\s*from\s*["'][^"']*["'];?/gm, "")
+    .replace(/^\s*export\s+\*(?:\s+as\s+[\w$]+)?\s+from\s*["'][^"']*["'];?/gm, "")
+    .replace(/^(\s*)export\s+default\s+/gm, "$1");
+  return exportNames(t, path).filter((n) => n !== "default");
+}
+
+/** The nearest ancestor directory of `file` holding a package manifest, else "." (the repo root). */
+function packageRoot(file, manifests) {
+  for (let d = dirname(file); ; d = dirname(d)) {
+    if (manifests.has(d)) return d;
+    if (d === "." || d === "/" || d === "") return ".";
+  }
+}
+
+/**
+ * Exported names the lane added (vs `base`) in its changed non-test source files that other non-test source files of
+ * the same package root already declare at HEAD. A name 3+ other modules declare is a convention (GET, metadata), not a
+ * collision. @returns {Promise<Array<{symbol, path, others:string[]}>>}; never throws ([] on any failure).
+ */
+export async function duplicateExports({ git, cwd, base }) {
+  try {
+    const g = out(git);
+    const keep = (f) => SOURCE_RE.test(f) && !isTestPath(f) && !SKIP_RE.test(f);
+    const changed = lines(await g(["-c", "core.quotepath=off", "diff", "--name-only", "--diff-filter=AM", `${base}...HEAD`])).filter(keep);
+    if (!changed.length) return [];
+    const added = new Set(lines(await g(["-c", "core.quotepath=off", "diff", "--name-only", "--diff-filter=A", `${base}...HEAD`])));
+    const manifests = new Set(lines(await g(["-c", "core.quotepath=off", "ls-files"])).filter((f) => MANIFESTS.includes(posix.basename(f))).map((f) => posix.dirname(f)));
+    const read = (f) => { try { return fs.readFileSync(join(cwd, f), "utf8"); } catch { return ""; } };
+    const res = [];
+    let names = 0;
+    for (const f of changed) {
+      const was = new Set(added.has(f) ? [] : declaredExports(await g(["show", `${base}:${f}`]), f));
+      const fresh = declaredExports(read(f), f).filter((n) => !was.has(n) && n.length >= MIN_NAME);
+      const root = packageRoot(f, manifests);
+      for (const name of fresh) {
+        if (++names > MAX_NAMES) return res;
+        const hits = lines(await g(["-c", "core.quotepath=off", "grep", "-l", "-w", "-e", name, "HEAD", "--", ...(root === "." ? [] : [`${root}/`])]))
+          .map((l) => l.replace(/^HEAD:/, ""))
+          .filter((p) => p !== f && keep(p) && packageRoot(p, manifests) === root);
+        const others = [];
+        for (const p of hits) if (declaredExports(read(p), p).includes(name)) others.push(p);
+        if (others.length && others.length < CONVENTION) res.push({ symbol: name, path: f, others: others.sort() });
+      }
+    }
+    return res;
+  } catch { return []; }
+}

package/bin/lean/postmerge.test.mjs

@@ -0,0 +1,79 @@
+// 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 { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { postMergeCommands, declaredExports, duplicateExports } from "./postmerge.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 (a) => sh(cwd, ...a);
+const put = (root, files) => { for (const [p, t] of Object.entries(files)) { mkdirSync(dirname(join(root, p)), { recursive: true }); writeFileSync(join(root, p), t); } };
+/** A repo with `base` committed on main and `lane` committed on a lane branch. */
+function repo(base, lane) {
+  const d = tmpDir("postmerge-");
+  sh(d, "init", "-q", "-b", "main");
+  put(d, base); sh(d, "add", "-A"); sh(d, "commit", "-qm", "base");
+  sh(d, "checkout", "-q", "-b", "lane");
+  put(d, lane); sh(d, "add", "-A"); sh(d, "commit", "-qm", "lane");
+  return d;
+}
+const dups = (d) => duplicateExports({ git: gitIn(d), cwd: d, base: "main" });
+
+const BASE = {
+  "apps/web/package.json": "{}",
+  "apps/web/inbox/actions.ts": "export async function undoActivityAction() {}\nexport async function reassignCaptureAction() {}\n",
+  "packages/x/package.json": "{}",
+  "packages/x/src/feed.ts": "export function feedOnly() {}\n",
+};
+
+describe("duplicate exports (#4406)", () => {
+  it("a lane export another module of the same app declares is a finding with both paths", async () => {
+    const d = repo(BASE, { "apps/web/feed/actions.ts": "export async function undoActivityAction() {}\nexport async function undoFeedActivityAction() {}\n" });
+    assert.deepEqual(await dups(d), [{ symbol: "undoActivityAction", path: "apps/web/feed/actions.ts", others: ["apps/web/inbox/actions.ts"] }]);
+  });
+
+  it("another package, a barrel re-export, a test file and an export the file already had are not findings", async () => {
+    const d = repo({ ...BASE, "apps/web/feed/old.ts": "export function keepMe() {}\n", "apps/web/feed/twin.ts": "export function keepMe() {}\n" }, {
+      "packages/x/src/actions.ts": "export async function undoActivityAction() {}\n",
+      "apps/web/index.ts": "export { undoActivityAction } from './inbox/actions';\nexport * from './inbox/actions';\n",
+      "apps/web/__tests__/actions.test.ts": "export const undoActivityAction = 1;\n",
+      "apps/web/feed/old.ts": "export function keepMe() {}\nexport const touched = 1;\n",
+    });
+    assert.deepEqual(await dups(d), []);
+  });
+
+  it("a name 3+ other modules declare is a convention, not a collision; default is never one", async () => {
+    const route = "export async function GET() {}\nexport default function Page() {}\n";
+    const d = repo({ ...BASE, "apps/web/a/route.ts": route, "apps/web/b/route.ts": route, "apps/web/c/route.ts": route }, { "apps/web/d/route.ts": route });
+    assert.deepEqual(await dups(d), []);
+  });
+
+  it("Python modules of one package collide too; unreadable git yields []", async () => {
+    const d = repo({ "svc/pyproject.toml": "", "svc/a.py": "def resolve_tenant():\n  pass\n" }, { "svc/b.py": "def resolve_tenant():\n  pass\n" });
+    assert.deepEqual(await dups(d), [{ symbol: "resolve_tenant", path: "svc/b.py", others: ["svc/a.py"] }]);
+    assert.deepEqual(await duplicateExports({ git: async () => { throw new Error("boom"); }, cwd: d, base: "main" }), []);
+  });
+
+  it("declaredExports drops re-exports and default", () => {
+    assert.deepEqual(declaredExports("export { a } from './a';\nexport * as ns from './n';\nexport default function x() {}\nexport const b = 1;\nconst c = 2;\nexport { c };\n", "m.ts").sort(), ["b", "c"]);
+  });
+});
+
+describe("post-merge commands (#4406)", () => {
+  const SCOPED = [
+    { kind: "typecheck", command: "pnpm exec tsc -p .", cwd: "apps/web", mode: "scoped" },
+    { kind: "typecheck", command: "", cwd: "packages/x", mode: "skip" },
+    { kind: "typecheck", command: "pnpm run typecheck", cwd: ".", mode: "full" },
+    { kind: "lint", command: "eslint .", cwd: ".", mode: "scoped" },
+  ];
+  it("verify.post_merge wins; else the non-skip scoped typecheck rows in their package dir; ci mode runs none", () => {
+    assert.deepEqual(postMergeCommands({ configured: " make check ", scoped: SCOPED, mode: "ci" }), ["make check"]);
+    assert.deepEqual(postMergeCommands({ scoped: SCOPED, mode: "local" }), ["cd apps/web && pnpm exec tsc -p .", "pnpm run typecheck"]);
+    assert.deepEqual(postMergeCommands({ scoped: SCOPED, mode: "hybrid" }).length, 2);
+    assert.deepEqual(postMergeCommands({ scoped: SCOPED, mode: "ci" }), []);
+    assert.deepEqual(postMergeCommands({ scoped: null }), []);
+  });
+});

package/bin/lean/precheck.mjs

@@ -1,39 +1,62 @@
 // SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /**
- * Pre-PR declared check commands (#4240), one round (#4331): the commands run concurrently up to the host worker cap
- * (the caller holds one heavy-step slot for the whole round), each timed, inside one total budget. A command that never
+ * Pre-PR declared check commands (#4240), one round (#4331): the commands run concurrently up to the host worker cap,
+ * each timed, inside one total budget. #4344: the worker cap is shared, not multiplied (k running commands get
+ * max(1, floor(N / k)) workers each), and `acquire` takes one heavy-step slot per running command. A command that never
  * started before the budget ran out, or that the budget cut short, is left to CI (`deferred-to-ci`), never a failure.
  * Repo-agnostic: commands are opaque `bash -c` strings run through the injected `run`.
+ * #4364: `planPrecheck` is the one selection and budget rule shared by the engine's pre-PR round and `forgedock check`,
+ * which the builder runs in-session (`selfCheck`); `worktreeFingerprint` tells whether that run saw the final tree.
  */
+import { createHash } from "node:crypto";
+import { scopeChecks, selectCommands } from "./testmap.mjs";
+import { LOG_CAP } from "./verify.mjs";
+
+/** #4364: the engine's check plan for `forgedock check` (written beside contract.json) and the CLI's last run record. */
+export const CHECK_PLAN_FILE = ".forge-lean/check-plan.json";
+export const SELF_CHECK_FILE = ".forge-lean/self-check.json";
+/** #4390: full output of each failing check command (`forgedock check`, the engine's precheck round). */
+export const CHECK_LOG_DIR = ".forge-lean/logs";
 
 /** rc of a command killed by its timeout (effects.mjs runCheckCommand). */
 const TIMEOUT_RC = 124;
 
 /**
  * @param {{commands:string[], parallelism?:number, budgetMs:number, perCommandMs:number, now?:() => number,
- *   run:(a:{command:string, timeoutMs:number}) => Promise<{rc:number, output?:string}>}} p
+ *   acquire?:() => Promise<{release?:Function}|null>,
+ *   run:(a:{command:string, timeoutMs:number, workers:number}) => Promise<{rc:number, output?:string}>}} p
+ *   acquire: awaited per command before its timeout is computed (the wait counts against the budget); a throw runs ungated
  * @returns {Promise<{results:{command:string, rc:number, output:string, ms:number}[], deferred:string[], ms:number}>}
  *   results in input order (commands that ran and were not cut by the budget); deferred in input order
  */
-export async function runChecks({ commands, parallelism = 1, budgetMs, perCommandMs, now = () => Date.now(), run }) {
+export async function runChecks({ commands, parallelism = 1, budgetMs, perCommandMs, now = () => Date.now(), acquire, run }) {
   const list = Array.isArray(commands) ? commands : [];
   const workers = Math.max(1, Math.floor(Number(parallelism)) || 1);
+  const k = Math.max(1, Math.min(workers, list.length)), share = Math.max(1, Math.floor(workers / k));
   const start = now(), deadline = start + (Number(budgetMs) > 0 ? Number(budgetMs) : 0);
   const per = Number(perCommandMs) > 0 ? Number(perCommandMs) : Infinity;
   const slots = new Array(list.length).fill(null);
   let next = 0;
+  /** One command, once its slot (if any) is held: the slot wait counts against the budget. */
+  async function runOne(command) {
+    const left = deadline - now();
+    if (left <= 0) return { deferred: true };
+    const timeoutMs = Math.min(per, left), t = now();
+    let r;
+    try { r = await run({ command, timeoutMs, workers: share }); } catch (e) { r = { rc: 127, output: String(e?.message ?? e) }; }
+    const rc = Number.isInteger(r?.rc) ? r.rc : 1;
+    // the budget, not the command's own timeout, cut it short: CI runs it
+    if (rc === TIMEOUT_RC && timeoutMs < per) return { deferred: true };
+    return { command, rc, output: String(r?.output ?? ""), ms: Math.max(0, now() - t) };
+  }
   async function worker() {
     while (next < list.length) {
-      const i = next++, command = list[i], left = deadline - now();
-      if (left <= 0) { slots[i] = { deferred: true }; continue; }
-      const timeoutMs = Math.min(per, left), t = now();
-      let r;
-      try { r = await run({ command, timeoutMs }); } catch (e) { r = { rc: 127, output: String(e?.message ?? e) }; }
-      const rc = Number.isInteger(r?.rc) ? r.rc : 1;
-      // the budget, not the command's own timeout, cut it short: CI runs it
-      if (rc === TIMEOUT_RC && timeoutMs < per) { slots[i] = { deferred: true }; continue; }
-      slots[i] = { command, rc, output: String(r?.output ?? ""), ms: Math.max(0, now() - t) };
+      const i = next++, command = list[i];
+      if (deadline - now() <= 0) { slots[i] = { deferred: true }; continue; }
+      let g = null;
+      try { g = acquire ? await acquire() : null; } catch { g = null; }
+      try { slots[i] = await runOne(command); } finally { try { g?.release?.(); } catch { /* fail-open */ } }
     }
   }
   await Promise.all(Array.from({ length: Math.min(workers, list.length) }, worker));
@@ -53,3 +76,105 @@ export function formatPrecheckSummary(rows) {
   const deferred = ran.reduce((a, r) => a + (Number.isInteger(r.precheck_deferred) ? r.precheck_deferred : 0), 0);
   return `precheck: ${(ms / 60000).toFixed(1)}m total over ${ran.length} lane${ran.length === 1 ? "" : "s"}${deferred ? `, ${deferred} deferred to CI` : ""}`;
 }
+
+/**
+ * #4364: the pre-PR commands and budget for a round: `scopeChecks` over the trimmed learned commands (a mapped learned
+ * command runs only when its globs match a changed file); budget lean.precheck.max_minutes, else
+ * verify.precheck_total_seconds (default 600 s); per command verify.precheck_timeout_seconds.
+ * @returns {{commands:string[], source:string, added:number, dropped:string[], selected:number, budgetMs:number, perCommandMs:number}}
+ */
+export function planPrecheck({ testMap = null, files = [], learned = [], maxMinutes, verify = {} }) {
+  const list = (Array.isArray(learned) ? learned : []).map((c) => String(c ?? "").trim()).filter(Boolean);
+  const m = scopeChecks(testMap, files, list);
+  const max = Number(maxMinutes);
+  const budgetMs = (max > 0 ? max * 60 : Number(verify.precheckTotalSeconds) || 600) * 1000;
+  return { ...m, selected: testMap ? selectCommands(testMap, files).length : 0, budgetMs, perCommandMs: (Number(verify.precheckTimeoutSeconds) || 300) * 1000 };
+}
+
+const lines = (out) => String(out ?? "").split("\n").map((x) => x.trim()).filter(Boolean);
+
+/**
+ * #4364: content fingerprint of the worktree against merge-base(base, HEAD): sha256 over the sorted (path, blob sha or
+ * "deleted") pairs of every tracked path that differs (committed, staged or not) plus untracked non-ignored files,
+ * `.forge-lean/` excluded. Committing after a check leaves it unchanged; any edit changes it.
+ * @param {{git:(args:string[]) => Promise<string>, base:string}} p
+ */
+export async function worktreeFingerprint({ git, base }) {
+  const mb = String(await git(["merge-base", base, "HEAD"])).trim();
+  const keep = (f) => !f.startsWith(".forge-lean/");
+  const deleted = new Set(lines(await git(["diff", "--name-only", "--diff-filter=D", mb])).filter(keep));
+  const paths = [...new Set([...lines(await git(["diff", "--name-only", mb])), ...lines(await git(["ls-files", "-o", "--exclude-standard"]))])].filter(keep).sort();
+  const live = paths.filter((f) => !deleted.has(f)), blobs = new Map();
+  for (let i = 0; i < live.length; i += 200) {
+    const part = live.slice(i, i + 200), shas = lines(await git(["hash-object", "--", ...part]));
+    part.forEach((f, j) => blobs.set(f, shas[j] ?? ""));
+  }
+  return createHash("sha256").update(paths.map((f) => `${f}\0${blobs.get(f) ?? "deleted"}`).join("\n")).digest("hex");
+}
+
+/** #4364: 'skipped' (no record), 'stale' (another tree), 'red' (this tree, failing) or 'green' (this tree, passing). */
+export function selfCheckState(record, fingerprint) {
+  if (!record || typeof record !== "object" || !record.fingerprint) return "skipped";
+  if (record.fingerprint !== fingerprint) return "stale";
+  return record.ok === true ? "green" : "red";
+}
+
+/**
+ * #4364 `forgedock check`: the contract's validate commands (reported `ci`, not run, in verify.mode ci, as the engine
+ * accepts them on a CI-verified head), then the planned pre-PR commands under the plan's budget, both through
+ * `runChecks` with the same worker cap. No heavy slot is taken here: the heavy shims on the builder's PATH gate the
+ * heavy binaries. ok = every command that ran exited 0 (deferred and `ci` are not failures, as in the engine).
+ * @param {{contract:object, plan:{mode?:string, commands:string[], budgetMs:number, perCommandMs:number}, parallelism?:number, now?:() => number, run:Function}} p
+ */
+export async function selfCheck({ contract, plan, parallelism = 1, now = () => Date.now(), run }) {
+  const vals = (Array.isArray(contract?.validate) ? contract.validate : []).filter((v) => v && String(v.command ?? "").trim());
+  const ci = plan?.mode === "ci", per = Number(plan?.perCommandMs) > 0 ? Number(plan.perCommandMs) : 300000;
+  const validate = [];
+  if (ci) for (const v of vals) validate.push({ id: v.id, command: String(v.command), status: "ci" });
+  else if (vals.length) {
+    const cmds = vals.map((v) => String(v.command));
+    // as the engine's validate rerun: each command its own timeout, no round budget
+    const r = await runChecks({ commands: cmds, parallelism, budgetMs: Infinity, perCommandMs: per, now, run });
+    const byCmd = new Map(r.results.map((x) => [x.command, x]));
+    for (const v of vals) { const x = byCmd.get(String(v.command)); validate.push(x ? { id: v.id, ...x } : { id: v.id, command: String(v.command), status: "deferred-to-ci" }); }
+  }
+  const pre = await runChecks({ commands: plan?.commands ?? [], parallelism, budgetMs: plan?.budgetMs ?? 0, perCommandMs: per, now, run });
+  const commands = [...pre.results];
+  const ok = [...validate, ...commands].every((x) => x.status || x.rc === 0);
+  return { ok, validate, commands, deferred: pre.deferred };
+}
+
+/** #4390: summary lines naming a failing test, as common runners print them (pytest, TAP/node --test, jest/vitest, go, cargo). */
+const FAIL_ID_RE = /^\s*(?:FAILED |ERROR |not ok \d|FAIL |[✕×✗] |--- FAIL: |test \S.* \.\.\. FAILED)/;
+export const QUIET_TAIL_LINES = 40;
+
+/**
+ * #4390 quiet-output contract: one failure as its last `lines` lines (at most `maxChars`, cut marked with `…`), the
+ * failing-test-id lines found anywhere in the output (deduped, at most `maxIds`) and, when given, the full log's path.
+ */
+export function quietFailure(output, { lines = QUIET_TAIL_LINES, maxChars = Infinity, logPath = null, maxIds = 30 } = {}) {
+  const all = String(output ?? "").split("\n");
+  while (all.length && !all[all.length - 1].trim()) all.pop();
+  const from = Math.max(0, all.length - lines);
+  let tail = all.slice(from).join("\n");
+  const cut = from > 0 || tail.length > maxChars;
+  if (tail.length > maxChars) tail = tail.slice(-maxChars);
+  const ids = [...new Set(all.filter((l) => FAIL_ID_RE.test(l)).map((l) => l.trim().slice(0, 300)))];
+  const out = [tail ? `${cut ? "…" : ""}${tail}` : "(no output)"];
+  if (ids.length) out.push(`failing tests:\n${ids.slice(0, maxIds).map((l) => `  ${l}`).join("\n")}${ids.length > maxIds ? `\n  … and ${ids.length - maxIds} more` : ""}`);
+  if (logPath) out.push(`full log: ${logPath}`);
+  return out.join("\n");
+}
+
+/** #4364: the compact pass/fail table `forgedock check` prints; #4390: each failure quiet (`quietFailure`), within `cap` chars. */
+export function formatCheckTable(r, cap = LOG_CAP) {
+  const word = (x) => (x.status === "ci" ? "CI" : x.status ? "DEFERRED" : x.rc === 0 ? "PASS" : `FAIL exit ${x.rc}`);
+  const rows = [...(r.validate ?? []).map((x) => ({ ...x, label: `${x.id} ${x.command}` })), ...(r.commands ?? []).map((x) => ({ ...x, label: x.command })),
+    ...(r.deferred ?? []).map((c) => ({ command: c, label: c, status: "deferred-to-ci" }))];
+  const out = rows.map((x) => `${word(x).padEnd(12)} ${Number.isFinite(x.ms) ? `${(x.ms / 1000).toFixed(1)}s`.padStart(7) : "".padStart(7)}  ${x.label}`);
+  const failed = rows.filter((x) => !x.status && x.rc !== 0);
+  const per = Math.max(500, Math.floor(cap / Math.max(1, failed.length))); // verify.mjs capLogs share
+  for (const f of failed) out.push("", `--- ${f.label} (exit ${f.rc})`, quietFailure(f.output, { maxChars: per, logPath: f.logPath ?? null }));
+  out.push("", r.ok ? "check: PASS" : `check: FAIL (${failed.length} failing)`);
+  return out.join("\n");
+}