forgedock 1.29.0 → 1.30.0

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,13 +53,66 @@ 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
+ * 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 = 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);
+  const base = commands.length;
+  let added = 0;
+  for (const c of Array.isArray(selected) ? selected : []) if (add(c)) added++;
+  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, 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,
@@ -56,3 +56,55 @@ describe("test map (#4272)", () => {
     assert.equal(await factsPath(["/wt"], async () => { throw new Error("EACCES"); }), null);
   });
 });
+
+describe("mergeChecks (#4315): the map can only add checks", () => {
+  it("a partial map keeps every learned command and adds the ones it selects that learned lacks", () => {
+    assert.deepEqual(mergeChecks(["npm test", "cd pkg && npm test"], ["make lint", "npm test"]),
+      { commands: ["make lint", "npm test", "cd pkg && npm test"], added: 1, source: "test-map+learned" });
+  });
+  it("duplicates, whitespace variants included, appear once", () => {
+    assert.deepEqual(mergeChecks(["npm  run   lint", " npm run lint", "npm test"], ["npm run lint ", "npm run lint"]).commands, ["npm run lint", "npm test"]);
+  });
+  it("an empty selection keeps the learned commands; no learned commands keep the map's selection", () => {
+    assert.deepEqual(mergeChecks([], ["make lint"]), { commands: ["make lint"], added: 0, source: "learned" });
+    assert.deepEqual(mergeChecks(["npm test"], []), { commands: ["npm test"], added: 1, source: "test-map" });
+    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(".*")}$`);

package/bin/lean/verify.test.mjs

@@ -22,9 +22,9 @@ function fake(o = {}) {
 
 describe("verify-by-CI config (#4167)", () => {
   it("parseVerify defaults to local and rejects invalid values", () => {
-    assert.deepEqual(parseVerify({}), { mode: "local", workflow: null, pathsInput: null, skipPaths: [...DEFAULT_SKIP_PATHS], maxRounds: 2, precheckTimeoutSeconds: 300, checkRun: false });
+    assert.deepEqual(parseVerify({}), { mode: "local", workflow: null, pathsInput: null, skipPaths: [...DEFAULT_SKIP_PATHS], maxRounds: 2, precheckTimeoutSeconds: 300, precheckTotalSeconds: 600, checkRun: false });
     const v = parseVerify({ mode: "ci", workflow: ".github/workflows/verify.yml", paths_input: "changed_paths", skip_paths: "*.md, docs/** ,", max_rounds: "3" });
-    assert.deepEqual(v, { mode: "ci", workflow: ".github/workflows/verify.yml", pathsInput: "changed_paths", skipPaths: ["*.md", "docs/**"], maxRounds: 3, precheckTimeoutSeconds: 300, checkRun: false });
+    assert.deepEqual(v, { mode: "ci", workflow: ".github/workflows/verify.yml", pathsInput: "changed_paths", skipPaths: ["*.md", "docs/**"], maxRounds: 3, precheckTimeoutSeconds: 300, precheckTotalSeconds: 600, checkRun: false });
     assert.equal(parseVerify({ mode: "remote" }).mode, "local");
     assert.equal(parseVerify({ workflow: "x; rm -rf /" }).workflow, null);
     assert.equal(parseVerify({ max_rounds: "-1" }).maxRounds, 2);
@@ -122,6 +122,12 @@ describe("forgedock/verify check run (#4270)", () => {
   const result = { validation: [{ id: "V1", exit: 0 }, { id: "V2", ci: true }], requirements: [{ id: "R1", status: "implemented" }] };
   const out = (r) => JSON.parse(/```json\n([\s\S]*)\n```/.exec(r.text)[1]);
 
+  it("#4318 parseVerify precheck_total_seconds: default 600, integer 1-7200 accepted, others fall back", () => {
+    assert.equal(parseVerify({}).precheckTotalSeconds, 600);
+    assert.equal(parseVerify({ precheck_total_seconds: "1800" }).precheckTotalSeconds, 1800);
+    assert.equal(parseVerify({ precheck_total_seconds: "7200" }).precheckTotalSeconds, 7200);
+    for (const bad of ["0", "-5", "1.5", "abc", "7201"]) assert.equal(parseVerify({ precheck_total_seconds: bad }).precheckTotalSeconds, 600, bad);
+  });
   it("parseVerify: check_run is true only for the literal true; default false", () => {
     assert.equal(parseVerify({}).checkRun, false);
     assert.equal(parseVerify({ check_run: "true" }).checkRun, true);

package/commands/deploy-pr.md

@@ -357,8 +357,9 @@ else
   # Check current CI status
   # Fail closed: valid fields only (`status`/`conclusion` do not exist on gh pr checks --json; the
   # old query errored and defaulted to 0 = "no failures"). An unreadable result counts as failing.
+  # forgedock/verify (the lean engine's report-only gate summary) is not a code failure: ignored, as wait-ci-green.sh does.
   CURRENT_CI_STATUS=$(gh pr checks "$PR_NUMBER" $GH_FLAG --json name,bucket \
-    --jq '[.[] | select(.bucket == "fail" or .bucket == "cancel")] | length' 2>/dev/null || echo "1")
+    --jq '[.[] | select(.name != "forgedock/verify") | select(.bucket == "fail" or .bucket == "cancel")] | length' 2>/dev/null || echo "1")
 
   if [ "$CURRENT_CI_STATUS" -eq 0 ]; then
     echo "CI gate: PASSED (no failing checks)"
@@ -378,9 +379,9 @@ else
 
       CI_FIXES=$((CI_FIXES + 1))
 
-      # Re-check CI status after fix attempt
-      FAILING_AFTER=$(gh pr checks "$PR_NUMBER" $GH_FLAG --json name,status,conclusion \
-        --jq '[.[] | select(.conclusion == "failure")] | length' 2>/dev/null || echo "0")
+      # Re-check CI status after fix attempt (same fail-closed query as above)
+      FAILING_AFTER=$(gh pr checks "$PR_NUMBER" $GH_FLAG --json name,bucket \
+        --jq '[.[] | select(.name != "forgedock/verify") | select(.bucket == "fail" or .bucket == "cancel")] | length' 2>/dev/null || echo "1")
 
       if [ "$FAILING_AFTER" -eq 0 ]; then
         echo "CI gate: PASSED after $CI_ITER iteration(s)"

package/commands/orchestrate.md

@@ -38,7 +38,8 @@ Do this yourself from issue text and the code. Spawn no sub-agents here.
 
    It closes, with the evidence on the issue and no lane, every issue that a merged PR already fixed (one
    short read-only validation on a small model) or an auto-filed CI failure whose workflow is green again
-   (the green run link). It checks K issues at a time. Its last line is `lanes: #A #B ...`: continue with only
+   (the green run link), unless it is flaky (wording or `flaky` label), was reopened after a pre-filter close, or
+   the workflow failed and passed at the same SHA. It checks K issues at a time. Its last line is `lanes: #A #B ...`: continue with only
    those issues. This is the only pre-filter in this command: lanes run `forgedock run-issue`, which does not
    pre-filter again. Keep its
    `pre-filter:` line for the report.
@@ -140,16 +141,18 @@ When a lane finishes (agent lanes; the batch runner applies the same rules itsel
   wait on the sub-issues.
 - `merged` or `invalid`: start the next ready issue.
 - `needs-human` with a **recoverable code**: `ci.red`, `base.conflict` (merge conflict), `ci-pending` on a conflicting
-  PR, `contract.invalid` caused by an issue edited mid-run, and `builder.block_untyped` (an in-scope technical choice).
+  PR, `contract.invalid` caused by an issue edited mid-run, `builder.block_untyped` (an in-scope technical choice),
+  and the environment codes `env.tool_missing` (a validate command the host cannot run) and `env.repro_unrunnable`
+  (the repro harness could not run the repro test).
   These are mechanical. **Do not ask for confirmation on them.** The batch runner recovers each one itself
   (`orchestration.recovery.max_attempts`, default 1 per issue). It launches one recovery lane under the same lease, lane
   and admission rules as any lane, with `run-issue --recover <code> [--recover-attempt n]` (core path only:
-  `--path full` rejects `--recover`). That lane:
+  `--path full` rejects `--recover`; recovery is off when `engine.path: full`). That lane:
   - removes `needs-human`;
   - resumes the open PR: merges the base, fixes the failed required checks from their logs, and pushes new commits only;
   - re-queues the issue, keeping its dependents queued in the same batch.
 
-  Report what was recovered afterwards. A failed recovery stays `needs-human` with its evidence, exactly once (failed = `needs-human`, `ci-pending`, or a final `engine-error`/`deferred`; `invalid`, `decomposed` and `dependency-*` are not failures and never re-label), and there
+  Report what was recovered afterwards. A failed recovery stays `needs-human` with its evidence, re-labelled exactly once per issue, by the final attempt only (failed = `needs-human`, `ci-pending`, or a final `engine-error`/`deferred`; `invalid`, `decomposed` and `dependency-*` are not failures and never re-label). With `max_attempts > 1` a non-final attempt adds no label or comment: the runner either launches the next attempt or, when none follows, re-labels it once itself, so the label does not flap between attempts. There
   is no second attempt beyond `max_attempts`.
 - `needs-human` with a **human code** (`builder.blocked`: product-decision, spend, credentials, promotion, customer): an
   external action agents cannot take, or a product decision too critical for agents. It is never auto-recovered. Read

package/commands/review-pr-staging.md

@@ -660,8 +660,13 @@ git diff origin/$DEFAULT_BRANCH...origin/$STAGING_BRANCH | grep -iE "(api[_-]?ke
 type forge_resolve >/dev/null 2>&1 || { setopt nonomatch 2>/dev/null || true; FORGE_SOURCED_ROOT='${CLAUDE_PLUGIN_ROOT}'; for _r in "$(cygpath -u "${FORGEDOCK_HOME:-}" 2>/dev/null || printf %s "${FORGEDOCK_HOME:-}")" '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGE_HOME:-}" "$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null | sed 's|/commands/work-on\.md$||')" "$(head -n 1 "${CODEX_HOME:-$HOME/.codex}/forge-home" 2>/dev/null)" "$HOME/.claude/plugins/marketplaces/forgedock" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/forgedock/forgedock/* "$HOME/.claude"/plugins/cache/forgedock/forgedock/*; do case "$_r" in /*) [ -f "$_r/scripts/lib/forge-resolve.sh" ] && { . "$_r/scripts/lib/forge-resolve.sh"; break; };; esac; done; type forge_resolve >/dev/null 2>&1 || forge_resolve() { :; }; }
 . "$(forge_resolve lib/fence-bootstrap.sh)" || { echo "BLOCKED: ForgeDock helper lib/fence-bootstrap.sh not resolvable"; exit 1; }   # FENCE_BOOTSTRAP
 gh pr checks "$PR_NUMBER" -R "$GH_REPO" 2>&1
+# forgedock/verify (the lean engine's report-only gate summary) is not a code failure: ignored, as wait-ci-green.sh does.
+# Fail closed: an unreadable result counts as failing.
+CI_FAILING=$(gh pr checks "$PR_NUMBER" -R "$GH_REPO" --json name,bucket \
+  --jq '[.[] | select(.name != "forgedock/verify") | select(.bucket == "fail" or .bucket == "cancel")] | length' 2>/dev/null || echo "1")
+echo "CI_FAILING: $CI_FAILING"
 ```
-Any CI failure → BLOCK DEPLOY (unless autofixed in Phase 1F).
+`CI_FAILING` > 0 → BLOCK DEPLOY (unless autofixed in Phase 1F). A red `forgedock/verify` alone does not block.
 
 ### Phase 1F: CI Autofix
 

package/docs/CONFIG.md

@@ -590,11 +590,14 @@ Settings of the core work-on (`bin/lean/`) that change its contract.
 ```yaml
 lean:
   repro_test: prefer   # off | prefer (default)
+  precheck:
+    max_minutes: 10    # optional pre-PR check round budget in minutes (1-120)
 ```
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `repro_test` | string | No | `prefer` (default): on an issue labelled `bug` or `type:bug`, the plan step must freeze a `repro_test` in the contract (`{"path","id","command"}`) when the bug is testable. Before review, the engine runs `scripts/acceptance-red-green.sh` for that command on the host in every verify mode: one targeted test, red on the base (head's changed test files overlaid) and green on head. Any other result, including a test that could not run, fails the precheck as `conformance.unimplemented` (it blocks in shadow too) and goes back to the builder for one in-session fix round. A bug that is not testable (specs, docs, workflows, environment) records `"repro_test":"none"` with a one-line `repro_test_reason` and the lane continues as before. `off` gives exactly the previous contract and precheck. Each proof emits a `REPRO_RED_GREEN` run-log event (`base`, `head`) and adds a trajectory decision. |
+| `repro_test` | string | No | `prefer` (default): on an issue labelled `bug` or `type:bug`, the plan step must freeze a `repro_test` in the contract (`{"path","id","command"}`) when the bug is testable. Before review, the engine runs `scripts/acceptance-red-green.sh` for that command on the host in every verify mode: one targeted test, red on the base (head's changed test files overlaid) and green on head. A test that ran but is not red on the base and green on head fails the precheck as `conformance.unimplemented` (it blocks in shadow too) and goes back to the builder for one in-session fix round. A head the harness could not run at all (timeout, missing runner or dependencies) ends `needs-human` with the recoverable code `env.repro_unrunnable`, not a builder round: the batch runner's recovery lane reruns it through the repo's own toolchain (see docs/OUTCOME-CODES.md). The harness runs with the lane env (`TMPDIR`, toolchain) and the workspace dependency trees, and a repro test file that is new on head is run against the base sources. A bug that is not testable (specs, docs, workflows, environment) records `"repro_test":"none"` with a one-line `repro_test_reason` and the lane continues as before. `off` gives exactly the previous contract and precheck. Each proof emits a `REPRO_RED_GREEN` run-log event (`base`, `head`) and adds a trajectory decision. |
+| `precheck.max_minutes` | number | No | Total budget in minutes (1–120) of one round of pre-PR check commands (#4331). The flat form `lean.precheck_max_minutes` also works and wins. When unset, `verify.precheck_total_seconds` applies (default 600 s). Check commands run change-scoped (a learned command with a test-map entry runs only when its globs match the changed files; unmapped commands always run), concurrently up to the host worker cap under one heavy slot, each timed (`ms` in the `PRECHECK_COMMANDS` run-log event). Commands not started when the budget runs out are recorded `deferred-to-ci` (an anomaly, not a failure) and left to CI. |
 
 ## `verify` (OPTIONAL)
 
@@ -608,6 +611,7 @@ verify:
   skip_paths: "*.md,docs/**"    # optional, comma-separated; default *.md,*.mdx,*.rst,*.txt,docs/**,devdocs/**
   max_rounds: 2                 # optional CI fix rounds before needs-human (default 2)
   precheck_timeout_seconds: 300 # optional per-command timeout of the declared pre-PR checks (default 300)
+  precheck_total_seconds: 600   # optional total budget of one pre-PR check round (default 600)
   check_run: true               # optional; post the forgedock/verify check run (default false)
 ```
 
@@ -619,6 +623,7 @@ verify:
 | `skip_paths` | string | No | Comma-separated globs. A glob without `/` matches the basename anywhere; `**` spans directories. When every changed file matches, the lane skips CI verification (a docs-only lane runs no CI matrix). |
 | `max_rounds` | integer | No | Builder fix rounds for red CI (0–10, default 2). Also bounds the merge-time fix rounds and the declared-check fix rounds below, in every mode. |
 | `precheck_timeout_seconds` | integer | No | Timeout of each declared check command (1–3600, default 300); a timed-out command counts as failed (exit 124). |
+| `precheck_total_seconds` | integer | No | Total budget of one round of pre-PR check commands (1–7200, default 600; it was 1800 before 1.30.0). `lean.precheck.max_minutes` takes precedence. Commands not started within the budget are deferred to CI, not failed. |
 | `check_run` | boolean | No | Default `false` (no Checks API call, behaviour unchanged). `true`: after each push of a reviewed head (PR open, base-sync, merge-time fix round) the engine posts one completed `forgedock/verify` check run on that head (forge#4270), `success` iff every deterministic gate the lane already ran passed: declared check commands, undeclared package edges, docs freshness, contract scope, validate ids, requirement status, hotspot growth, amendments. The output carries each gate's id, pass/fail and evidence as JSON; the run log records a `VERIFY` event. Report only: ForgeDock never makes it required and never waits on it (it is ignored by its own CI waits); requiring it is the repository's branch-protection choice. Creating check runs needs a token that may (a GitHub App with `checks: write`); a Checks API failure is logged as an anomaly and never fails the lane. |
 
 **Flow** (`ci`/`hybrid`, `bin/lean/verify.mjs` `runCiVerify`):
@@ -821,6 +826,8 @@ decomposition:
 
 **With `close_parent: false`** (default): unchanged. The parent stays open and is closed by C3 when the last child closes.
 
+The lean (core) path reads the same key (#4337): with `close_parent: true` it closes the parent at decomposition as `not planned`, keeps `workflow:decomposed` and lists the sub-issues in the closing comment; dependents still wait on the sub-issues, and a trusted `FORGE:DECOMPOSED:REVOKED` reopens it. With the default `false` the lean parent stays open.
+
 **Limitation**: `--retry` and engine resume refuse closed issues, so a closed decomposed parent cannot be re-run. It has nothing left to run; work on its open children instead.
 
 **Commands that use this section**: `work-on` (`decompose` D6.5, `close` C3), `orchestrate`

package/docs/OUTCOME-CODES.md

@@ -47,6 +47,8 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
 | `cli.timeout` | CLI child ran and was killed at the wall-clock limit; a normal attempt (consumes one of `maxAttempts`), usage recorded when the CLI emitted any | engine | `err.code` `CLI_TIMEOUT` |
 | `cli.spawn_failed` | The CLI could not be started for a reason that repeats on every rerun (`E2BIG` argv too large, `ENOENT`/`EACCES`/`ENOEXEC` binary missing or not executable, `ENAMETOOLONG`). Core work-on ends `needs-human` with this code instead of `engine-error`, so `forgedock orchestrate` does not spend its relaunch on it | lean, engine | `err.code` `CLI_SPAWN_FAILED` (E2BIG) or `err.spawnDeterministic` (other errnos keep their `err.code`); `err.spawnErrno` holds the errno |
 | `env.setup_failed` | forge.yaml `env.setup` (run once per fresh lane worktree, before the builder) exited non-zero, timed out or could not start. An environment error, not a build failure: the builder never ran. Core work-on ends `needs-human` with this code instead of `engine-error`, so `forgedock orchestrate` does not relaunch it; fix the setup command or the environment and rerun | lean | `io.runSetup` exit code / spawn error |
+| `env.tool_missing` | Core work-on (forge#4323): a validate command the builder recorded as failed was rerun by the engine and could not run because the host lacks a tool or module (`command not found` / exit 127, Python `No module named x`, Node `Cannot find module|package 'x'` for a bare name the repo does not track). An environment error, not a conformance failure: no builder resume, no reviewer. Ends `needs-human` naming the tool; recoverable by `forgedock orchestrate` (the recovery lane runs the check through the repo's own toolchain). Skipped on a CI-verified head | lean | `gate()` rerun via `io.runCommand`, `{rc, output}` classified by `conformance.mjs` `missingTool` |
+| `env.repro_unrunnable` | Core work-on (forge#4334): on a bug lane the frozen `repro_test` could not be run on head by `scripts/acceptance-red-green.sh` (`HEAD=UNRUNNABLE`: timeout, exit 126/127, unclassifiable output) or the harness returned no result. An environment error, not a conformance failure: no builder resume, no reviewer. Ends `needs-human`; recoverable by `forgedock orchestrate` (the recovery lane reruns the repro command through the repo's own toolchain and installed dependencies). Other non-proofs (passes on base, fails on head, base unrunnable) stay `conformance.unimplemented` | lean | `gate()` `io.redGreen` words, classified by `conformance.mjs` `reproFailures` |
 | `sandbox.start_failed` | A `forgedock orchestrate` lane sandbox (forge.yaml `execution`, provider `container` or `remote`) could not start: bad image, missing endpoint or credential, refused launch. The lane never ran. Final `needs-human` row: not relaunched and not counted by the engine-error circuit breaker | orchestrate | `bin/lean/execution.mjs` `providerLanes`: `provider.start` threw without `retryable` |
 | `sandbox.capacity` | The sandbox provider had no capacity for the lane (HTTP 429/503 from the remote transport). `deferred` with backoff (`Retry-After` when sent), bounded by `orchestration.max_deferrals` | orchestrate | `provider.start` threw with `err.retryable: true` |
 | `lease.held` | Another live agent holds the issue lease | engine | Foreign live lease on acquire |
@@ -58,7 +60,7 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
 | `lane.branch_missing` | Core work-on: the lane branch (e.g. `milestone/<slug>`) does not exist on origin; fail closed | lean | `git ls-remote --heads origin` |
 | `lane.unresolved` | Core work-on: the lane could not be worked out (milestone or default branch unreadable, empty milestone slug, bad `feature_pattern`); fail closed | lean | Failed `gh` read or config |
 | `invalid` | Issue is invalid or in a divergent closed state | investigate, engine | `INVESTIGATION:INVALID` marker, or live snapshot |
-| `decomposed` | Issue was decomposed into sub-issues. In core work-on, the builder reported `block.kind: "split-required"`; the engine files the sub-issues (`**Parent**` and `**Depends on**` lines) and returns them as `subissues` for `forgedock orchestrate` to run | investigate, decompose, lean | `FORGE:DECOMPOSED` or the decomposition assessment; `result.json` `block.subissues` |
+| `decomposed` | Issue was decomposed into sub-issues. In core work-on, the builder reported `block.kind: "split-required"`; the engine files the sub-issues (`**Parent**` and `**Depends on**` lines) and returns them as `subissues` for `forgedock orchestrate` to run. With `decomposition.close_parent: true` the parent is then closed `not planned` (label kept) and its dependents wait on the sub-issues | investigate, decompose, lean | `FORGE:DECOMPOSED` or the decomposition assessment; `result.json` `block.subissues` |
 | `builder.blocked` | Core work-on: the builder reported an external action agents cannot take, or a product decision too critical for agents: `block.kind: "human"` with `why` one of `credentials`, `spend`, `promotion`, `customer`, `product-decision`. An upstream issue, a needed split, or prod data that monitoring access can read never count | lean | `result.json` status `blocked` + typed `block` |
 | `builder.block_untyped` | Core work-on: the builder stayed `blocked` without a valid typed reason (missing `block`, a non-human `why` such as prod data, or a dependency that is not open) after one corrective resume | lean | `result.json` status `blocked`, twice |
 | `builder.no_evidence` | Core work-on: the builder reported invalid/already-fixed without file:line evidence, so the issue was not closed | lean | `result.json` with empty `evidence` |
@@ -69,7 +71,7 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
 | `review.incomplete` | Core work-on: the conformance review twice returned no complete rows (a generic PASS, a missing requirement/scope/preserve row, evidence in a file that does not exist); nothing merged | lean | `checkCompleteness` problems on both reviewer runs |
 | `review.inconsistent` | Core work-on: the reviewer twice said NONCONFORMING without any failing row; the reviewer is re-asked, the builder's resume is not spent | lean | Verdict/row mismatch on both reviewer runs |
 | `conformance.omission` | Core work-on: an issue requirement is missing from or narrowed by the frozen contract, after one builder resume | lean | Review `issue_coverage` row not `covered` |
-| `conformance.unimplemented` | Core work-on: a contracted requirement is partial, missing or unvalidated, or a validate command failed, after one builder resume | lean | Precheck (result.json, validation) or review requirement row |
+| `conformance.unimplemented` | Core work-on: a contracted requirement is partial, missing or unvalidated, or a validate command failed, after one builder resume (a validate the host cannot run for a missing tool or module is `env.tool_missing`, and a repro test the harness cannot run on head is `env.repro_unrunnable`, instead) | lean | Precheck (result.json, validation) or review requirement row |
 | `conformance.scope_creep` | Core work-on: a changed file is not authorized by a deliverable or typed amendment, after one builder resume | lean | Precheck changed files or review `scope` row `none` |
 | `conformance.untracked_deferral` | Core work-on: a requirement was deferred without a typed amendment or a tracking issue, after one builder resume | lean | Precheck or review requirement row `deferred` on a `deliver` requirement |
 | `conformance.unjustified_deferral` | Core work-on: the reviewer judged a deferred or post-deploy requirement unjustified (it belongs in this change), after one builder resume; nothing is filed or merged | lean | Review requirement row `deferral_ok: false` |
@@ -93,11 +95,11 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
 `forgedock orchestrate` recovers mechanical outcomes inside the batch:
 
 - **recoverable**:
-  - needs-human with `ci.red`, `base.conflict` or `builder.block_untyped`;
+  - needs-human with `ci.red`, `base.conflict`, `builder.block_untyped`, `env.tool_missing` or `env.repro_unrunnable`;
   - `contract.invalid` when the issue was edited mid-run (`issueEdited`);
   - `ci-pending` on a conflicting PR, recovered as `base.conflict`.
 
-  The runner relaunches the issue once per `orchestration.recovery.max_attempts` (default 1) as a recovery lane (`run-issue --recover <code>`), under the normal admission rules. That lane removes the `needs-human` label, posts `FORGE:DECISION`, and resumes the open PR: base-sync, then CI fix rounds from the failed-check logs. Dependents stay queued. A merged recovery is reported as `recovered`. A failed one is final, keeps the recovery evidence on the row, and skips its dependents. A failed recovery stays `needs-human`: the lane re-adds the label (with a `FORGE:NEEDS_HUMAN` comment carrying the evidence) only for a final `needs-human` or `ci-pending`; the batch runner re-adds it, once, for a final `engine-error` or `deferred` after the recovery pass (those may be requeued, so the lane cannot know). `invalid`, `decomposed`, `dependency-*` and `merged` never re-label.
+  The runner relaunches the issue once per `orchestration.recovery.max_attempts` (default 1) as a recovery lane (`run-issue --recover <code>`), under the normal admission rules. That lane removes the `needs-human` label, posts `FORGE:DECISION`, and resumes the open PR: base-sync, then CI fix rounds from the failed-check logs. Dependents stay queued. A merged recovery is reported as `recovered`. A failed one is final, keeps the recovery evidence on the row, and skips its dependents. A failed recovery stays `needs-human`: the lane re-adds the label (with a `FORGE:NEEDS_HUMAN` comment carrying the evidence) only for a final `needs-human` or `ci-pending`, and only when it is the last attempt (`attempt == max_attempts`); a non-final attempt that ends `needs-human` or `ci-pending` without another attempt following is re-labelled once by the batch runner; the batch runner re-adds it, once, for a final `engine-error` or `deferred` after the recovery pass (those may be requeued, so the lane cannot know). `invalid`, `decomposed`, `dependency-*` and `merged` never re-label. In-batch recovery is off when `engine.path: full`: the runner passes no recovery to the batch, and `run-issue --path full` rejects `--recover`.
 - **human**: `builder.blocked`, which is only reached by a typed human block: credentials, spend, promotion, customer or product-decision. It is never recovered, it skips dependents, and it is the only class in the report's escalation list.
 - **terminal**: every other code. No recovery runs, dependents are skipped, and the row is reported as `unrecovered`.
 

package/docs/RELEASE-NOTES.md

@@ -2,6 +2,16 @@
 
 Operator-facing notes for behavior changes that need action or awareness. Newest first.
 
+## v1.30.0: environment failures are recoverable, scoped pre-PR checks, decomposed parents can close
+
+- **New recoverable codes.** A validate command the host cannot run (missing interpreter, module or executable) ends `env.tool_missing`, and a repro test the harness could not run on head ends `env.repro_unrunnable`. Both were terminal `conformance.unimplemented` before. The batch runner recovers them like `ci.red` (see docs/OUTCOME-CODES.md).
+- **Contract freeze is stricter.** Validate and repro commands that read `$TMPDIR` files they do not create are rejected at freeze, and validate commands are preflighted for their interpreters and modules (a miss asks the builder for one contract correction). Engine-run commands now get the builder's lane env (`TMPDIR`, toolchain), and the repro harness uses the workspace dependency trees and runs a new head test file against the base.
+- **Pre-PR checks.** Learned check commands run change-scoped (when a test map covers them), concurrently and timed, within a round budget: `lean.precheck.max_minutes`, else `verify.precheck_total_seconds`, whose default drops from 1800 s to **600 s**. Commands left when the budget runs out are `deferred-to-ci`, not failed. Set `FORGE_HOST_PARALLELISM=1` if your check commands share state (cache files, a test database, a fixed port).
+- **Decomposed parents.** The lean path honours `decomposition.close_parent`: with `true` a decomposed parent closes `not planned` right after decomposition (label kept, sub-issues listed); its dependents still wait on the sub-issues, and a trusted revoke reopens it. Default `false` keeps it open.
+- **Hand-off.** Enumerating tests (exhaustiveness guards) are discovered for the change, and sequence-numbered migrations that collide with the base are renumbered by the builder.
+
+Action: set `decomposition.close_parent: true` to close decomposed parents. Raise `lean.precheck.max_minutes` if your pre-PR checks legitimately need more than 10 minutes.
+
 ## v1.29.0: in-batch recovery and context pack on by default
 
 - **In-batch recovery** (`orchestration.recovery.max_attempts`, default 1): `forgedock orchestrate` now launches one recovery lane per issue for a mechanical `needs-human` (`ci.red`, `base.conflict`, `ci-pending` on a conflicting PR, `contract.invalid` after a mid-run issue edit, `builder.block_untyped`). The lane removes `needs-human`, resumes the PR and re-queues the issue. A recovery that ends anything but `merged` re-applies `needs-human` with a recovery-evidence `FORGE:NEEDS_HUMAN` comment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"

package/scripts/acceptance-red-green.sh

@@ -6,13 +6,14 @@
 # Usage: acceptance-red-green.sh --repo-path <worktree> --base-ref <ref> --test-cmd "<cmd>" [--timeout <sec>]
 # Runs <cmd> in <worktree> (head) first. Only when head RAN does it create a detached base worktree at
 # `git merge-base HEAD <base-ref>` (under mktemp -d, never inside the repo), overlay head's changed test files
-# onto it, and run <cmd> there. Each run is classified with classify-test-run.sh.
+# onto it, link head's untracked dependency trees (every node_modules next to a tracked package.json, a root .venv),
+# and run <cmd> there. Each run is classified with classify-test-run.sh.
 # Prints exactly one line on stdout:   BASE=<FAILED|RAN|RAN_NOTHING|UNRUNNABLE|SKIPPED> HEAD=<FAILED|RAN|RAN_NOTHING|UNRUNNABLE>
 #   FAILED      the run executed and failed
 #   RAN         the run executed and passed
 #   RAN_NOTHING the runner exercised nothing
 #   UNRUNNABLE  could not execute (timeout 124, not executable 126/127, worktree/overlay/classifier failure)
-#   SKIPPED     base was not run because head did not PASS
+#   SKIPPED     base was not run because head did not PASS (never a missing file: head's new test files are overlaid)
 # Never prints a verdict on success of cleanup: the base worktree is removed on every exit path (trap + explicit remove).
 # Callers map: HEAD=RAN BASE=FAILED -> proof; BASE=RAN -> passes on base (gate FAIL); anything else that is not a proof -> DEGRADED/FAIL.
 # Exit: 0 line printed | 2 usage error (stdout empty so callers fail closed)
@@ -81,8 +82,16 @@ while IFS= read -r f; do
   [ -f "$REPO/$f" ] && [ ! -L "$REPO/$f" ] || continue   # deleted at head, or a symlink: never copied
   mkdir -p "$BASE_WT/$(dirname "$f")" && cp -p "$REPO/$f" "$BASE_WT/$f" 2>/dev/null && [ -f "$BASE_WT/$f" ] || OVERLAY_OK=false
 done <<< "$CHANGED"
-# Untracked dependency tree (never in git): link it so a missing install is not mistaken for a red run.
-[ -d "$REPO/node_modules" ] && [ ! -e "$BASE_WT/node_modules" ] && ln -s "$REPO/node_modules" "$BASE_WT/node_modules" 2>/dev/null
+# Untracked dependency trees (never in git): link head's so a missing install is not mistaken for a red run (#4334):
+# every node_modules next to a tracked package.json (workspace packages too, e.g. apps/web/node_modules) and a root .venv.
+DEPS=$( { git -C "$REPO" ls-files -- package.json '*/package.json' 2>/dev/null | while IFS= read -r p; do
+  d=$(dirname "$p"); [ "$d" = "." ] && echo node_modules || echo "$d/node_modules"; done; echo .venv; } | sort -u )
+while IFS= read -r t; do
+  [ -n "$t" ] || continue
+  case "$t" in */node_modules/*) continue ;; esac   # a package.json inside an installed tree
+  [ -d "$REPO/$t" ] && [ ! -e "$BASE_WT/$t" ] && [ ! -L "$BASE_WT/$t" ] || continue
+  mkdir -p "$BASE_WT/$(dirname "$t")" 2>/dev/null && ln -s "$REPO/$t" "$BASE_WT/$t" 2>/dev/null
+done <<< "$DEPS"
 
 if [ "$OVERLAY_OK" != "true" ]; then BASE_RES=UNRUNNABLE; else BASE_RES=$(run_in "$BASE_WT"); fi
 cleanup   # explicit; the EXIT trap is the backstop

package/scripts/acceptance-red-green.test.sh

@@ -70,5 +70,19 @@ fi
 out=$(bash "$RG" --repo-path "$R1" 2>/dev/null); rc=$?
 { [ "$rc" -eq 2 ] && [ -z "$out" ]; } && ok "missing args exit 2, empty stdout" || bad "usage: rc=$rc out='$out'"
 
+# 11. workspace monorepo (#4334): a new test file in a package needs that package's untracked node_modules and the root
+#     .venv; base gets head's trees linked, so it runs and fails on the defect (not 127 on a missing install)
+R5="$TMP/r5"; make_repo "$R5"
+mkdir -p "$R5/apps/web"; printf '{}\n' > "$R5/package.json"; printf '{"name":"web"}\n' > "$R5/apps/web/package.json"
+printf 'node_modules/\n.venv/\n' > "$R5/.gitignore"; git -C "$R5" add -A; git -C "$R5" commit -qm pkgs; git -C "$R5" update-ref refs/remotes/origin/main HEAD
+fix_head "$R5"
+mkdir -p "$R5/apps/web/node_modules/dep" "$R5/.venv/bin"
+printf 'echo dep\n' > "$R5/apps/web/node_modules/dep/run.sh"; printf 'echo venv\n' > "$R5/.venv/bin/tool"
+mkdir -p "$R5/apps/web/__tests__"
+printf 'bash node_modules/dep/run.sh >/dev/null 2>&1 || exit 127\nbash ../../.venv/bin/tool >/dev/null 2>&1 || exit 127\ntest "$(bash ../../app.sh)" = good && echo "1 passed"\n' > "$R5/apps/web/__tests__/t.test.sh"
+git -C "$R5" add -A; git -C "$R5" commit -qm test
+check "workspace node_modules and .venv linked into base; new nested test overlaid" "BASE=FAILED HEAD=RAN" "$R5" "cd apps/web && bash __tests__/t.test.sh"
+[ -d "$R5/apps/web/node_modules/dep" ] && [ -d "$R5/.venv/bin" ] && ok "head dependency trees survive base cleanup" || bad "head dependency trees removed by cleanup"
+
 echo "$PASS passed, $FAILN failed"
 [ "$FAILN" -eq 0 ]