forgedock 1.15.0 → 1.16.1

package/bin/engine/phases.mjs

@@ -218,6 +218,26 @@ 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"));
+}
+
+/**
+ * forge#3772: investigation close evidence, shared by close.reconcile and close.detectOutcome.
+ * A trusted FORGE:TRAJECTORY, or a trusted current-cycle FORGE:PHASE:COMPLETE (multi-phase body).
+ * Throws on fetch error; callers fail closed.
+ */
+async function hasInvestigationCloseEvidence(issue, io) {
+  const { comments } = await issueMarkers(issue, io);
+  return comments.some((b) => startsWithHeader(b, "FORGE:TRAJECTORY"))
+    || hasPhaseComplete(sliceToCurrentCycle(comments));
+}
+
 /**
  * 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).
@@ -520,6 +540,8 @@ async function reviewArgs(state, ctx, io) {
 
 /** 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;
+/** Default `build.diff_size.batch_seam_min` (docs/CONFIG.md); the engine cannot read forge.yaml here. */
+const DEFAULT_BATCH_SEAM_MIN = 3;
 
 /**
  * Is the issue assessed for decomposition? Evaluated on ONE comment: the newest
@@ -541,23 +563,41 @@ function isDecomposed(report) {
     console.error(`[engine] conflicting decomposition signals (heading=${verdict ?? "none"}, markers=${[...markers].join("+") || "none"}); treating as not decomposed`);
     return false;
   }
-  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. The factor is
-  // the investigator's effective `ESTIMATE_FACTOR:` (positive decimal); absent/invalid -> 1.2.
+  // forge#3573 safety net inputs: own-line, 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 seamsM = /^INDEPENDENT_SEAMS:[ \t]*(\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 * factor) {
-      console.error(`[engine] investigator estimate ${estimate} exceeds gate ${threshold} x ${factor}; routing to decompose`);
-      return true;
+  const sized = est && gate && Number(gate[1]) > 0;
+  const estimate = sized ? Number(est[1]) : 0;
+  const threshold = sized ? Number(gate[1]) : 0;
+  if ((verdict ?? marker) === "YES") {
+    // forge#3786: a YES the numbers do not require is downgraded to NO unless the report
+    // carries an own-line `DECOMPOSE_JUSTIFICATION:` line. Required = estimate over
+    // threshold x factor, or the seam clause (seams >= batch_seam_min and estimate over
+    // threshold / 2). The engine cannot see the `batch` label or the configured
+    // `batch_seam_min`, so it uses the default 3 and stays lenient for batches. Absent
+    // numeric fields keep the YES (no silent downgrade of a malformed report).
+    if (sized) {
+      const seams = seamsM ? Number(seamsM[1]) : 0;
+      const required = estimate > threshold * factor || (seams >= DEFAULT_BATCH_SEAM_MIN && estimate > threshold / 2);
+      const justified = /^DECOMPOSE_JUSTIFICATION:[ \t]*\S/m.test(text);
+      if (!required && !justified) {
+        console.error(`[engine] unsupported DECOMPOSE:YES (estimate ${estimate}, seams ${seams}, gate ${threshold} x ${factor}, no DECOMPOSE_JUSTIFICATION); treating as not decomposed`);
+        return false;
+      }
     }
+    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.
+  if (sized && estimate > threshold * factor) {
+    console.error(`[engine] investigator estimate ${estimate} exceeds gate ${threshold} x ${factor}; routing to decompose`);
+    return true;
   }
   return false;
 }
@@ -959,9 +999,11 @@ export const PHASES = [
         // 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.
+        // forge#3772: investigation exits are normally single-phase (close.md C1 skips the
+        // multi-phase guard for them); a trusted current-cycle PHASE:COMPLETE is accepted as a
+        // safety net so a multi-phase body cannot make every retry fail.
         try {
-          const { comments } = await issueMarkers(state.issue, io);
-          return { satisfied: comments.some((b) => startsWithHeader(b, "FORGE:TRAJECTORY")), terminalReason: "investigation" };
+          return { satisfied: await hasInvestigationCloseEvidence(state.issue, io), terminalReason: "investigation" };
         } catch { return { satisfied: false }; }
       }
       if (snap.state === "CLOSED") return { satisfied: true };
@@ -992,8 +1034,17 @@ export const PHASES = [
       if (snap.labels.includes(PHASE_MARKERS.close.completionLabel))
         return { status: "committed", terminalReason: "merged", outputs: {} };
       // forge#3534: an investigation exit closes the issue itself; keep that reason honest.
-      if (snap.state === "CLOSED")
-        return { status: "committed", terminalReason: state.terminalReason === "investigation" ? "investigation" : "invalid", outputs: {} };
+      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 hasInvestigationCloseEvidence(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/runlog.mjs

@@ -61,6 +61,11 @@ 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;
+  // forge#3772: reason of the LAST RUN_TERMINAL, so a reopen can tell a needs-human terminal
+  // (label cleared by a human) from an engine-error retry.
+  let lastTerminalReason = null;
   for (const e of events) {
     switch (e.event) {
       case "RUN_START":
@@ -75,6 +80,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;
@@ -82,6 +88,7 @@ export function deriveState(events) {
         break;
       case "RUN_TERMINAL":
         s.terminal = true; s.terminalReason = e.reason ?? "done"; s.v = e.seq;
+        lastTerminalReason = s.terminalReason;
         break;
       // forge#3511: an explicit `run-issue --retry` reopens an engine-error
       // terminal. Bumping `v` makes the local state newer than the stale
@@ -91,6 +98,18 @@ 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.
+        // forge#3772: only when the terminal being reopened was itself needs-human (the engine
+        // reopens that only after a live read shows the label cleared). An engine-error retry
+        // keeps remediate committed so the resume guard is not bypassed.
+        if (lastCommitPhase === "remediate" && lastCommitReason === "needs-human"
+            && lastTerminalReason === "needs-human") {
+          s.committed = s.committed.filter((p) => p !== "remediate");
+        }
+        lastTerminalReason = null;
+        s.lastRateLimit = null; // forge#3791: an explicit reopen never re-enters a stale pause
         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 +121,8 @@ 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; lastTerminalReason = null; s.v = e.seq;
+        s.lastRateLimit = null; // forge#3791
         break;
       // forge#2524: a session-limit pause is purely informational — it does
       // NOT touch committed/terminal/terminalReason. The phase that hit the
@@ -111,9 +131,16 @@ export function deriveState(events) {
       // run correctly re-enters pickPhase at the same phase with no special
       // casing needed here beyond recording the diagnostic below.
       case "PHASE_RATE_LIMITED":
-        s.lastRateLimit = { phase: e.phase, resetAt: e.resetAt ?? null, waitMs: e.waitMs ?? null };
+        // forge#3791: backendId is the non-secret identity of the backend/account that hit the limit.
+        s.lastRateLimit = { phase: e.phase, resetAt: e.resetAt ?? null, waitMs: e.waitMs ?? null, backendId: e.backendId ?? null };
         s.v = e.seq;
         break;
+      // forge#3791: the paused phase attempting again means the pause is over. A crash
+      // mid-pause appends no PHASE_START, so a same-backend relaunch still resumes the wait.
+      // `v` is intentionally not bumped.
+      case "PHASE_START":
+        if (s.lastRateLimit && e.phase === s.lastRateLimit.phase) s.lastRateLimit = null;
+        break;
       // PHASE_START / PHASE_FAILED do not change committed state
     }
   }

package/bin/engine.mjs

@@ -4,7 +4,8 @@
  * GitHub state (phase.detectOutcome). All effects are injected → fully testable.
  */
 import { fileURLToPath } from "node:url";
-import { hostname as osHostname } from "node:os";
+import { createHash, scryptSync } from "node:crypto";
+import { hostname as osHostname, homedir } from "node:os";
 import { appendEvent, readLog, deriveState, rewriteLog } from "./engine/runlog.mjs";
 import { pickPhase, TERMINAL_REASONS, issueSnapshot, hasInvestigationExit, postCycleMarker, nextCycleNumber } from "./engine/phases.mjs";
 import { reconcileState } from "./engine/reconcile.mjs";
@@ -36,6 +37,21 @@ export const DEFAULT_MAX_SESSION_LIMIT_PAUSES = 5;
 // the engine and is still capped by `maxSessionLimitPauses`.
 export const DEFAULT_SESSION_LIMIT_WAIT_MS = 30 * 60 * 1000;
 
+/**
+ * forge#3791: non-secret identity of the backend/account a usage-limit pause belongs to.
+ * Truncated sha256 over the resolved backend, the Claude config dir, and a scrypt fingerprint of the
+ * API key (when set; a password KDF, not a bare hash, so the secret is never hashed cheaply). The raw key and path are never emitted.
+ * @param {{backend?: string, env?: object}} [p]
+ * @returns {string} 16 hex chars
+ */
+export function backendIdentity({ backend, env = process.env } = {}) {
+  const sha = (s) => createHash("sha256").update(String(s)).digest("hex");
+  const cfg = env.CLAUDE_CONFIG_DIR || `${homedir()}/.claude`;
+  const key = env.ANTHROPIC_API_KEY
+    ? scryptSync(String(env.ANTHROPIC_API_KEY), "forgedock-backend-identity", 16).toString("hex") : "";
+  return sha(JSON.stringify([backend ?? "auto", cfg, key])).slice(0, 16);
+}
+
 /**
  * Validates the subset of `runIssue()`'s options that must fail fast,
  * synchronously, before any state I/O or timer creation — `backend` and the
@@ -491,10 +507,22 @@ export async function runIssue(opts) {
   // the phase early. Same-host resume reads the LOCAL run-log's lastRateLimit
   // (the remote FORGE:STATE does not carry it). The lease is renewed while we
   // wait so a second relaunch still defers.
-  const rl = local?.lastRateLimit;
+  // forge#3791: after a --retry reopen/next-cycle the reducer cleared the pause, so read the
+  // post-reopen state, not the pre-reopen `local` derive.
+  const rl = (reopened ? state : local)?.lastRateLimit;
   const pendingPhase = pickPhase(state);
-  if (pendingPhase && rl && rl.phase === pendingPhase.id &&
-      typeof rl.resetAt === "number" && Number.isFinite(rl.resetAt) && rl.resetAt > now()) {
+  const currentBackendId = backendIdentity({ backend, env: process.env });
+  const rlApplies = !!(pendingPhase && rl && rl.phase === pendingPhase.id &&
+      typeof rl.resetAt === "number" && Number.isFinite(rl.resetAt) && rl.resetAt > now());
+  // forge#3791: only wait when the pause was recorded by this same backend/account. A record
+  // without backendId (pre-fix) cannot be attributed, so it does not wait.
+  if (rlApplies && rl.backendId !== currentBackendId) {
+    emitProgress({
+      event: "phase_resumed", phase: pendingPhase.id, reason: "session-limit",
+      detail: "rate-limit pause belongs to another backend; not waiting",
+    });
+  }
+  if (rlApplies && rl.backendId === currentBackendId) {
     const waitMs = Math.min(rl.resetAt - now(), MAX_RESUME_RATE_LIMIT_WAIT_MS);
     emitProgress({
       event: "phase_paused", phase: pendingPhase.id, reason: "session-limit", resetAt: rl.resetAt,
@@ -514,6 +542,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") ||
@@ -694,6 +724,7 @@ export async function runIssue(opts) {
             appendEvent(dir, issue, {
               event: "PHASE_RATE_LIMITED", phase: phase.id,
               resetAt: hasResetEpoch ? resetAtMs : null, resetAtDisplay: e.resetAt || null, waitMs,
+              backendId: backendIdentity({ backend, env: process.env }),
             });
             // forge#2524 AC6: progress observer sees the pause so a caller
             // (bin/engine-cli.mjs) can render the wait state instead of the

package/bin/runner.mjs

@@ -52,9 +52,28 @@ import { join, dirname, basename, relative, isAbsolute, extname, win32 as win32P
 import os from "os";
 import { execSync, spawnSync } from "child_process";
 import { createRequire } from "module";
+import { fileURLToPath } from "url";
 import { parseForgeYaml, resolveModelAlias } from "./forge-utils.mjs";
 import { DEFAULT_SPAWN_MAX_BUFFER_BYTES } from "./cli-spawn-shared.mjs";
 
+// Package root (the directory that holds bin/, commands/ and scripts/). Exported to every
+// phase child as FORGEDOCK_HOME so spec fences can source scripts/lib/*.sh without a
+// cache scan. A value the operator already set is never overridden.
+/** Windows drive-letter path (C:\x or C:/x) -> /c/x, the form the bash helpers accept; other paths are returned unchanged. */
+export function toPosixRoot(p, platform = process.platform) {
+  if (platform !== "win32") return p;
+  const m = /^([A-Za-z]):[\\/](.*)$/.exec(p);
+  return m ? `/${m[1].toLowerCase()}/${m[2].replace(/\\/g, "/")}` : p.replace(/\\/g, "/");
+}
+
+const FORGEDOCK_PACKAGE_ROOT = toPosixRoot(dirname(dirname(fileURLToPath(import.meta.url))));
+
+/** Returns `env` with FORGEDOCK_HOME defaulted to the package root (never overriding a set value). */
+export function withForgedockHome(env) {
+  if (!env.FORGEDOCK_HOME) env.FORGEDOCK_HOME = FORGEDOCK_PACKAGE_ROOT;
+  return env;
+}
+
 const DEFAULT_MODEL = "claude-sonnet-5";
 const DEFAULT_MAX_ITERATIONS = 50;
 const DEFAULT_MAX_TOKENS = 16384;
@@ -1391,7 +1410,7 @@ export function runCliBackend({
     // Mirrors the existing scrub in the `run_bash` tool handler below.
     // GH_TOKEN/GITHUB_TOKEN and all other env vars are intentionally left
     // intact — only the Anthropic key is removed.
-    const childEnv = { ...process.env };
+    const childEnv = withForgedockHome({ ...process.env });
     delete childEnv.ANTHROPIC_API_KEY;
 
     // No `shell` option (defaults to false): argv is passed as discrete,
@@ -2182,7 +2201,7 @@ export function getToolHandlers(cwd) {
       // into the model loop, so a prompt-injection payload could otherwise issue
       // a run_bash command that exfiltrates the key. gh/git auth tokens
       // (GH_TOKEN/GITHUB_TOKEN) are intentionally left intact.
-      const childEnv = { ...process.env };
+      const childEnv = withForgedockHome({ ...process.env });
       delete childEnv.ANTHROPIC_API_KEY;
       // Run under bash when available so bash-style commands the model emits
       // (heredocs, scripts/*.sh, single-quote semantics) behave consistently

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. The shared helpers (`scripts/lib/forge-resolve.sh`, `scripts/lib/fence-bootstrap.sh`) are sourced through marker-free stubs, so a conversion reads as a net reduction.
+- Exemption: the `spec-size-exempt` PR label only (needs triage rights; a PR-body marker is not honoured). 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/orchestrate/phase-1-resolve.md

@@ -204,26 +204,9 @@ Phase 1 resolves `$ARGUMENTS` to a concrete issue-number list exactly once, at T
 Classify `$ARGUMENTS` and persist that classification alongside the resolved issue-number list, so Phase 4 (`phase-4-execution.md` Step 4B) can decide whether to re-run the query later in the batch:
 
 ```bash
-# FORGE_ROOT bootstrap (canonical; keep byte-identical across specs, guarded by scripts/forge-root.test.sh)
-FORGE_ROOT=""
-# Windows drive-letter FORGEDOCK_HOME (C:/x or C:\x) is normalized to /c/x (cygpath when present); relative values stay rejected.
-_h="${FORGEDOCK_HOME:-}"; case "$_h" in [A-Za-z]:[/\\]*) _w="$_h"; _h="$(cygpath -u "$_w" 2>/dev/null || true)"; [ -n "$_h" ] || _h="/$(printf %s "$_w" | cut -c1 | tr 'A-Z' 'a-z')$(printf %s "${_w#??}" | tr '\\' '/')" ;; esac
-# Only the official marketplace is trusted (name pinned; override only via the trusted FORGEDOCK_MARKETPLACE env, never repo files).
-_mk="${FORGEDOCK_MARKETPLACE:-forgedock}"; case "$_mk" in ""|.|..|*[!A-Za-z0-9._-]*) _mk="forgedock" ;; esac
-if [ -n "${FORGEDOCK_HOME:-}" ]; then case "$_h" in /*) FORGE_ROOT="$_h" ;; esac; else
-  # Portable to bash 3.2 (macOS), BSD/GNU coreutils and zsh: no mapfile, no sort -V, no bare globs (zsh aborts on no match). Every assignment ends in || true so the block survives set -e / pipefail.
-  _l="$HOME/.claude/commands/work-on.md"; _l="$(readlink -f "$_l" 2>/dev/null || readlink "$_l" 2>/dev/null || true)"; [ -n "$_l" ] && _l="$(dirname "$(dirname "$_l")")"
-  # Codex: install-codex.sh records the clone path in $CODEX_HOME/forge-home (one absolute path); skills are generated files, not symlinks.
-  _cx="${CODEX_HOME:-$HOME/.codex}"; case "$_cx" in /*) _x="$(head -n 1 "$_cx/forge-home" 2>/dev/null || true)" ;; *) _x="" ;; esac
-  # newest cached version first: numeric major.minor.patch of the version dir name only (non-semver names such as commit SHAs are skipped); a release outranks its pre-release (1.10.0 > 1.9.0 > 1.9.0-rc1)
-  _v="$(find -L "$HOME/.claude/plugins/cache" -mindepth 3 -maxdepth 3 -type d 2>/dev/null | awk -F/ -v mk="$_mk" '$(NF-2)==mk && $(NF-1)=="forgedock" && $NF ~ /^[0-9]+\.[0-9]+\.[0-9]+(-.*)?$/{v=$NF;p=index(v,"-");r=1;if(p){v=substr(v,1,p-1);r=0};split(v,a,".");printf "%d %d %d %d %s\n",a[1],a[2],a[3],r,$(0)}' | sort -k1,1nr -k2,2nr -k3,3nr -k4,4nr | cut -d' ' -f5- || true)"
-  _m="$HOME/.claude/plugins/marketplaces/$_mk"
-  # '${CLAUDE_PLUGIN_ROOT}' is substituted by Claude Code when it loads a plugin spec (the exact spelling only, never as an env var), so a running plugin resolves to its own root first; unsubstituted (other runtimes) it stays a literal that the /* check rejects.
-  _k="$(printf '%s\n' '${CLAUDE_PLUGIN_ROOT}' "${FORGE_HOME:-}" "$_l" "$_x" "$_v" "$_m")"
-  while IFS= read -r _c; do
-    case "$_c" in /*) [ -z "$FORGE_ROOT" ] && [ -f "$_c/scripts/verify-phase-trail.sh" ] && [ -f "$_c/scripts/lint-dispatch-prompt.sh" ] && [ -f "$_c/scripts/is-docs-only.sh" ] && [ -f "$_c/bin/engine/resolve.mjs" ] && [ -f "$_c/bin/engine/orchestrate-canary.mjs" ] && [ -f "$_c/bin/engine/admission.mjs" ] && FORGE_ROOT="$_c" ;; esac
-  done <<< "$_k"
-fi
+# FORGE_ROOT: shared resolver scripts/lib/forge-resolve.sh (empty when unresolved => callers fail closed)
+type forge_resolve >/dev/null 2>&1 || { setopt nonomatch 2>/dev/null || true; for _r in "$(cygpath -u "${FORGEDOCK_HOME:-}" 2>/dev/null || printf %s "${FORGEDOCK_HOME:-}")" '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGE_HOME:-}" "$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null | sed 's|/commands/work-on\.md$||')" "$(head -n 1 "${CODEX_HOME:-$HOME/.codex}/forge-home" 2>/dev/null)" "$HOME/.claude/plugins/marketplaces/forgedock" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/forgedock/forgedock/* "$HOME/.claude"/plugins/cache/forgedock/forgedock/*; do case "$_r" in /*) [ -f "$_r/scripts/lib/forge-resolve.sh" ] && { . "$_r/scripts/lib/forge-resolve.sh"; break; };; esac; done; type forge_resolve >/dev/null 2>&1 || forge_resolve() { :; }; }
+FORGE_ROOT="$(forge_root 2>/dev/null || true)"
 # Import ForgeDock's OWN resolve.mjs from FORGE_ROOT, never from the consumer {REPO_PATH}
 # (inert on non-ForgeDock repos, and would execute repo-controlled JS). Unresolved/missing => no output,
 # which Phase 4 treats as "literal" (never re-resolve) — fail closed, loudly.
@@ -394,26 +377,9 @@ After executing the plan, retain every ungrouped finding in the registry for the
 # batch metadata as `{number, affectedFile, members, memberCount}`.
 # Run this after initial resolution and every later admission event; execute the
 # returned `groups`/`extensions` member numbers against the repo each candidate came from.
-# FORGE_ROOT bootstrap (canonical; keep byte-identical across specs, guarded by scripts/forge-root.test.sh)
-FORGE_ROOT=""
-# Windows drive-letter FORGEDOCK_HOME (C:/x or C:\x) is normalized to /c/x (cygpath when present); relative values stay rejected.
-_h="${FORGEDOCK_HOME:-}"; case "$_h" in [A-Za-z]:[/\\]*) _w="$_h"; _h="$(cygpath -u "$_w" 2>/dev/null || true)"; [ -n "$_h" ] || _h="/$(printf %s "$_w" | cut -c1 | tr 'A-Z' 'a-z')$(printf %s "${_w#??}" | tr '\\' '/')" ;; esac
-# Only the official marketplace is trusted (name pinned; override only via the trusted FORGEDOCK_MARKETPLACE env, never repo files).
-_mk="${FORGEDOCK_MARKETPLACE:-forgedock}"; case "$_mk" in ""|.|..|*[!A-Za-z0-9._-]*) _mk="forgedock" ;; esac
-if [ -n "${FORGEDOCK_HOME:-}" ]; then case "$_h" in /*) FORGE_ROOT="$_h" ;; esac; else
-  # Portable to bash 3.2 (macOS), BSD/GNU coreutils and zsh: no mapfile, no sort -V, no bare globs (zsh aborts on no match). Every assignment ends in || true so the block survives set -e / pipefail.
-  _l="$HOME/.claude/commands/work-on.md"; _l="$(readlink -f "$_l" 2>/dev/null || readlink "$_l" 2>/dev/null || true)"; [ -n "$_l" ] && _l="$(dirname "$(dirname "$_l")")"
-  # Codex: install-codex.sh records the clone path in $CODEX_HOME/forge-home (one absolute path); skills are generated files, not symlinks.
-  _cx="${CODEX_HOME:-$HOME/.codex}"; case "$_cx" in /*) _x="$(head -n 1 "$_cx/forge-home" 2>/dev/null || true)" ;; *) _x="" ;; esac
-  # newest cached version first: numeric major.minor.patch of the version dir name only (non-semver names such as commit SHAs are skipped); a release outranks its pre-release (1.10.0 > 1.9.0 > 1.9.0-rc1)
-  _v="$(find -L "$HOME/.claude/plugins/cache" -mindepth 3 -maxdepth 3 -type d 2>/dev/null | awk -F/ -v mk="$_mk" '$(NF-2)==mk && $(NF-1)=="forgedock" && $NF ~ /^[0-9]+\.[0-9]+\.[0-9]+(-.*)?$/{v=$NF;p=index(v,"-");r=1;if(p){v=substr(v,1,p-1);r=0};split(v,a,".");printf "%d %d %d %d %s\n",a[1],a[2],a[3],r,$(0)}' | sort -k1,1nr -k2,2nr -k3,3nr -k4,4nr | cut -d' ' -f5- || true)"
-  _m="$HOME/.claude/plugins/marketplaces/$_mk"
-  # '${CLAUDE_PLUGIN_ROOT}' is substituted by Claude Code when it loads a plugin spec (the exact spelling only, never as an env var), so a running plugin resolves to its own root first; unsubstituted (other runtimes) it stays a literal that the /* check rejects.
-  _k="$(printf '%s\n' '${CLAUDE_PLUGIN_ROOT}' "${FORGE_HOME:-}" "$_l" "$_x" "$_v" "$_m")"
-  while IFS= read -r _c; do
-    case "$_c" in /*) [ -z "$FORGE_ROOT" ] && [ -f "$_c/scripts/verify-phase-trail.sh" ] && [ -f "$_c/scripts/lint-dispatch-prompt.sh" ] && [ -f "$_c/scripts/is-docs-only.sh" ] && [ -f "$_c/bin/engine/resolve.mjs" ] && [ -f "$_c/bin/engine/orchestrate-canary.mjs" ] && [ -f "$_c/bin/engine/admission.mjs" ] && FORGE_ROOT="$_c" ;; esac
-  done <<< "$_k"
-fi
+# FORGE_ROOT: shared resolver scripts/lib/forge-resolve.sh (empty when unresolved => callers fail closed)
+type forge_resolve >/dev/null 2>&1 || { setopt nonomatch 2>/dev/null || true; for _r in "$(cygpath -u "${FORGEDOCK_HOME:-}" 2>/dev/null || printf %s "${FORGEDOCK_HOME:-}")" '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGE_HOME:-}" "$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null | sed 's|/commands/work-on\.md$||')" "$(head -n 1 "${CODEX_HOME:-$HOME/.codex}/forge-home" 2>/dev/null)" "$HOME/.claude/plugins/marketplaces/forgedock" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/forgedock/forgedock/* "$HOME/.claude"/plugins/cache/forgedock/forgedock/*; do case "$_r" in /*) [ -f "$_r/scripts/lib/forge-resolve.sh" ] && { . "$_r/scripts/lib/forge-resolve.sh"; break; };; esac; done; type forge_resolve >/dev/null 2>&1 || forge_resolve() { :; }; }
+FORGE_ROOT="$(forge_root 2>/dev/null || true)"
 # Import ForgeDock's OWN admission.mjs from FORGE_ROOT, never from the consumer {REPO_PATH}.
 # Unresolved/missing => no plan: every candidate stays an ungrouped singleton (fail closed, loudly).
 BATCH_PLAN=""