forgedock 1.29.1 → 1.30.0

package/bin/lean/preflight.test.mjs

@@ -0,0 +1,61 @@
+// 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 { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { shellSegments, pythonImports, nodeImports, preflightProbes, preflightProblems } from "./preflight.mjs";
+import { runCheckCommand } from "./effects.mjs";
+import { repoTracks } from "./conformance.mjs";
+import { tmpDir } from "../tests/_tmp.mjs";
+
+const C = (...commands) => ({ deliverables: [], validate: commands.map((command, i) => ({ id: `V${i + 1}`, command })) });
+const needs = (c, o) => preflightProbes(c, o).probes.map((p) => [p.kind, p.tool, p.interp ?? null, p.ids.join(",")]);
+
+describe("#4328 validate preflight: what a command needs", () => {
+  it("splits on && || | ; and newlines, keeps quotes and $(...) whole", () => {
+    assert.deepEqual(shellSegments(`cd a && python3 -c "import yaml; print('x | y')" | tee "$TMPDIR/o" ; git diff $(git merge-base HEAD origin/x) -- a || true`),
+      [["cd", "a"], ["python3", "-c", "import yaml; print('x | y')"], ["tee", "$TMPDIR/o"], ["git", "diff", "$(git merge-base HEAD origin/x)", "--", "a"], ["true"]]);
+  });
+  it("python -c imports and -m modules (top-level, absolute only); node -e bare packages", () => {
+    assert.deepEqual(pythonImports("import yaml, os.path as p\nfrom jsonschema.validators import x; from . import y; from __future__ import annotations; __import__('toml')"), ["yaml", "os", "jsonschema", "toml"]);
+    assert.deepEqual(nodeImports(`const z=require("zod"); import("@scope/pkg/sub"); import fs from "node:fs"; require("./x"); require("path")`), ["zod", "@scope/pkg"]);
+  });
+  it("probes each bare executable, a bare python's modules and node -e packages, deduped across validate ids", () => {
+    assert.deepEqual(needs(C(`FOO=1 python3 -c "import yaml,json"`, "python3 -m pytest -q tests/x.py && jq . a.json", `node -e "require('zod')"`, "python3 -c 'import yaml'")), [
+      ["command", "python3", null, "V1,V2,V4"], ["python-module", "yaml", "python3", "V1,V4"], ["python-module", "json", "python3", "V1"],
+      ["python-module", "pytest", "python3", "V2"], ["command", "jq", null, "V2"], ["command", "node", null, "V3"], ["node-module", "zod", "node", "V3"]]);
+  });
+  it("wrappers and paths: only the wrapper is probed; ./script and .venv/bin/python and $VAR never are", () => {
+    assert.deepEqual(needs(C(`uv run python -c "import yaml"`, "./scripts/check.sh", `.venv/bin/python -c "import yaml"`, "$PY -m x", "npx vitest run a.test.ts")),
+      [["command", "uv", null, "V1"], ["command", "npx", null, "V5"]]);
+  });
+  it("skips names the repo tracks and names a deliverable's change adds", () => {
+    const c = { ...C(`python3 -c "import app, yaml"`, `node -e "require('left-pad')"`), deliverables: [{ id: "D1", path: "package.json", change: "add devDependency left-pad for the check" }] };
+    assert.deepEqual(needs(c, { repoHas: repoTracks(["app/__init__.py"]) }).map((x) => x[1]), ["python3", "yaml", "node"]);
+  });
+  it("caps the probes and reports the dropped count", () => {
+    const r = preflightProbes(C(Array.from({ length: 25 }, (_, i) => `tool${i}`).join(" && ")), { cap: 20 });
+    assert.equal(r.probes.length, 20); assert.equal(r.dropped, 5);
+  });
+  it("a problem line names the ids, the kind and the tool and forbids a global install", () => {
+    const [p] = preflightProblems([{ ids: ["V5"], tool: "yaml", kind: "python-module", interp: "python3" }]);
+    assert.match(p, /^V5: needs Python module 'yaml' \(for python3\), which this host lacks/);
+    assert.match(p, /repo's own toolchain .*never a global install/);
+  });
+  it("the probes are real read-only shell checks: present tools pass, absent ones fail", async () => {
+    const dir = tmpDir("preflight-");
+    mkdirSync(join(dir, "node_modules", "here"), { recursive: true }); writeFileSync(join(dir, "node_modules", "here", "package.json"), "{}");
+    mkdirSync(join(dir, "sub"));
+    const probes = preflightProbes(C("bash -c true", "no-such-tool-4328 --x", `node -e "require('here'); require('fs'); require('absent-pkg-4328')"`)).probes;
+    const rc = {};
+    for (const p of probes) rc[`${p.kind}:${p.tool}`] = (await runCheckCommand({ command: p.probe, cwd: join(dir, "sub"), timeoutMs: 15000 })).rc;
+    assert.equal(rc["command:bash"], 0); assert.notEqual(rc["command:no-such-tool-4328"], 0);
+    assert.equal(rc["command:node"], 0); assert.equal(rc["node-module:here"], 0, "found in an ancestor node_modules");
+    assert.notEqual(rc["node-module:absent-pkg-4328"], 0);
+    const py = preflightProbes(C(`python3 -c "import json, no_such_mod_4328"`)).probes.filter((p) => p.kind === "python-module");
+    if ((await runCheckCommand({ command: "command -v python3", cwd: dir })).rc === 0) {
+      assert.deepEqual(await Promise.all(py.map(async (p) => (await runCheckCommand({ command: p.probe, cwd: dir })).rc !== 0)), [false, true]);
+    }
+  });
+});

package/bin/lean/prompts.mjs

@@ -85,6 +85,7 @@ If the issue is already fixed or invalid, write ${RESULT_FILE} {"status":"alread
  "validate":[{"id":"V1","command":"<exact command: the new regression test plus the existing tests that reference the files you change; a git diff compares against the merge base (origin/<lane>...HEAD), never the moving origin/<lane> tip>"}],
  "decisions":[{"id":"K1","choice":"<a non-obvious choice: a new dependency, a copied pattern, a boundary relied on>","justification":"<why, with file:line>","source":"doc|lint|precedent|spec"}]}
 Every requirement and acceptance criterion in the issue and its maintainers' comments is one requirement, quoted verbatim (others' comments are context, not requirements). Never drop or narrow one silently: "defer" (separate work) and "post-deploy" (only checkable after a deploy) are judged by the reviewer and, if accepted, filed by the engine as a tracked follow-up issue. A requirement you can do in this change is "deliver". List every file you will change as a deliverable; tests are always allowed.
+A validate or repro command must not read a $TMPDIR file it does not create itself: each run gets a fresh TMPDIR.
 A new dependency between workspace packages (a workspace package added to a package.json dependencies, devDependencies or peerDependencies) must be a deliverable on that package.json whose change names the package and gives the reason, citing the architecture doc where there is one; "the lint allows it" or "there is a precedent" is not a reason on its own. Record each non-obvious choice in "decisions" with where its justification comes from (doc, lint, precedent or spec); omit the field when there is none. Then stop.
 
 ${BLOCK_RULES}`;
@@ -93,7 +94,7 @@ ${BLOCK_RULES}`;
 /** Builder call 2, same session: implement the frozen contract. */
 export function builderImplementPrompt(mode = "local", { toolchain = null, sparse = null, facts = null } = {}) {
   const remote = mode === "ci" || mode === "hybrid";
-  return `The engine froze ${CONTRACT_FILE}; it is now the authority. Implement it exactly: change only deliverable paths (tests are always allowed), keep every preserve item intact, add a regression test, ${remote ? VERIFY_RUN[mode] : "run every validate command"}, and commit. Do not push or touch GitHub.
+  return `The engine froze ${CONTRACT_FILE}; it is now the authority. Implement it exactly: change only deliverable paths (tests are always allowed), keep every preserve item intact, add a regression test, ${remote ? VERIFY_RUN[mode] : "run every validate command"}, run the repo's formatter on the files you changed, and commit. Do not push or touch GitHub.
 
 ${HOST_RULES}${toolchainRule(toolchain)}${sparseRule(sparse)}${factsRule(facts)}${remote ? `\n\n${VERIFY_RULES[mode]}` : ""}
 
@@ -147,6 +148,39 @@ export function hotspotBuildRule(facts) {
   return `\n\nDon't grow a file over ${facts.file_lines} lines by more than ${facts.growth_lines} lines. Put new code next to it.`;
 }
 
+/** #4322: tests that enumerate the siblings of a module the issue names (bin/lean/enumerating.mjs), for the plan; "" when none. */
+export function enumeratingPlanNote(list) {
+  if (!Array.isArray(list) || !list.length) return "";
+  return `\n\nEnumerating tests (found by the engine): these tests list every member of a module or directory this issue names, so a new export, table, job, action, namespace or file there must join their list or CI goes red. List each one you will touch under Affected Files in ${INVESTIGATION_FILE}, and add a validate command that runs only those tests.\n${list.slice(0, 40).map((e) => `- ${e.module} -> ${e.test}:${e.line} (${e.why})`).join("\n")}`;
+}
+
+const NOT_MEMBER = `or, when the symbol is not a member of that list, record {"symbol":"<name>","test":"<test path>","why":"<why it is not a member>"} in ${RESULT_FILE} "not_members"`;
+
+/** #4322: the builder rule citing the plan's enumerating tests; "" when none. */
+export function enumeratingBuildRule(list) {
+  if (!Array.isArray(list) || !list.length) return "";
+  return `\n\nEnumerating tests: add every new exported symbol, table, job, action, namespace or file to each test listed below whose list enumerates its siblings, one test-list edit per new symbol, ${NOT_MEMBER}.\n${list.slice(0, 40).map((e) => `- ${e.module} -> ${e.test}:${e.line}`).join("\n")}`;
+}
+
+/** #4322: after implement, new symbols that tests enumerating their siblings do not name. */
+export function missingEntriesPrompt(missing, mode = "local") {
+  return `These tests enumerate the siblings of symbols or files this change adds, but do not name them (CI will fail on the stale list):\n${missing.slice(0, 30).map((m) => `- ${m.symbol} (${m.module}) -> ${m.test}:${m.line}`).join("\n")}\n\nFor each, add the symbol to that test's list, ${NOT_MEMBER}. ${rerun(mode)}, commit, and update ${IMPLEMENTATION_FILE} and ${RESULT_FILE}. Do not push or touch GitHub.`;
+}
+
+const RENUMBER_RULE = "Renumber the lane's files, never the base's: rename each with git mv to its new number, keep the SQL (or other migration source) byte-identical, regenerate the snapshot and journal with the repo's own migration generator (never hand- or text-merge the journal), keep journal entries strictly ordered, and update every reference to the old name.";
+
+/** #4322: lane-added sequence-numbered files whose number the base already uses, at hand-off or after a base-sync. */
+export function sequencePrompt(collisions, lane, mode = "local") {
+  const rows = collisions.slice(0, 30).map((c) => `- ${c.lane} -> number ${c.next}${c.base.length ? ` (base has ${c.base.join(", ")})` : " (moves to keep the order)"}`).join("\n");
+  return `origin/${lane} already uses sequence numbers this change adds:\n${rows}\n\nFirst bring the branch up to date with \`git merge --no-edit origin/${lane}\` if it is not (already fetched; never rebase or force). ${RENUMBER_RULE} ${rerun(mode)}, commit, and update ${IMPLEMENTATION_FILE} and ${RESULT_FILE}. Do not push or touch GitHub.`;
+}
+
+/** #4322: the base-sync conflict addition when a conflicted file is a numbered migration or a journal; "" otherwise. */
+export function sequenceSyncNote(files) {
+  const hit = (files ?? []).some((f) => /(?:^|\/)\d{3,}[_-][^/]*$|(?:^|\/)_journal\.json$/.test(String(f)));
+  return hit ? ` A numbered migration or its journal conflicts: do not text-merge it. ${RENUMBER_RULE}` : "";
+}
+
 export function contractCorrectionPrompt(problems) {
   return `Your ${CONTRACT_FILE} is not valid:\n${problems.slice(0, 20).map((p) => `- ${p}`).join("\n")}\n\nFix the contract (planning only, no code, no commit) and stop. Do not push or touch GitHub.`;
 }
@@ -207,7 +241,7 @@ export const REVIEWER_SYSTEM = `You are an independent conformance reviewer of o
 
 You receive the GitHub issue with its comments, the frozen contract (requirements quoted from the issue, deliverables, preserve constraints, validate commands) with typed amendments, the builder's result with validation output, the changed files, the diff, and a row skeleton with one row per contract id and changed file. The engine computes the verdict from your rows; a reply without rows is rejected, so fill the skeleton rather than composing rows: fill EVERY row (set each empty status, evidence and validated_by, and each null deferral_ok; keep the ids and files as given):
 - issue_coverage: one row per requirement or acceptance criterion in the issue, quoted verbatim, saying whether the contract covers it, narrows it, or misses it. The skeleton lists the contract's quotes; add a row for any issue requirement the contract does not quote.
-- requirements: one row per contract requirement id: implemented|partial|missing|deferred|post-deploy|not-applicable, with repo-relative path:line evidence (e.g. src/app/route.ts:12, not route.ts:12) and the validate id or test that proves it (validated_by). For a defer or post-deploy requirement add deferral_ok: true only if it is genuinely separate work or only checkable after a deploy, false if it belongs in this change.
+- requirements: one row per contract requirement id: implemented|partial|missing|deferred|post-deploy|not-applicable, with evidence as a backtick-quoted repo-relative path:line copied verbatim from the changed files, including (group), [slug] and [...slug] folders (e.g. \`apps/web/app/(console)/layout.tsx:12\`, not route.ts:12) and the validate id or test that proves it (validated_by). For a defer or post-deploy requirement add deferral_ok: true only if it is genuinely separate work or only checkable after a deploy, false if it belongs in this change.
 - scope: one row per changed file, pre-filled with the engine's authorization: the deliverable id that authorizes it (deliverables may be directories or globs), "test", "incidental" (changelog, lockfile), or "none" with what it changes. Change it only if the diff shows the file does something its deliverable does not cover.
 - preserve: one row per preserve id: intact|violated|unverified, with path:line. The skeleton starts each at "unverified"; set intact only after checking it.
 - regressions: concrete breakages only, each with path:line.
@@ -257,7 +291,7 @@ export function reviewerPrompt({ issue, comments = [], contract, result, files =
  * for, with the exact problems and the reviewer's previous reply; no diff is re-sent (the worktree still holds the change).
  */
 export function reviewerRepairPrompt({ missing = [], problems = [], rows = null }) {
-  return `Your conformance review is incomplete. The engine keeps your other rows; answer ONLY for these ids or sections: ${missing.join(", ") || "(see the problems)"}.\n\n<previous_reply_problems>\nYour previous reply was rejected as incomplete. Fix exactly these:\n${problems.slice(0, 60).map((p) => `- ${String(p).slice(0, 300)}`).join("\n")}\n</previous_reply_problems>\n\n<previous_reply>\n${cap(JSON.stringify(rows ?? {}), 20000)}\n</previous_reply>\n\nRead the changed files in your worktree as needed. Output ONLY a JSON object in a json code fence with just the rows for those ids (requirements rows by id, preserve rows by id, scope rows by file, issue_coverage in full if it is listed) plus "verdict":"CONFORMS|NONCONFORMING" consistent with all rows. Evidence is repo-relative path:line.`;
+  return `Your conformance review is incomplete. The engine keeps your other rows; answer ONLY for these ids or sections: ${missing.join(", ") || "(see the problems)"}.\n\n<previous_reply_problems>\nYour previous reply was rejected as incomplete. Fix exactly these:\n${problems.slice(0, 60).map((p) => `- ${String(p).slice(0, 300)}`).join("\n")}\n</previous_reply_problems>\n\n<previous_reply>\n${cap(JSON.stringify(rows ?? {}), 20000)}\n</previous_reply>\n\nRead the changed files in your worktree as needed. Output ONLY a JSON object in a json code fence with just the rows for those ids (requirements rows by id, preserve rows by id, scope rows by file, issue_coverage in full if it is listed) plus "verdict":"CONFORMS|NONCONFORMING" consistent with all rows. Evidence is a backtick-quoted repo-relative path:line copied verbatim (e.g. \`apps/web/app/(console)/layout.tsx:12\`); for an evidence path reported as not existing, give the full repo-relative path of that file from the changed files or the repository.`;
 }
 
 /** Pre-filter (#4123): one read-only, single-turn check of an issue a cheap signal flagged as possibly already fixed. */

package/bin/lean/recovery.test.mjs

@@ -417,3 +417,78 @@ describe("#4316 one shared recovery evidence text", () => {
     }
   });
 });
+
+describe("#4318: the batch-exit relabel survives a throw and a signal; relabel results; full non-final reason", () => {
+  const LONG = `ci.red: line one ${"x".repeat(400)}\nsecond line END-OF-REASON`;
+  const NH = (code, detail) => ({ terminalReason: "needs-human", code, detail });
+  // issue 1 ends ci.red; attempt 1/2 is queued, and `onRecovering` runs when the runner reports it
+  const queued = (opts) => {
+    const relabels = [], ran = [];
+    const p = orchestrate({ issues: [1], parallel: 1, recovery: { maxAttempts: 2 }, readBody: async () => "",
+      relabelNeedsHuman: opts.relabel ?? (async (x) => { relabels.push(x); }),
+      runOne: async (n, _l, ctx = {}) => { ran.push(ctx.recover ?? null); await new Promise((r) => setImmediate(r)); return NH("ci.red", LONG); },
+      ...opts.extra(relabels) });
+    return { p, relabels, ran };
+  };
+
+  it("an exception out of the loop relabels the queued recovery once, then propagates", async () => {
+    let boom = false;
+    const { p, relabels, ran } = queued({ extra: () => ({
+      now: () => { if (boom) throw new Error("clock broke"); return 1000; },
+      onUpdate: (r) => { if (r.outcome === "recovering") boom = true; } }) });
+    await assert.rejects(p, /clock broke/);
+    assert.deepEqual(ran, [null], "attempt 1 never launched");
+    assert.equal(relabels.length, 1); assert.equal(relabels[0].issue, 1);
+    assert.ok(relabels[0].evidence.includes(LONG), "full persisted reason");
+    assert.match(relabels[0].evidence, /the batch stopped \(batch failed: clock broke\)/);
+  });
+
+  it("onExit hands the caller the relabel: a signal relabels with its cause, once; the normal exit does not repeat it", async () => {
+    let exitFn = null;
+    const { p, relabels } = queued({ extra: () => ({
+      onExit: (fn) => { exitFn = fn; },
+      onUpdate: async (r) => { if (r.outcome === "recovering" && exitFn) { const f = exitFn; exitFn = null; await f("interrupted by SIGINT"); await f("again"); } } }) });
+    await p;
+    assert.equal(relabels.length, 1, "idempotent");
+    assert.match(relabels[0].evidence, /the batch stopped \(interrupted by SIGINT\)/);
+  });
+
+  it("a non-final attempt's relabel carries the full multi-line reason, not 300 chars", async () => {
+    const relabels = [];
+    await orchestrate({ issues: [1], parallel: 1, recovery: { maxAttempts: 2 }, readBody: async () => "", relabelNeedsHuman: async (x) => { relabels.push(x); },
+      runOne: async (_n, _l, ctx = {}) => (ctx.recover ? NH("builder.blocked", LONG) : NH("ci.red", "red")) });
+    assert.equal(relabels.length, 1);
+    assert.ok(relabels[0].evidence.includes(LONG));
+    assert.ok(relabels[0].evidence.includes("END-OF-REASON"));
+  });
+
+  describe("relabel results on the batch-exit path", () => {
+    const lost = (relabel) => {
+      let state = { v: 1, order: [1], deps: { 1: [] }, pending: [], results: {}, running: { 1: { startedAt: 1, pid: 999 } }, recoveries: { 1: 2 },
+        recovering: { 1: { code: "ci.red", attempt: 2, detail: LONG, outcome: "needs-human", result_code: "ci.red", prev_attempt: 1 } },
+        breaker: { at: 1, detail: "circuit breaker: tripped" } };
+      const store = { load: () => state, save: (s) => { state = s; }, log: () => {} };
+      const calls = [];
+      const go = () => orchestrate({ issues: [1], store, recovery: { maxAttempts: 2 }, readBody: async () => "", adopt: async () => null,
+        relabelNeedsHuman: async (x) => { calls.push(x); return relabel(); }, runOne: async () => ({ terminalReason: "merged" }) });
+      return { go, calls, state: () => state };
+    };
+    it("a failed label add (false / \"failed\" / a throw) is not recorded: the next resume retries it", async () => {
+      for (const relabel of [() => false, () => "failed", () => { throw new Error("gh down"); }]) {
+        const b = lost(relabel);
+        await b.go();
+        assert.equal(b.state().relabelled, undefined);
+        await b.go();
+        assert.equal(b.calls.length, 2, "retried on resume");
+      }
+    });
+    it("\"skipped\" (closed or leased issue) and true are recorded: no retry", async () => {
+      for (const relabel of [() => "skipped", () => true]) {
+        const b = lost(relabel);
+        await b.go(); await b.go();
+        assert.deepEqual(b.state().relabelled, [1]);
+        assert.equal(b.calls.length, 1);
+      }
+    });
+  });
+});

package/bin/lean/sequence.mjs

@@ -0,0 +1,102 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Sequence-numbered artifacts at hand-off (#4322): migrations named `<number>_<name>` (0007_usage.sql, 0007_x.py,
+ * meta/0007_snapshot.json) that the lane added with a number the base already uses. Union merge (#3969) cannot help: a
+ * duplicate number is a semantic collision and a drizzle-style journal is structured JSON. The engine only detects and
+ * verifies; the builder renumbers with the repo's own migration generator. Deterministic (git only), never throws.
+ */
+import { basename, dirname, posix } from "node:path";
+
+const NUM_RE = /^(\d{3,})[_-]/;
+const SKIP_RE = /(?:^|\/)(?:node_modules|vendor|dist|build)\//;
+const lines = (s) => String(s ?? "").split("\n").map((x) => x.trim()).filter(Boolean);
+const numOf = (p) => NUM_RE.exec(basename(p))?.[1] ?? null;
+const inDir = (dir) => (dir === "." ? [] : [`${dir}/`]);
+const out = (git) => async (args) => { try { return String(await git(args)); } catch { return ""; } };
+
+/** Lane-added numbered files (base...HEAD), with their blob ids. */
+async function laneNumbered(git, base) {
+  const g = out(git);
+  const added = lines(await g(["-c", "core.quotepath=off", "diff", "--name-only", "--diff-filter=A", `${base}...HEAD`])).filter((f) => numOf(f) && !SKIP_RE.test(f));
+  const res = [];
+  for (const path of added) res.push({ path, blob: (await g(["rev-parse", `HEAD:${path}`])).trim() });
+  return res;
+}
+
+/**
+ * Collisions: in each directory where a lane-added numbered file shares its number with a different base file (another
+ * name, or the same path with other content), every lane-added numbered file there must move, in order, above the base's
+ * highest number. @returns {Promise<Array<{dir, number, lane, base:string[], next}>>} (base [] = moves only to keep order)
+ */
+export async function sequenceCollisions({ git, base }) {
+  try {
+    const g = out(git);
+    const lane = await laneNumbered(git, base);
+    const res = [];
+    for (const dir of [...new Set(lane.map((f) => dirname(f.path)))]) {
+      const mine = lane.filter((f) => dirname(f.path) === dir).sort((a, b) => Number(numOf(a.path)) - Number(numOf(b.path)) || a.path.localeCompare(b.path));
+      const theirs = [];
+      for (const l of lines(await g(["-c", "core.quotepath=off", "ls-tree", base, ...inDir(dir)]))) {
+        const m = /^\d+\s+blob\s+(\S+)\t(.+)$/.exec(l);
+        if (m && dirname(m[2]) === dir && numOf(m[2])) theirs.push({ path: m[2], blob: m[1] });
+      }
+      const clash = (f) => theirs.filter((t) => numOf(t.path) === numOf(f.path) && (t.path !== f.path || t.blob !== f.blob)).map((t) => t.path);
+      if (!mine.some((f) => clash(f).length)) continue;
+      const width = Math.max(...mine.map((f) => numOf(f.path).length));
+      let next = Math.max(0, ...theirs.map((t) => Number(numOf(t.path))));
+      for (const f of mine) res.push({ dir, number: numOf(f.path), lane: f.path, base: clash(f), next: String(++next).padStart(width, "0") });
+    }
+    return res;
+  } catch { return []; }
+}
+
+/**
+ * Drizzle-style journal checks for `dirs` at `ref` (`<dir>/meta/_journal.json`, {entries:[{idx, tag}]}): duplicate idx
+ * or tag, idx or tag number not strictly increasing, a numbered .sql file without a tag. No journal: [].
+ */
+export async function journalProblems({ git, ref = "HEAD", dirs = [] }) {
+  const g = out(git), problems = [];
+  for (const dir of [...new Set(dirs)]) {
+    const jp = posix.join(dir, "meta", "_journal.json");
+    const text = await g(["show", `${ref}:${jp}`]);
+    if (!text.trim()) continue;
+    let entries;
+    try { entries = JSON.parse(text).entries; } catch { problems.push(`${jp}: not valid JSON`); continue; }
+    if (!Array.isArray(entries)) { problems.push(`${jp}: no entries array`); continue; }
+    const tags = new Set();
+    for (let i = 0; i < entries.length; i++) {
+      const e = entries[i] ?? {}, prev = entries[i - 1];
+      if (tags.has(e.tag)) problems.push(`${jp}: duplicate tag ${e.tag}`);
+      tags.add(e.tag);
+      if (prev && !(Number(e.idx) > Number(prev.idx))) problems.push(`${jp}: idx ${e.idx} (${e.tag}) not after ${prev.idx} (${prev.tag})`);
+      const n = numOf(String(e.tag ?? "")), pn = prev ? numOf(String(prev.tag ?? "")) : null;
+      if (n && pn && !(Number(n) > Number(pn))) problems.push(`${jp}: ${e.tag} not numbered after ${prev.tag}`);
+    }
+    for (const l of lines(await g(["-c", "core.quotepath=off", "ls-tree", "--name-only", ref, ...inDir(dir)]))) {
+      if (dirname(l) === dir && l.endsWith(".sql") && numOf(l) && !tags.has(basename(l, ".sql"))) problems.push(`${jp}: no entry for ${basename(l)}`);
+    }
+  }
+  return problems;
+}
+
+/** Lane-added numbered files with their blobs, recorded before a renumber so verifyRenumber can prove the SQL kept. */
+export const snapshotLane = ({ git, base }) => laneNumbered(git, base).catch(() => []);
+
+/**
+ * After the builder renumbered: no collision remains, every recorded non-JSON file (the SQL; snapshots are regenerated)
+ * still exists byte-identical in its directory, and the journals are strictly ordered. @returns {Promise<{ok, problems}>}
+ */
+export async function verifyRenumber({ git, base, before = [] }) {
+  try {
+    const problems = [];
+    const left = await sequenceCollisions({ git, base });
+    for (const c of left.filter((x) => x.base.length)) problems.push(`${c.lane} still shares number ${c.number} with ${c.base.join(", ")}`);
+    const now = await laneNumbered(git, base);
+    for (const b of before.filter((f) => !f.path.endsWith(".json"))) {
+      if (!now.some((f) => dirname(f.path) === dirname(b.path) && f.blob === b.blob)) problems.push(`${b.path}: content changed or file gone after renumbering (keep it byte-identical, rename only)`);
+    }
+    problems.push(...await journalProblems({ git, dirs: [...new Set([...before, ...now].map((f) => dirname(f.path)))] }));
+    return { ok: !problems.length, problems };
+  } catch (e) { return { ok: false, problems: [String(e?.message ?? e)] }; }
+}

package/bin/lean/sequence.test.mjs

@@ -0,0 +1,112 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Fixture: a drizzle-style migrations dir (NNNN_name.sql + meta/_journal.json + meta/NNNN_snapshot.json) where the base
+// gains 0007 while the lane adds its own 0007 (#4322).
+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 { sequenceCollisions, journalProblems, snapshotLane, verifyRenumber } from "./sequence.mjs";
+import { sequencePrompt, sequenceSyncNote } from "./prompts.mjs";
+
+const sh = (cwd, ...a) => execFileSync("git", a, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], 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); } };
+const commit = (d, m) => { sh(d, "add", "-A"); sh(d, "commit", "-qm", m); };
+const journal = (...tags) => `${JSON.stringify({ version: "7", entries: tags.map((tag, idx) => ({ idx, tag, when: 1000 + idx })) }, null, 2)}\n`;
+
+const USAGE_SQL = "CREATE TABLE usage (id int);\n";
+/** main: 0006 init; lane (from main): 0007_usage; then main gains 0007_billing_reconcile. */
+function fixture() {
+  const d = tmpDir("seq-");
+  sh(d, "init", "-q", "-b", "main");
+  put(d, { "db/drizzle/0006_init.sql": "CREATE TABLE t (id int);\n", "db/drizzle/meta/_journal.json": journal("0006_init"), "db/drizzle/meta/0006_snapshot.json": '{"id":"s6"}\n' });
+  commit(d, "init");
+  sh(d, "checkout", "-qb", "lane");
+  put(d, { "db/drizzle/0007_usage.sql": USAGE_SQL, "db/drizzle/meta/_journal.json": journal("0006_init", "0007_usage"), "db/drizzle/meta/0007_snapshot.json": '{"id":"lane7","prevId":"s6"}\n' });
+  commit(d, "lane migration");
+  sh(d, "checkout", "-q", "main");
+  put(d, { "db/drizzle/0007_billing_reconcile.sql": "CREATE TABLE billing (id int);\n", "db/drizzle/meta/_journal.json": journal("0006_init", "0007_billing_reconcile"), "db/drizzle/meta/0007_snapshot.json": '{"id":"s7","prevId":"s6"}\n' });
+  commit(d, "base migration");
+  sh(d, "checkout", "-q", "lane");
+  return d;
+}
+
+/** What the builder does when asked: merge the base, keep the base's journal/snapshot, rename the lane's SQL, regenerate. */
+function renumber(d, { sql = null, tags = ["0006_init", "0007_billing_reconcile", "0008_usage"] } = {}) {
+  try { sh(d, "merge", "--no-edit", "main"); } catch { /* journal and snapshot conflict: resolved below */ }
+  sh(d, "checkout", "--theirs", "--", "db/drizzle/meta/_journal.json", "db/drizzle/meta/0007_snapshot.json");
+  sh(d, "mv", "db/drizzle/0007_usage.sql", "db/drizzle/0008_usage.sql");
+  if (sql) put(d, { "db/drizzle/0008_usage.sql": sql });
+  put(d, { "db/drizzle/meta/_journal.json": journal(...tags), "db/drizzle/meta/0008_snapshot.json": '{"id":"lane8","prevId":"s7"}\n' });
+  commit(d, "renumber");
+}
+
+describe("sequence-numbered migrations at hand-off (#4322)", () => {
+  it("detects the lane's 0007 against the base's 0007 (other name, and same snapshot path with other content) and proposes 0008", async () => {
+    const d = fixture();
+    const c = await sequenceCollisions({ git: gitIn(d), base: "main" });
+    assert.deepEqual(c.map((x) => [x.lane, x.base, x.next]), [
+      ["db/drizzle/0007_usage.sql", ["db/drizzle/0007_billing_reconcile.sql"], "0008"],
+      ["db/drizzle/meta/0007_snapshot.json", ["db/drizzle/meta/0007_snapshot.json"], "0008"],
+    ]);
+    const p = sequencePrompt(c, "main");
+    assert.match(p, /git merge --no-edit origin\/main/);
+    assert.match(p, /db\/drizzle\/0007_usage\.sql -> number 0008 \(base has db\/drizzle\/0007_billing_reconcile\.sql\)/);
+    assert.match(p, /byte-identical[\s\S]*regenerate the snapshot and journal with the repo's own migration generator \(never hand- or text-merge the journal\)[\s\S]*strictly ordered/);
+  });
+
+  it("a correct renumber verifies: SQL unchanged, snapshot regenerated, journal strictly ordered, no collision left", async () => {
+    const d = fixture();
+    const before = await snapshotLane({ git: gitIn(d), base: "main" });
+    assert.deepEqual(before.map((f) => f.path), ["db/drizzle/0007_usage.sql", "db/drizzle/meta/0007_snapshot.json"]);
+    renumber(d);
+    assert.deepEqual(await sequenceCollisions({ git: gitIn(d), base: "main" }), []);
+    assert.deepEqual(await verifyRenumber({ git: gitIn(d), base: "main", before }), { ok: true, problems: [] });
+  });
+
+  it("an edited SQL body, an unordered journal, or no renumber at all fails verification", async () => {
+    let d = fixture(); let before = await snapshotLane({ git: gitIn(d), base: "main" });
+    renumber(d, { sql: "CREATE TABLE usage (id bigint);\n" });
+    assert.match((await verifyRenumber({ git: gitIn(d), base: "main", before })).problems.join("\n"), /0007_usage\.sql: content changed/);
+
+    d = fixture(); before = await snapshotLane({ git: gitIn(d), base: "main" });
+    renumber(d, { tags: ["0006_init", "0008_usage", "0007_billing_reconcile"] });
+    const v = await verifyRenumber({ git: gitIn(d), base: "main", before });
+    assert.equal(v.ok, false);
+    assert.match(v.problems.join("\n"), /_journal\.json: 0007_billing_reconcile not numbered after 0008_usage/);
+
+    d = fixture(); before = await snapshotLane({ git: gitIn(d), base: "main" });
+    const left = await verifyRenumber({ git: gitIn(d), base: "main", before });
+    assert.match(left.problems.join("\n"), /0007_usage\.sql still shares number 0007 with db\/drizzle\/0007_billing_reconcile\.sql/);
+  });
+
+  it("a text-clean base merge still collides (no journal: e.g. app/migrations/0007_x.py), and later lane files move to keep the order", async () => {
+    const d = tmpDir("seq-");
+    sh(d, "init", "-q", "-b", "main");
+    put(d, { "app/migrations/0006_init.py": "x\n" }); commit(d, "init");
+    sh(d, "checkout", "-qb", "lane");
+    put(d, { "app/migrations/0007_a.py": "a\n", "app/migrations/0008_b.py": "b\n" }); commit(d, "lane");
+    sh(d, "checkout", "-q", "main");
+    put(d, { "app/migrations/0007_c.py": "c\n" }); commit(d, "base");
+    sh(d, "checkout", "-q", "lane");
+    sh(d, "merge", "--no-edit", "main");
+    const c = await sequenceCollisions({ git: gitIn(d), base: "main" });
+    assert.deepEqual(c.map((x) => [x.lane, x.base.length, x.next]), [["app/migrations/0007_a.py", 1, "0008"], ["app/migrations/0008_b.py", 0, "0009"]]);
+    assert.deepEqual(await journalProblems({ git: gitIn(d), dirs: ["app/migrations"] }), []);
+  });
+
+  it("regression guard: no numbered file added, or numbers above the base's, is no collision; a broken git never throws", async () => {
+    const d = fixture();
+    sh(d, "reset", "-q", "--hard", "main");
+    put(d, { "src/a.ts": "x\n", "db/drizzle/0008_new.sql": "y\n" }); commit(d, "lane2");
+    assert.deepEqual(await sequenceCollisions({ git: gitIn(d), base: "main" }), []);
+    const bad = async () => { throw new Error("boom"); };
+    assert.deepEqual(await sequenceCollisions({ git: bad, base: "main" }), []);
+    assert.equal(sequenceSyncNote(["src/a.ts", "package.json"]), "");
+    assert.match(sequenceSyncNote(["db/drizzle/meta/_journal.json"]), /do not text-merge/);
+    assert.match(sequenceSyncNote(["db/drizzle/0007_usage.sql"]), /Renumber the lane's files/);
+  });
+});

package/bin/lean/testmap.mjs

@@ -6,7 +6,8 @@
  * command) picks the checks for the lane's changed files; `.forge/repo-facts.json` (scripts/repo-facts.sh) is cited to
  * the builder by path. The test map's commands are run, so it is read from the base ref, then the main checkout, never
  * the builder-writable lane worktree (#4297); repo facts are looked up in the worktree, then the main checkout. A missing
- * or invalid file is absent: the lane keeps forge.yaml `learned.test_commands` and today's prompts.
+ * or invalid file is absent: the lane keeps forge.yaml `learned.test_commands` and today's prompts. With a map, a learned
+ * command the map covers runs only when its globs match a changed file (`scopeChecks`, #4331).
  *
  *   node bin/lean/testmap.mjs --map FILE --select FILE...   print the selected commands, one per line
  */
@@ -52,21 +53,32 @@ export function selectCommands(map, files) {
   for (const e of map?.entries ?? []) {
     const res = e.globs.map((g) => globToRegex(g.replace(/^\.\//, "")));
     if (!changed.some((f) => res.some((re) => re.test(f)))) continue;
-    const cwd = typeof e.cwd === "string" && e.cwd && e.cwd !== "." ? e.cwd : "";
-    const cmd = cwd ? `cd ${shellQuote(cwd)} && ${e.command.trim()}` : e.command.trim();
+    const cmd = entryCommand(e);
     if (!out.includes(cmd)) out.push(cmd);
   }
   return out;
 }
 
+/**
+ * #4318: the dedupe key of a check command: whitespace collapsed, a leading `cd . && ` dropped, `<pm> run test` read as
+ * `<pm> test` (npm/pnpm/yarn/bun) and an `npx`/`bunx [--yes|-y]` prefix dropped, so one suite under two spellings runs once.
+ */
+export function checkKey(c) {
+  let k = String(c ?? "").trim().replace(/\s+/g, " ");
+  k = k.replace(/^cd \.\/? && /, "");
+  const cd = /^((?:cd|pushd) \S+ && )?(.*)$/.exec(k), pre = cd[1] ?? "";
+  const cmd = cd[2].replace(/^(?:npx|bunx)(?: (?:--yes|-y))? /, "").replace(/^(npm|pnpm|yarn|bun) run test(?= |$)/, "$1 test");
+  return pre + cmd;
+}
+
 /**
  * #4315: the pre-PR checks are the learned commands (in order) plus each map-selected command they lack; compared
- * whitespace-collapsed, so the map can only add checks, never remove one. `source`: "learned" when the map added
- * nothing, "test-map" when there were no learned commands, else "test-map+learned".
+ * by `checkKey` (#4318), so the map can only add checks, never remove one; the first spelling seen is kept. `source`:
+ * "learned" when the map added nothing, "test-map" when there were no learned commands, else "test-map+learned".
  * @returns {{commands:string[], source:string, added:number}}
  */
 export function mergeChecks(selected, learned) {
-  const norm = (c) => String(c ?? "").trim().replace(/\s+/g, " ");
+  const norm = checkKey;
   const commands = [], seen = new Set();
   const add = (c) => { const t = String(c ?? "").trim(), k = norm(t); if (!k || seen.has(k)) return false; seen.add(k); commands.push(t); return true; };
   for (const c of Array.isArray(learned) ? learned : []) add(c);
@@ -76,6 +88,31 @@ export function mergeChecks(selected, learned) {
   return { commands, added, source: !added ? "learned" : base ? "test-map+learned" : "test-map" };
 }
 
+/**
+ * #4331: change-scoped pre-PR checks. A learned command the map covers (an entry's command, with its `cd <cwd> && `
+ * prefix, has the same `checkKey`) runs only when one of those entries has a glob matching a changed file; a learned
+ * command with no map entry always runs (the safe default); map-selected commands the learned list lacks are added
+ * as in `mergeChecks`. No map: the learned list unchanged. `source` is "learned" when the map added and dropped
+ * nothing, "test-map" when there were no learned commands, else "test-map+learned".
+ * @returns {{commands:string[], source:string, added:number, dropped:string[]}}
+ */
+export function scopeChecks(map, files, learned) {
+  const list = Array.isArray(learned) ? learned : [];
+  if (!map) { const m = mergeChecks([], list); return { ...m, dropped: [] }; }
+  const selected = selectCommands(map, files), hit = new Set(selected.map(checkKey));
+  const mapped = new Set((map.entries ?? []).map((e) => checkKey(entryCommand(e))));
+  const dropped = [], kept = [];
+  for (const c of list) { const k = checkKey(c); if (!k) continue; (mapped.has(k) && !hit.has(k) ? dropped : kept).push(String(c).trim()); }
+  const m = mergeChecks(selected, kept);
+  return { commands: m.commands, added: m.added, dropped, source: !m.added && !dropped.length ? "learned" : kept.length || dropped.length ? "test-map+learned" : "test-map" };
+}
+
+/** An entry's command as `selectCommands` emits it (`cd <cwd> && cmd` for a non-root cwd). */
+function entryCommand(e) {
+  const cwd = typeof e.cwd === "string" && e.cwd && e.cwd !== "." ? e.cwd : "";
+  return cwd ? `cd ${shellQuote(cwd)} && ${e.command.trim()}` : e.command.trim();
+}
+
 /** The path of the first repo-facts file under `dirs` that exists, or null; never throws. */
 export async function factsPath(dirs, exists) {
   if (typeof exists !== "function") return null;

package/bin/lean/testmap.test.mjs

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { parseTestMap, readTestMap, selectCommands, mergeChecks, factsPath, TEST_MAP_FILE, REPO_FACTS_FILE } from "./testmap.mjs";
+import { parseTestMap, readTestMap, selectCommands, mergeChecks, scopeChecks, checkKey, factsPath, TEST_MAP_FILE, REPO_FACTS_FILE } from "./testmap.mjs";
 
 const MAP = {
   version: 1,
@@ -71,3 +71,40 @@ describe("mergeChecks (#4315): the map can only add checks", () => {
     assert.deepEqual(mergeChecks(undefined, undefined), { commands: [], added: 0, source: "learned" });
   });
 });
+
+describe("mergeChecks (#4318): one suite under two spellings runs once", () => {
+  it("collapses <pm> run test / <pm> test, npx [--yes] X / X and cd . && X / X, keeping the first spelling", () => {
+    assert.deepEqual(mergeChecks(["pnpm test", "vitest", "make lint"], ["pnpm run test", "npx --yes vitest", "cd . && make lint"]),
+      { commands: ["pnpm run test", "npx --yes vitest", "cd . && make lint"], added: 0, source: "learned" });
+    assert.deepEqual(mergeChecks(["cd pkg && npx vitest run", "cd other && vitest run"], ["cd pkg && vitest run"]).commands, ["cd pkg && vitest run", "cd other && vitest run"]);
+  });
+  it("checkKey keeps different suites apart", () => {
+    assert.notEqual(checkKey("npm run test:unit"), checkKey("npm test"));
+    assert.notEqual(checkKey("cd a && npm test"), checkKey("npm test"));
+    assert.equal(checkKey("bunx -y  jest"), "jest");
+  });
+});
+
+describe("scopeChecks (#4331): a mapped learned command runs only when its globs match", () => {
+  const map = { version: 1, entries: [
+    { globs: ["commands/**"], command: "bash scripts/check-a.sh", cwd: "." },
+    { globs: ["bin/**"], command: "bash scripts/check-b.sh", cwd: "." },
+    { globs: ["src/**"], command: "npm test", cwd: "pkg" },
+    { globs: ["**/*.py"], command: "uv run pytest", cwd: "." }] };
+  const learned = ["bash scripts/check-a.sh", "bash scripts/check-b.sh", "make lint"];
+  it("a lane changing only commands/foo.md runs the matching mapped commands plus the unmapped ones", () => {
+    assert.deepEqual(scopeChecks(map, ["commands/foo.md"], learned),
+      { commands: ["bash scripts/check-a.sh", "make lint"], added: 0, dropped: ["bash scripts/check-b.sh"], source: "test-map+learned" });
+  });
+  it("no map keeps the learned list; nothing added or dropped is source learned", () => {
+    assert.deepEqual(scopeChecks(null, ["commands/foo.md"], learned), { commands: learned, added: 0, dropped: [], source: "learned" });
+    assert.deepEqual(scopeChecks(map, ["commands/foo.md"], ["bash scripts/check-a.sh", "make lint"]).source, "learned");
+  });
+  it("matches by checkKey and by the entry's cwd prefix; map-selected commands are added", () => {
+    const r = scopeChecks(map, ["src/x.js", "a.py"], ["cd . && bash scripts/check-a.sh", "cd pkg && npm run test", "npm test"]);
+    assert.deepEqual(r.dropped, ["cd . && bash scripts/check-a.sh"]);
+    assert.deepEqual(r.commands, ["cd pkg && npm run test", "npm test", "uv run pytest"]);
+    assert.equal(r.source, "test-map+learned");
+    assert.deepEqual(scopeChecks(map, ["a.py"], []), { commands: ["uv run pytest"], added: 1, dropped: [], source: "test-map" });
+  });
+});

package/bin/lean/verify.mjs

@@ -13,6 +13,9 @@ export const DEFAULT_SKIP_PATHS = Object.freeze(["*.md", "*.mdx", "*.rst", "*.tx
 export const DEFAULT_MAX_ROUNDS = 2;
 /** Per-command timeout of the pre-PR declared check commands (#4240, `verify.precheck_timeout_seconds`). */
 export const DEFAULT_PRECHECK_TIMEOUT_SECONDS = 300;
+/** Total budget of one round of pre-PR check commands (#4318, `verify.precheck_total_seconds`; 10 min since #4331, and
+ * forge.yaml `lean.precheck.max_minutes` overrides it). The rest of the round is deferred to CI. */
+export const DEFAULT_PRECHECK_TOTAL_SECONDS = 600;
 /** Total characters of failed-job log handed to the builder. */
 export const LOG_CAP = 12000;
 /** No run or check for the head after this long means CI is unavailable (local fallback). */
@@ -26,7 +29,7 @@ const OK = ["success", "neutral", "skipped"];
 
 /**
  * forge.yaml `verify:` section (block style; parseForgeYaml gives strings) → {mode, workflow, pathsInput, skipPaths,
- * maxRounds, precheckTimeoutSeconds, checkRun}. Invalid values fall back to the defaults; mode defaults to local (today's
+ * maxRounds, precheckTimeoutSeconds, precheckTotalSeconds, checkRun}. Invalid values fall back to the defaults; mode defaults to local (today's
  * behaviour); checkRun (`check_run`, #4270) is true only for the literal `true`.
  */
 export function parseVerify(sec = {}) {
@@ -41,8 +44,10 @@ export function parseVerify(sec = {}) {
   const maxRounds = str(s.max_rounds) !== "" && Number.isInteger(n) && n >= 0 && n <= 10 ? n : DEFAULT_MAX_ROUNDS;
   const t = Number(str(s.precheck_timeout_seconds));
   const precheckTimeoutSeconds = str(s.precheck_timeout_seconds) !== "" && Number.isInteger(t) && t >= 1 && t <= 3600 ? t : DEFAULT_PRECHECK_TIMEOUT_SECONDS;
+  const tt = Number(str(s.precheck_total_seconds));
+  const precheckTotalSeconds = str(s.precheck_total_seconds) !== "" && Number.isInteger(tt) && tt >= 1 && tt <= 7200 ? tt : DEFAULT_PRECHECK_TOTAL_SECONDS;
   const checkRun = str(s.check_run).toLowerCase() === "true";
-  return { mode, workflow, pathsInput, skipPaths, maxRounds, precheckTimeoutSeconds, checkRun };
+  return { mode, workflow, pathsInput, skipPaths, maxRounds, precheckTimeoutSeconds, precheckTotalSeconds, checkRun };
 }
 
 const globRe = (g) => new RegExp(`^${g.split("**").map((p) => p.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")).join(".*")}$`);