forgedock 1.14.0 → 1.16.0

package/bin/engine/phases-args.test.mjs

@@ -100,6 +100,17 @@ describe("engine phase args satisfy each target spec's argument-hint (forge#3499
     await assert.rejects(() => close.buildArgs({ ...state, pr: null, terminalReason: "merged" }, ctx, io), PhaseArgsError);
   });
 
+  it("close investigation: --terminal-state investigation, never --pr (forge#3534)", async () => {
+    const close = PHASES.find((p) => p.id === "close");
+    for (const pr of [null, 12]) {
+      const args = await close.buildArgs({ ...state, pr, terminalReason: "investigation" }, ctx, io);
+      assert.equal(args[args.indexOf("--terminal-state") + 1], "investigation");
+      assert.ok(!args.includes("--pr"));
+    }
+    for (const reason of ["needs-human", "awaiting-merge", "engine-error"])
+      await assert.rejects(() => close.buildArgs({ ...state, terminalReason: reason }, ctx, io), PhaseArgsError);
+  });
+
   it("close derives --terminal-state from the run's terminal reason", async () => {
     const close = PHASES.find((p) => p.id === "close");
     for (const [reason, expected] of [[null, "merged"], ["invalid", "invalid"], ["decomposed", "decomposed"]]) {

package/bin/engine/phases.mjs

@@ -95,6 +95,8 @@ async function issueMarkers(issue, io) {
   return { comments };
 }
 
+/** Non-terminal held-resume record (remediate.md Phase M8, forge#3685): header and sentinel are the same line; never a COMPLETE marker. */
+const REMEDIATION_HELD_MARKER = "FORGE:REMEDIATION_HELD";
 const reEscape = (x) => x.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 /** True when `body` STARTS with the typed header `<!-- {header}` (e.g. `FORGE:BUILDER`). */
 function startsWithHeader(body, header) {
@@ -175,6 +177,9 @@ export async function postCycleMarker(issue, n, io) {
  * `FORGE:ACCEPTANCE_GATE:PASSED` => "pass"; `:FAILED`, `:BLOCKED` or a
  * `FORGE:BUILD_BLOCKED` comment => "blocked"; none => "none" (legacy / crash
  * paths keep their prior behaviour). `comments` are trusted bodies, oldest first.
+ * Stays fail-closed by design. A blocked state clears only via a newer PASSED, which a
+ * re-invocation posts: build.md B0 "gate resume" re-enters B6.5 instead of returning
+ * ALREADY_DONE when the newest gate marker is blocked (forge#3725).
  */
 function latestGateState(comments) {
   const gate = "FORGE:ACCEPTANCE_GATE";
@@ -187,11 +192,41 @@ function latestGateState(comments) {
   }
   return "none";
 }
+/**
+ * Investigation exit evidence (forge#3534): a trusted comment led by
+ * `<!-- FORGE:INVESTIGATION:DELIVERABLES -->` as a full line. Anchored like every
+ * other marker, so the string quoted inside another comment never counts.
+ */
+function hasInvestigationMarker(comments) {
+  const m = PHASE_MARKERS.build.investigationMarker;
+  return hasMarker(comments, m, m);
+}
+/**
+ * forge#3534 (SEC-3716-1): does the issue carry a trusted current-cycle investigation exit marker?
+ * The implement child closes an investigation issue itself (CLOSED, no `workflow:merged`), so the
+ * engine's divergence guard must not read that as a dead issue before build.reconcile runs.
+ * Fail closed: any fetch error means "no marker" (the guard then behaves as before).
+ */
+export async function hasInvestigationExit(issue, io) {
+  try {
+    const { comments } = await issueMarkers(issue, io);
+    return hasInvestigationMarker(sliceToCurrentCycle(comments));
+  } catch { return false; }
+}
 /** close.md C2 PHASE_COMPLETE evidence in the current cycle (forge#3545). */
 function hasPhaseComplete(comments) {
   return hasMarker(comments, "FORGE:PHASE:COMPLETE", "FORGE:PHASE:COMPLETE");
 }
 
+/**
+ * close.md's own idempotency key: a trusted FORGE:TRAJECTORY comment. Shared by close.reconcile
+ * and close.detectOutcome so the two cannot drift. Throws on fetch error; callers fail closed.
+ */
+async function hasTrajectory(issue, io) {
+  const { comments } = await issueMarkers(issue, io);
+  return comments.some((b) => startsWithHeader(b, "FORGE:TRAJECTORY"));
+}
+
 /**
  * Trusted comment bodies, chronological — the same single fetch + trust predicate
  * as issueMarkers() (one path, forge#3542). Fail closed: a fetch error yields `[]` here (issueMarkers itself propagates it).
@@ -228,6 +263,33 @@ function sizeGateRoutesToDecompose(comments) {
   if (!m || m[1] !== "OVER" || !/^###[ \t]+Split Proposal\b/m.test(body)) return false;
   return !comments.slice(idx + 1).some((c) => starts(c, override) && overrideHasJustification(c));
 }
+/**
+ * Decompose loop guard (mirrors build.md B5.5 and decompose.md Guard 1). Returns a
+ * short reason string when the issue must NOT be routed to decompose, else null:
+ * a `**Parent**: #N` body line (a sub-issue; decompose Guard 1 would BLOCK it), a
+ * TRUSTED `FORGE:DECOMPOSED` comment, or a TRUSTED justified `FORGE:SIZE_OVERRIDE`.
+ * `comments` MUST be trusted bodies. A body-fetch failure fails toward the guard
+ * (not decomposed) so an error can never route into a refusing decompose phase.
+ */
+async function decomposeLoopGuard(issue, comments, io) {
+  const starts = (c, m) => typeof c === "string" && c.trimStart().startsWith(`<!-- ${m}`);
+  if (comments.some((c) => starts(c, "FORGE:DECOMPOSED"))) return "already decomposed (FORGE:DECOMPOSED)";
+  if (comments.some((c) => starts(c, PHASE_MARKERS.build.sizeOverrideMarker) && overrideHasJustification(c)))
+    return "justified FORGE:SIZE_OVERRIDE";
+  let body;
+  try {
+    const out = String((await io.gh(["issue", "view", String(issue), "--json", "body", "--jq", ".body"])) ?? "");
+    body = out;
+    if (out.trimStart().startsWith("{")) {
+      try { const j = JSON.parse(out); if (j && typeof j.body === "string") body = j.body; } catch { /* raw text */ }
+    }
+  } catch {
+    return "issue body unavailable (failing toward not decomposed)";
+  }
+  if (/^\*\*Parent\*\*:[ \t]*#\d+/m.test(body.replace(/\r\n/g, "\n"))) return "sub-issue (**Parent**: #N)";
+  return null;
+}
+
 /** Cheap untrusted pre-check: does ANY comment look like an OVER gate? Only then is the trusted fetch worth making. */
 function mayRouteToDecompose(comments) {
   const gate = PHASE_MARKERS.build.sizeGateMarker;
@@ -465,8 +527,8 @@ async function reviewArgs(state, ctx, io) {
           "--branch", need(state.branch, "branch", BRANCH_RE), ...baseArgs(state)];
 }
 
-/** Default `build.diff_size.estimate_factor` (docs/CONFIG.md); mirrored here for the isDecomposed safety net. */
-const ESTIMATE_FACTOR = 1.2;
+/** Default `build.diff_size.estimate_factor` (docs/CONFIG.md); used when the report carries no valid `ESTIMATE_FACTOR:` field. */
+const DEFAULT_ESTIMATE_FACTOR = 1.2;
 
 /**
  * Is the issue assessed for decomposition? Evaluated on ONE comment: the newest
@@ -491,14 +553,18 @@ function isDecomposed(report) {
   if ((verdict ?? marker) === "YES") return true;
   // forge#3573 safety net: an investigator NO whose own size estimate is clearly over
   // the gate (estimate > threshold x factor) fails toward decompose. Own-line,
-  // whole-number fields only; absent/0/non-numeric fields have no effect.
+  // whole-number fields only; absent/0/non-numeric fields have no effect. The factor is
+  // the investigator's effective `ESTIMATE_FACTOR:` (positive decimal); absent/invalid -> 1.2.
   const est = /^ESTIMATED_DIFF_LINES:[ \t]*(\d+)[ \t]*$/m.exec(text);
   const gate = /^GATE_THRESHOLD:[ \t]*(\d+)[ \t]*$/m.exec(text);
+  const fac = /^ESTIMATE_FACTOR:[ \t]*(\d+(?:\.\d+)?)[ \t]*$/m.exec(text);
+  const parsedFactor = fac ? Number(fac[1]) : NaN;
+  const factor = Number.isFinite(parsedFactor) && parsedFactor > 0 ? parsedFactor : DEFAULT_ESTIMATE_FACTOR;
   if (est && gate) {
     const estimate = Number(est[1]);
     const threshold = Number(gate[1]);
-    if (threshold > 0 && estimate > threshold * ESTIMATE_FACTOR) {
-      console.error(`[engine] investigator estimate ${estimate} exceeds gate ${threshold} x ${ESTIMATE_FACTOR}; routing to decompose`);
+    if (threshold > 0 && estimate > threshold * factor) {
+      console.error(`[engine] investigator estimate ${estimate} exceeds gate ${threshold} x ${factor}; routing to decompose`);
       return true;
     }
   }
@@ -527,8 +593,16 @@ export const PHASES = [
         return { status: "committed", terminalReason: "invalid", outputs: { verdict: "INVALID" } };
       if (closing === complete) {
         // investigate.md emits `### Decomposition Assessment` then `**YES**|**NO**`.
-        if (isDecomposed(report))
+        if (isDecomposed(report)) {
+          // Lazy: the body fetch only happens on the decompose path. A child / already
+          // decomposed / overridden issue cannot be decomposed (decompose Guard 1 BLOCKs).
+          const guard = await decomposeLoopGuard(state.issue, comments, io);
+          if (guard) {
+            console.error(`[engine] decompose suppressed for #${state.issue}: ${guard}; treating as not decomposed`);
+            return { status: "committed", outputs: { verdict: "CONFIRMED" } };
+          }
           return { status: "committed", terminalReason: "decomposed", outputs: { decompose: true } };
+        }
         return { status: "committed", outputs: { verdict: "CONFIRMED" } };
       }
       return { status: "failed", detail: `no ${PHASE_MARKERS.investigate.completionMarker} marker` };
@@ -590,6 +664,8 @@ export const PHASES = [
         const merged = await mergedPrForBranch(branch, state.lane, io);
         if (merged) return { satisfied: true, outputs: { branch, pr: merged.number } };
       }
+      // forge#3534: an investigation exit already posted its deliverables marker: build is done.
+      if (hasInvestigationMarker(comments)) return { satisfied: true, terminalReason: "investigation", outputs: {} };
       return { satisfied: false };
     },
     async detectOutcome(state, io) {
@@ -608,14 +684,21 @@ export const PHASES = [
       const ahead = branch ? await commitsAhead(state.lane, branch, io) : -1; // … AND real commits
       // forge#3545: fail closed. COMPLETE is written before the B6.5 acceptance gate, so a
       // newer FAILED/BLOCKED gate (or BUILD_BLOCKED) must not be committed and move on to
-      // review. Non-retryable: a retry would only re-read the same append-only markers;
-      // a repaired build posts a newer PASSED, which clears this.
+      // review. Non-retryable: a retry would only re-read the same append-only markers.
+      // A newer PASSED clears this: either the in-build repair loop posts it, or a fresh
+      // build invocation does via build.md B0 gate resume (re-enters B6.5; forge#3725).
       if (latestGateState(comments) === "blocked") {
         return { status: "failed", detail: `acceptance gate blocked (builder complete=${complete} commitsAhead=${ahead} branch=${branch || "unresolved"})`, retryable: false };
       }
       if (complete && ahead > 0) {
         return { status: "committed", outputs: { branch, ...buildChildEvidence(comments) } };
       }
+      // forge#3534: INVESTIGATION_COMPLETE writes no code and opens no PR, so it never
+      // posts FORGE:BUILDER:COMPLETE with commits. The durable deliverables marker is the
+      // ground truth. Not retried; review is skipped and close runs `--terminal-state investigation`.
+      if (hasInvestigationMarker(comments)) {
+        return { status: "committed", terminalReason: "investigation", outputs: {} };
+      }
       // B5.5 NEEDS_DECOMPOSE: the size gate posts no FORGE:BUILDER:COMPLETE and
       // build.md says the router (not build) dispatches decompose with no
       // needs-human. Non-retryable by construction: a retry re-measures and
@@ -667,7 +750,8 @@ export const PHASES = [
     id: "review",
     command: "work-on/review",
     buildArgs: reviewArgs,
-    entryCondition: (s) => s.committed.includes("build"),
+    // forge#3534: an investigation build has no PR to review; close runs directly.
+    entryCondition: (s) => s.committed.includes("build") && s.terminalReason !== "investigation",
     async reconcile(state, io) {
       const pr = await openPrFor(state, io);   // adopt an existing PR instead of opening a second
       return pr ? { satisfied: false, outputs: { pr } } : { satisfied: false };
@@ -794,6 +878,19 @@ export const PHASES = [
           ? { status: "committed", terminalReason: "merged", outputs: { reGateOutcome } }
           : { status: "committed", terminalReason: "merged", outputs: { reGateOutcome, closeHandoff: true } };
       };
+      // forge#3685: a resume that ends HELD posts a non-terminal FORGE:REMEDIATION_HELD record (no COMPLETE).
+      // Newest-wins between the held record and COMPLETE, by position in the (trusted, scoped) comment list.
+      const isHeld = (b) => startsWithHeader(b, REMEDIATION_HELD_MARKER) && hasSentinelLine(b, REMEDIATION_HELD_MARKER);
+      let heldAt = -1, completeAt = -1;
+      scoped.forEach((b, i) => {
+        if (isHeld(b)) heldAt = i;
+        if (startsWithHeader(b, PHASE_MARKERS.remediate.header) && hasSentinelLine(b, completion)) completeAt = i;
+      });
+      if (heldAt >= 0 && heldAt > completeAt) {
+        // Merged PR hands to close; otherwise awaiting-merge (terminal for the engine, re-entered by an operator), never a retry.
+        if (await prMerged()) return mergedResult("AUTO-LANDED");
+        return { status: "committed", terminalReason: "awaiting-merge", outputs: { reGateOutcome: "HELD-AWAITING-MERGE" } };
+      }
       if (latest === null) {
         if (await prMerged()) return mergedResult("AUTO-LANDED");
         return { status: "failed", detail: `no ${completion} marker` };
@@ -841,20 +938,23 @@ export const PHASES = [
       // non-merged handoff reason (needs-human, awaiting-merge, engine-error, ...) must never
       // be closed as merged.
       const reason = state.terminalReason ?? null;
-      if (reason !== null && !["merged", "decomposed", "invalid"].includes(reason))
+      if (reason !== null && !["merged", "decomposed", "invalid", "investigation"].includes(reason))
         throw new PhaseArgsError(`refusing close --terminal-state merged from terminalReason ${JSON.stringify(reason)}`);
       const terminal = reason === "decomposed" ? "decomposed"
-        : reason === "invalid" ? "invalid" : "merged";
+        : reason === "invalid" ? "invalid"
+        : reason === "investigation" ? "investigation" : "merged";
       const args = [String(state.issue), ...repoArgs(ctx), ...baseArgs(state)];
       // forge#3504: a merged close with no PR is fabricated evidence — require it.
-      if (state.pr != null || terminal === "merged") args.push("--pr", need(state.pr, "pr", /^[0-9]+$/));
+      // forge#3534: an investigation close is PR-less by definition; never pass --pr.
+      if (terminal !== "investigation" && (state.pr != null || terminal === "merged")) args.push("--pr", need(state.pr, "pr", /^[0-9]+$/));
       if (state.branch) args.push("--branch", need(state.branch, "branch", BRANCH_RE));
       const wt = await resolveWorktree(state, io);
       if (wt && PATH_RE.test(wt)) args.push("--worktree", wt);
       args.push("--terminal-state", terminal);
       return args;
     },
-    entryCondition: (s) => s.committed.includes("review"),
+    entryCondition: (s) => s.committed.includes("review")
+      || (s.committed.includes("build") && s.terminalReason === "investigation"), // forge#3534
     async reconcile(state, io) {
       // Idempotent resume: issue already CLOSED → skip the LLM re-run. forge#3644: the
       // workflow:merged label alone is NOT proof close ran — remediate M7 labels the issue
@@ -864,6 +964,14 @@ export const PHASES = [
       // strict subset of what satisfies this predicate on a CLOSED issue).
       const snap = await issueSnapshot(state.issue, io);
       if (!snap.ok) return { satisfied: false };
+      if (snap.state === "CLOSED" && state.terminalReason === "investigation") {
+        // forge#3534: the implement child closes an investigation issue itself, so CLOSED is no
+        // proof close.md ran (board, summary, trajectory). Its own idempotency key is the
+        // FORGE:TRAJECTORY comment; only that makes this satisfied.
+        try {
+          return { satisfied: await hasTrajectory(state.issue, io), terminalReason: "investigation" };
+        } catch { return { satisfied: false }; }
+      }
       if (snap.state === "CLOSED") return { satisfied: true };
       // forge#3545: a current-cycle FORGE:PHASE:COMPLETE means close already ran to its
       // PHASE_COMPLETE exit; do not re-run it.
@@ -891,8 +999,18 @@ export const PHASES = [
       // (already in TERMINAL_REASONS) rather than inventing a new one.
       if (snap.labels.includes(PHASE_MARKERS.close.completionLabel))
         return { status: "committed", terminalReason: "merged", outputs: {} };
-      if (snap.state === "CLOSED")
-        return { status: "committed", terminalReason: "invalid", outputs: {} };
+      // forge#3534: an investigation exit closes the issue itself; keep that reason honest.
+      if (snap.state === "CLOSED") {
+        if (state.terminalReason !== "investigation")
+          return { status: "committed", terminalReason: "invalid", outputs: {} };
+        // The issue is always already CLOSED for an investigation run, so require the same
+        // positive evidence as reconcile (a trusted FORGE:TRAJECTORY); fail closed on error.
+        let ran = false;
+        try { ran = await hasTrajectory(state.issue, io); } catch { ran = false; }
+        return ran
+          ? { status: "committed", terminalReason: "investigation", outputs: {} }
+          : { status: "failed", detail: "investigation close: no FORGE:TRAJECTORY" };
+      }
       // forge#3545: PHASE_COMPLETE is a valid close exit (multi-phase issue: PR merged,
       // issue deliberately left OPEN). Only the current cycle's marker counts.
       if (snap.state === "OPEN") {

package/bin/engine/phases.test.mjs

@@ -0,0 +1,24 @@
+// Spec-contract test (forge#3725): the build.md B0 resume block must re-enter
+// B6.5 when the newest acceptance-gate marker is blocked (see latestGateState
+// in phases.mjs), instead of returning ALREADY_DONE.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+describe("latestGateState / ACCEPTANCE_GATE spec contract (forge#3725)", () => {
+  it("build.md B0 gate resume re-enters B6.5 before returning ALREADY_DONE", () => {
+    const spec = readFileSync(path.join(ROOT, "commands/work-on/build.md"), "utf8");
+    const start = spec.indexOf("**Resume check**");
+    const end = spec.indexOf("- If there is no `<!-- FORGE:INVESTIGATOR -->`", start);
+    assert.ok(start >= 0 && end > start, "B0 resume block found");
+    const b0 = spec.slice(start, end);
+    assert.match(b0, /ACCEPTANCE_GATE:(FAILED|BLOCKED)/);
+    assert.match(b0, /BUILD_BLOCKED/);
+    assert.match(b0, /re-enter at \*\*Phase B6\.5\*\*/);
+    assert.ok(b0.indexOf("Gate resume") < b0.indexOf("status: ALREADY_DONE"), "gate resume precedes ALREADY_DONE");
+  });
+});

package/bin/engine/runlog.mjs

@@ -61,6 +61,8 @@ export function deriveState(events) {
               remediationKind: null };
   // forge#3528: handoff reason of the LAST PHASE_COMMIT only (replaced, not sticky).
   let lastCommitReason = null;
+  // forge#3754: phase of the LAST PHASE_COMMIT, so a reopen can tell a remediate-terminal run.
+  let lastCommitPhase = null;
   for (const e of events) {
     switch (e.event) {
       case "RUN_START":
@@ -75,6 +77,7 @@ export function deriveState(events) {
         // remediate instead of defaulting to a "merged" close.
         if (e.terminalReason) s.terminalReason = e.terminalReason;
         lastCommitReason = e.terminalReason ?? null;
+        lastCommitPhase = e.phase ?? null;
         // forge#3530: the review's remediation kind must survive resume. A later review
         // commit replaces it; a committed remediate consumes it, so it is never reused.
         if (e.phase === "review") s.remediationKind = e.outputs?.remediation ?? null;
@@ -91,6 +94,12 @@ export function deriveState(events) {
       // retry re-enters remediate/decompose instead of close/build.
       case "RUN_REOPEN":
         s.terminal = false; s.terminalReason = lastCommitReason; s.v = e.seq;
+        // forge#3754: a remediate that ended needs-human is re-run after a human clears the
+        // label. Un-commit it (new array, no in-place mutation) so the forge#3506 resume guard
+        // does not re-terminate and remediate's entryCondition re-selects it.
+        if (lastCommitPhase === "remediate" && lastCommitReason === "needs-human") {
+          s.committed = s.committed.filter((p) => p !== "remediate");
+        }
         break;
       // forge#3562: an explicit `run-issue --retry` on a `phase-complete` run
       // (multi-phase issue: this phase merged, more remain) starts a NEW cycle.
@@ -102,7 +111,7 @@ export function deriveState(events) {
       case "RUN_NEXT_CYCLE":
         s.terminal = false; s.terminalReason = null; s.committed = [];
         s.branch = null; s.pr = null; s.remediationKind = null;
-        lastCommitReason = null; s.v = e.seq;
+        lastCommitReason = null; lastCommitPhase = null; s.v = e.seq;
         break;
       // forge#2524: a session-limit pause is purely informational — it does
       // NOT touch committed/terminal/terminalReason. The phase that hit the

package/bin/engine.mjs

@@ -6,7 +6,7 @@
 import { fileURLToPath } from "node:url";
 import { hostname as osHostname } from "node:os";
 import { appendEvent, readLog, deriveState, rewriteLog } from "./engine/runlog.mjs";
-import { pickPhase, TERMINAL_REASONS, issueSnapshot, postCycleMarker, nextCycleNumber } from "./engine/phases.mjs";
+import { pickPhase, TERMINAL_REASONS, issueSnapshot, hasInvestigationExit, postCycleMarker, nextCycleNumber } from "./engine/phases.mjs";
 import { reconcileState } from "./engine/reconcile.mjs";
 import { makeProjector } from "./engine/projector.mjs";
 import { VALID_BACKENDS } from "./runner.mjs";
@@ -271,7 +271,9 @@ export const MAX_RESUME_RATE_LIMIT_WAIT_MS = 6 * 60 * 60 * 1000;
  *   the last committed phase. forge#3562: when it is `phase-complete` (a
  *   multi-phase issue whose phase merged with more remaining), start a new
  *   cycle (RUN_NEXT_CYCLE) that resets committed/branch/pr and restarts at
- *   investigate. Any other terminal reason is left untouched and returns
+ *   investigate. forge#3571: `needs-human` is reopened (RUN_REOPEN) only when
+ *   a live read shows the issue OPEN with the label cleared. Any other terminal
+ *   reason (or an unreadable snapshot) is left untouched and returns
  *   `not-retryable`.
  * @param {boolean} [opts.waitLease] - forge#3574: when another live holder owns
  *   the lease, poll (via `sleep`, bounded by `leaseTtlMs`) until it expires or
@@ -369,18 +371,45 @@ export async function runIssue(opts) {
   // so the run resumes from its last committed phase. Placed AFTER the I3
   // lease guard (never weaken that ordering) and BEFORE the unconditional
   // lease write below, which then publishes `terminal:false` at the reopen's
-  // higher `v`. Only `engine-error` is ever reopened; needs-human / merged /
-  // decomposed / etc. terminals are left untouched.
+  // higher `v`. `engine-error` is reopened unconditionally; forge#3571:
+  // `needs-human` only once the label is cleared. merged / decomposed / etc.
+  // terminals are left untouched.
   // forge#3562: `phase-complete` is also retryable, but as a NEW cycle
   // (RUN_NEXT_CYCLE clears committed) rather than a reopen of the same one.
   let reopened = false;
   if (retry && state?.terminal) {
-    if (state.terminalReason !== "engine-error" && state.terminalReason !== "phase-complete") {
+    if (state.terminalReason !== "engine-error" && state.terminalReason !== "phase-complete" &&
+        state.terminalReason !== "needs-human") {
       return {
         terminalReason: "not-retryable",
-        detail: `issue ${issue} ended ${state.terminalReason}; --retry only resumes an engine-error or phase-complete run`,
+        detail: `issue ${issue} ended ${state.terminalReason}; --retry only resumes an engine-error, phase-complete or needs-human run`,
       };
     }
+    // forge#3571: a human clearing `needs-human` is the hand-back signal. Reopen
+    // only on a live read showing the issue OPEN and the label gone; a label
+    // still present keeps today's refusal, and an unreadable snapshot fails closed.
+    if (state.terminalReason === "needs-human") {
+      let snap;
+      try { snap = await issueSnapshot(issue, io); } catch { snap = { ok: false, state: null }; }
+      if (!snap.ok) {
+        return {
+          terminalReason: "not-retryable",
+          detail: `issue ${issue} state could not be read; --retry did not reopen the needs-human run`,
+        };
+      }
+      if (snap.state === "CLOSED") {
+        return {
+          terminalReason: "not-retryable",
+          detail: `issue ${issue} is CLOSED; --retry does not reopen a needs-human run on a closed issue`,
+        };
+      }
+      if ((snap.labels || []).includes("needs-human")) {
+        return {
+          terminalReason: "not-retryable",
+          detail: `issue ${issue} still carries needs-human; resolve it and remove the label before --retry`,
+        };
+      }
+    }
     // forge#3562 (SEC-3): a new cycle discards `committed`, so check the live
     // issue first. A CLOSED issue has nothing left to run; an unreadable
     // snapshot fails closed rather than resetting a possibly-finished run.
@@ -485,6 +514,8 @@ export async function runIssue(opts) {
     // must honour that reason instead of picking the next phase (close would throw in buildArgs
     // and end as engine-error; build would run on a decomposed parent). Review's `needs-human`
     // is a handoff to remediate, so only these committed phases trigger the guard.
+    // forge#3754: a reopened (--retry) remediate-terminal run has `remediate` un-committed by the
+    // run-log reducer, so this guard does not fire and remediate re-runs.
     if (state.terminalReason && TERMINAL_REASONS.includes(state.terminalReason) &&
         ((state.committed.includes("remediate") && !["merged", "decomposed", "invalid"].includes(state.terminalReason)) ||
          (state.committed.includes("decompose") && state.terminalReason === "decomposed") ||
@@ -524,8 +555,13 @@ export async function runIssue(opts) {
         // Reuses the existing "invalid" terminal reason (TERMINAL_REASONS)
         // rather than inventing a new one; #2353 makes the same choice for
         // `close`'s own CLOSED-not-merged case.
-        const isDead = snap.labels.includes("workflow:invalid") ||
+        let isDead = snap.labels.includes("workflow:invalid") ||
           (snap.state === "CLOSED" && !snap.labels.includes("workflow:merged"));
+        // forge#3534: an investigation exit closes the issue itself without `workflow:merged`.
+        // With the trusted deliverables marker present, a CLOSED (not invalid) issue is not
+        // divergent: build.reconcile must run so the run reaches close --terminal-state investigation.
+        if (isDead && phase.id === "build" && snap.state === "CLOSED" && !snap.labels.includes("workflow:invalid") &&
+            await hasInvestigationExit(issue, io)) isDead = false;
         if (isDead) {
           const detail = `issue ${issue} is ${snap.state === "CLOSED" ? "closed" : "open"} ` +
             `with divergent state before phase ${phase.id} (labels: ${snap.labels.join(", ") || "none"})`;

package/bin/forgedock.mjs

@@ -3207,7 +3207,7 @@ function help() {
     ["npx forgedock disable [dir]", "Opt a directory out of ForgeDock"],
     ["npx forgedock status [dir]", "Show ForgeDock state for a directory"],
     ["npx forgedock run <cmd> [args]", "Run a command headlessly (local claude CLI or Anthropic API)"],
-    ["npx forgedock run-issue <issue> --lane <lane> [--retry] [--wait-lease]", "Drive one issue through the durable engine (--retry reopens an engine-error run; --wait-lease waits for a held lease; exit 75 = deferred, lease held)"],
+    ["npx forgedock run-issue <issue> --lane <lane> [--retry] [--wait-lease]", "Drive one issue through the durable engine (--retry reopens an engine-error run, or a needs-human run once the label is cleared; --wait-lease waits for a held lease; exit 75 = deferred, lease held)"],
     ["npx forgedock resume-stalled [--dry-run]", "Fleet stall recovery — re-dispatch expired-lease issues"],
     ["npx forgedock demo", "Set up a risk-free demo repo and print next steps"],
     ["npx forgedock labels [setup] [--repo owner/repo]", "Bootstrap ForgeDock-managed labels on a GitHub repo (idempotent)"],

package/commands/forge-stats.md

@@ -52,6 +52,16 @@ Commands are classified by role. Each role has a max line count — beyond this,
 
 ---
 
+## CI Spec-Size Budget
+
+`scripts/check-spec-size.sh` (job `spec-size-budget` in `check-commands.yml`, PRs only) enforces a budget that is independent of the line-count `.baselines`; the baseline is refreshed on release via `/forge-stats baseline`. It compares bytes against the PR base:
+
+- `review-pr.md`, `review-pr-staging.md`, `work-on/remediate.md`, `work-on/review.md`, `work-on.md` may not grow by more than 2% or 4 KB. Shrinking always passes.
+- No `commands/**` file may gain a copy of a canonical block (FORGE_ROOT bootstrap, TRUSTED_SCRIPT/HELPER_SCRIPT resolver, FENCE_BOOTSTRAP anchor); the per-file marker count may not rise. Tighten to an outright ban once the shared helper (#3493) lands.
+- Exemption: the `spec-size-exempt` PR label, or a `<!-- spec-size-exempt: <reason> -->` line in the PR body (non-empty reason). The job summary lists the per-file delta and any waiver.
+
+---
+
 ## Mode: `diff` (default)
 
 Compare current line counts against the last git commit. Shows what grew and what shrank.

package/commands/issue.md

@@ -367,8 +367,23 @@ Run the deterministic dedup script first (authoritative check), then fall back t
 # empty, so this is a no-op for that path.
 DEDUP_EXCLUDE_ARGS=()
 [ -n "$PROGRAMMATIC_EXCLUDE" ] && DEDUP_EXCLUDE_ARGS=(--exclude "$PROGRAMMATIC_EXCLUDE")
-DEDUP_RESULT=$(scripts/issue-dedup.sh "{PROPOSED_TITLE}" {GH_FLAG} "${DEDUP_EXCLUDE_ARGS[@]}" 2>&1)
-DEDUP_EXIT=$?
+# HELPER_SCRIPT resolver (DEDUP_SCRIPT; trusted-install tiers only, never the working directory or the target repo, #3400/#3483): plugin root, FORGE_ROOT, FORGEDOCK_HOME, FORGE_HOME, install symlink, marketplaces, newest pinned plugin cache under CLAUDE_CONFIG_DIR then ~/.claude. The cache scan matters because the plugin-root placeholder is not always substituted in forked runs.
+_l="$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null || true)"; _l="${_l%/commands/work-on.md}"
+_tc="$(printf '%s\n' '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGEDOCK_HOME:-}" "${FORGE_HOME:-}" "$_l" "$HOME/.claude/plugins/marketplaces/forgedock")"
+for _cfg in "${CLAUDE_CONFIG_DIR:-}" "$HOME/.claude"; do
+  [ -n "$_cfg" ] && _tc="$_tc"$'\n'"$(find -L "$_cfg/plugins/cache/forgedock/forgedock" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | awk -F/ '$NF ~ /^[0-9]+\.[0-9]+\.[0-9]+$/{split($NF,a,".");printf "%d %d %d %s\n",a[1],a[2],a[3],$(0)}' | sort -k1,1nr -k2,2nr -k3,3nr | cut -d' ' -f4- || true)"
+done
+DEDUP_SCRIPT=""
+while IFS= read -r _c; do
+  case "$_c" in /*) [ -z "$DEDUP_SCRIPT" ] && [ -f "$_c/scripts/issue-dedup.sh" ] && DEDUP_SCRIPT="$_c/scripts/issue-dedup.sh" ;; esac
+done <<< "$_tc"
+# Unresolved helper: no deterministic result (exit 0, empty) so the LLM fallback below still runs; never exit 1 (duplicate STOP).
+if [ -n "$DEDUP_SCRIPT" ]; then
+  DEDUP_RESULT=$(bash "$DEDUP_SCRIPT" "{PROPOSED_TITLE}" {GH_FLAG} "${DEDUP_EXCLUDE_ARGS[@]}" 2>&1)
+  DEDUP_EXIT=$?
+else
+  DEDUP_RESULT=""; DEDUP_EXIT=0
+fi
 
 if [ "$DEDUP_EXIT" -eq 1 ]; then
   echo "Near-duplicate detected: $DEDUP_RESULT"

package/commands/orchestrate/phase-4-execution.md

@@ -3806,15 +3806,22 @@ for FILE in "${!SURFACE_FILE_MEMBERS[@]}"; do
     # Dedup-check with member exclusion (MANDATORY — forge#2432, identical mechanism to
     # phase-1-resolve.md's mirror block; this site keeps its existing direct-to-gh issue
     # creation below rather than migrating to /issue's Skill routing, since this loop runs
-    # per-completion-cycle and a direct scripts/issue-dedup.sh call is cheaper here). A
+    # per-completion-cycle and a direct issue-dedup.sh call is cheaper here). A
     # batch title necessarily restates its own members' subject matter by construction —
     # excluding the cluster's own member numbers means Phase-2D-style dedup only fires on
     # a GENUINE non-member duplicate. --exclude narrows the candidate set; it is NOT a
     # --force equivalent.
     CHUNK_LIST=$(IFS=,; echo "${CHUNK[*]}")
     PROPOSED_BATCH_TITLE="fix(batch): P3 review findings — ${SAFE_SURFACE_AREA} (same-run batch)"
-    DEDUP_RESULT=$(scripts/issue-dedup.sh "$PROPOSED_BATCH_TITLE" {GH_FLAG} --exclude "$CHUNK_LIST" 2>&1)
-    DEDUP_EXIT=$?
+    # Resolve the helper from the FORGE_ROOT bootstrap above (trusted install root, never the cwd/target repo, #3679). Unresolved: skip the dedup check (exit 0), never read as a duplicate.
+    DEDUP_SCRIPT=""
+    [ -n "$FORGE_ROOT" ] && [ -f "$FORGE_ROOT/scripts/issue-dedup.sh" ] && DEDUP_SCRIPT="$FORGE_ROOT/scripts/issue-dedup.sh"
+    if [ -n "$DEDUP_SCRIPT" ]; then
+      DEDUP_RESULT=$(bash "$DEDUP_SCRIPT" "$PROPOSED_BATCH_TITLE" {GH_FLAG} --exclude "$CHUNK_LIST" 2>&1)
+      DEDUP_EXIT=$?
+    else
+      DEDUP_RESULT=""; DEDUP_EXIT=0
+    fi
 
     if [ "$DEDUP_EXIT" -eq 1 ]; then
       # Genuine non-member duplicate — some other open issue already covers this exact