forgedock 1.21.0 → 1.22.0

package/bin/lean/lean.mjs

@@ -1,24 +1,20 @@
 // SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /**
- * Lean path (#4081): validate -> architect -> implement in ONE warm builder session, deterministic gates,
- * one independent reviewer (plus a security reviewer on risky paths), then deterministic merge and close.
- * Every stage is posted to the issue as a structured FORGE:* comment. All effects are injected through `io`
- * (gh, git, runner, ciLocal, waitCiGreen, transitionLabel, fs, sleep) so the module is fully unit-testable.
+ * Core work-on: ONE plain builder session does the work, ONE read-only reviewer answers two questions, and
+ * ForgeDock registers everything on GitHub (labels, one register comment, PR, merge). No investigation, synthesis,
+ * severity taxonomy, risk tiers or local CI gates. All effects are injected through `io` so it is unit-testable.
  */
 import { join } from "node:path";
 import { appendEvent } from "../engine/runlog.mjs";
-import { codeForTerminalReason } from "../engine/outcome-codes.mjs";
+import { codeForTerminalReason, OUTCOME_CODES } from "../engine/outcome-codes.mjs";
 import { ciPollDelayMs, ENGINE_VERSION } from "../engine.mjs";
 import { openDependency } from "../engine/phases.mjs";
-import { OUTCOME_CODES } from "../engine/outcome-codes.mjs";
-import { riskTier, isDocsOnly, isTestFile, isLargeDiff, isBlocking, parseFindings } from "./risk.mjs";
-import { BUILDER_SYSTEM, REVIEWER_SYSTEM, SECURITY_REVIEWER_SYSTEM, LEAN_DIR, builderPrompt, resumeGatePrompt, resumeReviewPrompt, reviewerPrompt } from "./prompts.mjs";
+import { renderValidate, renderPlan, renderReview, renderRegister, renderPrBody } from "./render.mjs";
+import { REVIEWER_SYSTEM, LEAN_DIR, RESULT_FILE, builderPrompt, resumeBuilderPrompt, reviewerPrompt, parseVerdict } from "./prompts.mjs";
 
-export const MAX_ROUNDS = 2;
 export const DEFAULT_REVIEWER_MODEL = "claude-sonnet-5-5";
-const NS = "lean";
-
+export const REGISTER_MARKER = "FORGE:WORK-ON";
 const num = (v) => (Number.isFinite(v) ? v : null);
 
 /**
@@ -28,99 +24,96 @@ const num = (v) => (Number.isFinite(v) ? v : null);
  * @param {string} o.lane            base branch (staging|main)
  * @param {string} o.cwd             main checkout (worktrees are added from here)
  * @param {string} o.dir             run-log dir
- * @param {object} o.io              injected effects
- * @param {"lean"|"auto"} [o.path]
+ * @param {object} o.io              injected effects: gh, git, runner, waitCiGreen, transitionLabel, fs, projector?, now?, sleep?
  * @param {string} [o.builderModel]  default: CLI default
  * @param {string} [o.reviewerModel] default claude-sonnet-5-5
  * @param {number} [o.ciMaxMinutes]  remote-CI wait budget (default 360); exhaustion is NOT needs-human
  */
-export async function runLean(o) {
-  const { issue, repo, lane, cwd, dir, io, path = "lean", builderModel = null, reviewerModel = DEFAULT_REVIEWER_MODEL,
-    ciMaxMinutes = 360, onProgress = () => {}, emitTelemetry = null, random = Math.random } = o;
+export async function runCore(o) {
+  const { issue, repo, lane, cwd, dir, io, builderModel = null, reviewerModel = DEFAULT_REVIEWER_MODEL,
+    ciMaxMinutes = 360, mergeWait = "required", onProgress = () => {}, emitTelemetry = null, random = Math.random } = o;
   const now = io.now ?? (() => Date.now());
   const sleep = io.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const base = `origin/${lane}`;
   const branch = `feat/issue-${issue}-lean`;
   const wt = join(o.worktreeRoot ?? join(cwd, ".claude", "worktrees"), `lean-${issue}`);
   const t0 = now();
-  const links = {};
+  const usage = { cost_usd: 0, input: 0, output: 0, cache: 0 };
   let sessionId = null;
-  const usageTotal = { cost_usd: 0 };
 
   const ev = (e) => appendEvent(dir, issue, e);
   const emit = async (rec) => { try { await emitTelemetry?.({ ...rec, issue }); } catch { /* never fails a run */ } };
   const ghc = (args) => io.gh(args);
   const git = (args) => io.git(args, { cwd: wt });
-  const file = (n) => `${wt}/${LEAN_DIR}/${n}`;
 
-  async function attempt(phase, n, r, extra = {}) {
+  async function attempt(phase, n, r) {
     const rec = { event: "PHASE_ATTEMPT_USAGE", phase, attempt: n, usage: r?.usage ?? null, duration_ms: num(r?.durationMs) ?? 0,
-      cost_usd: num(r?.costUsd), model: r?.model ?? null, turns: num(r?.turns), ...extra };
+      cost_usd: num(r?.costUsd), model: r?.model ?? null, turns: num(r?.turns) };
     ev(rec); await emit(rec);
-    usageTotal.cost_usd += r?.costUsd ?? 0;
+    const u = r?.usage ?? {};
+    usage.cost_usd += r?.costUsd ?? 0;
+    usage.input += u.input_tokens ?? 0; usage.output += u.output_tokens ?? 0;
+    usage.cache += (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
   }
-  async function commit(phase) { ev({ event: "PHASE_COMMIT", phase }); onProgress({ event: "phase_exit", phase, status: "committed" }); }
+  const post = async (marker, body) => {
+    const out = String(await ghc(["issue", "comment", String(issue), "-R", repo, "--body", `<!-- ${marker} -->\n${body}`])).trim();
+    return /https?:\/\/\S+/.exec(out)?.[0] ?? null;
+  };
+  const label = async (state) => { try { await io.transitionLabel(issue, state); } catch { /* labels are best effort */ } };
+  const usageLine = () => `cost $${usage.cost_usd.toFixed(4)}, tokens ${usage.input} in / ${usage.output} out / ${usage.cache} cache, wall ${Math.round((now() - t0) / 60000 * 10) / 10} min`;
 
-  async function post(marker, title, body, attrs = "") {
-    const text = `<!-- ${marker} ${NS} v1${attrs} -->\n## ${marker}\n${title ? `${title}\n\n` : ""}${body}`;
-    const out = String(await ghc(["issue", "comment", String(issue), "-R", repo, "--body", text])).trim();
-    const url = /https?:\/\/\S+/.exec(out)?.[0] ?? null;
-    if (url) (links[marker] ??= []).push(url);
-    return url;
+  // ---- lease (same FORGE:STATE lease the full path uses) ----
+  const agentId = o.agentId ?? `core_${process.pid}`;
+  const leaseTtlMs = o.leaseTtlMs ?? 25 * 60000; // below the projector's 30 min honour cap
+  let leaseState = null, leaseTimer = null;
+  const writeLease = (lease, extra = {}) => io.projector.writeState(issue, { ...leaseState, ...extra, lease });
+  const renew = async () => { if (io.projector && leaseState) { try { await writeLease({ by: agentId, until: now() + leaseTtlMs }); } catch { /* best effort */ } } };
+  async function releaseLease(reason) {
+    if (leaseTimer) { clearInterval(leaseTimer); leaseTimer = null; }
+    if (!io.projector || !leaseState) return;
+    const terminal = ["merged", "invalid", "needs-human", "engine-error"].includes(reason);
+    try { await writeLease(null, terminal ? { terminal: true, terminalReason: reason } : {}); } catch { /* best effort */ }
   }
 
   let done = null, wtCreated = false;
-  const WORKFLOW = ["investigating", "building", "in-review"].map((x) => `workflow:${x}`).join(",");
   async function finish(reason, detail = "", extra = {}) {
     if (done) return done; // idempotent: exactly one RUN_TERMINAL and one telemetry emit
     const code = codeForTerminalReason(reason);
     ev({ event: "RUN_TERMINAL", reason, code });
     await emit({ event: "RUN_TERMINAL", reason, code });
-    // A run that did not reach a success/handoff state must not leave a stale in-progress label behind.
     if (["needs-human", "engine-error"].includes(reason)) {
-      try { await ghc(["issue", "edit", String(issue), "-R", repo, "--remove-label", WORKFLOW]); } catch { /* best effort */ }
+      const wf = ["investigating", "building", "in-review"].map((x) => `workflow:${x}`).join(",");
+      try { await ghc(["issue", "edit", String(issue), "-R", repo, "--remove-label", wf]); } catch { /* best effort */ }
     }
     await releaseLease(reason);
-    // The worktree is scratch; the branch stays when a PR (or a human) may need it.
     if (wtCreated) {
       try { await io.git(["worktree", "remove", "--force", wt], { cwd }); } catch { /* best effort */ }
       if (reason === "invalid" && !extra.pr) { try { await io.git(["branch", "-D", branch], { cwd }); } catch { /* best effort */ } }
     }
-    done = { terminalReason: reason, detail, branch, worktree: wt, cost_usd: usageTotal.cost_usd, wall_ms: now() - t0, ...extra };
+    done = { terminalReason: reason, detail, branch, worktree: wt, cost_usd: usage.cost_usd, tokens: { input: usage.input, output: usage.output, cache: usage.cache }, wall_ms: now() - t0, ...extra };
     return done;
   }
   async function needsHuman(why) {
-    try { await post("FORGE:NEEDS_HUMAN", "", why); await ghc(["issue", "edit", String(issue), "-R", repo, "--add-label", "needs-human"]); } catch { /* best effort */ }
+    try {
+      await post("FORGE:NEEDS_HUMAN", `## Needs human\n${why}\n\n_${usageLine()}_`);
+      await ghc(["issue", "edit", String(issue), "-R", repo, "--add-label", "needs-human"]);
+    } catch { /* best effort */ }
     return finish("needs-human", why);
   }
-  async function label(state) { try { await io.transitionLabel(issue, state); } catch { /* labels are best effort */ } }
 
-  async function builder(phase, n, prompt, resume) {
-    onProgress({ event: "phase_enter", phase });
+  async function builder(n, prompt, resume) {
+    onProgress({ event: "phase_enter", phase: "build" });
     await renew();
-    const r = await io.runner({ role: "builder", issue, cwd: wt, model: builderModel, resume,
-      system: resume ? "" : BUILDER_SYSTEM, prompt });
+    const r = await io.runner({ role: "builder", issue, cwd: wt, model: builderModel, resume, system: "", prompt });
     await renew();
     if (r?.sessionId) sessionId = r.sessionId;
+    await attempt("implement", n, r);
+    onProgress({ event: "phase_exit", phase: "build", status: "committed" });
     return r;
   }
-  const readJson = async (n) => { try { return JSON.parse(await io.fs.read(file(n))); } catch { return null; } };
+  const readResult = async () => { try { const j = JSON.parse(await io.fs.read(`${wt}/${RESULT_FILE}`)); return j && typeof j === "object" ? j : null; } catch { return null; } };
 
-  // Same issue lease the full path uses (FORGE:STATE lease via the projector): two runs cannot race.
-  const agentId = o.agentId ?? `lean_${process.pid}`;
-  // 25 min: below the projector's 30 min honour cap. The CLI is spawned synchronously (no timer can fire), so the
-  // lease is also renewed immediately before and after every builder/reviewer/ci-local call and each CI poll.
-  const leaseTtlMs = o.leaseTtlMs ?? 25 * 60000;
-  let leaseState = null, leaseTimer = null;
-  const writeLease = (lease, extra = {}) => io.projector.writeState(issue, { ...leaseState, ...extra, lease });
-  async function releaseLease(reason) {
-    if (leaseTimer) { clearInterval(leaseTimer); leaseTimer = null; }
-    if (!io.projector || !leaseState) return;
-    const terminal = ["merged", "invalid", "needs-human", "engine-error"].includes(reason);
-    try { await writeLease(null, terminal ? { terminal: true, terminalReason: reason } : {}); } catch { /* best effort */ }
-  }
-  const renew = async () => { if (io.projector && leaseState) { try { await writeLease({ by: agentId, until: now() + leaseTtlMs }); } catch { /* best effort */ } } };
-  // Same Depends-on admission as the full path, before any state write or worktree.
+  // ---- admission: Depends-on refusal, then lease ----
   {
     let dep = null;
     try { dep = await openDependency(issue, io); } catch (e) { dep = { unreadable: true, detail: `issue ${issue} **Depends on** check failed: ${e?.message || e}` }; }
@@ -132,18 +125,17 @@ export async function runLean(o) {
   }
   if (io.projector) {
     let st = null;
-    try { st = await io.projector.readState(issue); } catch { /* unreadable: proceed, the write below is best effort */ }
+    try { st = await io.projector.readState(issue); } catch { /* unreadable: proceed */ }
     if (st?.lease && st.lease.until > now() && st.lease.by !== agentId) {
       return { terminalReason: "deferred", code: "lease-held", detail: `issue ${issue} leased by ${st.lease.by} until ${new Date(st.lease.until).toISOString()}`, branch, worktree: wt };
     }
-    leaseState = st ?? { v: 1, run: `lean_${issue}`, issue, lane, committed: [], phase: null, branch: null, pr: null, terminal: false, terminalReason: null };
-    leaseState = { ...leaseState, terminal: false };
+    leaseState = { ...(st ?? { v: 1, run: `core_${issue}`, issue, lane, committed: [], phase: null, branch: null, pr: null, terminalReason: null }), terminal: false };
     try { await writeLease({ by: agentId, until: now() + leaseTtlMs }); } catch { /* best effort */ }
     leaseTimer = setInterval(() => { writeLease({ by: agentId, until: now() + leaseTtlMs }).catch(() => {}); }, o.leaseRenewMs ?? 120000);
     leaseTimer.unref?.();
   }
 
-  ev({ event: "RUN_START", run: `lean_${issue}_${t0}`, issue, lane, path: "lean", version: ENGINE_VERSION, forge_version: ENGINE_VERSION, repo });
+  ev({ event: "RUN_START", run: `core_${issue}_${t0}`, issue, lane, path: "core", version: ENGINE_VERSION, forge_version: ENGINE_VERSION, repo });
   let iss;
   try {
     iss = JSON.parse(await ghc(["issue", "view", String(issue), "-R", repo, "--json", "number,title,body,state"]));
@@ -151,9 +143,12 @@ export async function runLean(o) {
   if (String(iss.state).toUpperCase() === "CLOSED") return finish("invalid", "issue already closed");
 
   try {
+    // ---- 1. claim ----
     await label("investigating");
+    await post("FORGE:STARTED", `Started work on #${issue} (base \`${lane}\`).`);
+
+    // ---- 2. worktree (resume an open PR / remote branch) ----
     try { await io.git(["fetch", "origin", lane], { cwd }); } catch { /* offline: use the local ref */ }
-    // Reruns resume: an open PR or a remote branch for this issue means earlier work exists (e.g. ci-pending).
     let resumed = null;
     try {
       const prs = JSON.parse(String(await ghc(["pr", "list", "-R", repo, "--head", branch, "--state", "open", "--json", "number,headRefOid"])) || "[]");
@@ -171,178 +166,113 @@ export async function runLean(o) {
     wtCreated = true;
     const excl = String(await git(["rev-parse", "--git-path", "info/exclude"])).trim();
     await io.fs.append(excl.startsWith("/") ? excl : `${wt}/${excl}`, `\n${LEAN_DIR}/\n`);
+    const changedFiles = async () => String(await git(["diff", "--name-only", `${base}...HEAD`])).split("\n").map((s) => s.trim()).filter(Boolean);
 
-    let planMd = null, validate = null, implRound = 1, gateRounds = 0;
-    const postImpl = async () => {
-      const impl = await readJson("implement.json");
-      await post("FORGE:IMPLEMENT", impl ? `**Round:** ${implRound}` : "**implement.json missing**", "```json\n" + JSON.stringify(impl ?? {}, null, 2) + "\n```", ` round=${implRound}`);
-      return impl;
-    };
-    const diffStats = async () => {
-      const files = String(await git(["diff", "--name-only", `${base}...HEAD`])).split("\n").map((s) => s.trim()).filter(Boolean);
-      let lines = 0;
-      for (const l of String(await git(["diff", "--numstat", `${base}...HEAD`])).split("\n")) {
-        const [a, d] = l.split("\t"); lines += (Number(a) || 0) + (Number(d) || 0);
-      }
-      return { files, lines };
-    };
-    const gateFailure = async () => {
-      const { files } = await diffStats();
-      if (files.length === 0) return { kind: "no-commit", tail: "No commit on the branch relative to the base. Commit your change." };
-      if (!(await readJson("implement.json"))) return { kind: "implement-json", tail: `${LEAN_DIR}/implement.json is missing or invalid JSON.` };
-      if (!isDocsOnly(files) && !files.some(isTestFile)) {
-        return { kind: "missing-test", tail: "No test file changed. Add a regression test that fails without the fix (and passes with it)." };
+    // ---- 3. builder ----
+    let result = null, attemptN = 0, validateUrl = null, planUrl = null, reviewUrl = null;
+    if (!(resumed && (await changedFiles()).length > 0)) {
+      await label("building");
+      await builder(++attemptN, builderPrompt(issue), null);
+      result = await readResult();
+      const files0 = await changedFiles();
+      const evidence = (Array.isArray(result?.evidence) ? result.evidence : []).filter((x) => typeof x === "string" && x.trim());
+      const verdict = result ? (result.status === "fixed" ? "valid" : result.status) : null;
+      const closing = ["invalid", "already-fixed"].includes(result?.status);
+      if (closing && !evidence.length) return await needsHuman(`Builder reported "${result.status}" without evidence, so the issue is not closed automatically.\n\n${result.summary ?? "(no summary)"}`);
+      // The validation comment (no model call): verdict, evidence, one-line summary. For invalid/already-fixed it IS the evidence comment.
+      if (verdict) validateUrl = await post("FORGE:VALIDATE", renderValidate(result, verdict));
+      if (closing) {
+        await ghc(["issue", "close", String(issue), "-R", repo, "--reason", "not planned"]);
+        await label("invalid");
+        return await finish("invalid", result.summary ?? result.status);
       }
-      await renew();
-      const ci = await io.ciLocal({ cwd: wt, base });
-      await renew();
-      if (ci.result === "BROKEN") return { kind: "ci-local-broken", fatal: true, tail: ci.tail ?? "ci-local reported no result" };
-      if (ci.result === "FAIL") return { kind: "ci-local", tail: ci.tail ?? "" };
-      return null;
-    };
-    const runGates = async () => {
-      for (;;) {
-        const f = await gateFailure();
-        if (!f) return null;
-        if (f.fatal) return needsHuman(`gate ${f.kind}: the local CI gate could not report a result, so the change is unverified.\n\n${String(f.tail).slice(-2000)}`);
-        if (gateRounds >= MAX_ROUNDS) return needsHuman(`gate ${f.kind} still failing after ${MAX_ROUNDS} resume rounds:\n\n${String(f.tail).slice(-3000)}`);
-        gateRounds++; implRound++;
-        if (!sessionId) return needsHuman(`gate ${f.kind} failed and the builder session id is unknown, cannot resume`);
-        const rr = await builder("implement", implRound, resumeGatePrompt(f), sessionId);
-        await attempt("implement", implRound, rr, {});
-        await postImpl();
-      }
-    };
-
-    let approvedHead = null;
-    if (resumed) {
-      // Resume from the knowledge graph: plan and last review verdict come from the issue comments.
-      const bodies = (JSON.parse(String(await ghc(["issue", "view", String(issue), "-R", repo, "--json", "comments"])) || "{}").comments ?? []).map((c) => String(c.body ?? ""));
-      const lastOf = (m) => bodies.filter((b) => b.includes(`<!-- ${m} ${NS}`)).pop();
-      const planC = lastOf("FORGE:PLAN");
-      planMd = planC ? planC.replace(/^[\s\S]*?## FORGE:PLAN\n/, "") : "";
-      const rev = lastOf("FORGE:REVIEW");
-      const m = rev && /\*\*Verdict:\*\* APPROVED[^\n]*reviewed ([0-9a-f]{7,40})/.exec(rev);
-      const curHead = String(await git(["rev-parse", "HEAD"])).trim();
-      if (m && curHead.startsWith(m[1])) approvedHead = curHead;
-      ev({ event: "RUN_RESUMED", pr: resumed.pr, approved: Boolean(approvedHead) });
-    } else {
-    // ---- builder: validate + architect + implement in one session ----
-    const r = await builder("validate", 1, builderPrompt({ issue: iss, base: lane, branch }), null);
-    validate = await readJson("validate.json");
-    await attempt("implement", 1, r, { stages: "validate,architect,implement" });
-    if (!validate) return await needsHuman("builder did not write validate.json");
-    await post("FORGE:VALIDATE", `**Status:** ${validate.status}`, "```json\n" + JSON.stringify(validate, null, 2) + "\n```");
-    if (validate.status !== "valid") {
-      const evidence = (Array.isArray(validate.evidence) ? validate.evidence : []).filter((x) => typeof x === "string" && x.trim());
-      if (!["invalid", "already-fixed"].includes(validate.status) || evidence.length === 0) {
-        return await needsHuman(`validate returned status "${validate.status}" ${evidence.length ? "" : "without evidence "}so the issue is not closed automatically.\n\nBuilder reasoning: ${validate.summary ?? "(none)"}`);
-      }
-      await commit("validate");
-      await ghc(["issue", "close", String(issue), "-R", repo, "--reason", "not planned"]);
-      await label("invalid");
-      return await finish("invalid", validate.summary ?? validate.status);
-    }
-    await commit("validate");
-    await label("building");
-
-    planMd = await io.fs.read(file("plan.md")).catch(() => null);
-    if (!planMd) return await needsHuman("builder did not write plan.md");
-    await post("FORGE:PLAN", "", planMd);
-    await commit("architect");
-
-    await postImpl();
-    await commit("implement");
-
-    const g0 = await runGates();
-    if (g0) return g0;
-    }
-
-    // ---- auto path: risky AND large escalates to the full pipeline ----
-    const st = await diffStats();
-    const risk = riskTier(st.files, `${iss.title}\n${iss.body ?? ""}`);
-    if (!resumed && path === "auto" && risk.tier === "high" && isLargeDiff({ files: st.files.length, lines: st.lines })) {
-      await post("FORGE:ROUTE", "", `Risk tier high (${risk.reasons.slice(0, 5).join(", ")}) and diff large (${st.files.length} files, ${st.lines} lines): routing to the full pipeline.`);
-      return await finish("route-full", "risk high and diff large");
+      if (result?.status === "blocked") return await needsHuman(`Builder is blocked: ${result.summary ?? "(no summary)"}`);
+      if (!files0.length) return await needsHuman(`Builder made no commit${result ? ` (status "${result.status}")` : " and wrote no result.json"}.\n\n${result?.summary ?? ""}`);
+      planUrl = await post("FORGE:PLAN", renderPlan(result, files0));
     }
 
-    // ---- review loop ----
+    // ---- 4. review (one retry through the same builder session) ----
     await label("in-review");
-    let reviewRound = 0, reviewedHead = null, prior = null, reviewAttempt = 0;
-    const review = async (role, system, delta) => {
-      for (let tryN = 0; tryN < 2; tryN++) {
-        const diff = String(await git(["diff", delta ? `${reviewedHead}..HEAD` : `${base}...HEAD`]));
+    let review = null, reviewN = 0;
+    const doReview = async () => {
+      for (let t = 0; t < 2; t++) {
+        const diff = String(await git(["diff", `${base}...HEAD`]));
         await renew();
-        const rr = await io.runner({ role, issue, cwd: wt, model: reviewerModel, resume: null, system, readOnly: true,
-          prompt: reviewerPrompt({ issue: iss, plan: planMd, diff, prior, delta }) });
+        const rr = await io.runner({ role: "reviewer", issue, cwd: wt, model: reviewerModel, resume: null, system: REVIEWER_SYSTEM, readOnly: true,
+          prompt: reviewerPrompt({ issue: iss, diff }) });
         await renew();
-        await attempt("review", ++reviewAttempt, rr);
-        const f = parseFindings(rr?.text);
-        if (f) return f.map((x) => ({ ...x, reviewer: role }));
+        await attempt("review", ++reviewN, rr);
+        const v = parseVerdict(rr?.text);
+        if (v) return v;
       }
       return null;
     };
-    for (;!approvedHead;) {
-      const head = String(await git(["rev-parse", "HEAD"])).trim();
-      const delta = reviewedHead !== null;
-      const roles = [["reviewer", REVIEWER_SYSTEM]];
-      if (risk.tier === "high") roles.push(["security-reviewer", SECURITY_REVIEWER_SYSTEM]);
-      const all = [];
-      for (const [role, system] of roles) {
-        const f = await review(role, system, delta);
-        if (f === null) return await needsHuman(`${role} returned no parseable findings twice`);
-        all.push(...f);
-      }
-      reviewedHead = head;
-      const blocking = all.filter(isBlocking);
-      const notes = all.filter((x) => !isBlocking(x));
-      const row = (x) => `- **${x.severity}/${x.confidence}** ${x.file ?? "?"}:${x.line ?? "?"} (${x.scope ?? "introduced"}, ${x.reviewer}) ${x.title ?? ""}${x.failure_scenario ? ` — ${x.failure_scenario}` : ""}`;
-      await post("FORGE:REVIEW", `**Verdict:** ${blocking.length ? "BLOCKING" : "APPROVED"} | round ${reviewRound + 1} | reviewed ${head.slice(0, 12)}${delta ? " (delta)" : ""} | risk ${risk.tier}`,
-        `### Blocking (${blocking.length})\n${blocking.map(row).join("\n") || "none"}\n\n### Notes (${notes.length}, not filed as issues)\n${notes.map(row).join("\n") || "none"}\n\n\`\`\`json\n${JSON.stringify(all, null, 2)}\n\`\`\``);
-      await commit("review");
-      if (!blocking.length) break;
-      if (reviewRound >= MAX_ROUNDS) return await needsHuman(`${blocking.length} blocking finding(s) after ${MAX_ROUNDS} fix rounds`);
-      if (!sessionId) return await needsHuman("blocking findings and the builder session id is unknown, cannot resume");
-      reviewRound++; implRound++; prior = blocking;
-      const rr = await builder("implement", implRound, resumeReviewPrompt({ findings: blocking }), sessionId);
-      await attempt("implement", implRound, rr);
-      await postImpl();
-      const g1 = await runGates();
-      if (g1) return g1;
+    review = await doReview();
+    if (!review) return await needsHuman("Reviewer returned no parseable verdict twice.");
+    if (review.fail) {
+      if (!sessionId) return await needsHuman(`Review FAIL and the builder session id is unknown, cannot resume: ${review.reason}`);
+      await builder(++attemptN, resumeBuilderPrompt(review.reason), sessionId);
+      result = (await readResult()) ?? result;
+      review = await doReview();
+      if (!review) return await needsHuman("Reviewer returned no parseable verdict twice (re-review).");
+      if (review.fail) return await needsHuman(`Review FAIL twice. Last reason: ${review.reason}`);
     }
+    reviewUrl = await post("FORGE:REVIEW", renderReview(review));
+    ev({ event: "PHASE_COMMIT", phase: "review" });
 
-    // ---- merge and close (no model) ----
+    // ---- 5. push + PR ----
+    const files = await changedFiles();
     await git(["push", "-u", "origin", branch]);
-    const final = await diffStats();
-    const linkLines = Object.entries(links).map(([k, v]) => `- ${k}: ${v.join(", ")}`).join("\n");
     const prOut = resumed?.pr ? `/pull/${resumed.pr}` : String(await ghc(["pr", "create", "-R", repo, "--base", lane, "--head", branch,
-      "--title", `${(validate?.title ?? iss.title)} (#${issue})`,
-      "--body", `Closes #${issue}\n\nLean path run. Knowledge graph:\n${linkLines}\n\nFiles: ${final.files.length}, lines: ${final.lines}`])).trim();
+      "--title", `${iss.title} (#${issue})`, "--body", renderPrBody({ issue, result, gitFiles: files })])).trim();
     const pr = Number(/\/pull\/(\d+)/.exec(prOut)?.[1] ?? /(\d+)\s*$/.exec(prOut)?.[1]);
-    if (!Number.isInteger(pr)) return await needsHuman(`could not parse PR number from: ${prOut.slice(0, 200)}`);
+    if (!Number.isInteger(pr)) return await needsHuman(`Could not parse the PR number from: ${prOut.slice(0, 200)}`);
     ev({ event: "PR_OPENED", pr });
+    const prUrl = /https?:\/\/\S+/.exec(prOut)?.[0] ?? `https://github.com/${repo}/pull/${pr}`;
+    const localHead = String(await git(["rev-parse", "HEAD"])).trim();
 
-    const startedAt = now();
-    let pollIndex = 0, gateHead = null;
-    for (;;) {
-      await renew();
-      const w = await io.waitCiGreen(pr, repo, 0).catch(() => ({ rc: 2, text: "" }));
-      if (w.rc === 0) { gateHead = /CI_GATE_HEAD:\s*([0-9a-f]{7,40})/.exec(w.text ?? "")?.[1] ?? null; break; }
-      if (w.rc === 1) return await needsHuman(`remote CI failed on PR #${pr}:\n${String(w.text).slice(-2000)}`);
-      if (now() - startedAt >= ciMaxMinutes * 60000) {
-        // Slow CI is never a needs-human: leave the PR open and resumable.
-        ev({ event: "CI_PENDING_WAIT", state: "end", pr, result: "timeout" });
-        return await finish("ci-pending", `PR #${pr} still waiting on CI after ${ciMaxMinutes} min`, { pr });
-      }
-      onProgress({ event: "phase_paused", phase: "merge", detail: `CI pending on PR #${pr}` });
-      await sleep(ciPollDelayMs(pollIndex++, random));
+    // ---- 6. the register comment ----
+    // merge policy: required (default) | all | none
+    let policy = mergeWait, required = [];
+    if (mergeWait === "required") {
+      try { required = (await io.requiredChecks?.(lane)) ?? []; } catch { required = []; }
     }
-    const localHead = String(await git(["rev-parse", "HEAD"])).trim();
-    if (gateHead && !(localHead.startsWith(gateHead) || gateHead.startsWith(localHead))) {
-      return await needsHuman(`CI gate passed for ${gateHead.slice(0, 12)} but the reviewed head is ${localHead.slice(0, 12)}; refusing to merge an unreviewed head.`);
+    const policyText = mergeWait === "required" ? (required.length ? `required (${required.join(", ")})` : "required (no required checks: merged right after review)") : mergeWait;
+    await post(REGISTER_MARKER, renderRegister({ result, gitFiles: files, review, links: { validate: validateUrl, plan: planUrl, review: reviewUrl }, prUrl, usage: usageLine(), policy: policyText }));
+
+    // ---- 7. wait per policy, merge at the reviewed head ----
+    if (policy === "none" || (policy === "required" && !required.length)) {
+      // merge right after review
+    } else {
+      const startedAt = now();
+      let pollIndex = 0, gateHead = null;
+      for (;;) {
+        await renew();
+        if (policy === "all") {
+          const w = await io.waitCiGreen(pr, repo, 0).catch(() => ({ rc: 2, text: "" }));
+          if (w.rc === 0) { gateHead = /CI_GATE_HEAD:\s*([0-9a-f]{7,40})/.exec(w.text ?? "")?.[1] ?? null; break; }
+          if (w.rc === 1) return await needsHuman(`Remote CI failed on PR #${pr}:\n${String(w.text).slice(-2000)}`);
+        } else {
+          let states = [];
+          try { states = (await io.checkStates(pr)) ?? []; } catch { states = []; }
+          const st = (n) => states.find((x) => x.name === n)?.state ?? "pending";
+          const failed = required.filter((n) => st(n) === "failure");
+          if (failed.length) return await needsHuman(`Required check(s) failed on PR #${pr}: ${failed.join(", ")}`);
+          if (required.every((n) => st(n) === "success")) break;
+        }
+        if (now() - startedAt >= ciMaxMinutes * 60000) {
+          // Slow CI is never a needs-human: leave the PR open and resumable.
+          ev({ event: "CI_PENDING_WAIT", state: "end", pr, result: "timeout" });
+          return await finish("ci-pending", `PR #${pr} still waiting on CI after ${ciMaxMinutes} min`, { pr });
+        }
+        onProgress({ event: "phase_paused", phase: "merge", detail: `CI pending on PR #${pr}` });
+        await sleep(ciPollDelayMs(pollIndex++, random));
+      }
+      if (gateHead && !(localHead.startsWith(gateHead) || gateHead.startsWith(localHead))) {
+        return await needsHuman(`CI passed for ${gateHead.slice(0, 12)} but the reviewed head is ${localHead.slice(0, 12)}; refusing to merge an unreviewed head.`);
+      }
     }
     await ghc(["pr", "merge", String(pr), "-R", repo, "--merge", "--match-head-commit", localHead]);
-    await post("FORGE:CLOSE", "", `Merged PR #${pr} at ${localHead.slice(0, 12)}.\n\n- Review rounds: ${reviewRound}\n- Gate rounds: ${gateRounds}\n- Cost: $${usageTotal.cost_usd.toFixed(4)}\n- Wall: ${Math.round((now() - t0) / 1000)}s\n${linkLines}`);
     await ghc(["issue", "close", String(issue), "-R", repo, "--reason", "completed"]).catch(() => {});
     await label("merged");
     return await finish("merged", `PR #${pr}`, { pr });
@@ -350,3 +280,5 @@ export async function runLean(o) {
     return finish("engine-error", e?.message ?? String(e));
   }
 }
+
+export const runLean = runCore;