forgedock 1.26.0 → 1.27.0

package/bin/lean/ledger.mjs

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Lane resource ledger (#4179): `~/.forge/ledger/<batch>/<lane>.json` lists every resource a lane owns (worktree, branch,
+ * run tmp, spawned pids, containers/volumes the builder reported) with owner, batch, lane, issue, created and expires.
+ * Each resource is registered BEFORE it is created and released only after its teardown succeeded, so a lane that dies
+ * leaves an exact record behind. Teardown acts only on what the ledger lists; this module itself only reads and writes
+ * the ledger file (no git, gh, docker or kill calls).
+ */
+import * as nodeFs from "node:fs";
+import { homedir, hostname } from "node:os";
+import { join } from "node:path";
+
+export const ledgerRoot = () => join(homedir(), ".forge", "ledger");
+export const LEDGER_TTL_MS = 6 * 3600 * 1000;
+export const LEDGER_KINDS = Object.freeze(["worktree", "branch", "tmp", "pid", "container", "volume"]);
+/** A path segment that cannot escape the root: [A-Za-z0-9._-] only, never "." or "..". */
+export const safeSegment = (s) => { const v = String(s ?? "").replace(/[^A-Za-z0-9._-]/g, "_"); return !v || /^\.+$/.test(v) ? "_" : v; };
+
+/** Docker ownership labels (#4181): owner, batch, lane, issue, expires (epoch ms, as the ledger), values [A-Za-z0-9_.-] only. */
+export function dockerLabels({ batch, lane, issue, expires } = {}) {
+  const v = (x) => String(x ?? "").replace(/[^A-Za-z0-9_.-]/g, "-") || "unknown";
+  return [`forgedock.owner=1`, `forgedock.batch=${v(batch)}`, `forgedock.lane=${v(lane)}`, `forgedock.issue=${v(issue)}`, `forgedock.expires=${v(expires)}`];
+}
+
+export function makeLedger({ root = ledgerRoot(), batch = "adhoc", lane, owner, issue, host = hostname(), pid = process.pid, now = () => Date.now(), ttlMs = LEDGER_TTL_MS, fs = nodeFs } = {}) {
+  const dir = join(root, safeSegment(batch));
+  const path = join(dir, `${safeSegment(lane ?? `lane-${issue}`)}.json`);
+  const read = () => { try { const j = JSON.parse(fs.readFileSync(path, "utf8")); return j && typeof j === "object" && Array.isArray(j.resources) ? j : null; } catch { return null; } };
+  const write = (j) => {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${path}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(j, null, 2) + "\n");
+    fs.renameSync(tmp, path);
+  };
+  const fresh = () => { const c = now(); return { v: 1, owner, batch: String(batch), lane: String(lane ?? `lane-${issue}`), issue, host, pid, created: c, expires: c + ttlMs, resources: [] }; };
+  const same = (r, kind, value) => r.kind === kind && String(r.value) === String(value);
+  return {
+    path,
+    read,
+    /** Idempotent; call BEFORE the resource is created. `extra` (e.g. {marker}) is kept on the entry. */
+    register(kind, value, extra = {}) {
+      if (!LEDGER_KINDS.includes(kind) || value == null || value === "") return false;
+      const j = read() ?? fresh();
+      Object.assign(j, { owner, host, pid, expires: now() + ttlMs });
+      if (!j.resources.some((r) => same(r, kind, value))) j.resources.push({ kind, value, ...extra, registered: now() });
+      write(j);
+      return true;
+    },
+    release(kind, value) {
+      const j = read();
+      if (!j) return false;
+      const n = j.resources.length;
+      j.resources = j.resources.filter((r) => !same(r, kind, value));
+      if (j.resources.length !== n) write(j);
+      return j.resources.length !== n;
+    },
+    entries(kind) { return (read()?.resources ?? []).filter((r) => !kind || r.kind === kind); },
+    /** Delete the file only when it lists nothing; a non-empty ledger stays for the next run or the reaper. */
+    remove() {
+      const j = read();
+      if (j && j.resources.length) return false;
+      try { fs.rmSync(path, { force: true }); } catch { return false; }
+      return true;
+    },
+  };
+}

package/bin/lean/ledger.test.mjs

@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { makeLedger, safeSegment, LEDGER_TTL_MS, dockerLabels } from "./ledger.mjs";
+
+describe("lane resource ledger (#4179)", () => {
+  it("register/release round trip carries owner, batch, lane, issue, created and expires", () => {
+    const root = tmpDir("ledger-");
+    let t = 1000;
+    const l = makeLedger({ root, batch: "b20261019-1", lane: "lean-7", owner: "core_1", issue: 7, host: "h", pid: 11, now: () => t });
+    assert.equal(l.path, join(root, "b20261019-1", "lean-7.json"));
+    assert.equal(l.read(), null);
+    assert.equal(l.register("worktree", "/wt/lean-7"), true);
+    l.register("branch", "feat/issue-7-lean");
+    l.register("pid", 4242, { marker: "claude" });
+    l.register("worktree", "/wt/lean-7"); // idempotent
+    t = 2000;
+    l.register("container", "lean7-pg");
+    const j = JSON.parse(readFileSync(l.path, "utf8"));
+    assert.deepEqual({ owner: j.owner, batch: j.batch, lane: j.lane, issue: j.issue, host: j.host, pid: j.pid, created: j.created }, { owner: "core_1", batch: "b20261019-1", lane: "lean-7", issue: 7, host: "h", pid: 11, created: 1000 });
+    assert.equal(j.expires, 2000 + LEDGER_TTL_MS, "each registration extends expiry");
+    assert.deepEqual(j.resources.map((r) => `${r.kind}:${r.value}`), ["worktree:/wt/lean-7", "branch:feat/issue-7-lean", "pid:4242", "container:lean7-pg"]);
+    assert.equal(l.entries("pid")[0].marker, "claude");
+    assert.equal(l.register("nonsense", "x"), false, "unknown kinds are refused");
+    assert.equal(l.release("pid", "4242"), true);
+    assert.equal(l.release("pid", 4242), false);
+    assert.equal(l.remove(), false, "a ledger that still lists resources is kept");
+    for (const r of l.entries()) l.release(r.kind, r.value);
+    assert.equal(l.remove(), true);
+    assert.equal(existsSync(l.path), false);
+  });
+
+  it("writes are atomic (no tmp file left behind) and names cannot escape the root", () => {
+    const root = tmpDir("ledger-");
+    const l = makeLedger({ root, batch: "../../etc", lane: "../passwd", issue: 1 });
+    l.register("tmp", "/x");
+    assert.equal(dirname(dirname(l.path)), root);
+    assert.deepEqual(readdirSync(dirname(l.path)), [l.path.split("/").at(-1)]);
+    for (const [i, o] of [["..", "_"], [".", "_"], ["", "_"], ["a/b", "a_b"], ["milestone/x", "milestone_x"], ["b1.2", "b1.2"]]) assert.equal(safeSegment(i), o);
+  });
+
+  it("a simulated crash (no teardown) leaves every registered resource readable by a fresh process", () => {
+    const root = tmpDir("ledger-");
+    const l = makeLedger({ root, batch: "b1", lane: "lean-9", owner: "core_9", issue: 9 });
+    for (const [k, v] of [["tmp", "/home/x/.forge/tmp/runs/9-1"], ["branch", "feat/issue-9-lean"], ["worktree", "/wt/lean-9"], ["pid", 77]]) l.register(k, v);
+    // the process dies here: nothing is released
+    const after = makeLedger({ root, batch: "b1", lane: "lean-9", issue: 9 }).read();
+    assert.equal(after.owner, "core_9");
+    assert.deepEqual(after.resources.map((r) => r.kind), ["tmp", "branch", "worktree", "pid"]);
+  });
+});
+
+describe("docker ownership labels (#4181)", () => {
+  it("owner, batch, lane, issue and expires, in order; values cannot inject", () => {
+    assert.deepEqual(dockerLabels({ batch: "b1", lane: "lean-7", issue: 7, expires: 123 }),
+      ["forgedock.owner=1", "forgedock.batch=b1", "forgedock.lane=lean-7", "forgedock.issue=7", "forgedock.expires=123"]);
+    const l = dockerLabels({ batch: "a b;rm -rf", lane: "", issue: null, expires: undefined });
+    assert.equal(l[1], "forgedock.batch=a-b-rm--rf"); assert.equal(l[2], "forgedock.lane=unknown"); assert.equal(l[3], "forgedock.issue=unknown");
+    for (const e of l) assert.match(e, /^forgedock\.[a-z]+=[A-Za-z0-9_.-]+$/);
+  });
+});

package/bin/lean/orchestrate.mjs

@@ -218,6 +218,15 @@ export async function orchestrate({ issues, parallel = 3, runOne, readBody, pref
     if (p) track(n, Promise.resolve(p).then((r) => settle(n, r, rec, checked.get(n) ?? null)));
     else { runRecs.delete(n); if (!pending.includes(n) && !results.has(n)) pending.unshift(n); }
   }
+  // A resume re-derives each unfinished issue's lane from its current milestone (#4153): a re-milestone takes effect.
+  if (saved && resolveLane) {
+    for (const n of order) {
+      if (results.has(n) || running.has(n)) continue;
+      let l; try { l = await resolveLane(n); } catch (e) { l = { ok: false, code: "lane.unresolved", detail: e?.message ?? String(e) }; }
+      lanes.set(n, l);
+    }
+    noteCrossLane();
+  }
   save();
 
   const K = () => { let k = null; try { k = getParallel?.(); } catch { k = null; } return Number.isInteger(k) && k >= 1 ? k : parallel; };

package/bin/lean/prompts.mjs

@@ -12,6 +12,29 @@ export const CONTRACT_FILE = `${LEAN_DIR}/contract.json`;
 
 const HOST_RULES = `Host rules (many lanes share this machine): run only targeted tests (specific test files or -k filters), never the full suite. Never create extra checkouts, copies or base clones of the repo; compare against the base with git show or git diff origin/<base> instead. Never install browsers. Keep all scratch files under $TMPDIR.`;
 
+/** Verify-by-CI (#4167): in ci/hybrid mode the engine runs the repo's CI on GitHub runners; the host runs only light checks. */
+const LIGHT = "run only formatters and linters on the files you changed";
+const VERIFY_RUN = { ci: `${LIGHT} (no type-checks, test suites or test containers)`, hybrid: "run the targeted validate commands" };
+const VERIFY_RULES = {
+  ci: `Verification runs on CI (forge.yaml verify.mode: ci). Do NOT run type-checks (tsc and the like), test suites (pytest, jest, node --test and the like) or docker/test containers on this host: ${LIGHT}. The engine pushes the branch, runs CI and sends failures back to you. In ${RESULT_FILE} record each validate id you did not run as {"id":"V1","command":"","ci":true}.`,
+  hybrid: `Verification also runs on CI (forge.yaml verify.mode: hybrid). Run the targeted validate commands and ${LIGHT}; never the full suite and no docker/test containers. The engine pushes the branch, runs CI and sends failures back to you. Record each validate id you did not run as {"id":"V1","command":"","ci":true}.`,
+};
+const rerun = (mode) => (mode === "ci" ? `Re-run the light checks only (${LIGHT}); the engine re-verifies on CI` : "Re-run the validate commands");
+
+/** Base-sync conflict resolution: which checks to run after resolving (#4167: ci mode runs light checks only). */
+export const syncChecks = (mode = "local") => (mode === "ci" ? `${LIGHT} (the engine re-verifies on CI)` : "run the relevant tests");
+
+/** CI failed on the pushed branch (#4167): one fix round in the builder's own session. */
+export function ciFailurePrompt(failures, mode = "local") {
+  const list = failures.slice(0, 10).map((f) => `#### ${f.job ?? "check"}${f.url ? ` (${f.url})` : ""}\n${f.log ? `\`\`\`\n${f.log}\n\`\`\`` : "(no log available: open the url)"}`).join("\n\n");
+  return `CI failed on the pushed branch:\n\n${list}\n\nFix the cause in the code (or record a typed amendment with a why in ${RESULT_FILE}). ${rerun(mode)}, commit, and update ${IMPLEMENTATION_FILE} and ${RESULT_FILE}. Do not push or touch GitHub.`;
+}
+
+/** CI could not run (no workflow run, no checks, dispatch refused): the local fallback (#4167). */
+export function ciUnavailablePrompt() {
+  return `CI verification is unavailable for this branch, so verification falls back to this host. Run every validate command locally (targeted, as the host rules say), fix any failure, commit, and update ${IMPLEMENTATION_FILE} and ${RESULT_FILE} with each command's real exit code. Do not push or touch GitHub.`;
+}
+
 /** Builder call 1: investigate and write the contract. No code edits. */
 export function builderPlanPrompt(n) {
   return `Resolve issue #${n} (read it with gh issue view ${n} --comments). This first step is PLANNING ONLY: do not edit code, do not commit.
@@ -39,22 +62,25 @@ If the issue is already fixed or invalid, write ${RESULT_FILE} {"status":"alread
  "deliverables":[{"id":"D1","path":"<file to change>","change":"<what>","requirements":["R1"]}],
  "preserve":[{"id":"P1","what":"<caller, contract or behaviour that must not change, with its path>"}],
  "validate":[{"id":"V1","command":"<exact command: the new regression test plus the existing tests that reference the files you change>"}]}
-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. Then stop.
+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 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. Then stop.
 
 ${BLOCK_RULES}`;
 }
 
 /** Builder call 2, same session: implement the frozen contract. */
-export function builderImplementPrompt() {
-  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, run every validate command, and commit. Do not push or touch GitHub.
+export function builderImplementPrompt(mode = "local") {
+  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.
 
-${HOST_RULES}
+${HOST_RULES}${remote ? `\n\n${VERIFY_RULES[mode]}` : ""}
 
 The contract changes only through typed amendments in ${RESULT_FILE}, each with a why, which the engine posts on the issue:
 - {"kind":"add-deliverable","path":"<file>","why":""}: a file you must change that the contract did not list.
 - {"kind":"add-requirement","requirement":{"id":"R9","quote":"<verbatim from the issue>","disposition":"deliver|defer|post-deploy"},"why":""}: an issue requirement the contract missed.
 - {"kind":"defer|post-deploy","requirement":"R#","why":""}: a contracted requirement that becomes separate work or a post-deploy check. The engine files it as a tracked follow-up.
 Never report a deliver requirement as "deferred" or "follow-up" without an amendment.
+A new dependency between workspace packages in a package.json that no deliverable names (that package.json, with the package in its change) is blocked by the engine: add it through add-deliverable with a why naming the package, or do not add it.
 
 When done and committed, write ${IMPLEMENTATION_FILE} (markdown, no HTML comments):
 ### Approach
@@ -64,6 +90,8 @@ When done and committed, write ${IMPLEMENTATION_FILE} (markdown, no HTML comment
 ### Notes   (behavior changes, env vars)
 
 Finally write ${RESULT_FILE}: {"status":"fixed","summary":"one line","requirements":[{"id":"R1","status":"implemented|partial|missing","evidence":"file:line"}],"validation":[{"id":"V1","command":"","exit":0}],"tests":[{"command":"","result":"pass|fail: ...","fails_without_fix":true|false|"unknown"}],"amendments":[]}
+Docker: start containers with docker run --rm; pass --label for each entry of $FORGE_DOCKER_LABELS on every docker run, volume create, network create and build (compose: on services, volumes, networks); tear down via trap/finally.
+If you started Docker containers or volumes that are still there, list their names in ${RESULT_FILE} as "resources":{"containers":[],"volumes":[]} so the engine removes them when the lane ends.
 If you find you are blocked, write "status":"blocked" with a typed "block" instead.`;
 }
 
@@ -72,8 +100,13 @@ export function contractCorrectionPrompt(problems) {
 }
 
 /** The one bounded correction round, in the builder's own session. */
-export function conformanceResumePrompt(failures) {
-  return `The change does not conform to the frozen contract and the issue:\n${failures.slice(0, 30).map((f) => `- ${f.code}: ${String(f.detail).slice(0, 500)}`).join("\n")}\n\nFix each item in the code, or record a typed amendment with a why in ${RESULT_FILE}. Re-run the validate commands, commit, and update ${IMPLEMENTATION_FILE} and ${RESULT_FILE}. Do not push or touch GitHub.`;
+export function conformanceResumePrompt(failures, mode = "local") {
+  return `The change does not conform to the frozen contract and the issue:\n${failures.slice(0, 30).map((f) => `- ${f.code}: ${String(f.detail).slice(0, 500)}`).join("\n")}\n\nFix each item in the code, or record a typed amendment with a why in ${RESULT_FILE}. ${rerun(mode)}, commit, and update ${IMPLEMENTATION_FILE} and ${RESULT_FILE}. Do not push or touch GitHub.`;
+}
+
+/** forge#4159: the one resume for package.json edges between workspace packages the contract does not name. */
+export function structurePrompt(edges, mode = "local") {
+  return `This change adds dependencies between workspace packages that the frozen contract does not name:\n${edges.slice(0, 30).map((e) => `- ${e.from} -> ${e.to} (${e.kind}, ${e.manifest})`).join("\n")}\n\nFor each one, add it to the contract with a reason, or remove it: either record {"kind":"add-deliverable","path":"<that package.json>","why":"<names the package and why this dependency is right>"} in ${RESULT_FILE}, or drop the dependency from the package.json and the code that needs it. ${rerun(mode)}, commit, and update ${IMPLEMENTATION_FILE} and ${RESULT_FILE}. Do not push or touch GitHub.`;
 }
 
 /** Human-only block reasons (#4124). Everything else agents resolve: a dependency, a split, prod data monitoring can read. */
@@ -97,6 +130,7 @@ You receive the GitHub issue with its comments, the frozen contract (requirement
 - scope: one row per changed file: the deliverable id that authorizes it (deliverables may be directories or globs), "test", "incidental" (changelog, lockfile), or "none" with what it changes.
 - preserve: one row per preserve id: intact|violated|unverified, with path:line.
 - regressions: concrete breakages only, each with path:line.
+Start from <row_skeleton> when given: it already lists every row the engine requires. Keep every id and file, fill each status and evidence, and add issue_coverage rows for issue requirements the contract does not quote. Scope rows are needed only for the files listed there; the engine authorizes the rest.
 
 Output ONLY a JSON object in a json code fence:
 {"issue_coverage":[{"quote":"","contract_ids":["R1"],"status":"covered|narrowed|missing"}],"requirements":[{"id":"R1","status":"","evidence":"path:line","validated_by":"V1","deferral_ok":true,"note":""}],"scope":[{"file":"","authorized_by":"D1|test|none","note":""}],"preserve":[{"id":"P1","status":"","evidence":"path:line"}],"regressions":[{"at":"path:line","failure":""}],"verdict":"CONFORMS|NONCONFORMING","summary":"one line"}
@@ -132,9 +166,9 @@ export function boundDiff(diff, { stat = "", base = "", maxBytes = REVIEW_DIFF_M
     + (list.length ? `\n<omitted_files>\n${list.join("\n")}\n</omitted_files>` : "");
 }
 
-export function reviewerPrompt({ issue, comments = [], contract, result, files = [], diff, stat = "", base = "" }) {
+export function reviewerPrompt({ issue, comments = [], contract, result, files = [], diff, stat = "", base = "", structure = "", skeleton = null, retry = null }) {
   const notes = comments.map((c) => String(c?.body ?? "")).filter((b) => !/^<!-- FORGE:/.test(b.trim()));
-  return `Issue #${issue.number}: ${issue.title}\n\n<issue_body>\n${cap(issue.body ?? "", 20000)}\n</issue_body>\n\n<issue_comments>\n${cap(notes.join("\n---\n"), 8000)}\n</issue_comments>\n\n<contract>\n${cap(JSON.stringify(contract ?? {}, null, 1), 12000)}\n</contract>\n\n<builder_result>\n${cap(JSON.stringify(result ?? {}, null, 1), 6000)}\n</builder_result>\n\n<changed_files>\n${files.join("\n")}\n</changed_files>\n\n<diff>\n${boundDiff(diff, { stat, base })}\n</diff>`;
+  return `Issue #${issue.number}: ${issue.title}\n\n<issue_body>\n${cap(issue.body ?? "", 20000)}\n</issue_body>\n\n<issue_comments>\n${cap(notes.join("\n---\n"), 8000)}\n</issue_comments>\n\n<contract>\n${cap(JSON.stringify(contract ?? {}, null, 1), 12000)}\n</contract>\n\n<builder_result>\n${cap(JSON.stringify(result ?? {}, null, 1), 6000)}\n</builder_result>\n\n<changed_files>\n${files.join("\n")}\n</changed_files>\n\n<diff>\n${boundDiff(diff, { stat, base })}\n</diff>${structure ? `\n<structure>${String(structure).replace(/[\r\n]+/g, " ")}</structure>` : ""}${skeleton ? `\n\n<row_skeleton>\n${cap(JSON.stringify(skeleton), 12000)}\n</row_skeleton>` : ""}${retry?.problems?.length ? `\n\n<previous_reply_problems>\nYour previous reply was rejected as incomplete. Fix exactly these and return the complete corrected JSON:\n${retry.problems.slice(0, 60).map((x) => `- ${x}`).join("\n")}\n</previous_reply_problems>${retry.previous ? `\n\n<previous_reply>\n${cap(retry.previous, 8000)}\n</previous_reply>` : ""}` : ""}`;
 }
 
 /** Pre-filter (#4123): one read-only, single-turn check of an issue a cheap signal flagged as possibly already fixed. */

package/bin/lean/render.mjs

@@ -141,7 +141,7 @@ export function renderPrBody({ issue, investigation, contract, implementation, r
 
 // ---- trajectory ----
 export function renderTrajectory(T) {
-  const rows = [["Validate", T.validate], ["Plan", T.plan], ["Implement", T.implement], ["Review", T.review], ["PR", T.pr], ["Base Sync", T.baseSync ?? "not needed"], ["Merge", T.merge], ["Close", T.close]];
+  const rows = [["Validate", T.validate], ["Plan", T.plan], ["Implement", T.implement], ...(T.verify ? [["Verify", T.verify]] : []), ["Review", T.review], ["PR", T.pr], ["Base Sync", T.baseSync ?? "not needed"], ["Merge", T.merge], ["Close", T.close]];
   const cellPair = (v) => {
     const [res, notes] = Array.isArray(v) ? v : [v, ""];
     return `${cell(res ?? "not reached")} | ${notes ? cell(notes) : "-"}`;

package/bin/lean/verify.mjs

@@ -0,0 +1,113 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Verify-by-CI (#4167): run the lane's heavy verification on CI runners instead of the host. The engine pushes the
+ * branch, dispatches the configured workflow (or waits on the head commit's push-triggered checks), and returns the
+ * failed jobs' log tails for the builder's fix loop. All GitHub effects go through the injected io.
+ */
+import { ciPollDelayMs } from "../engine.mjs";
+
+export const VERIFY_MODES = Object.freeze(["local", "ci", "hybrid"]);
+/** Changed files that never need the CI matrix (docs-only lanes skip CI verification). */
+export const DEFAULT_SKIP_PATHS = Object.freeze(["*.md", "*.mdx", "*.rst", "*.txt", "docs/**", "devdocs/**"]);
+export const DEFAULT_MAX_ROUNDS = 2;
+/** 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). */
+export const DEFAULT_GRACE_MS = 5 * 60000;
+const LEAN_PREFIX = ".forge-lean/";
+const OK = ["success", "neutral", "skipped"];
+
+/**
+ * forge.yaml `verify:` section (block style; parseForgeYaml gives strings) → {mode, workflow, pathsInput, skipPaths,
+ * maxRounds}. Invalid values fall back to the defaults; mode defaults to local (today's behaviour).
+ */
+export function parseVerify(sec = {}) {
+  const s = sec && typeof sec === "object" ? sec : {};
+  const str = (v) => (v === undefined || v === null ? "" : String(v).trim());
+  const mode = VERIFY_MODES.includes(str(s.mode)) ? str(s.mode) : "local";
+  const workflow = /^[A-Za-z0-9._/-]+$/.test(str(s.workflow)) ? str(s.workflow) : null;
+  const pathsInput = /^[A-Za-z_][A-Za-z0-9_-]*$/.test(str(s.paths_input)) ? str(s.paths_input) : null;
+  const rawSkip = Array.isArray(s.skip_paths) ? s.skip_paths : str(s.skip_paths) ? str(s.skip_paths).split(",") : null;
+  const skipPaths = rawSkip ? rawSkip.map((x) => String(x).trim()).filter(Boolean) : [...DEFAULT_SKIP_PATHS];
+  const n = Number(str(s.max_rounds));
+  const maxRounds = str(s.max_rounds) !== "" && Number.isInteger(n) && n >= 0 && n <= 10 ? n : DEFAULT_MAX_ROUNDS;
+  return { mode, workflow, pathsInput, skipPaths, maxRounds };
+}
+
+const globRe = (g) => new RegExp(`^${g.split("**").map((p) => p.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")).join(".*")}$`);
+/** A glob without "/" matches the basename anywhere (gitignore style); one with "/" matches the whole path. */
+export function matchesGlob(file, glob) {
+  const f = String(file), g = String(glob).replace(/^\.?\//, "");
+  return g.includes("/") ? globRe(g).test(f) : globRe(g).test(f.split("/").at(-1));
+}
+/** Changed files that CI must see: everything except the engine's own `.forge-lean/` hand-off files. */
+export const verifiableFiles = (files) => (files ?? []).filter((f) => f && !String(f).startsWith(LEAN_PREFIX));
+/** True when every verifiable changed file matches a skip glob (a docs-only lane), or there is none. */
+export function skipsCi(files, skipPaths = DEFAULT_SKIP_PATHS) {
+  const fs = verifiableFiles(files);
+  return fs.every((f) => skipPaths.some((g) => matchesGlob(f, g)));
+}
+
+/** Tail each log so the total stays under `cap` characters. */
+export function capLogs(failures, cap = LOG_CAP) {
+  const per = Math.max(500, Math.floor(cap / Math.max(1, failures.length)));
+  return failures.map((f) => { const l = String(f.log ?? ""); return { ...f, log: l.length > per ? `…${l.slice(-per)}` : l }; });
+}
+const runIdOf = (url) => /\/actions\/runs\/(\d+)/.exec(String(url ?? ""))?.[1] ?? null;
+const sameSha = (a, b) => Boolean(a && b) && (String(a).startsWith(b) || String(b).startsWith(a));
+
+/**
+ * One CI verification of `head` on `branch`. Returns {result: pass|fail|timeout|unavailable|skipped, failures, runUrl,
+ * detail, runId}. `push` is called before any CI call (never for a skipped lane); `exclude` lists run ids already judged,
+ * so a re-dispatch on the same head never reuses an old run; `onPoll` runs before each wait (lease renew, progress).
+ */
+export async function runCiVerify({ io, branch, head, changedFiles, verify, ciMaxMinutes = 360, now = () => Date.now(), sleep, random = Math.random,
+  push = async () => {}, exclude = [], onPoll = async () => {}, graceMs = DEFAULT_GRACE_MS }) {
+  const v = verify ?? parseVerify({});
+  const files = verifiableFiles(changedFiles);
+  if (skipsCi(files, v.skipPaths)) return { result: "skipped", failures: [], runUrl: null, detail: `all ${files.length} changed file(s) match skip_paths` };
+  await push();
+  const startedAt = now();
+  const unavailable = (detail) => ({ result: "unavailable", failures: [], runUrl: null, detail });
+  if (v.workflow) {
+    if (!io.dispatchWorkflow || !io.workflowRuns) return unavailable("no workflow dispatch seam");
+    const inputs = v.pathsInput ? { [v.pathsInput]: files.join("\n") } : {};
+    try { await io.dispatchWorkflow({ workflow: v.workflow, ref: branch, inputs }); }
+    catch (e) { return unavailable(`workflow ${v.workflow} could not be dispatched: ${String(e?.stderr ?? e?.message ?? e).split("\n")[0].slice(0, 200)}`); }
+  } else if (!io.commitChecks) return unavailable("no commit-checks seam");
+  const skip = new Set(exclude.map(String));
+  for (let i = 0; ; i++) {
+    if (v.workflow) {
+      let runs = [];
+      try { runs = (await io.workflowRuns({ workflow: v.workflow, branch })) ?? []; } catch { runs = []; }
+      const run = runs.find((r) => sameSha(r?.headSha, head) && !skip.has(String(r?.databaseId)));
+      if (run && String(run.status).toLowerCase() === "completed") {
+        const c = String(run.conclusion ?? "").toLowerCase();
+        if (OK.includes(c)) return { result: "pass", failures: [], runUrl: run.url ?? null, runId: run.databaseId, detail: `${v.workflow} ${c}` };
+        let log = "";
+        try { log = String((await io.failedLogs?.(run.databaseId)) ?? ""); } catch { log = ""; }
+        return { result: "fail", failures: capLogs([{ job: run.name ?? v.workflow, url: run.url ?? null, log }]), runUrl: run.url ?? null, runId: run.databaseId, detail: `${v.workflow} ${c || "failed"}` };
+      }
+      if (!run && now() - startedAt >= graceMs) return unavailable(`no ${v.workflow} run for ${String(head).slice(0, 12)} appeared within ${Math.round(graceMs / 60000)} min`);
+    } else {
+      let checks = [];
+      try { checks = (await io.commitChecks(head)) ?? []; } catch { checks = []; }
+      if (!checks.length && now() - startedAt >= graceMs) return unavailable(`no checks reported for ${String(head).slice(0, 12)} within ${Math.round(graceMs / 60000)} min`);
+      if (checks.length && checks.every((c) => c.state !== "pending")) {
+        const failed = checks.filter((c) => c.state === "failure");
+        if (!failed.length) return { result: "pass", failures: [], runUrl: null, detail: `${checks.length} check(s) green` };
+        const logs = {}, out = [];
+        for (const c of failed) {
+          const id = runIdOf(c.url);
+          if (id && !(id in logs)) { try { logs[id] = String((await io.failedLogs?.(id)) ?? ""); } catch { logs[id] = ""; } }
+          out.push({ job: c.name, url: c.url ?? null, log: id && !out.some((x) => runIdOf(x.url) === id) ? logs[id] : "" });
+        }
+        return { result: "fail", failures: capLogs(out), runUrl: failed[0].url ?? null, detail: `${failed.length} check(s) failed: ${failed.map((c) => c.name).join(", ")}` };
+      }
+    }
+    if (now() - startedAt >= ciMaxMinutes * 60000) return { result: "timeout", failures: [], runUrl: null, detail: `CI still pending after ${ciMaxMinutes} min` };
+    await onPoll();
+    await sleep(ciPollDelayMs(i, random));
+  }
+}

package/bin/lean/verify.test.mjs

@@ -0,0 +1,95 @@
+// 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 { parseVerify, matchesGlob, skipsCi, capLogs, runCiVerify, DEFAULT_SKIP_PATHS, LOG_CAP } from "./verify.mjs";
+import { precheck } from "./conformance.mjs";
+
+const HEAD = "abc123abc123abc123";
+/** Fake io + clock: `runs` is a list of successive workflowRuns answers (the last repeats); `checks` likewise. */
+function fake(o = {}) {
+  const f = { clock: 0, dispatched: [], logsFor: [], pushes: 0, runsQ: [...(o.runs ?? [])], checksQ: [...(o.checks ?? [])] };
+  f.io = {
+    dispatchWorkflow: async (a) => { if (o.dispatchError) throw Object.assign(new Error("HTTP 422"), { stderr: o.dispatchError }); f.dispatched.push(a); },
+    workflowRuns: async () => (f.runsQ.length > 1 ? f.runsQ.shift() : f.runsQ[0] ?? []),
+    commitChecks: async () => (f.checksQ.length > 1 ? f.checksQ.shift() : f.checksQ[0] ?? []),
+    failedLogs: async (id) => { f.logsFor.push(String(id)); return o.log ?? `log of ${id}`; },
+  };
+  f.args = (extra = {}) => ({ io: f.io, branch: "feat/issue-7-lean", head: HEAD, changedFiles: ["src/a.ts", ".forge-lean/result.json"], verify: parseVerify({ mode: "ci", workflow: "verify.yml", paths_input: "changed_paths" }),
+    ciMaxMinutes: 30, now: () => f.clock, sleep: async (ms) => { f.clock += ms; }, random: () => 0.5, push: async () => { f.pushes++; }, ...extra });
+  return f;
+}
+
+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 });
+    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 });
+    assert.equal(parseVerify({ mode: "remote" }).mode, "local");
+    assert.equal(parseVerify({ workflow: "x; rm -rf /" }).workflow, null);
+    assert.equal(parseVerify({ max_rounds: "-1" }).maxRounds, 2);
+    assert.equal(parseVerify({ max_rounds: "0" }).maxRounds, 0);
+    assert.equal(parseVerify({ mode: "hybrid" }).mode, "hybrid");
+  });
+  it("globs: a pattern without / matches the basename anywhere; ** spans directories", () => {
+    assert.ok(matchesGlob("README.md", "*.md")); assert.ok(matchesGlob("pkg/a/CHANGELOG.md", "*.md"));
+    assert.ok(matchesGlob("docs/guide/x.png", "docs/**")); assert.ok(!matchesGlob("src/docs/x.ts", "docs/**"));
+    assert.ok(!matchesGlob("src/a.ts", "*.md")); assert.ok(!matchesGlob("a.mdx.ts", "*.mdx"));
+  });
+  it("a docs-only change skips CI; one code file does not; .forge-lean files are ignored", () => {
+    assert.ok(skipsCi(["README.md", "docs/a.md", ".forge-lean/result.json"]));
+    assert.ok(!skipsCi(["README.md", "src/a.ts"]));
+    assert.ok(!skipsCi(["poetry.lock"]), "a lock file is never docs-only");
+  });
+  it("capLogs keeps the tails within the cap", () => {
+    const out = capLogs([{ job: "a", log: "x".repeat(50000) + "END-A" }, { job: "b", log: "short" }]);
+    assert.ok(out[0].log.endsWith("END-A")); assert.ok(out[0].log.length <= LOG_CAP / 2 + 1); assert.equal(out[1].log, "short");
+  });
+  it("precheck: a CI-verified head covers validate ids left to CI; a recorded failure still fails", () => {
+    const contract = { requirements: [], deliverables: [{ id: "D1", path: "src/a.ts", change: "x", requirements: [] }], validate: [{ id: "V1", command: "tsc" }, { id: "V2", command: "lint" }] };
+    const result = { validation: [{ id: "V1", command: "tsc", ci: true }, { id: "V2", command: "lint", exit: 0 }] };
+    const kinds = (r, ciVerified) => precheck({ contract, result: r, changedFiles: ["src/a.ts"], ciVerified }).failures.map((f) => f.kind);
+    assert.deepEqual(kinds(result, false), ["validate_missing"]);
+    assert.deepEqual(kinds(result, true), []);
+    assert.deepEqual(kinds({ validation: [] }, true), []);
+    assert.deepEqual(kinds({ validation: [{ id: "V1", exit: 0 }, { id: "V2", exit: 1 }] }, true), ["validate_failed"]);
+  });
+});
+
+describe("runCiVerify (#4167)", () => {
+  it("docs-only: skipped without a push or any CI call", async () => {
+    const f = fake();
+    const r = await runCiVerify(f.args({ changedFiles: ["README.md", "docs/x.md"] }));
+    assert.equal(r.result, "skipped"); assert.equal(f.pushes, 0); assert.equal(f.dispatched.length, 0);
+  });
+  it("workflow: pushes, dispatches on the branch with the changed paths, waits for the run of this head, passes", async () => {
+    const f = fake({ runs: [[], [{ databaseId: 9, headSha: HEAD, status: "in_progress" }], [{ databaseId: 9, headSha: HEAD, status: "completed", conclusion: "success", url: "u9" }]] });
+    const r = await runCiVerify(f.args());
+    assert.equal(r.result, "pass"); assert.equal(r.runId, 9); assert.equal(f.pushes, 1);
+    assert.deepEqual(f.dispatched, [{ workflow: "verify.yml", ref: "feat/issue-7-lean", inputs: { changed_paths: "src/a.ts" } }]);
+  });
+  it("workflow: a red run returns the failed-job log; excluded (already judged) runs are never reused", async () => {
+    const f = fake({ runs: [[{ databaseId: 1, headSha: HEAD, status: "completed", conclusion: "failure" }, { databaseId: 2, headSha: HEAD, status: "completed", conclusion: "failure", name: "verify", url: "u2" }]], log: "poetry.lock is out of date" });
+    const r = await runCiVerify(f.args({ exclude: [1] }));
+    assert.equal(r.result, "fail"); assert.equal(r.runId, 2); assert.deepEqual(f.logsFor, ["2"]);
+    assert.deepEqual(r.failures, [{ job: "verify", url: "u2", log: "poetry.lock is out of date" }]);
+  });
+  it("workflow: a refused dispatch, or no run within the grace period, is unavailable (local fallback)", async () => {
+    assert.equal((await runCiVerify(fake({ dispatchError: "workflow does not have workflow_dispatch trigger" }).args())).result, "unavailable");
+    const r = await runCiVerify(fake({ runs: [[{ databaseId: 5, headSha: "other", status: "completed", conclusion: "success" }]] }).args());
+    assert.equal(r.result, "unavailable"); assert.match(r.detail, /no verify\.yml run/);
+  });
+  it("slow CI is a timeout at the budget, never a failure", async () => {
+    const f = fake({ runs: [[{ databaseId: 3, headSha: HEAD, status: "queued" }]] });
+    const r = await runCiVerify(f.args({ ciMaxMinutes: 10 }));
+    assert.equal(r.result, "timeout"); assert.ok(f.clock >= 10 * 60000);
+  });
+  it("no workflow: waits on the head's push-triggered checks and fetches each failed Actions run's log once", async () => {
+    const f = fake({ checks: [[{ name: "lint", state: "pending" }], [{ name: "lint", state: "success" }, { name: "test", state: "failure", url: "https://github.com/o/r/actions/runs/55/job/1" }, { name: "types", state: "failure", url: "https://github.com/o/r/actions/runs/55/job/2" }]] });
+    const r = await runCiVerify(f.args({ verify: parseVerify({ mode: "ci" }) }));
+    assert.equal(r.result, "fail"); assert.deepEqual(f.logsFor, ["55"]); assert.equal(f.dispatched.length, 0);
+    assert.deepEqual(r.failures.map((x) => [x.job, Boolean(x.log)]), [["test", true], ["types", false]]);
+    const g = fake({ checks: [[]] });
+    assert.equal((await runCiVerify(g.args({ verify: parseVerify({ mode: "ci" }) }))).result, "unavailable");
+  });
+});

package/commands/adopt.md

@@ -421,6 +421,9 @@ Where `{reason}` is a brief signal: "confirmed bug + file refs", "P1 + acceptanc
 
 4. To re-run adoption on newly added issues:
    \`/adopt\` (already-labeled issues are skipped automatically)
+
+{If the repo's boundary config contains an allow-all rule (check as in `/forgedock-init` 2G: eslint-plugin-boundaries `from: [X], allow: ['*']`, dependency-cruiser with no `forbidden` rules, Nx `onlyDependOnLibsWithTags: ['*']`), add once:}
+5. Your boundary config allows every package to import every package ({FILE}: {RULE}). Consider tightening it per package; core work-on only reports import growth along allowed edges.
 ```
 
 ---

package/commands/audit.md

@@ -261,14 +261,9 @@ Classify where the breakdown occurred. Use these categories:
 - **Root cause**: The single most impactful failure point. If THIS had worked, the problem wouldn't have reached production.
 - **Contributing factors**: Other pipeline links that could have caught it as a safety net but didn't.
 
-### 3D: Cross-reference with Pipeline Hardening Principles
+### 3D: Cross-reference with the hardening layers
 
-Before proposing a fix, check which layer it belongs to (from CLAUDE.md):
-
-- **Quality gate** → static analysis, grep-catchable patterns
-- **Review agents** → semantic reasoning, library API contracts, cross-service interactions
-- **Domain detection** → broad category matching, not per-bug-instance
-- **Builder rules** → prevention at write time, simple memorable rules
+Before proposing a fix, pick its layer from `NORTHSTAR.md` § Where a fix belongs: the earliest, cheapest layer that would have stopped it (issue spec/plan rule → builder rule → deterministic check → domain detection → review prompt line → new agent, last resort).
 
 **Do NOT propose a quality-gate grep check for a reasoning failure. Do NOT propose a review-agent prompt change for a pattern grep could catch.**
 
@@ -368,7 +363,7 @@ Files that need changes:
 - If tightening a review agent: describe the reasoning step to add
 - If adding context/architect guidance: describe the lookup or trace step}
 
-**Hardening layer justification** (per CLAUDE.md Pipeline Hardening Principles):
+**Hardening layer justification** (per `NORTHSTAR.md` § Where a fix belongs):
 {Explain why this fix belongs in the proposed layer and not another}
 
 ### Related Prior Work