forgedock 1.25.1 → 1.26.0

package/bin/engine/outcome-codes.mjs

@@ -63,6 +63,18 @@ export const OUTCOME_CODES = Object.freeze({
   BUILDER_NO_COMMIT: "builder.no_commit",
   REVIEW_FAILED: "review.failed",
   REVIEW_NO_VERDICT: "review.no_verdict",
+  // Core work-on conformance gate (bin/lean/conformance.mjs).
+  CONTRACT_INVALID: "contract.invalid",
+  REVIEW_INCOMPLETE: "review.incomplete",
+  REVIEW_INCONSISTENT: "review.inconsistent",
+  CONFORMANCE_OMISSION: "conformance.omission",
+  CONFORMANCE_UNIMPLEMENTED: "conformance.unimplemented",
+  CONFORMANCE_SCOPE_CREEP: "conformance.scope_creep",
+  CONFORMANCE_UNTRACKED_DEFERRAL: "conformance.untracked_deferral",
+  CONFORMANCE_UNJUSTIFIED_DEFERRAL: "conformance.unjustified_deferral",
+  CONFORMANCE_PRESERVE_VIOLATED: "conformance.preserve_violated",
+  CONFORMANCE_REGRESSION: "conformance.regression",
+  FOLLOWUP_UNAVAILABLE: "followup.unavailable",
   MERGE_HEAD_MISMATCH: "merge.head_mismatch",
   // Non-failure terminals, so a RUN_TERMINAL for a healthy run is not counted as a gap.
   COMPLETED: "completed",

package/bin/engine-cli.mjs

@@ -94,6 +94,13 @@ export function readEnginePath(cwd = process.cwd()) {
     return ENGINE_PATHS.includes(v) ? v : undefined;
   } catch { return undefined; }
 }
+/** forge.yaml `engine.conformance` (shadow|enforce) for the core work-on gate; undefined when absent or invalid (the core defaults to shadow). */
+export function readConformanceMode(cwd = process.cwd()) {
+  try {
+    const v = String(parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.engine?.conformance ?? "").trim();
+    return ["shadow", "enforce"].includes(v) ? v : undefined;
+  } catch { return undefined; }
+}
 function readLeanSetting(key, cwd = process.cwd()) {
   try {
     const v = String(parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.engine?.[`lean_${key}`] ?? "").trim();
@@ -528,7 +535,7 @@ export async function runFromCli(argv, deps = {}) {
     try {
       lres = await runCore({ issue, repo: leanRepo, ...(lane ? { lane } : {}), laneOverride, branches: readBranches(), cwd: process.cwd(), dir, io: leanIo, path: enginePath, onProgress,
       emitTelemetry: deps.emitTelemetry ?? makeEmitTelemetry({ repo: leanRepo }),
-      admission: readAdmission(), ...readCoreLimits(), ...(readMergeWait() ? { mergeWait: readMergeWait() } : {}), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model") ? { reviewerModel: readLeanSetting("reviewer_model") } : {}) });
+      admission: readAdmission(), ...readCoreLimits(), ...(readMergeWait() ? { mergeWait: readMergeWait() } : {}), ...(readConformanceMode() ? { conformance: readConformanceMode() } : {}), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model") ? { reviewerModel: readLeanSetting("reviewer_model") } : {}) });
     } catch (e) { report({ terminalReason: "engine-error", detail: String(e?.message ?? e).slice(0, 500) }); throw e; }
     report(lres);
     if (lres.code === "host.busy") { console.log(`issue #${issue} → deferred (${lres.detail})`); return lres; }
@@ -780,7 +787,7 @@ export async function orchestrateFromCli(argv, deps = {}) {
     const { runCore } = deps.leanModule;
     const emitTelemetry = deps.emitTelemetry ?? makeEmitTelemetry({ repo });
     lanes = { adopt: null, runOne: (n, ln) => runCore({ issue: n, repo, lane: ln, laneOverride, branches, cwd, dir, io: leanIo, agentId: `orch_${process.pid}_${n}`, emitTelemetry,
-      admission: readAdmission(cwd), ...readCoreLimits(cwd), ...(readMergeWait(cwd) ? { mergeWait: readMergeWait(cwd) } : {}), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model", cwd) ? { reviewerModel: readLeanSetting("reviewer_model", cwd) } : {}) }) };
+      admission: readAdmission(cwd), ...readCoreLimits(cwd), ...(readMergeWait(cwd) ? { mergeWait: readMergeWait(cwd) } : {}), ...(readConformanceMode(cwd) ? { conformance: readConformanceMode(cwd) } : {}), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model", cwd) ? { reviewerModel: readLeanSetting("reviewer_model", cwd) } : {}) }) };
   } else {
     lanes = batchMod.detachedLanes({ batch, cwd, script: deps.laneScript ?? fileURLToPath(new URL("./forgedock.mjs", import.meta.url)), bin: deps.laneBin, pollMs: deps.pollMs,
       laneArgs: (n, ln) => ["--repo", repo, ...(ln ? ["--lane", ln] : []), ...(laneOverride ? ["--lane-override"] : []), ...(model ? ["--model", model] : [])] });

package/bin/lean/conformance.e2e.test.mjs

@@ -0,0 +1,232 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * End-to-end conformance gate on a disposable REAL git repository: a bare origin with main + staging, a clone,
+ * lane worktrees, real commits, diffs, test runs and --no-ff merges into staging. GitHub is in-memory. The builder
+ * makes real code edits; the reviewer is an oracle that derives every row from the real worktree (or a generic PASS).
+ * Fixture: a small service whose routes leak a spend reservation on 429; issue #101 asks for three routes fixed or
+ * tracked, the 429 re-thrown unchanged, a regression test, and billing pricing unchanged.
+ */
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync, spawnSync } from "node:child_process";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { runCore } from "./lean.mjs";
+
+const GIT_ENV = { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@example.invalid", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@example.invalid", GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1" };
+const git = (args, cwd) => { try { return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: GIT_ENV }); } catch (e) { throw Object.assign(new Error(`git ${args.join(" ")}: ${e.stderr || e.message}`), { stderr: String(e.stderr ?? "") }); } };
+const HAVE_GIT = spawnSync("git", ["--version"]).status === 0;
+const writeAll = (root, files) => { for (const [p, c] of Object.entries(files)) { fs.mkdirSync(path.dirname(path.join(root, p)), { recursive: true }); fs.writeFileSync(path.join(root, p), c); } };
+
+// ---- fixture ----
+const Q = {
+  R1: "The scrape route must release the spend reservation when the rate limiter rejects the request.",
+  R2: "The search route must release the spend reservation when the rate limiter rejects the request.",
+  R3: "The export route has the same leak and must be fixed or tracked in a follow-up issue.",
+  R4: "The original 429 error must be re-thrown unchanged (status 429 and retryAfter preserved).",
+  AC1: "A regression test shows outstanding reservations return to 0 after a 429 on each fixed route.",
+  AC2: "Existing route tests still pass.",
+  AC3: "Billing pricing is unchanged.",
+};
+const ISSUE = { number: 101, title: "429 from the rate limiter leaks the spend reservation in scrape, search and export",
+  body: `## Problem\nWhen the per-user rate limiter rejects a request with 429, the scrape, search and export routes have already reserved spend and never release it.\n\n## Requirements\n1. ${Q.R1}\n2. ${Q.R2}\n3. ${Q.R3}\n4. ${Q.R4}\n\n## Acceptance Criteria\n- [ ] ${Q.AC1}\n- [ ] ${Q.AC2}\n- [ ] ${Q.AC3}` };
+const FN = { scrape: "scrape", search: "search", export: "exportData" };
+const route = (r, fixed) => `import { reserve, ${fixed ? "release, " : ""}settle } from "../quota.js";\nimport { check } from "../ratelimit.js";\n\nexport async function ${FN[r]}(req, limits) {\n  const id = reserve(req.user, 1);\n${fixed ? "  try {\n    check(req.user, limits);\n  } catch (e) {\n    release(id);\n    throw e;\n  }" : "  check(req.user, limits);"}\n  settle(id);\n  return { ok: true, ${r}: req.q };\n}\n`;
+const BILLING = "export function price(units) { return units * 0.01; }\n";
+const BASE = {
+  "package.json": `{ "name": "fixture-svc", "type": "module", "private": true }\n`,
+  "src/quota.js": "const r = new Map();\nlet n = 1;\nexport function reserve(user, amount) { const id = n++; r.set(id, { user, amount }); return id; }\nexport function release(id) { return r.delete(id); }\nexport function settle(id) { return r.delete(id); }\nexport function outstanding() { return r.size; }\nexport function _reset() { r.clear(); n = 1; }\n",
+  "src/ratelimit.js": "export class RateLimited extends Error { constructor(s) { super(\"rate limited\"); this.status = 429; this.retryAfter = s; } }\nexport function check(user, limits) { if ((limits[user] ?? 1) <= 0) throw new RateLimited(30); limits[user] = (limits[user] ?? 1) - 1; }\n",
+  "src/billing.js": BILLING,
+  "src/routes/scrape.js": route("scrape", false), "src/routes/search.js": route("search", false), "src/routes/export.js": route("export", false),
+  "test/routes.test.js": `import test from "node:test";\nimport assert from "node:assert/strict";\nimport { scrape } from "../src/routes/scrape.js";\nimport { price } from "../src/billing.js";\ntest("scrape answers under the limit", async () => assert.deepEqual(await scrape({ user: "u", q: "a" }, { u: 3 }), { ok: true, scrape: "a" }));\ntest("price", () => assert.equal(price(150), 1.5));\n`,
+};
+const leakTest = (rs) => `import test from "node:test";\nimport assert from "node:assert/strict";\nimport { outstanding, _reset } from "../src/quota.js";\n${rs.map((r) => `import { ${FN[r]} } from "../src/routes/${r}.js";`).join("\n")}\nfor (const [n, fn] of [${rs.map((r) => `["${r}", ${FN[r]}]`).join(", ")}]) test(\`\${n}: 429 releases and re-throws\`, async () => { _reset(); await assert.rejects(fn({ user: "u", q: "x" }, { u: 0 }), (e) => e.status === 429 && e.retryAfter === 30); assert.equal(outstanding(), 0); });\n`;
+const V1 = "node --test test/routes.test.js test/leak.test.js"; // explicit files: Node 26 rejects directory args to --test
+
+const D = { R1: { id: "D1", path: "src/routes/scrape.js", change: "release on 429", requirements: ["R1", "R4"] }, R2: { id: "D2", path: "src/routes/search.js", change: "release on 429", requirements: ["R2", "R4"] },
+  R3: { id: "D3", path: "src/routes/export.js", change: "release on 429", requirements: ["R3", "R4"] }, R5: { id: "D4", path: "test/leak.test.js", change: "regression test", requirements: ["R5"] } };
+const req = (id, disposition = "deliver", extra = {}) => ({ id, quote: Q[id === "R5" ? "AC1" : id], disposition, ...extra });
+const contract = (reqs) => ({ requirements: reqs, deliverables: reqs.filter((r) => r.disposition === "deliver" && D[r.id]).map((r) => D[r.id]),
+  preserve: [{ id: "P1", what: `${Q.AC3} (src/billing.js price())` }, { id: "P2", what: `${Q.AC2} (test/routes.test.js)` }], validate: [{ id: "V1", command: V1 }] });
+const FULL = () => contract([req("R1"), req("R2"), req("R3"), req("R4"), req("R5")]);
+const OMIT = () => contract([req("R1"), req("R2"), req("R4"), req("R5")]);
+const DEFER = () => contract([req("R1"), req("R2"), req("R3", "defer", { why: "export.js ships on the data-export module's own release train" }), req("R4"), req("R5")]);
+
+// ---- world ----
+function makeWorld(dir, script) {
+  const origin = path.join(dir, "origin.git"), repo = path.join(dir, "repo"), merger = path.join(dir, "merger");
+  git(["init", "-q", "--bare", "-b", "main", origin], dir);
+  git(["clone", "-q", origin, repo], dir);
+  writeAll(repo, BASE);
+  git(["add", "-A"], repo); git(["commit", "-q", "-m", "base"], repo);
+  git(["push", "-q", "origin", "main"], repo); git(["push", "-q", "origin", "main:staging"], repo); git(["fetch", "-q", "origin"], repo);
+  git(["clone", "-q", origin, merger], dir);
+  const gh = { issues: { 101: { ...ISSUE, state: "OPEN", reason: null, labels: new Set(), comments: [] } }, next: 200, prs: [] };
+  const counts = { builder: 0, reviewer: 0 };
+  const tools = (wt) => ({
+    write: (files) => writeAll(wt, files),
+    lean: (name, v) => writeAll(wt, { [`.forge-lean/${name}`]: typeof v === "string" ? v : JSON.stringify(v) }),
+    commit: (m) => { git(["add", "-A"], wt); if (git(["status", "--porcelain"], wt).trim()) git(["commit", "-q", "-m", m], wt); },
+    restore: (p) => git(["checkout", "origin/staging", "--", p], wt),
+    run: (cmd) => spawnSync("sh", ["-c", cmd], { cwd: wt, encoding: "utf8" }).status,
+    changed: () => git(["diff", "--name-only", "origin/staging...HEAD"], wt).trim().split("\n").filter(Boolean),
+  });
+  const io = {
+    gh: async (a) => {
+      const k = a.slice(0, 2).join(" "), n = Number(a[2]), val = (f) => a[a.indexOf(f) + 1];
+      if (a[0] === "api") return "";
+      if (k === "repo view") return "main\n";
+      if (k === "issue view" && a.includes("milestone")) return JSON.stringify({ milestone: null });
+      if (k === "issue view") { const i = gh.issues[n]; return JSON.stringify({ number: i.number, title: i.title, body: i.body, state: i.state, comments: [] }); }
+      if (k === "issue comment") { gh.issues[n].comments.push(val("--body")); return `https://github.com/o/r/issues/${n}#c${gh.issues[n].comments.length}\n`; }
+      if (k === "issue edit") { for (let i = 0; i < a.length; i++) { if (a[i] === "--add-label") a[i + 1].split(",").forEach((l) => gh.issues[n].labels.add(l)); if (a[i] === "--remove-label") a[i + 1].split(",").forEach((l) => gh.issues[n].labels.delete(l)); } return ""; }
+      if (k === "issue close") { Object.assign(gh.issues[n], { state: "CLOSED", reason: val("--reason") }); return ""; }
+      if (k === "pr list") return "[]";
+      if (k === "pr create") { const p = { number: 300 + gh.prs.length, base: val("--base"), head: val("--head"), body: val("--body"), state: "OPEN" }; gh.prs.push(p); return `https://github.com/o/r/pull/${p.number}\n`; }
+      if (k === "pr view") return JSON.stringify({ mergeable: "MERGEABLE", mergeStateStatus: "CLEAN" });
+      if (k === "pr merge") {
+        const p = gh.prs.find((x) => x.number === n);
+        git(["fetch", "-q", "origin"], merger);
+        assert.ok(git(["rev-parse", `origin/${p.head}`], merger).startsWith(val("--match-head-commit").slice(0, 12)), "merges only the reviewed head");
+        git(["checkout", "-q", "-B", p.base, `origin/${p.base}`], merger);
+        git(["merge", "-q", "--no-ff", "-m", `Merge PR #${n}`, `origin/${p.head}`], merger);
+        git(["push", "-q", "origin", p.base], merger);
+        p.state = "MERGED"; return "";
+      }
+      throw new Error(`unexpected gh ${a.join(" ")}`);
+    },
+    git: async (args, { cwd } = {}) => git(args, cwd ?? repo),
+    runner: async (c) => {
+      const n = ++counts[c.role];
+      const text = c.role === "builder" ? (await script.builder(n, c, tools(c.cwd)), "done") : script.reviewer(n, c);
+      return { text, sessionId: "sess-1", usage: { input_tokens: 1, output_tokens: 1 }, costUsd: 0, durationMs: 1, turns: 1, model: "m" };
+    },
+    transitionLabel: async (n, st) => { const i = gh.issues[n]; for (const l of [...i.labels]) if (l.startsWith("workflow:")) i.labels.delete(l); i.labels.add(`workflow:${st}`); },
+    requiredChecks: async () => [],
+    fileFollowups: async ({ parent, items }) => { // stands in for scripts/file-deferred-followups.sh: ONE batched issue per parent
+      let f = Object.values(gh.issues).find((i) => i.parent === parent);
+      if (!f) { f = { number: gh.next++, parent, title: `Follow-up from #${parent}`, body: "", state: "OPEN", labels: new Set(), comments: [], items: [] }; gh.issues[f.number] = f; }
+      for (const it of items) if (!f.items.includes(it.key)) f.items.push(it.key);
+      return Object.fromEntries(items.map((i) => [i.key, f.number]));
+    },
+    fs: { read: async (p) => fs.readFileSync(p, "utf8"), stat: async (p) => fs.statSync(p), append: async (p, t) => fs.appendFileSync(p, t), write: async (p, t) => fs.writeFileSync(p, t),
+      exists: async (p) => fs.existsSync(p), rmdir: async (p) => fs.rmSync(p, { recursive: true, force: true }) },
+  };
+  const observe = (ret) => {
+    git(["fetch", "-q", "origin"], merger);
+    const staged = (p) => git(["show", `origin/staging:${p}`], merger);
+    const i = gh.issues[101], pr = gh.prs[0];
+    return { ret, issue: i, pr, counts, followups: Object.values(gh.issues).filter((x) => x.number !== 101),
+      markers: i.comments.map((c) => /<!-- (FORGE:[A-Z_]+)/.exec(c)?.[1]),
+      staging: { search: staged("src/routes/search.js").includes("release(id)"), export: staged("src/routes/export.js").includes("release(id)"), billingChanged: staged("src/billing.js") !== BILLING } };
+  };
+  return { io, repo, observe };
+}
+
+// ---- builder and reviewer scripts ----
+const fix = (t, rs) => t.write(Object.fromEntries([...rs.map((r) => [`src/routes/${r}.js`, route(r, true)]), ["test/leak.test.js", leakTest(rs)]]));
+const claimAll = (k) => k.requirements.map((r) => ({ id: r.id, status: r.disposition === "deliver" ? "implemented" : "deferred", evidence: D[r.id] ? `${D[r.id].path}:7` : "" }));
+function builderScript(cs) {
+  let res = null;
+  const finish = (t) => { res.validation = [{ id: "V1", command: V1, exit: t.run(V1) }]; t.lean("implementation.md", `### Approach\nrelease in a catch\n\n### Changes\n${t.changed().map((f) => `- ${f}`).join("\n")}\n\n### Acceptance Criteria Status\n- see result\n\n### Verification\n- ${V1}\n\n### Notes\nnone`); t.lean("result.json", res); };
+  return async (n, c, t) => {
+    if (n === 1) { t.lean("investigation.md", "**Verdict**: CONFIRMED\n**Confidence**: high\n**Severity**: high\n**Task Type**: bug\n\n### Root Cause\ncheck() throws after reserve() with no release"); t.lean("contract.json", cs.contract()); return; }
+    if (n === 2) { cs.impl(t); t.commit("fix: release on 429"); res = { status: "fixed", summary: "release on 429", requirements: (cs.claims ?? claimAll)(cs.contract()), amendments: [] }; finish(t); return; }
+    if (cs.resume) { cs.resume(t, res); t.commit("fix: conformance"); }
+    finish(t);
+  };
+}
+/** A diligent reviewer made deterministic: every row comes from the worktree the engine handed it. */
+function oracle(c) {
+  const between = (tag) => c.prompt.split(`<${tag}>\n`)[1].split(`\n</${tag}>`)[0];
+  const k = JSON.parse(between("contract")), files = between("changed_files").split("\n").filter(Boolean);
+  const read = (p) => { try { return fs.readFileSync(path.join(c.cwd, p), "utf8"); } catch { return ""; } };
+  const lineOf = (p, s) => read(p).split("\n").findIndex((l) => l.includes(s)) + 1;
+  const R = { R1: "scrape", R2: "search", R3: "export" };
+  const rows = k.requirements.map((r) => {
+    if (r.disposition !== "deliver") return { id: r.id, status: r.disposition === "defer" ? "deferred" : r.disposition, deferral_ok: Boolean(r.why) };
+    if (R[r.id]) { const p = `src/routes/${R[r.id]}.js`; return read(p).includes("release(id)") ? { id: r.id, status: "implemented", evidence: `${p}:${lineOf(p, "release(id)")}`, validated_by: "V1" } : { id: r.id, status: "missing", evidence: `${p}:${lineOf(p, "check(")}`, note: "no release on 429" }; }
+    if (r.id === "R4") return { id: "R4", status: "implemented", evidence: `src/routes/scrape.js:${lineOf("src/routes/scrape.js", "throw e")}`, validated_by: "V1" };
+    return { id: r.id, status: read("test/leak.test.js") ? "implemented" : "missing", evidence: "test/leak.test.js:5", validated_by: "V1" };
+  });
+  const covered = (q) => k.requirements.some((r) => r.quote === q) || k.preserve.some((p) => p.what.includes(q));
+  const billing = git(["diff", "--name-only", "origin/staging...HEAD", "--", "src/billing.js"], c.cwd).trim() !== "";
+  const rv = { issue_coverage: Object.values(Q).map((q) => ({ quote: q, status: covered(q) ? "covered" : "missing" })), requirements: rows,
+    scope: files.map((f) => ({ file: f, authorized_by: k.deliverables.find((d) => d.path === f)?.id ?? (f.startsWith("test/") ? "test" : "none") })),
+    preserve: [{ id: "P1", status: billing ? "violated" : "intact", evidence: "src/billing.js:1" }, { id: "P2", status: "intact", evidence: "test/routes.test.js:1" }], regressions: [] };
+  const bad = rv.issue_coverage.some((x) => x.status !== "covered") || rows.some((r) => ["missing", "partial"].includes(r.status)) || rv.scope.some((s) => s.authorized_by === "none") || billing;
+  return "```json\n" + JSON.stringify({ ...rv, verdict: bad ? "NONCONFORMING" : "CONFORMS", summary: "oracle" }) + "\n```";
+}
+const generic = () => "```json\n" + JSON.stringify({ verdict: "PASS", fixes_issue: true, regression: false, reason: "looks good" }) + "\n```";
+
+async function runCase(cs, conformance = "enforce") {
+  const dir = tmpDir("conf-e2e-");
+  const w = makeWorld(dir, { builder: builderScript(cs), reviewer: (n, c) => (cs.generic ? generic() : oracle(c)) });
+  const ret = await runCore({ issue: 101, repo: "o/r", lane: "staging", cwd: w.repo, worktreeRoot: path.join(dir, "wt"), dir: path.join(dir, "runs"), io: w.io, random: () => 0.5, stableMs: 0, livePollMs: 20, conformance });
+  return w.observe(ret);
+}
+const blocked = (o, code) => {
+  assert.equal(o.ret.terminalReason, "needs-human"); assert.equal(o.ret.code, code);
+  assert.equal(o.pr, undefined, "no PR"); assert.equal(o.issue.state, "OPEN");
+  assert.ok(o.issue.labels.has("needs-human")); assert.ok(![...o.issue.labels].some((l) => l.startsWith("workflow:")));
+  assert.ok(!o.staging.search && !o.staging.export, "staging untouched");
+};
+const merged = (o) => {
+  assert.equal(o.ret.terminalReason, "merged"); assert.equal(o.pr.state, "MERGED"); assert.equal(o.pr.base, "staging");
+  assert.equal(o.issue.state, "CLOSED"); assert.equal(o.issue.reason, "completed"); assert.deepEqual([...o.issue.labels], ["workflow:merged"]);
+  assert.match(o.pr.body, /Closes #101$/);
+};
+
+describe("conformance gate end-to-end (real git, disposable repo)", { skip: !HAVE_GIT && "git not available" }, () => {
+  it("1 complete: conforms, merges into staging, closes completed", async () => {
+    const o = await runCase({ contract: FULL, impl: (t) => fix(t, ["scrape", "search", "export"]) });
+    merged(o); assert.ok(o.staging.search && o.staging.export && !o.staging.billingChanged);
+    assert.deepEqual([o.counts.builder, o.counts.reviewer], [2, 1]);
+    assert.deepEqual(o.markers, ["FORGE:STARTED", "FORGE:INVESTIGATION", "FORGE:CONTRACT", "FORGE:IMPLEMENTATION", "FORGE:REVIEW", "FORGE:TRAJECTORY"]);
+  });
+  it("2 omission: the contract silently drops requirement 3; review catches it; issue stays open, nothing merged", async () => {
+    const o = await runCase({ contract: OMIT, impl: (t) => fix(t, ["scrape", "search"]) });
+    blocked(o, "conformance.omission"); assert.deepEqual([o.counts.builder, o.counts.reviewer], [3, 2]);
+  });
+  it("2b omission recovered by typed amendments on the resume: merges with all three routes fixed", async () => {
+    const o = await runCase({ contract: OMIT, impl: (t) => fix(t, ["scrape", "search"]),
+      resume: (t, res) => { fix(t, ["scrape", "search", "export"]); res.requirements.push({ id: "R3", status: "implemented" });
+        res.amendments = [{ kind: "add-requirement", requirement: req("R3"), why: "the issue's requirement 3 was missing" }, { kind: "add-deliverable", id: "D3", path: "src/routes/export.js", why: "implements R3" }]; } });
+    merged(o); assert.ok(o.staging.export); assert.ok(o.markers.includes("FORGE:AMENDMENT"));
+  });
+  it("3 scope creep: an unauthorized billing change is stopped by the precheck and reverted before it can reach staging", async () => {
+    const o = await runCase({ contract: FULL, impl: (t) => { fix(t, ["scrape", "search", "export"]); t.write({ "src/billing.js": "export function price(units) { return Math.round(units) * 0.01; }\n" }); },
+      resume: (t) => t.restore("src/billing.js") });
+    merged(o); assert.equal(o.staging.billingChanged, false); assert.deepEqual([o.counts.builder, o.counts.reviewer], [3, 1]);
+  });
+  it("4 a claimed follow-up without a tracking issue blocks merge before any review", async () => {
+    const o = await runCase({ contract: FULL, impl: (t) => fix(t, ["scrape", "search"]), claims: (k) => claimAll(k).map((r) => (r.id === "R3" ? { id: "R3", status: "deferred", note: "follow-up" } : r)) });
+    blocked(o, "conformance.untracked_deferral"); assert.equal(o.counts.reviewer, 0); assert.equal(o.followups.length, 0);
+  });
+  it("4b the deferral made typed on the resume is tracked, linked, and the issue closes", async () => {
+    const o = await runCase({ contract: FULL, impl: (t) => fix(t, ["scrape", "search"]), claims: (k) => claimAll(k).map((r) => (r.id === "R3" ? { id: "R3", status: "deferred" } : r)),
+      resume: (t, res) => { res.amendments = [{ kind: "defer", requirement: "R3", why: "export ships on its own release train" }]; } });
+    merged(o); assert.equal(o.followups.length, 1); assert.equal(o.followups[0].state, "OPEN");
+    assert.match(o.pr.body, new RegExp(`Remaining work tracked\\n- #${o.followups[0].number}`)); assert.ok(o.markers.includes("FORGE:TRACKED"));
+  });
+  it("5 a contracted deferral is filed once the reviewer accepts it, and the issue closes with the link", async () => {
+    const o = await runCase({ contract: DEFER, impl: (t) => fix(t, ["scrape", "search"]) });
+    merged(o); assert.equal(o.followups.length, 1); assert.deepEqual(o.followups[0].items, [`R3: ${Q.R3}`]);
+    assert.match(o.issue.comments.find((c) => c.includes("FORGE:CONTRACT")), /defer \(filed after review accepts it\)/);
+    assert.match(o.pr.body, new RegExp(`Remaining work tracked\\n- #${o.followups[0].number}`));
+    assert.ok(o.issue.comments.some((c) => c.includes("FORGE:TRACKED") && c.includes(`#${o.followups[0].number}`)));
+  });
+  it("shadow (default): an omission merges as today, and the posted review says the gate would block it", async () => {
+    const o = await runCase({ contract: OMIT, impl: (t) => fix(t, ["scrape", "search"]) }, "shadow");
+    merged(o); assert.equal(o.staging.export, false, "the omitted route still leaks, exactly as today");
+    assert.match(o.issue.comments.find((c) => c.includes("FORGE:REVIEW")), /would BLOCK \(nonconforming\)[\s\S]*conformance\.omission/);
+    assert.deepEqual([o.counts.builder, o.counts.reviewer], [2, 1]);
+  });
+  it("6 a generic PASS over an incomplete implementation never merges (review.incomplete)", async () => {
+    const o = await runCase({ contract: FULL, impl: (t) => fix(t, ["scrape", "export"]), generic: true });
+    blocked(o, "review.incomplete"); assert.deepEqual([o.counts.builder, o.counts.reviewer], [2, 2]);
+  });
+});

package/bin/lean/conformance.mjs

@@ -0,0 +1,238 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Conformance gate for the core work-on: the builder's frozen contract, typed amendments, deterministic prechecks,
+ * the structured conformance review and the close plan. Pure functions; lean.mjs owns every effect.
+ *
+ * The reviewer supplies per-row judgements; the engine computes the verdict. A review without rows (a generic
+ * "PASS") is incomplete, and incomplete never merges.
+ */
+import { OUTCOME_CODES } from "../engine/outcome-codes.mjs";
+
+export const DISPOSITIONS = Object.freeze(["deliver", "defer", "not-applicable", "post-deploy"]);
+/** Dispositions the engine files as a tracked follow-up issue before anything merges. */
+export const TRACKED = Object.freeze(["defer", "post-deploy"]);
+const REQ_STATUS = ["implemented", "partial", "missing", "deferred", "post-deploy", "not-applicable"];
+const COVER_STATUS = ["covered", "narrowed", "missing"];
+const PRESERVE_STATUS = ["intact", "violated", "unverified"];
+const EVIDENCE_RE = /^([^\s:]+):(\d+)/;
+/** Test files in any common ecosystem: test dirs, *.test.* / *.spec.*, test_*.*, *_test.*, *Test(s).java|kt|cs|php|scala, *_spec.rb, tests.rs, conftest.py, snapshots. */
+const TEST_RE = /(^|\/)(test|tests|__tests__|spec|specs|testdata|__snapshots__)\/|\.(test|spec)\.[a-z0-9]+$|(^|\/)test_[^/]+\.[a-z0-9]+$|_test\.[a-z0-9]+$|Tests?\.(java|kt|kts|cs|php|scala|swift)$|_spec\.rb$|(^|\/)tests\.rs$|(^|\/)conftest\.py$|\.bats$|\.snap$/;
+/** Files any change may touch without being a deliverable: changelogs and dependency lockfiles. */
+const INCIDENTAL_RE = /(^|\/)(CHANGELOG|CHANGES|HISTORY)(\.[a-z]+)?$|(^|\/)(package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|Cargo\.lock|poetry\.lock|uv\.lock|Pipfile\.lock|go\.sum|Gemfile\.lock|composer\.lock|mix\.lock|pubspec\.lock|Package\.resolved|gradle\.lockfile)$/i;
+export const MIN_QUOTE_CHARS = 12;
+/** A contract larger than this cannot be posted whole in one comment (the comment cap is 60k). */
+export const MAX_CONTRACT_CHARS = 40000;
+const C = OUTCOME_CODES;
+
+export const norm = (s) => String(s ?? "").replace(/[`*_>]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
+const ITEM_PREFIX_RE = /^\s*(?:[-*+]\s+)?(?:\[[ xX]\]\s+)?(?:\d+[.)]\s+)?/;
+/**
+ * A quote must be verbatim (whitespace and markdown emphasis aside) from the issue text: a substring of at least
+ * MIN_QUOTE_CHARS, or a shorter quote that is a whole line or list item (e.g. "- [ ] add --dry-run").
+ */
+export function inIssue(quote, issueText) {
+  const q = norm(quote);
+  if (q.length >= MIN_QUOTE_CHARS) return norm(issueText).includes(q);
+  if (q.length < 3) return false;
+  return String(issueText ?? "").split("\n").some((l) => norm(l.replace(ITEM_PREFIX_RE, "")) === q);
+}
+export const isTestPath = (p) => TEST_RE.test(String(p));
+export const isIncidentalPath = (p) => INCIDENTAL_RE.test(String(p));
+const cleanPath = (p) => String(p ?? "").trim().replace(/^\.\//, "");
+const globRe = (g) => new RegExp(`^${g.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*\/?/g, "\u0000").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]").replace(/\u0000/g, ".*")}$`);
+/** True when deliverable `d` (a file, a dir ending in "/", or a glob) covers changed file `f`. */
+export function pathCovers(d, f) {
+  const p = cleanPath(d), file = cleanPath(f);
+  if (!p) return false;
+  if (p.endsWith("/")) return file.startsWith(p);
+  if (/[*?]/.test(p)) return globRe(p).test(file);
+  return p === file;
+}
+/** The deliverable id that authorizes `f`, "test", "incidental", or null. */
+export function authorizationOf(contract, f) {
+  const d = (contract.deliverables ?? []).find((x) => pathCovers(x.path, f));
+  if (d) return d.id;
+  if (isTestPath(f)) return "test";
+  if (isIncidentalPath(f)) return "incidental";
+  return null;
+}
+const blank = (s) => !String(s ?? "").trim() || /^none$/i.test(String(s).trim());
+
+/** Shape check of the builder's contract.json against the issue text. Returns {ok, problems[]}. */
+export function validateContract(c, issueText) {
+  const problems = [];
+  if (!c || typeof c !== "object" || Array.isArray(c)) return { ok: false, problems: ["contract.json is missing or not a JSON object"] };
+  const reqs = Array.isArray(c.requirements) ? c.requirements : [];
+  if (!reqs.length) problems.push("the contract lists no requirements");
+  const ids = new Set();
+  for (const r of reqs) {
+    const id = r?.id;
+    if (!id || ids.has(id)) problems.push(`requirement id missing or duplicated: ${id}`);
+    ids.add(id);
+    if (!DISPOSITIONS.includes(r?.disposition)) problems.push(`${id}: disposition must be one of ${DISPOSITIONS.join("|")}`);
+    if (!inIssue(r?.quote, issueText)) problems.push(`${id}: quote is not verbatim from the issue (at least ${MIN_QUOTE_CHARS} characters)`);
+    if (TRACKED.includes(r?.disposition) && blank(r?.why)) problems.push(`${id}: ${r.disposition} needs a why`);
+    if (r?.disposition === "not-applicable" && blank(r?.evidence)) problems.push(`${id}: not-applicable needs file:line evidence`);
+  }
+  const dels = Array.isArray(c.deliverables) ? c.deliverables : [];
+  if (reqs.some((r) => r?.disposition === "deliver") && !dels.length) problems.push("deliver requirements but no deliverables");
+  for (const d of dels) if (!d?.id || !d?.path) problems.push(`deliverable without id or path: ${JSON.stringify(d).slice(0, 80)}`);
+  for (const p of Array.isArray(c.preserve) ? c.preserve : []) if (!p?.id || blank(p?.what)) problems.push("preserve entry without id or what");
+  if (!Array.isArray(c.validate) || !c.validate.length) problems.push("the contract names no validate[] commands");
+  else for (const v of c.validate) if (!v?.id || blank(v?.command)) problems.push("validate entry without id or command");
+  if (JSON.stringify(c).length > MAX_CONTRACT_CHARS) problems.push(`the contract is over ${MAX_CONTRACT_CHARS} characters; keep quotes to the requirement sentence and descriptions short`);
+  return { ok: problems.length === 0, problems };
+}
+
+/**
+ * Apply result.json amendments to the frozen contract. Kinds: add-deliverable {path}, add-requirement {requirement},
+ * defer|post-deploy {requirement: id}. Every amendment needs a why. Returns {contract, applied[], toTrack[], problems[]}.
+ */
+export function applyAmendments(frozen, amendments, issueText = null) {
+  const c = structuredClone(frozen);
+  c.deliverables = c.deliverables ?? [];
+  const applied = [], toTrack = [], problems = [];
+  for (const a of Array.isArray(amendments) ? amendments : []) {
+    const tag = JSON.stringify(a ?? null).slice(0, 100);
+    if (blank(a?.why)) { problems.push(`amendment without why: ${tag}`); continue; }
+    if (a.kind === "add-deliverable" && !blank(a.path)) {
+      if (!c.deliverables.some((d) => d.path === a.path)) c.deliverables.push({ id: a.id ?? `A${c.deliverables.length + 1}`, path: a.path, change: a.why, amended: true });
+    } else if (a.kind === "add-requirement" && a.requirement?.id && !blank(a.requirement?.quote)) {
+      if (c.requirements.some((r) => r.id === a.requirement.id)) { problems.push(`add-requirement reuses id ${a.requirement.id}`); continue; }
+      if (issueText != null && !inIssue(a.requirement.quote, issueText)) { problems.push(`add-requirement ${a.requirement.id}: quote is not verbatim from the issue`); continue; }
+      const r = { disposition: "deliver", ...a.requirement, amended: true };
+      if (!DISPOSITIONS.includes(r.disposition)) { problems.push(`add-requirement ${r.id}: bad disposition ${r.disposition}`); continue; }
+      if (TRACKED.includes(r.disposition) && blank(r.why)) r.why = a.why;
+      c.requirements.push(r);
+      if (TRACKED.includes(r.disposition)) toTrack.push(r);
+    } else if (TRACKED.includes(a.kind) && a.requirement) {
+      const r = c.requirements.find((x) => x.id === a.requirement);
+      if (!r) { problems.push(`amendment names unknown requirement ${a.requirement}`); continue; }
+      if (!TRACKED.includes(r.disposition)) { r.disposition = a.kind; r.why = a.why; r.amended = true; toTrack.push(r); }
+    } else { problems.push(`unknown or incomplete amendment: ${tag}`); continue; }
+    applied.push({ kind: a.kind, target: a.path ?? a.requirement?.id ?? a.requirement, why: String(a.why).trim() });
+  }
+  return { contract: c, applied, toTrack, problems };
+}
+
+/**
+ * Deterministic checks before any reviewer tokens are spent: unauthorized files, failed or missing validation,
+ * requirements not implemented, and deferrals without a tracking issue. Returns {ok, failures[]}.
+ */
+export function precheck({ contract, result, changedFiles, ignore = [] }) {
+  const failures = [];
+  const creep = changedFiles.filter((f) => !ignore.some((p) => f.startsWith(p)) && !authorizationOf(contract, f));
+  if (creep.length) failures.push({ code: C.CONFORMANCE_SCOPE_CREEP, detail: `changed outside the contract's deliverables: ${creep.join(", ")}` });
+  const runs = Array.isArray(result?.validation) ? result.validation : [];
+  for (const v of contract.validate ?? []) {
+    const r = runs.find((x) => x?.id === v.id);
+    if (!r) failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, detail: `validate ${v.id} (\`${v.command}\`) has no recorded result` });
+    else if (r.exit !== 0) failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, detail: `validate ${v.id} failed (exit ${r.exit})` });
+  }
+  const st = Array.isArray(result?.requirements) ? result.requirements : [];
+  for (const r of contract.requirements ?? []) {
+    const s = st.find((x) => x?.id === r.id)?.status;
+    if (TRACKED.includes(r.disposition)) continue; // typed deferrals are judged by the reviewer, then filed before the PR
+    if (r.disposition === "deliver") {
+      if (s === "deferred" || s === "post-deploy") failures.push({ code: C.CONFORMANCE_UNTRACKED_DEFERRAL, detail: `${r.id} was contracted as deliver but reported "${s}" without a typed amendment` });
+      else if (s !== "implemented") failures.push({ code: C.CONFORMANCE_UNIMPLEMENTED, detail: `${r.id} reported "${s ?? "no status"}"` });
+    }
+  }
+  return { ok: failures.length === 0, failures };
+}
+
+/** The reviewer's JSON object (a json fence first, then the outermost braces), or null. */
+export function parseReview(text) {
+  const s = String(text ?? "");
+  const fence = /```(?:json)?\s*([\s\S]*?)```/.exec(s)?.[1];
+  for (const cand of [fence, s.slice(s.indexOf("{"), s.lastIndexOf("}") + 1)]) {
+    if (!cand) continue;
+    try { const j = JSON.parse(cand); if (j && typeof j === "object" && !Array.isArray(j)) return j; } catch { /* next candidate */ }
+  }
+  return null;
+}
+
+/** Row completeness: every contract requirement, preserve item and changed file has a well-formed row. */
+export function checkCompleteness(rv, { contract, changedFiles, issueText, pathExists = () => false, ignore = [] }) {
+  const p = [];
+  const arr = (k) => (Array.isArray(rv?.[k]) ? rv[k] : null);
+  if (!["CONFORMS", "NONCONFORMING"].includes(rv?.verdict)) p.push("verdict must be CONFORMS or NONCONFORMING");
+  const cov = arr("issue_coverage");
+  if (!cov?.length) p.push("issue_coverage is missing or empty");
+  for (const c of cov ?? []) {
+    if (!COVER_STATUS.includes(c?.status)) p.push(`issue_coverage status invalid: ${c?.status}`);
+    if (!inIssue(c?.quote, issueText)) p.push(`issue_coverage quote is not verbatim from the issue: "${String(c?.quote ?? "").slice(0, 60)}"`);
+  }
+  const reqs = arr("requirements");
+  if (!reqs) p.push("requirements rows are missing");
+  for (const r of contract.requirements) {
+    const rows = (reqs ?? []).filter((x) => x?.id === r.id);
+    if (rows.length !== 1) { p.push(`requirement ${r.id} needs exactly one row (has ${rows.length})`); continue; }
+    const row = rows[0];
+    if (!REQ_STATUS.includes(row.status)) { p.push(`${r.id}: status invalid: ${row.status}`); continue; }
+    if (TRACKED.includes(r.disposition) && typeof row.deferral_ok !== "boolean") p.push(`${r.id}: a ${r.disposition} requirement needs deferral_ok true|false (is deferring it justified?)`);
+    if (row.status === "implemented") {
+      const m = EVIDENCE_RE.exec(String(row.evidence ?? ""));
+      if (!m) p.push(`${r.id}: implemented needs path:line evidence`);
+      else if (!changedFiles.includes(m[1]) && !pathExists(m[1])) p.push(`${r.id}: evidence path ${m[1]} does not exist`);
+      if (blank(row.validated_by)) p.push(`${r.id}: implemented needs validated_by (a validate id or test)`);
+    }
+  }
+  const scope = arr("scope");
+  if (!scope) p.push("scope rows are missing");
+  for (const f of changedFiles.filter((x) => !ignore.some((pre) => x.startsWith(pre)))) if (!(scope ?? []).some((s) => s?.file === f)) p.push(`changed file ${f} has no scope row`);
+  const pres = arr("preserve") ?? [];
+  for (const c of contract.preserve ?? []) {
+    const row = pres.find((x) => x?.id === c.id);
+    if (!row || !PRESERVE_STATUS.includes(row.status)) p.push(`preserve ${c.id} needs a row with status ${PRESERVE_STATUS.join("|")}`);
+  }
+  if (rv && rv.regressions != null && !Array.isArray(rv.regressions)) p.push("regressions must be an array");
+  return { complete: p.length === 0, problems: p };
+}
+
+/**
+ * The engine's decision from the reviewer's rows. state: conforms | nonconforming | review.unparseable | review.incomplete.
+ * failures[] are {code, detail}; `inconsistent` marks a CONFORMS verdict whose rows fail.
+ */
+export function decide(rv, ctx) {
+  if (!rv) return { state: "review.unparseable", failures: [{ code: C.REVIEW_NO_VERDICT, detail: "no JSON object in the reviewer reply" }] };
+  const comp = checkCompleteness(rv, ctx);
+  if (!comp.complete) return { state: "review.incomplete", failures: comp.problems.map((d) => ({ code: C.REVIEW_INCOMPLETE, detail: d })) };
+  const f = [];
+  for (const c of rv.issue_coverage) if (c.status !== "covered") f.push({ code: C.CONFORMANCE_OMISSION, detail: `issue requirement ${c.status}: "${c.quote}"${c.note ? ` (${c.note})` : ""}` });
+  for (const r of ctx.contract.requirements) {
+    const row = rv.requirements.find((x) => x.id === r.id);
+    if (r.disposition === "deliver" && row.status !== "implemented") {
+      f.push({ code: ["deferred", "post-deploy"].includes(row.status) ? C.CONFORMANCE_UNTRACKED_DEFERRAL : C.CONFORMANCE_UNIMPLEMENTED, detail: `${r.id} ${row.status}${row.note ? `: ${row.note}` : ""}${row.evidence ? ` (${row.evidence})` : ""}` });
+    }
+    if (TRACKED.includes(r.disposition) && row.deferral_ok === false) f.push({ code: C.CONFORMANCE_UNJUSTIFIED_DEFERRAL, detail: `${r.id} ${r.disposition} is not justified${row.note ? `: ${row.note}` : ""}; implement it` });
+  }
+  for (const s of rv.scope) {
+    if (!blank(s.authorized_by)) continue;
+    const engine = authorizationOf(ctx.contract, s.file);
+    if (engine === "test" || engine === "incidental") continue; // always allowed; a reviewer "none" here is a misreading, not creep
+    f.push({ code: C.CONFORMANCE_SCOPE_CREEP, detail: `${s.file}: ${s.note || "not authorized by the contract"}` });
+  }
+  for (const p of rv.preserve ?? []) if (p.status !== "intact") f.push({ code: C.CONFORMANCE_PRESERVE_VIOLATED, detail: `${p.id} ${p.status}${p.evidence ? ` (${p.evidence})` : ""}${p.note ? `: ${p.note}` : ""}` });
+  for (const r of rv.regressions ?? []) f.push({ code: C.CONFORMANCE_REGRESSION, detail: `${r?.at ?? "?"}: ${r?.failure ?? ""}` });
+  if (f.length) return { state: "nonconforming", failures: f, inconsistent: rv.verdict === "CONFORMS" };
+  // A NONCONFORMING verdict with every row passing gives the builder nothing to fix: re-ask the reviewer.
+  if (rv.verdict !== "CONFORMS") return { state: "review.inconsistent", failures: [{ code: C.REVIEW_INCONSISTENT, detail: "verdict NONCONFORMING with no failing row" }] };
+  return { state: "conforms", failures: [] };
+}
+
+/** Requirements the reviewer accepted as deferred or post-deploy that still need a tracking issue. */
+export const pendingTracking = (contract) => (contract.requirements ?? []).filter((r) => TRACKED.includes(r.disposition) && !r.tracked);
+
+/** After a conforming merge: close as completed, linking every tracking issue. */
+export function closePlan(contract) {
+  const tracked = [...new Set((contract.requirements ?? []).filter((r) => TRACKED.includes(r.disposition)).map((r) => r.tracked).filter(Boolean))];
+  return { reason: "completed", tracked };
+}
+
+/** One line per requirement for the follow-up script: a stable key (id + quote) and a why. Tabs and newlines removed. */
+export function followupItems(reqs) {
+  const flat = (s) => String(s ?? "").replace(/[\t\r\n`]+/g, " ").replace(/\s+/g, " ").trim();
+  return reqs.map((r) => ({ id: r.id, key: flat(`${r.id}: ${r.quote}`).slice(0, 240), why: flat(`${r.disposition}: ${r.why ?? ""}`).slice(0, 400) }));
+}