forgedock 1.3.0 → 1.5.0

package/bin/engine/phases.mjs

@@ -5,7 +5,29 @@
  * @typedef ... (see plan "Shared types")
  */
 
-export const TERMINAL_REASONS = ["merged", "invalid", "needs-human", "decomposed"];
+// forge#2378: marker/label strings are single-sourced from packages/protocol's
+// phase registry (itself derived from RESERVED_TYPES' completionSentinel fields
+// where available) — do NOT reintroduce inline "FORGE:..."/"INVESTIGATION:..."/
+// "workflow:merged" literals in this file. bin/hooks/interactive-engine.mjs
+// imports the identical registry, so the two can no longer drift apart the way
+// they did in forge#2375/PR#2395.
+import { PHASE_MARKERS } from "../../packages/protocol/src/phases.js";
+
+// forge#2261: "engine-error" is a distinct terminal reason for engine/tool-level
+// failures (e.g. an exhausted retry loop where the runner itself never once
+// succeeded, or a fail-fast CLI_BACKEND_FAILED/NO_API_KEY/NO_SDK throw) — kept
+// separate from "needs-human" so it is never misclassified as a genuine
+// human-judgment block by /orchestrate's classify_predecessor_state().
+//
+// forge#2379: "awaiting-merge" mirrors the `workflow:awaiting-merge` label
+// commands/work-on/remediate.md's Phase M8 sets on a HELD-AWAITING-MERGE
+// re-gate outcome (a clean re-review that didn't clear the #1809 Q1 auto-land
+// bar) — already recognized as a terminal state by work-on.md's Universal
+// Phase Dispatcher; this just gives the `remediate` phase's detectOutcome a
+// matching engine-level terminal reason to report instead of overloading
+// "needs-human" (which would misrepresent a clean-but-unmet-bar re-review as
+// a fresh human-judgment escalation).
+export const TERMINAL_REASONS = ["merged", "invalid", "needs-human", "decomposed", "engine-error", "awaiting-merge"];
 
 /**
  * Fetch the issue's comments. Returns both:
@@ -50,14 +72,19 @@ async function issueMarkers(issue, io) {
  *
  * Returns -1 (rather than 0) when the underlying `git` call itself failed
  * (lock contention, transient I/O error, ref not yet fetched, etc.) — distinct
- * from a genuine, successfully-computed 0. This distinction matters to the
+ * from a genuine, successfully-computed 0. More generally, -1 means "this
+ * count was not computed" — that includes both a git failure here AND a
+ * caller that had no resolvable branch to check in the first place (forge#2211:
+ * `detectOutcome` mirrors this same -1 sentinel for its unresolved-branch case
+ * rather than synthesizing its own 0). This distinction matters to the
  * build phase's `detectOutcome` (forge#2176): a *genuine* 0 ahead (git ran
  * cleanly and reported no new commits) is a stable fixed point safe to mark
- * non-retryable, but a transient git error folded into the same 0 would not
- * be — the very next attempt could see a different, non-erroring result with
- * no external input having changed, so it must remain retryable. Callers that
- * only compare `> 0` (reconcile()'s satisfied check) are unaffected: -1 is
- * still not `> 0`, so existing behavior there is unchanged.
+ * non-retryable, but a transient git error — or a not-yet-resolved branch —
+ * folded into the same 0 would not be — the very next attempt could see a
+ * different, computed result with no external input having changed, so it
+ * must remain retryable. Callers that only compare `> 0` (reconcile()'s
+ * satisfied check) are unaffected: -1 is still not `> 0`, so existing
+ * behavior there is unchanged.
  */
 async function commitsAhead(lane, branch, io) {
   try {
@@ -89,6 +116,36 @@ async function commitsAhead(lane, branch, io) {
  */
 function has(blob, marker) { return blob.includes(marker); }
 
+/**
+ * Fetch the issue's live `state` (OPEN/CLOSED) and `labels` in one call.
+ *
+ * This is the single data source for two consumers (forge#2352):
+ *  - the `close` phase's `reconcile`/`detectOutcome` below (which already made
+ *    this exact call inline before this helper existed — factored out here so
+ *    both call sites share one shape instead of drifting independently);
+ *  - the divergence guard in `bin/engine.mjs`'s `runIssue()` phase loop, which
+ *    calls this once per loop iteration (before running any phase other than
+ *    `close`) to detect an issue that was closed / labeled `workflow:invalid`
+ *    / labeled `needs-human` out from under an in-flight run.
+ *
+ * Returns `{ ok: false, state: null, labels: [] }` on any fetch/parse failure
+ * — callers must treat `ok: false` as "could not determine, do not act on
+ * this" rather than "issue has no labels/is not closed". This mirrors the
+ * existing fail-open behavior `close`'s `reconcile` already had (a `gh`
+ * failure there degrades to "not satisfied", never to a false positive).
+ */
+export async function issueSnapshot(issue, io) {
+  const out = await io.gh(["issue", "view", String(issue), "--json", "state,labels"]);
+  let j;
+  try {
+    j = JSON.parse(out || "{}");
+  } catch {
+    return { ok: false, state: null, labels: [] };
+  }
+  const labels = (j.labels || []).map((l) => l.name || l);
+  return { ok: true, state: j.state || null, labels };
+}
+
 /**
  * Parse the real branch name out of the `FORGE:BUILDER` comment's
  * `**Branch**: \`{BRANCH}\`` field (see `commands/work-on/build/implement.md`
@@ -129,7 +186,7 @@ function parseBranchFromMarkers(comments) {
   const re = /\*\*Branch\*\*:\s*`([^`]+)`/;
   for (let i = comments.length - 1; i >= 0; i--) {
     const body = comments[i];
-    if (!body || !body.includes("FORGE:BUILDER:COMPLETE")) continue;
+    if (!body || !body.includes(PHASE_MARKERS.build.completionMarker)) continue;
     const match = body.match(re);
     if (match) return match[1];
   }
@@ -155,15 +212,42 @@ export const PHASES = [
     entryCondition: () => true,
     async detectOutcome(state, io) {
       const { blob } = await issueMarkers(state.issue, io);
-      if (has(blob, "INVESTIGATION:INVALID"))
+      if (has(blob, PHASE_MARKERS.investigate.invalidMarker))
         return { status: "committed", terminalReason: "invalid", outputs: { verdict: "INVALID" } };
-      if (has(blob, "DECOMPOSE:YES"))
+      if (has(blob, PHASE_MARKERS.investigate.decomposedMarker))
         return { status: "committed", terminalReason: "decomposed", outputs: { decompose: true } };
-      if (has(blob, "INVESTIGATION:COMPLETE"))
+      if (has(blob, PHASE_MARKERS.investigate.completionMarker))
         return { status: "committed", outputs: { verdict: "CONFIRMED" } };
-      return { status: "failed", detail: "no INVESTIGATION:COMPLETE marker" };
+      return { status: "failed", detail: `no ${PHASE_MARKERS.investigate.completionMarker} marker` };
     },
-    isTerminalAfter: (s) => s.terminalReason === "invalid" || s.terminalReason === "decomposed",
+    // forge#2379: no longer terminal after "decomposed" — that reason now
+    // hands off to the "decompose" phase below (see bin/engine.mjs's
+    // runIssue(), which special-cases exactly this phase/reason combination
+    // to skip its own immediate-terminate check and let pickPhase run again).
+    // "invalid" is unaffected — investigate.md never posts anything further
+    // after INVESTIGATION:INVALID, so that path still terminates in place.
+    isTerminalAfter: (s) => s.terminalReason === "invalid",
+  },
+  {
+    // forge#2379: "decompose" was previously only a terminal reason on
+    // investigate (the run stopped the instant DECOMPOSE:YES was seen) —
+    // work-on/decompose (sub-issue fan-out, FORGE:DECOMPOSED posting) was
+    // never actually dispatched by the engine. This phase closes that gap:
+    // entryCondition fires exactly when investigate's own outcome signaled
+    // decompose, so pickPhase now genuinely dispatches work-on/decompose
+    // before the run terminates.
+    id: "decompose",
+    command: "work-on/decompose",
+    entryCondition: (s) => s.terminalReason === "decomposed",
+    async detectOutcome(state, io) {
+      const { blob } = await issueMarkers(state.issue, io);
+      if (has(blob, PHASE_MARKERS.decompose.completionMarker))
+        return { status: "committed", terminalReason: "decomposed", outputs: {} };
+      return { status: "failed", detail: `no ${PHASE_MARKERS.decompose.completionMarker} marker` };
+    },
+    // Always terminal: decomposition spawns independent sub-issues, each of
+    // which runs its own /work-on pipeline — nothing more for THIS run to do.
+    isTerminalAfter: () => true,
   },
   {
     id: "context",
@@ -173,12 +257,12 @@ export const PHASES = [
       // Idempotent resume: FORGE:CONTEXT:COMPLETE present → skip the LLM re-run.
       // Bare FORGE:CONTEXT matches a partial/interrupted annotation — require :COMPLETE.
       const { blob } = await issueMarkers(state.issue, io);
-      return has(blob, "FORGE:CONTEXT:COMPLETE") ? { satisfied: true } : { satisfied: false };
+      return has(blob, PHASE_MARKERS.context.completionMarker) ? { satisfied: true } : { satisfied: false };
     },
     async detectOutcome(state, io) {
       const { blob } = await issueMarkers(state.issue, io);
       // Context is non-critical: a missing marker is a VISIBLE skip, not a hard fail (spec §7).
-      if (has(blob, "FORGE:CONTEXT")) return { status: "committed", outputs: {} };
+      if (has(blob, PHASE_MARKERS.context.presenceMarker)) return { status: "committed", outputs: {} };
       return { status: "committed", outputs: { skipped: true, which: "context" } };
     },
   },
@@ -190,13 +274,13 @@ export const PHASES = [
       // Idempotent resume: FORGE:ARCHITECT:COMPLETE present → skip the LLM re-run.
       // Bare FORGE:ARCHITECT matches a partial/interrupted annotation — require :COMPLETE.
       const { blob } = await issueMarkers(state.issue, io);
-      return has(blob, "FORGE:ARCHITECT:COMPLETE") ? { satisfied: true } : { satisfied: false };
+      return has(blob, PHASE_MARKERS.architect.completionMarker) ? { satisfied: true } : { satisfied: false };
     },
     async detectOutcome(state, io) {
       const { blob } = await issueMarkers(state.issue, io);
-      return has(blob, "FORGE:ARCHITECT:COMPLETE")
+      return has(blob, PHASE_MARKERS.architect.completionMarker)
         ? { status: "committed", outputs: {} }
-        : { status: "failed", detail: "no FORGE:ARCHITECT:COMPLETE" };
+        : { status: "failed", detail: `no ${PHASE_MARKERS.architect.completionMarker}` };
     },
   },
   {
@@ -209,19 +293,24 @@ export const PHASES = [
       // check it's already ahead of base → treat as done, skip the LLM (forge#2174).
       const { blob, comments } = await issueMarkers(state.issue, io);
       const branch = resolveBranch(state, comments);
-      if (branch && has(blob, "FORGE:BUILDER:COMPLETE") && (await commitsAhead(state.lane, branch, io)) > 0) {
+      if (branch && has(blob, PHASE_MARKERS.build.completionMarker) && (await commitsAhead(state.lane, branch, io)) > 0) {
         return { satisfied: true, outputs: { branch } };
       }
       return { satisfied: false };
     },
     async detectOutcome(state, io) {
       const { blob, comments } = await issueMarkers(state.issue, io);
-      const complete = has(blob, "FORGE:BUILDER:COMPLETE");        // #1305: require :COMPLETE …
+      const complete = has(blob, PHASE_MARKERS.build.completionMarker); // #1305: require :COMPLETE …
       // Resolve the branch the builder actually created from the FORGE:BUILDER:COMPLETE
       // comment (ground truth), scoped to that specific comment — see
       // resolveBranch()/parseBranchFromMarkers() above (forge#2174, forge#2184).
       const branch = resolveBranch(state, comments);
-      const ahead = branch ? await commitsAhead(state.lane, branch, io) : 0; // … AND real commits
+      // forge#2211: an unresolved branch means the commit count was never
+      // computed at all — mirror commitsAhead()'s own "-1 = not computed"
+      // sentinel here instead of synthesizing a `0`, which is indistinguishable
+      // from a genuine git-confirmed zero and would wrongly trip the
+      // non-retryable guard below on the very first attempt.
+      const ahead = branch ? await commitsAhead(state.lane, branch, io) : -1; // … AND real commits
       if (complete && ahead > 0) return { status: "committed", outputs: { branch } };
       const detail = `builder complete=${complete} commitsAhead=${ahead} branch=${branch || "unresolved"}`;
       // forge#2176: when the builder has already posted FORGE:BUILDER:COMPLETE
@@ -241,10 +330,14 @@ export const PHASES = [
       // retry, so this branch intentionally leaves `retryable` unset
       // (defaults to retryable in bin/engine.mjs's runPhaseWithRetry).
       //
-      // `ahead === -1` means commitsAhead() itself failed (transient git
-      // error), NOT a confirmed zero — that is exactly the kind of failure
-      // a retry might resolve, so it must stay retryable too. Only a
-      // successfully-computed ahead of 0 (a real "nothing new to commit"
+      // `ahead === -1` means the count was never computed — either
+      // commitsAhead() itself failed (transient git error) or the branch
+      // could not be resolved at all (forge#2211: `resolveBranch()` returned
+      // null, e.g. on the very first build attempt before any
+      // FORGE:BUILDER:COMPLETE comment names a branch). Neither is a
+      // confirmed zero — both are exactly the kind of failure a retry might
+      // resolve, so both must stay retryable. Only a successfully-computed
+      // ahead of 0 on a *resolved* branch (a real "nothing new to commit"
       // result) is the true fixed point this non-retryable signal targets.
       if (complete && ahead !== -1) return { status: "failed", detail, retryable: false };
       return { status: "failed", detail };
@@ -266,27 +359,100 @@ export const PHASES = [
       return { status: "failed", detail: "PR open, not merged" };
     },
   },
+  {
+    // forge#2379: `remediate` re-drives a needs-human PR via
+    // commands/work-on/remediate.md (checkout → classify FIXABLE/UNFIXABLE →
+    // fix → quality-gate → re-review → #1809 auto-land bar → merge-or-hold),
+    // finishing with a `FORGE:REMEDIATION`/`FORGE:REMEDIATION:COMPLETE`
+    // marker posted to BOTH the PR and this issue (Phase M8), carrying a
+    // `**Re-gate outcome**: AUTO-LANDED | HELD-AWAITING-MERGE | RE-ESCALATED
+    // | UNFIXABLE` field. This entry registers that outcome vocabulary in the
+    // phase table (closing the literal "remediate appears nowhere in the
+    // engine" gap) and is fully unit-tested via `pickPhase`/`detectOutcome`.
+    //
+    // KNOWN LIMITATION (documented, not fixed here — see forge#2379
+    // investigation "What We Found"): `review`'s `"blocked"` outcome (the
+    // needs-human escalation) causes `bin/engine.mjs`'s `runIssue()` to
+    // `terminate()` immediately, before `review` is ever added to
+    // `state.committed` — and the divergence guard just above that also
+    // pauses before any non-`close` phase once the issue carries
+    // `needs-human`. So a single continuous `runIssue()` walk cannot reach
+    // this phase's `entryCondition` today. In practice `remediate.md` is
+    // (correctly, per `work-on.md` Phase 0A.1) invoked as its own separate
+    // top-level entry point (`/work-on <pr> --remediate`), not as a
+    // continuation of the original run — this phase entry documents and
+    // tests the target state shape for a future run that reconstructs
+    // `committed`/`terminalReason` from live GitHub state (e.g. a dedicated
+    // remediation-run entry point) rather than from a fresh local run-log.
+    // Making that live wiring real is out of this issue's scope — it needs
+    // changes to `review`'s `"blocked"` contract and to `bin/tests/engine.test.mjs`,
+    // both outside this issue's declared file set.
+    id: "remediate",
+    command: "work-on/remediate",
+    entryCondition: (s) => s.committed.includes("review") && s.terminalReason === "needs-human",
+    async detectOutcome(state, io) {
+      const { blob } = await issueMarkers(state.issue, io);
+      if (!has(blob, PHASE_MARKERS.remediate.completionMarker))
+        return { status: "failed", detail: `no ${PHASE_MARKERS.remediate.completionMarker} marker` };
+      // Parse the **Re-gate outcome**: field remediate.md's Phase M8 posts
+      // (e.g. "**Re-gate outcome**: AUTO-LANDED to staging" — value is the
+      // first whitespace-delimited token after the colon).
+      const match = blob.match(/\*\*Re-gate outcome\*\*:\s*([A-Z-]+)/);
+      const reGateOutcome = match ? match[1] : null;
+      switch (reGateOutcome) {
+        case "AUTO-LANDED":
+          // remediate.md's own Phase M8 already drove close in this case
+          // (see that file's "If the outcome was AUTO-LANDED" branch) — the
+          // issue should already carry workflow:merged by the time this
+          // reads, but the terminal reason here is what THIS phase reports,
+          // independent of close's own idempotent detectOutcome re-check.
+          return { status: "committed", terminalReason: "merged", outputs: { reGateOutcome } };
+        case "HELD-AWAITING-MERGE":
+          return { status: "committed", terminalReason: "awaiting-merge", outputs: { reGateOutcome } };
+        case "RE-ESCALATED":
+        case "UNFIXABLE":
+          // Both leave the issue at needs-human (a fresh escalation, or a
+          // policy judgment call respectively) — reuse the existing
+          // "needs-human" terminal reason rather than inventing two more,
+          // matching the #2352/#2353 precedent of reusing an existing
+          // TERMINAL_REASONS value where semantically equivalent.
+          return { status: "committed", terminalReason: "needs-human", outputs: { reGateOutcome } };
+        default:
+          return { status: "failed", detail: `FORGE:REMEDIATION:COMPLETE present but Re-gate outcome unrecognized/missing: ${reGateOutcome || "none"}` };
+      }
+    },
+    isTerminalAfter: () => true,
+  },
   {
     id: "close",
     command: "work-on/close",
     entryCondition: (s) => s.committed.includes("review"),
     async reconcile(state, io) {
       // Idempotent resume: issue already closed or workflow:merged label set → skip the LLM re-run.
-      const out = await io.gh(["issue", "view", String(state.issue), "--json", "state,labels"]);
-      let j;
-      try { j = JSON.parse(out || "{}"); } catch { return { satisfied: false }; }
-      const labels = (j.labels || []).map((l) => l.name || l);
-      return (j.state === "CLOSED" || labels.includes("workflow:merged"))
+      const snap = await issueSnapshot(state.issue, io);
+      if (!snap.ok) return { satisfied: false };
+      return (snap.state === "CLOSED" || snap.labels.includes(PHASE_MARKERS.close.completionLabel))
         ? { satisfied: true }
         : { satisfied: false };
     },
     async detectOutcome(state, io) {
-      const out = await io.gh(["issue", "view", String(state.issue), "--json", "state,labels"]);
-      let j;
-      try { j = JSON.parse(out || "{}"); } catch { return { status: "failed", detail: "malformed gh response" }; }
-      const labels = (j.labels || []).map((l) => l.name || l);
-      if (j.state === "CLOSED" || labels.includes("workflow:merged"))
+      const snap = await issueSnapshot(state.issue, io);
+      if (!snap.ok) return { status: "failed", detail: "malformed gh response" };
+      // forge#2353: a bare `state === "CLOSED"` is NOT sufficient evidence that
+      // a PR actually merged — the divergence guard in bin/engine.mjs (forge#2352)
+      // can now route a closed-as-invalid or otherwise closed-not-merged issue
+      // into this phase (see that guard's own comment for why `close` is exempt
+      // from it), and reporting `terminalReason: "merged"` for that case would
+      // inflate run-log/telemetry merge-rate consumers with runs that never
+      // shipped a PR. Only `workflow:merged` — the label the review phase's own
+      // merge flow sets — is proof of an actual merge. A CLOSED issue without
+      // that label is still a real terminal state (nothing left for this phase
+      // to do), just not a "merged" one — reuse the existing "invalid" reason
+      // (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: {} };
       return { status: "failed", detail: "issue not closed" };
     },
     isTerminalAfter: () => true,

package/bin/engine/resolve.mjs

@@ -0,0 +1,256 @@
+/**
+ * Issue-set resolution predicate model — standing-query re-resolution (forge#2236).
+ *
+ * `/orchestrate`'s Phase 1 (`commands/orchestrate/phase-1-resolve.md`) turns
+ * `$ARGUMENTS` into a concrete list of issue numbers exactly once, at T0, and
+ * that list is frozen for the rest of the run (`commands/orchestrate/phase-4-execution.md`
+ * states this plainly: "Phase 1 only runs once, at the start."). Of the 8
+ * input patterns Phase 1 accepts, only one (`#1 #2 #3` — an explicit literal
+ * set) is actually a one-time snapshot by nature. The other 7
+ * (`milestone <slug>`, `next <N>`, `next <N> all-repos`, `fast-lane`,
+ * `priority:P0`/`priority:P1`/..., `mcp:fast`/`n8n:next 3`, a bare `<slug>`)
+ * are standing queries/predicates — "work all P0s", "work this milestone" —
+ * and a new issue matching that predicate mid-run is currently invisible to
+ * the DAG until the operator re-invokes `/orchestrate` by hand.
+ *
+ * This module is the typed reference implementation for two decisions Phase 1
+ * and Phase 4 need to make about that gap:
+ *
+ *   1. `classifyInputPattern` — is this input a `literal` set (never
+ *      re-resolve — the list of numbers IS the intent) or a `query`
+ *      (re-resolve periodically — the predicate is the intent)?
+ *   2. `shouldReResolve` — given that classification and the run's
+ *      `orchestration.reresolve` config, should Phase 4's Step 4B loop
+ *      actually re-run the query this round?
+ *   3. `foldNewMatches` — of the issue numbers a re-resolution just
+ *      returned, which ones are genuinely new (not already in this run's
+ *      processed-issue registry) and therefore candidates to fold into the
+ *      live DAG?
+ *
+ * As with `bin/engine/admission.mjs` (forge#2234), this module does not
+ * itself shell out to `gh`/`yq` — the orchestrator is LLM-executed prose,
+ * not a `bin/engine/` call site, so `commands/orchestrate/phase-1-resolve.md`
+ * and `commands/orchestrate/phase-4-execution.md` mirror these rules by hand
+ * in bash. Any change to the classification table or defaults here MUST be
+ * mirrored there too (see forge#1837 — mirrored-logic drift between grep ERE
+ * and a typed reference is a recurring review-finding class in this pair of
+ * files).
+ *
+ * Hard invariant (by design, not configurable): `foldNewMatches` only ever
+ * narrows a re-resolved set down to "not yet processed" — it does not itself
+ * decide admission. Every folded-in issue (`newMatches`) MUST still be
+ * dispatched through the exact same path a T0-resolved issue takes —
+ * standard DAG dependency analysis (`phase-3-dependency.md`) followed by
+ * Step 4A/4B's `dispatch_headroom`-gated dispatch (see
+ * `phase-4-execution.md` Step 4B.6) — before an agent is dispatched on it.
+ * This is deliberately **not** Step 4C's `admission.mjs`'s
+ * `evaluateCascadeFinding` chain: that gate's rules (comment/typo keyword
+ * heuristic, P3+same-file defer, generation cap) are shaped for
+ * cascade-spawned review-findings — a different issue-origin stream — and
+ * would incorrectly restrict legitimate re-resolved standing-query issues
+ * if applied here. A mid-run check that detects new work but never
+ * actually wires into dispatch is exactly the dead-code failure class
+ * documented in forge#1832 (`SURFACE_BATCHED_FINDINGS`) — this module must
+ * not become a second instance of it.
+ */
+
+/**
+ * @typedef {"literal"|"query"} InputKind
+ */
+
+/**
+ * @typedef {Object} ClassifiedInput
+ * @property {InputKind} kind
+ * @property {string} pattern - Canonical name of the matched pattern, e.g.
+ *   "literal-numbers", "milestone", "next-n", "next-n-all-repos",
+ *   "fast-lane", "priority", "repo-scoped", "bare-slug".
+ * @property {string[]} args - The raw argument tokens (excluding the pattern
+ *   keyword itself) that produced this classification, preserved so a
+ *   re-resolution round can replay the exact same query. Exceptions:
+ *   `priority` and `repo-scoped` keep the FULL token list instead of
+ *   slicing off a leading keyword token — for those two patterns the
+ *   pattern keyword is fused into the same token as its argument
+ *   (`priority:P0`, `mcp:fast-lane`, `n8n:next`), so there is no separable
+ *   leading keyword token to drop the way there is for `milestone <slug>`
+ *   or `next <N>`. Slicing here would destroy the only copy of the data a
+ *   re-resolution round needs to replay the query.
+ */
+
+/**
+ * Classify a raw `/orchestrate` input string per the Phase 1 input-pattern
+ * table (`commands/orchestrate/phase-1-resolve.md` "Input Patterns").
+ *
+ * Only an explicit list of bare/`#`-prefixed, optionally repo-prefixed issue
+ * numbers (`#1 #2 #3`, `1 2 3`, `#123 mcp:5 n8n:12`) classifies as `literal`.
+ * Every other recognized pattern is a `query` — the predicate, not the
+ * resolved list, is the caller's actual intent, per the issue's finding that
+ * a query re-run mid-batch is what a standing predicate like `priority:P0`
+ * or `fast-lane` implies. An input that matches no known pattern still
+ * classifies as `query` with `pattern: "unknown"` — unrecognized input is
+ * handed to Phase 1's existing milestone/label fallback resolution, which is
+ * itself a query (bare `<slug>` row), not a literal set.
+ *
+ * @param {string} input - Raw `$ARGUMENTS` string (already trimmed).
+ * @returns {ClassifiedInput}
+ */
+export function classifyInputPattern(input) {
+  const trimmed = (input ?? "").trim();
+  const tokens = trimmed.length > 0 ? trimmed.split(/\s+/) : [];
+
+  // literal-numbers: every token is a bare integer or a (optionally
+  // repo-prefixed) `#`-prefixed integer, e.g. "1 2 3", "#1 #2 #3",
+  // "#123 mcp:5 n8n:12". At least one token is required — empty input is
+  // not a literal set, it falls through to "unknown".
+  const literalNumberToken = /^([a-zA-Z0-9_-]+:)?#?\d+$/;
+  if (tokens.length > 0 && tokens.every((t) => literalNumberToken.test(t))) {
+    return { kind: "literal", pattern: "literal-numbers", args: tokens };
+  }
+
+  const lower = trimmed.toLowerCase();
+
+  if (/^milestone\s+/.test(lower)) {
+    return { kind: "query", pattern: "milestone", args: tokens.slice(1) };
+  }
+
+  if (/^next\s+\d+\s+all-repos$/.test(lower)) {
+    return { kind: "query", pattern: "next-n-all-repos", args: tokens.slice(1) };
+  }
+
+  if (/^next\s+\d+$/.test(lower)) {
+    return { kind: "query", pattern: "next-n", args: tokens.slice(1) };
+  }
+
+  if (lower === "fast-lane" || lower === "fast") {
+    return { kind: "query", pattern: "fast-lane", args: [] };
+  }
+
+  if (/^priority:p\d+$/.test(lower) || /^[a-zA-Z0-9_-]+:priority:p\d+$/.test(lower)) {
+    return { kind: "query", pattern: "priority", args: tokens };
+  }
+
+  // repo-scoped queries: "mcp:fast", "n8n:next 3", "mcp:cascade", etc. — a
+  // repo prefix followed by a colon and a recognized query keyword. Checked
+  // after the more specific patterns above so e.g. "mcp:5" (a repo-prefixed
+  // literal number) is not mis-classified here — literalNumberToken already
+  // claimed that shape.
+  if (/^[a-zA-Z0-9_-]+:(fast-lane|fast|next|cascade|review-findings|findings)\b/.test(lower)) {
+    return { kind: "query", pattern: "repo-scoped", args: tokens };
+  }
+
+  if (/^(cascade|review-findings|findings)\b/.test(lower)) {
+    return { kind: "query", pattern: "cascade", args: tokens.slice(1) };
+  }
+
+  if (tokens.length === 1 && tokens[0].length > 0) {
+    // bare `<slug>` — try milestone first, then label search (Phase 1's own
+    // fallback order). Still a query: the slug's membership can change.
+    return { kind: "query", pattern: "bare-slug", args: tokens };
+  }
+
+  return { kind: "query", pattern: "unknown", args: tokens };
+}
+
+/**
+ * @typedef {Object} ReResolveConfig
+ * @property {boolean|string} [enabled] - Explicit off switch. `false` or the
+ *   string `"off"` (case-insensitive) disables re-resolution regardless of
+ *   `kind`. Absent/`undefined`/`true`/`"on"` leaves the default (on for
+ *   query-kind input) in effect. This mirrors the validate-warn-fall-back
+ *   idiom's spirit but re-resolution has only two valid states, so an
+ *   unrecognized value is treated as `true` (default-on) rather than an
+ *   error — the safer default in this context is "keep the existing
+ *   behavior of periodic re-check", not "silently stop tracking a standing
+ *   predicate".
+ * @property {number} [maxRounds] - Bound on how many times a single run may
+ *   re-resolve the same predicate. Required to satisfy the issue's
+ *   "termination is bounded" acceptance criterion — a standing predicate
+ *   that keeps matching must not re-resolve forever. `undefined`/absent
+ *   means "no additional bound beyond the caller's own token-budget /
+ *   generation caps" (those are enforced downstream, by `admission.mjs`,
+ *   not here).
+ */
+
+/**
+ * Decide whether Phase 4's Step 4B loop should re-run the originating query
+ * this round.
+ *
+ * @param {ClassifiedInput} classified - Result of `classifyInputPattern`.
+ * @param {ReResolveConfig} [config]
+ * @param {number} [roundsSoFar] - How many re-resolution rounds have already
+ *   run this batch (0 on the first call).
+ * @returns {{ reResolve: boolean, reason: string }}
+ */
+export function shouldReResolve(classified, config = {}, roundsSoFar = 0) {
+  if (classified.kind === "literal") {
+    return {
+      reResolve: false,
+      reason: "literal issue-number set — the list IS the intent, never re-resolve",
+    };
+  }
+
+  const enabledRaw = config.enabled;
+  // The `"off"` string branch IS reachable via the real `yq`-based bash
+  // mirror in `phase-4-execution.md` Step 4B.6 — not just from direct JS
+  // callers (e.g. this file's own unit tests). `yq`'s default core schema
+  // only coerces the literal scalars `true`/`false` to booleans; an
+  // unquoted `enabled: off` in forge.yaml is parsed as the plain string
+  // `"off"` (verified: `yq '.a.enabled' <<< 'a: {enabled: off}'` prints
+  // `off`, `... | type` prints `!!str`), which then survives
+  // `process.argv[3] === "false" ? false : process.argv[3]` unchanged and
+  // reaches this branch as the string `"off"`. Only `enabled: false`
+  // (unquoted) is coerced by `yq` to boolean `false` before this code
+  // runs. Do not remove this branch as unreachable dead code.
+  const disabled =
+    enabledRaw === false || (typeof enabledRaw === "string" && enabledRaw.trim().toLowerCase() === "off");
+  if (disabled) {
+    return { reResolve: false, reason: "orchestration.reresolve.enabled is off" };
+  }
+
+  if (typeof config.maxRounds === "number" && Number.isFinite(config.maxRounds) && roundsSoFar >= config.maxRounds) {
+    return {
+      reResolve: false,
+      reason: `orchestration.reresolve.max_rounds (${config.maxRounds}) reached — bounded termination`,
+    };
+  }
+
+  return {
+    reResolve: true,
+    reason: `query pattern "${classified.pattern}" is a standing predicate — re-resolving`,
+  };
+}
+
+/**
+ * Narrow a freshly re-resolved issue-number list down to genuinely new
+ * issues — ones not already present in the run's processed-issue registry
+ * (T0-resolved issues plus any already admitted in a prior re-resolution
+ * round). This function does NOT decide admission; every returned number
+ * (`newMatches`) must still be dispatched through the same path a
+ * T0-resolved issue takes — standard DAG dependency analysis followed by
+ * Step 4A/4B's dispatch (`phase-4-execution.md` Step 4B.6) — NOT through
+ * Step 4C's `admission.mjs`'s `evaluateCascadeFinding` chain, which is
+ * reserved for the cascade-spawned review-finding stream — see module
+ * docstring's "Hard invariant".
+ *
+ * @param {number[]} reResolvedNumbers - Issue numbers the query returned this round.
+ * @param {Iterable<number>} processedRegistry - Issue numbers already
+ *   resolved at T0 or admitted in an earlier re-resolution round this run.
+ * @returns {{ newMatches: number[], alreadyProcessed: number[] }}
+ */
+export function foldNewMatches(reResolvedNumbers, processedRegistry) {
+  const processed = new Set(processedRegistry);
+  const newMatches = [];
+  const alreadyProcessed = [];
+  const seenThisCall = new Set();
+
+  for (const n of reResolvedNumbers ?? []) {
+    if (seenThisCall.has(n)) continue; // de-dupe within the same re-resolution result
+    seenThisCall.add(n);
+    if (processed.has(n)) {
+      alreadyProcessed.push(n);
+    } else {
+      newMatches.push(n);
+    }
+  }
+
+  return { newMatches, alreadyProcessed };
+}