forgedock 1.3.0 → 1.4.0

package/commands/cleanup.md

@@ -381,7 +381,7 @@ Do NOT call `gh api ... -X PATCH -f state=closed` on any milestone. This phase i
 
 ### Step 4B.1: Fetch open batchable P3 findings
 
-Eligibility is **default-batchable**: any open `review-finding` + `priority:P3` issue qualifies unless excluded below. The `<!-- FORGE:BATCHABLE -->` marker (still appended by `review-pr.md` at finding-creation time) is honored when present but is no longer required — matching `phase-1-resolve.md`'s eligibility rule. <!-- Changed: forge#1828 — marker was previously mandatory -->
+Eligibility is **default-batchable**: any open `review-finding` + a P3 priority label (`priority:P3` or bare `P3` — see `phase-1-resolve.md`'s "Priority label schema" note; some consumer repos label externally/legacy findings with the bare form) issue qualifies unless excluded below. The `<!-- FORGE:BATCHABLE -->` marker (still appended by `review-pr.md` at finding-creation time) is honored when present but is no longer required — matching `phase-1-resolve.md`'s eligibility rule. <!-- Changed: forge#1828 — marker was previously mandatory; forge#2232 — priority-schema tolerance -->
 
 ```bash
 # Find all open, unbatched P3 review findings. Excludes findings already
@@ -389,12 +389,16 @@ Eligibility is **default-batchable**: any open `review-finding` + `priority:P3`
 # exclusions (security, billing, anti-bot, auth) as the other two batching
 # sites, using the identical jq test() (Oniguruma) patterns so classification
 # cannot diverge between the three sweep locations. <!-- Changed: forge#1828 -->
+# NOTE: "priority:P3" is intentionally NOT in the --label filter — GH label filters are
+# exact-match and can't OR it with bare "P3", so the P3 test moves into the jq predicate
+# below (schema-tolerant, mirrors phase-1-resolve.md exactly). <!-- Added: forge#2232 -->
 UNBATCHED_P3=$(gh issue list {GH_FLAG} \
   --state open \
-  --label "review-finding,priority:P3" \
+  --label "review-finding" \
   --limit 500 \
   --json number,title,body,labels,createdAt \
-  --jq '.[] | select(([.labels[].name] | any(. == "batch")) | not)
+  --jq '.[] | select([.labels[].name] | any(test("^(priority:)?P3$")))
+         | select(([.labels[].name] | any(. == "batch")) | not)
          | select((.title | test("security|billing|anti-bot|auth"; "i")) | not)
          | select(.body | test("## Problem[\\s\\S]{0,500}(security|billing|anti-bot|auth)"; "i") | not)
          | select(([.labels[].name] | any(. == "security" or . == "billing" or . == "anti-bot" or . == "auth")) | not)')

package/commands/orchestrate/config.md

@@ -54,9 +54,49 @@ DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE")
 # renders full tables once at the end regardless of this value.
 NARRATION_MODE=$(yq '.pipeline.narration // "terse"' "$CONFIG_FILE" 2>/dev/null || echo "terse")
 [ "$NARRATION_MODE" = "null" ] && NARRATION_MODE="terse"
+
+# Cascade admission policy (forge#2234) — CLI flags take precedence over forge.yaml, which
+# takes precedence over the "balanced" default. Mirrors the --model <name> precedence
+# pattern below. See docs/CONFIG.md → `orchestration` for the full field reference and
+# `phase-4-execution.md` / `phase-1-resolve.md` for where each resolved value is consumed.
+# Extraction regex is an explicit character allowlist (`[A-Za-z0-9_-]+`), NOT a bare
+# `\S+` — `\S+` would accept `"`, `` ` ``, `$`, `(`, `)`, which a downstream yq fallback
+# embedding (`.orchestration.cascade.policy // "${CLI_CASCADE_POLICY:-balanced}"`) could
+# not safely absorb: an embedded `"` breaks out of the yq string literal, letting the
+# remainder be parsed as yq expression syntax (yq-expression injection — not shell/command
+# injection, since `awk` here only extracts text, never executes it). The allowlist also
+# matches the format every valid value actually takes: policy names are
+# `all`/`balanced`/`conservative`; max-generation is a positive integer or `unlimited`;
+# token-budget is a positive integer or `unlimited` — none of these ever contain anything
+# outside `[A-Za-z0-9_-]`. (forge#2301)
+echo "{ARGUMENTS}" | grep -qE -- '--policy[[:space:]]+[A-Za-z0-9_-]+' && \
+  CLI_CASCADE_POLICY=$(echo "{ARGUMENTS}" | grep -oE -- '--policy[[:space:]]+[A-Za-z0-9_-]+' | awk '{print $2}')
+echo "{ARGUMENTS}" | grep -qE -- '--max-generation[[:space:]]+[A-Za-z0-9_-]+' && \
+  CLI_MAX_GENERATION=$(echo "{ARGUMENTS}" | grep -oE -- '--max-generation[[:space:]]+[A-Za-z0-9_-]+' | awk '{print $2}')
+echo "{ARGUMENTS}" | grep -qE -- '--token-budget[[:space:]]+[A-Za-z0-9_-]+' && \
+  CLI_TOKEN_BUDGET=$(echo "{ARGUMENTS}" | grep -oE -- '--token-budget[[:space:]]+[A-Za-z0-9_-]+' | awk '{print $2}')
+# CLI_CASCADE_POLICY / CLI_MAX_GENERATION / CLI_TOKEN_BUDGET, when set, override the
+# corresponding forge.yaml → orchestration.cascade.* key for this invocation only — pass
+# them through as the yq `//` fallback value at each Step 4A.pre / Phase 1 resolution site
+# (`... // "${CLI_CASCADE_POLICY:-balanced}"`, etc.) instead of the bare literal default.
+# Even with the allowlist above, the final resolved value is STILL validated against the
+# same regex (`^[1-9][0-9]*$|^unlimited$` for the two numeric levers,
+# `^(all|balanced|conservative)$` for policy) at its consuming site in
+# phase-4-execution.md / phase-1-resolve.md before use — this allowlist is defense in
+# depth, not a replacement for that validation.
 ```
 
-All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{PROJECT_NAME}`, `{STAGING_BRANCH}`, `{DEFAULT_BRANCH}`, and `{NARRATION_MODE}` references below are populated from `forge.yaml`.
+All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{PROJECT_NAME}`, `{STAGING_BRANCH}`, `{DEFAULT_BRANCH}`, `{NARRATION_MODE}`, and `{CLI_CASCADE_POLICY}`/`{CLI_MAX_GENERATION}`/`{CLI_TOKEN_BUDGET}` references below are populated from `forge.yaml` and CLI flags.
+
+### Cascade Policy CLI Flags
+
+| Flag | Overrides | Example |
+|------|-----------|---------|
+| `--policy <all\|balanced\|conservative>` | `orchestration.cascade.policy` | `/orchestrate cascade --policy all` |
+| `--max-generation <N\|unlimited>` | `orchestration.cascade.max_generation` | `/orchestrate cascade --max-generation 3` |
+| `--token-budget <N\|unlimited>` | `orchestration.cascade.token_budget` | `/orchestrate cascade --token-budget unlimited` |
+
+Precedence: CLI flag > `forge.yaml → orchestration.cascade.*` > preset default (`balanced`). These flags are additive with, not a replacement for, the pre-existing `--include-deferred`/`--allow-gen2` flags documented in `phase-1-resolve.md` — those remain the fastest way to say "everything, right now," while `--max-generation`/`--policy` express finer-grained policy (e.g. "admit gen-2, stop at gen-3").
 
 ---
 

package/commands/orchestrate/phase-1-resolve.md

@@ -16,12 +16,138 @@ Parse `$ARGUMENTS` to determine which issues to work on:
 |-------|------------|
 | `milestone <slug>` | All open issues assigned to that GitHub milestone (default repo) |
 | `#1 #2 #3` or `1 2 3` | Specific issue numbers, optionally repo-prefixed (e.g., `#123 mcp:5 n8n:12`) |
-| `next <N>` | Top N priority open issues (priority:P0 first, then priority:P1, etc.) |
+| `next <N>` | Top N priority open issues (P0 first, then P1, etc. — accepts both `priority:P<n>` and bare `P<n>` labels, see "Priority label schema" note under P3 batching below) |
 | `next <N> all-repos` | Top N across ALL ecosystem repos |
 | `fast-lane` or `fast` | All open fast-lane issues (no milestone, bugs/fixes) |
-| `priority:P0` or `priority:P1` | All open issues with that priority label |
+| `priority:P0` or `priority:P1` | All open issues with that priority label (matches both `priority:P<n>` and bare `P<n>` on the target repo — see "Priority label schema" note below) |
 | `mcp:fast` or `n8n:next 3` | Repo-scoped queries |
-| `<slug>` (no keyword) | Try milestone first, then fall back to label search |
+| `cascade`, `review-findings`, or `findings` (optionally `--include-deferred` / `--allow-gen2`) | All open `review-finding` issues (default repo, or repo-scoped e.g. `mcp:cascade`). See "Cascade / Review-Finding Resolution" below — by default this admits up to `orchestration.cascade.max_generation` (default 1, i.e. generation ≥ 2 `PERMANENT_DEFERRED` findings excluded); the CLI flags force `unlimited` for this one run, overriding config. <!-- Added: forge#2231, forge#2234 -->|
+| `<slug>` (no keyword) | Try milestone first, then fall back to label search. If both resolve to zero issues, report near-miss label candidates instead of silently resolving to nothing — see "Near-Miss Suggestion" below. <!-- Added: forge#2231 -->|
+
+### Cascade / Review-Finding Resolution
+
+<!-- Added: forge#2231 -->
+
+When the input matches `cascade`, `review-findings`, or `findings` (case-insensitive, optionally repo-prefixed), resolve to open `review-finding`-labeled issues instead of a milestone or plain label search, then apply a generation depth check so the default set here matches what Step 4C would actually admit:
+
+```bash
+# Fetch all open review-finding issues, including body (needed for the generation check below —
+# unlike a plain label search, we cannot skip straight to {number,title,labels,milestone} here).
+CASCADE_CANDIDATES=$(gh issue list {GH_FLAG} --label "review-finding" --state open --limit 500 \
+  --json number,title,labels,milestone,body)
+
+# --- Cascade admission policy resolution (forge#2234) ---
+# orchestration.cascade.max_generation is the config-driven, granular successor to the
+# pre-#2234 --include-deferred/--allow-gen2 flags: instead of an all-or-nothing "admit
+# every deferred generation," an operator can say "admit up to generation 3" and no
+# further. Preset table mirrors phase-4-execution.md's Step 4A.pre resolution exactly
+# (see bin/engine/admission.mjs for the typed, unit-tested reference implementation).
+CASCADE_POLICY_NAME=$(yq '.orchestration.cascade.policy // "balanced"' forge.yaml 2>/dev/null || echo "balanced")
+[ "$CASCADE_POLICY_NAME" = "null" ] && CASCADE_POLICY_NAME="balanced"
+case "$CASCADE_POLICY_NAME" in
+  all) PRESET_MAX_GEN="unlimited" ;;
+  conservative|balanced) PRESET_MAX_GEN=1 ;;
+  *) echo "WARNING: forge.yaml → orchestration.cascade.policy \"${CASCADE_POLICY_NAME}\" is not one of: all, balanced, conservative — falling back to \"balanced\""
+     CASCADE_POLICY_NAME="balanced"; PRESET_MAX_GEN=1 ;;
+esac
+MAX_GENERATION=$(yq ".orchestration.cascade.max_generation // \"${PRESET_MAX_GEN}\"" forge.yaml 2>/dev/null || echo "$PRESET_MAX_GEN")
+[ "$MAX_GENERATION" = "null" ] && MAX_GENERATION="$PRESET_MAX_GEN"
+if [ "$MAX_GENERATION" != "unlimited" ] && ! echo "$MAX_GENERATION" | grep -qE '^[1-9][0-9]*$'; then
+  echo "WARNING: forge.yaml → orchestration.cascade.max_generation is not a positive integer or \"unlimited\" (\"${MAX_GENERATION}\") — falling back to default ${PRESET_MAX_GEN}"
+  MAX_GENERATION="$PRESET_MAX_GEN"
+fi
+
+# Pre-#2234 CLI override — still honored for this resolve step specifically. Either flag
+# forces MAX_GENERATION to "unlimited" for this run only, taking precedence over both the
+# preset and any explicit orchestration.cascade.max_generation value (a human typing
+# --allow-gen2 at the CLI is asking for everything, right now, overriding config).
+echo "{ARGUMENTS}" | grep -qE -- '--include-deferred|--allow-gen2' && MAX_GENERATION="unlimited"
+
+echo "Cascade resolve: policy=${CASCADE_POLICY_NAME} max_generation=${MAX_GENERATION} (forge.yaml → orchestration.cascade.max_generation; --include-deferred/--allow-gen2 forces unlimited)"
+# --- End cascade admission policy resolution ---
+
+# Generation depth — walks the "spawned from issue #N" / "source issue #N" chain up to
+# MAX_HOPS times, counting how many review-finding-labeled ancestors precede this finding.
+# Generation 1 = not spawned from a review-finding (an original issue). Generation 2 = spawned
+# from a review-finding. Generation 3 = spawned from a finding that was itself spawned from a
+# review-finding. This numeric walk (rather than the pre-#2234 single-hop boolean) is what
+# makes "admit gen-2, stop at gen-3" (max_generation: 3) expressible — a binary flag cannot
+# say that; it can only say "admit everything deferred" or "admit nothing deferred." Bounded
+# at MAX_HOPS to guard against a malformed/cyclic reference chain.
+MAX_HOPS=10
+compute_generation() {
+  local body="$1"
+  local generation=1
+  local hops=0
+  while [ "$hops" -lt "$MAX_HOPS" ]; do
+    # Portable two-step extraction (grep -E, not -P/PCRE — macOS BSD grep lacks \K support):
+    # first match the whole "spawned from issue #N" / "source issue: #N" phrase, then pull
+    # the trailing digits off that match.
+    local source_num
+    source_num=$(echo "$body" | grep -ioE 'spawned from issue #[0-9]+|source issue[: #]+[0-9]+' | head -1 | grep -oE '[0-9]+$')
+    [ -z "$source_num" ] && break
+    local source_data
+    source_data=$(gh issue view "$source_num" {GH_FLAG} --json labels,body 2>/dev/null) || break
+    echo "$source_data" | jq -e '[.labels[].name] | index("review-finding")' >/dev/null 2>&1 || break
+    generation=$((generation + 1))
+    body=$(echo "$source_data" | jq -r '.body')
+    hops=$((hops + 1))
+  done
+  echo "$generation"
+}
+
+CASCADE_RESOLVED="[]"
+echo "$CASCADE_CANDIDATES" | jq -c '.[]' | while IFS= read -r FINDING; do
+  FINDING_BODY=$(echo "$FINDING" | jq -r '.body')
+  GENERATION=$(compute_generation "$FINDING_BODY")
+  if [ "$MAX_GENERATION" = "unlimited" ] || [ "$GENERATION" -le "$MAX_GENERATION" ]; then
+    echo "$FINDING" | jq --argjson gen "$GENERATION" '{number, title, labels: [.labels[].name], milestone: .milestone.title, generation: $gen}'
+  fi
+done
+```
+
+**Generation > `max_generation` findings are excluded by default** by the loop above — a `review-finding` issue whose *source* chain is deeper than `orchestration.cascade.max_generation` (default: 1, i.e. generation ≥ 2 excluded — the pre-#2234 behavior, unchanged when the section is absent) is normally deferred permanently (`PERMANENT_DEFERRED`) by Step 4C's own absolute check. That cap is an **autonomy guard**, not a human-request guard: it exists to stop an unattended run from cascading forever, not to block an operator who explicitly asked for this exact bucket of work. See `phase-4-execution.md` Step 4C rule 1 and the reworded anti-pattern note for the full rationale.
+
+This resolve step is a human-requested entry point (the operator typed `cascade`/`review-findings`/`findings` directly), so it honors an explicit override:
+
+- `--include-deferred` or `--allow-gen2` appended to the input (e.g. `cascade --allow-gen2`, `review-findings --include-deferred`): forces `MAX_GENERATION="unlimited"` above, admitting every generation into the resolved set for this run. Without either flag, `orchestration.cascade.max_generation` (default 1) governs how deep the resolved set reaches — the flags/config only change what this **explicit** request is allowed to touch; they do not relax Step 4C's autonomous behavior for anything spawned *during* this run (see "Recursion safety" below).
+- **`orchestration.cascade.max_generation`** (forge#2234) is the config-driven successor to the CLI flags above and supports a granularity the flags cannot: `max_generation: 3` admits generations 1-3 and stops at 4, expressing "admit gen-2, stop at gen-3" directly — something an all-or-nothing `--allow-gen2` flag could never say. The flags remain available and, when passed, override config with `unlimited` for that one invocation.
+
+**Recursion safety (unchanged)**: findings spawned *during* this run by its own sweep agents are still never re-swept, regardless of whether `--include-deferred`/`--allow-gen2`/`orchestration.cascade.max_generation` was in effect at resolve time — see `phase-4-execution.md` Step 4C rules and the recursion-safety note near the anti-patterns list. The override above only widens what this one resolve step admits from the *pre-existing* open issue set; it has no effect on Step 4C's in-run admission logic.
+
+### Near-Miss Suggestion
+
+<!-- Added: forge#2231 -->
+
+When a bare `<slug>` (no keyword) resolves to **zero** issues via both the milestone lookup and the label-search fallback, do not silently return an empty set. Fetch the repo's label list and suggest the closest matching label(s) instead:
+
+```bash
+ALL_LABELS=$(gh label list {GH_FLAG} --json name --jq '.[].name')
+# Simple substring/prefix match against the attempted slug — no fuzzy-matching library required.
+NEAR_MISS=$(echo "$ALL_LABELS" | grep -iE "${SLUG:0:4}" || true)
+```
+
+Report back to the caller: `No milestone or label matched "{SLUG}". Did you mean: {NEAR_MISS list, or "review-finding"/"batch" if SLUG resembles "cascade"}?` This directly fixes the case reported in #2231 — `cascade` is not itself a label in most repos (the only cascade-adjacent labels are `review-finding` and `batch`), so a bare `cascade` slug previously resolved to nothing with no feedback. Note that `cascade`/`review-findings`/`findings` are now handled by the dedicated resolution rule above and never reach this bare-slug fallback path at all — this near-miss path remains for any other unmatched slug.
+
+### Predicate Persistence (literal set vs. standing query)
+
+<!-- Added: forge#2236 -->
+
+Phase 1 resolves `$ARGUMENTS` to a concrete issue-number list exactly once, at T0, and that list is currently frozen for the rest of the run (`phase-4-execution.md`: "Phase 1 only runs once, at the start."). Of the input patterns above, only `#1 #2 #3` / `1 2 3` (optionally repo-prefixed) is genuinely a one-time literal set — every other row (`milestone <slug>`, `next <N>`, `next <N> all-repos`, `fast-lane`, `priority:P0`/`priority:P1`, `mcp:fast`/`n8n:next 3`, a bare `<slug>`) is a **standing query**: the predicate ("all open P0s", "this milestone") is the caller's actual intent, not the specific numbers it happened to resolve to at T0.
+
+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
+node -e '
+import("{REPO_PATH}/bin/engine/resolve.mjs").then(({ classifyInputPattern }) => {
+  console.log(JSON.stringify(classifyInputPattern(process.argv[1])));
+}, () => process.exit(0));
+' "$ARGUMENTS"
+```
+
+This mirrors `bin/engine/resolve.mjs`'s `classifyInputPattern` — a typed, unit-tested reference implementation of the same literal-vs-query rule table shown here (see that file's docstring). As with `admission.mjs` for cascade policy, the two must stay in sync by hand: any change to which patterns count as `literal` vs `query` in this table must be mirrored in `resolve.mjs`, and vice versa.
+
+Persist the result (`kind`, `pattern`, `args`) next to the resolved issue-number list in the batch's in-memory/report state — e.g. `ORIGINATING_QUERY_KIND`, `ORIGINATING_QUERY_PATTERN`, `ORIGINATING_QUERY_ARGS`. Phase 4's re-resolution step (see `phase-4-execution.md` Step 4B) reads these three values; it never re-derives them from `$ARGUMENTS` a second time. If `kind` is `literal`, Phase 4 MUST NOT attempt to re-resolve — the list of numbers already resolved here IS the complete intent.
 
 ### Fetch the issues
 
@@ -42,7 +168,11 @@ gh issue view {NUMBER} -R {SATELLITE_REPO} --json number,title,labels,state,mile
 gh issue list {GH_FLAG} --state open --limit {N} --json number,title,labels,milestone
 # For each satellite in forge.yaml → repos.satellites:
 gh issue list -R {SATELLITE_REPO} --state open --limit 500 --json number,title,labels,milestone
-# Combine, sort by priority, take top N
+# Combine, sort by priority, take top N.
+# Priority rank when sorting: read each issue's labels and normalize to bare P<n> form —
+# `priority:P<n>` and bare `P<n>` both resolve to the same rank (see "Priority label schema"
+# note under P3 batching below); an issue with neither label form sorts last, not first, and
+# should be logged as untriaged rather than silently treated as top priority. <!-- Added: forge#2232 -->
 ```
 
 **Count validation**: After fetching issues, log the count returned. If a milestone query returns exactly 30 issues, warn the user: "WARNING: Exactly 30 issues returned — gh CLI default may have truncated results. Re-running with --limit 500 is recommended." (The --limit 500 above prevents this for standard runs, but verify if the count seems suspiciously low relative to milestone expectations.)
@@ -61,15 +191,107 @@ Remove issues that should NOT be worked on:
 
 If a `workflow:decomposed` issue is found, automatically expand it to its open sub-issues instead.
 
+### Source-PR Triage Hint (pre-flight, non-binding)
+
+<!-- Added: forge#2351 -->
+
+**This is a triage hint for the operator and the dispatched investigation agent — it is NEVER an automated verdict.** It must never cause an issue to be closed, skipped, or excluded from dispatch. See "CRITICAL: No duplicate detection at orchestrator level" below — that rule's spirit ("only a `/work-on` investigation agent, after reading the actual code, can determine validity") applies identically here: a closed-unmerged source PR is a reason to look closer, not a reason to skip looking at all.
+
+**Why this exists**: `staging-review`/`review-finding` issues carry a `**Source**: PR #{N}` citation in their body (e.g. `**Source**: PR #2337 — Deploy: staging → main`, or `**Source**: PR #2337 | Agent: material-change | Confidence: ... | Severity: ...` — see `review-pr-staging.md` and `review-pr.md` for the citation format). When that source PR closed without merging, the finding's premise ("this change lands on staging/main") may or may not still hold — resolving the PR's state ONCE per distinct PR number, before dispatch, costs one `gh pr view` call and gives the operator and the investigation agent a head start, without ever deciding the outcome.
+
+**Two counterexamples from the same 2026-07-17 run prove why this must stay a hint, never a skip:**
+- **#2339 / #2342** — source PR #2337 closed unmerged; the flagged change genuinely never landed by any route (`git log -S` found zero commits for #2339's flagged line; the widening commit in #2342 is not an ancestor of `origin/main`). The hint would have been correct here.
+- **#2346 / #2261 (the load-bearing counterexample)** — source PR #2337 also closed unmerged for #2346, but the flagged code reached `staging` anyway via a **different, independently-merged PR (#2261, commit `90376f5`)** — verified via `git merge-base --is-ancestor 90376f5 origin/staging`. #2346 correctly ended at `needs-human`, not `invalid`. A hint that had been treated as a verdict ("source PR never merged → close") would have been **factually wrong** here — sibling PRs can and do reintroduce or independently land the same code by a different route. **The rule to encode: "the source PR never merged" does NOT imply "the finding is moot."**
+
+**Resolve once per distinct PR number, not once per issue** (many findings from one staging review cite the same source PR):
+
+```bash
+# Fetch staging-review / review-finding issues from the already-resolved issue set.
+# Follows this file's per-issue `gh issue view` convention (see Step 3A/3B in
+# phase-3-dependency.md) rather than assuming a pre-materialized bulk JSON variable.
+declare -A SOURCE_PR_STATE_CACHE   # PR number -> "state|mergedAt" (cached, resolved once per PR)
+declare -A ISSUE_SOURCE_PR         # issue number -> cited PR number (or empty if no citation found)
+declare -A ISSUE_SOURCE_PR_STATE   # issue number -> "OPEN" | "MERGED" | "CLOSED_UNMERGED" | "unknown"
+declare -A ISSUE_LIKELY_MOOT       # issue number -> "yes" | "unknown"
+
+for NUM in {issue_numbers}; do
+  ISSUE_JSON_NUM=$(gh issue view "$NUM" {GH_FLAG} --json labels,body 2>/dev/null)
+  LABELS_NUM=$(echo "$ISSUE_JSON_NUM" | jq -r '[.labels[].name] | join(",")' 2>/dev/null || echo "")
+  case "$LABELS_NUM" in
+    *staging-review*|*review-finding*) : ;;
+    *) ISSUE_LIKELY_MOOT[$NUM]="unknown"; continue ;;
+  esac
+
+  ISSUE_BODY_NUM=$(echo "$ISSUE_JSON_NUM" | jq -r '.body // ""' 2>/dev/null || echo "")
+
+  # Extract the cited PR number. Anchored on the literal "**Source**: PR #" prefix so it
+  # matches both observed formats ("PR #2337 — Deploy: staging → main" and
+  # "PR #2337 | Agent: material-change | ..."); capture stops at the first non-digit.
+  PRNUM=$(echo "$ISSUE_BODY_NUM" | grep -oE '\*\*Source\*\*: PR #[0-9]+' | head -1 | grep -oE '[0-9]+' | head -1)
+  # Digits-only guard (defense in depth — the regex above already restricts to [0-9]+,
+  # but re-validate before interpolating into any gh command; see #1833 — an unsanitized
+  # issue-body-derived value was templated verbatim into a gh command elsewhere in this file).
+  if ! echo "$PRNUM" | grep -qE '^[0-9]+$'; then
+    ISSUE_SOURCE_PR[$NUM]=""
+    ISSUE_SOURCE_PR_STATE[$NUM]="unknown"
+    ISSUE_LIKELY_MOOT[$NUM]="unknown"
+    continue
+  fi
+  ISSUE_SOURCE_PR[$NUM]="$PRNUM"
+
+  # Resolve this PR's state ONCE — cache hit skips the gh call entirely for every
+  # subsequent issue citing the same PR number.
+  if [ -z "${SOURCE_PR_STATE_CACHE[$PRNUM]+x}" ]; then
+    PR_JSON=$(gh pr view "$PRNUM" {GH_FLAG} --json state,mergedAt 2>/dev/null)
+    if [ -n "$PR_JSON" ]; then
+      PR_STATE=$(echo "$PR_JSON" | jq -r '.state')
+      PR_MERGED_AT=$(echo "$PR_JSON" | jq -r '.mergedAt // "null"')
+      SOURCE_PR_STATE_CACHE[$PRNUM]="${PR_STATE}|${PR_MERGED_AT}"
+    else
+      # gh pr view failed (rate limit, deleted PR, network) — non-fatal, mark unknown and continue.
+      SOURCE_PR_STATE_CACHE[$PRNUM]="unknown|unknown"
+    fi
+  fi
+
+  CACHED="${SOURCE_PR_STATE_CACHE[$PRNUM]}"
+  C_STATE="${CACHED%%|*}"
+  C_MERGED="${CACHED##*|}"
+
+  if [ "$C_STATE" = "unknown" ]; then
+    ISSUE_SOURCE_PR_STATE[$NUM]="unknown"
+    ISSUE_LIKELY_MOOT[$NUM]="unknown"
+  elif [ "$C_STATE" = "CLOSED" ] && [ "$C_MERGED" = "null" ]; then
+    ISSUE_SOURCE_PR_STATE[$NUM]="CLOSED_UNMERGED"
+    ISSUE_LIKELY_MOOT[$NUM]="yes"
+  elif [ "$C_STATE" = "MERGED" ] || { [ "$C_STATE" = "CLOSED" ] && [ "$C_MERGED" != "null" ]; }; then
+    ISSUE_SOURCE_PR_STATE[$NUM]="MERGED"
+    ISSUE_LIKELY_MOOT[$NUM]="unknown"
+  else
+    ISSUE_SOURCE_PR_STATE[$NUM]="OPEN"
+    ISSUE_LIKELY_MOOT[$NUM]="unknown"
+  fi
+done
+```
+
+**Output arrays** (consumed downstream — never re-derived): `ISSUE_LIKELY_MOOT[$NUM]` (`yes`/`unknown`), `ISSUE_SOURCE_PR[$NUM]` (cited PR number or empty), `ISSUE_SOURCE_PR_STATE[$NUM]` (`OPEN`/`MERGED`/`CLOSED_UNMERGED`/`unknown`).
+
+- `commands/orchestrate/phase-3-dependency.md` Step 3E's Dependency Graph plan table dereferences `ISSUE_LIKELY_MOOT[$NUM]` as a `Source-PR Hint` column — informational only, never affecting a row's `Status`.
+- `commands/orchestrate/phase-4-execution.md`'s Agent-spawn template threads `ISSUE_LIKELY_MOOT[$NUM]` / `ISSUE_SOURCE_PR[$NUM]` / `ISSUE_SOURCE_PR_STATE[$NUM]` into the dispatched agent's initial context as `{SOURCE_PR_HINT_CONTEXT}`, explicitly framed as a starting point to check first — never as a reason to skip investigating.
+
+**MUST NOT**: This hint MUST NOT be used, anywhere in this pipeline, to auto-close an issue, auto-skip it from dispatch, exclude it from the resolved issue set, or substitute for the investigation agent's own evidence-based verdict. Every `likely-moot: yes` issue is still dispatched into a full `/work-on` pipeline exactly like every other issue in the resolved set — the "CRITICAL: No duplicate detection at orchestrator level" rule below governs this identically.
+
 ### P3 Review-Finding Batching (deterministic grouping rule)
 
 <!-- Added: forge#1333 -->
 <!-- Extended: forge#1818 — default-batchable eligibility, surface-area grouping, lowered same-file threshold -->
+<!-- Extended: forge#2232 — priority-label schema tolerance (bare P<n> vs priority:P<n>) -->
 
 Before finalizing the issue set, apply the P3 batching rule to reduce full-pipeline overhead on low-severity review findings.
 
+**Priority label schema**: ForgeDock's own issue creator (`review-pr.md`) writes only the canonical `priority:P<n>` label form. Some repos this pipeline operates against (issues opened externally, imported, or predating ForgeDock adoption) instead carry a bare `P<n>` label with no `priority:` prefix. Every priority-read check in this section — and its mirrors in `phase-4-execution.md` and `cleanup.md` — MUST accept both forms. `priority:P<n>` wins when (unusually) both are present on the same issue. Issue-*creation* call sites (the batch-issue creation below) are unaffected and keep writing canonical `priority:P<n>` only — there is no case where this pipeline needs to *write* the bare form. <!-- Added: forge#2232 -->
+
 **Trigger conditions** (default-batchable — no opt-in marker required):
-1. The issue has labels `review-finding` + `priority:P3`
+1. The issue has label `review-finding` + a P3 priority label (`priority:P3` or bare `P3`)
 2. The issue does NOT match any Safety exclusion below
 
 The `<!-- FORGE:BATCHABLE -->` marker (still appended by `review-pr.md` at finding-creation time) is honored when present but is no longer REQUIRED for eligibility — a `review-finding`+`priority:P3` issue is batchable by default unless explicitly excluded. This closes the gap where cascade-spawned findings that never carried the marker sat un-batched indefinitely. <!-- Added: forge#1818 -->
@@ -82,13 +304,17 @@ These exclusions apply regardless of priority: P1/P2 findings are already never
 
 **Grouping algorithm (surface area — same file first, leaf directory as broader fallback):** <!-- Changed: forge#1818 — was domain-only -->
 ```bash
-# Fetch all open batchable P3 issues (default-batchable; marker no longer required)
+# Fetch all open batchable P3 issues (default-batchable; marker no longer required).
+# NOTE: `--label` is an exact-match GH filter and cannot OR "priority:P3" with bare "P3" in
+# one query, so the P3 test moves into the jq predicate below (schema-tolerant, forge#2232).
+# Only "review-finding" stays in the --label filter.
 BATCHABLE_P3=$(gh issue list {GH_FLAG} \
   --state open \
-  --label "review-finding,priority:P3" \
+  --label "review-finding" \
   --limit 500 \
   --json number,title,body,labels \
-  --jq '.[] | select((.title | test("security|billing|anti-bot|auth"; "i")) | not)
+  --jq '.[] | select([.labels[].name] | any(test("^(priority:)?P3$")))
+         | select((.title | test("security|billing|anti-bot|auth"; "i")) | not)
          | select(.body | test("## Problem[\\s\\S]{0,500}(security|billing|anti-bot|auth)"; "i") | not)
          | select(([.labels[].name] | any(. == "security" or . == "billing" or . == "anti-bot" or . == "auth")) | not)')
 

package/commands/orchestrate/phase-3-dependency.md

@@ -605,15 +605,15 @@ fi
 value(issue) = priority_weight × danger_zone_weight
 ```
 
-**Priority weight** (from issue labels):
+**Priority weight** (from issue labels — matches both the canonical `priority:P<n>` form and the bare `P<n>` form some consumer repos use for externally/legacy-labeled issues; see `phase-1-resolve.md`'s "Priority label schema" note. `priority:P<n>` wins if both are present on the same issue): <!-- Added: forge#2232 -->
 
 | Label | Weight |
 |-------|--------|
-| `priority:P0` | 4.0 |
-| `priority:P1` | 3.0 |
-| `priority:P2` | 2.0 |
-| `priority:P3` | 1.0 |
-| *(no priority label)* | 1.5 |
+| `priority:P0` or `P0` | 4.0 |
+| `priority:P1` or `P1` | 3.0 |
+| `priority:P2` or `P2` | 2.0 |
+| `priority:P3` or `P3` | 1.0 |
+| *(neither form present)* | 1.5 |
 
 **Danger-zone weight** (from affected files via FORGE:INVESTIGATOR comment): Read the `### Affected Files` section and check each file path against the danger-zone list from `forge.yaml → review.danger_zones[]`. Each affected file that appears in a danger zone adds 0.5 to the weight (additive, capped at 2.0). Default (no matches): 1.0.
 
@@ -670,13 +670,18 @@ for NUM in "${ISSUES[@]}"; do
   LABELS=$(echo "$ISSUE_DATA" | jq -r '.labels[]' 2>/dev/null || echo '')
 
   # --- Value: priority weight ---
-  if echo "$LABELS" | grep -q "priority:P0"; then
+  # Schema-tolerant (forge#2232): matches canonical "priority:P<n>" (whole-line, via -E
+  # anchors so "priority:P0" doesn't also satisfy a "priority:P0x"-style label) or bare
+  # "P<n>". $LABELS is already a flat newline-separated list of label names (not a JSON
+  # array), so this stays a grep -E check rather than jq test() — no engine-mismatch risk
+  # since there is no jq counterpart mirrored at this specific site.
+  if echo "$LABELS" | grep -qE "^priority:P0$|^P0$"; then
     PRIO_WEIGHT=4.0
-  elif echo "$LABELS" | grep -q "priority:P1"; then
+  elif echo "$LABELS" | grep -qE "^priority:P1$|^P1$"; then
     PRIO_WEIGHT=3.0
-  elif echo "$LABELS" | grep -q "priority:P2"; then
+  elif echo "$LABELS" | grep -qE "^priority:P2$|^P2$"; then
     PRIO_WEIGHT=2.0
-  elif echo "$LABELS" | grep -q "priority:P3"; then
+  elif echo "$LABELS" | grep -qE "^priority:P3$|^P3$"; then
     PRIO_WEIGHT=1.0
   else
     PRIO_WEIGHT=1.5
@@ -814,6 +819,8 @@ done
 
 **Populate every row below by dereferencing `PREDECESSORS[$NUM]`, `ISSUE_DOMAIN[$NUM]`, `ISSUE_SCORE[$NUM]`, and `ISSUE_COST_ESTIMATE[$NUM]` computed in Steps 3B–3E.5 — do not fabricate values from memory or by re-reading issue titles at this point.** The Step 3D.6 gate having passed only guarantees the data structures exist; it does not substitute for actually reading them here. <!-- Added: forge#1913 -->
 
+**Source-PR Hint column**: when `ISSUE_LIKELY_MOOT[$NUM]` (populated by `phase-1-resolve.md`'s "Source-PR Triage Hint" step — see that file) is present for an issue, dereference it into a `Source-PR Hint` column. This column is **informational only** — it never changes a row's `Status` (Ready/Blocked), never removes a row from the table, and never causes a row to be excluded from dispatch. It exists purely so the operator can see, before confirming the plan, which `staging-review`/`review-finding` issues cite a source PR that closed without merging — a reason to look closer during that issue's own investigation phase, not a reason to skip it (see `phase-1-resolve.md`'s counterexamples: #2339/#2342 vs. #2346/#2261 — the same signal was right in one case and would have been wrong as a verdict in the other). <!-- Added: forge#2351 -->
+
 ```
 ## Orchestration Plan
 
@@ -845,16 +852,18 @@ done
 
 ### Dependency Graph
 
-| Issue | Predecessors | Domain | Score | Est. Cost | Status |
-|-------|-------------|--------|-------|-----------|--------|
-| #{A} | — | FRONTEND | {score} | ${cost} | Ready (dispatches 1st by score) |
-| #{B} | — | BILLING | {score} | ${cost} | Ready (dispatches 2nd by score) |
-| #{C} | — | WORKER | {score} | ${cost} [ε] | Ready (dispatches 3rd — ε-reserve) |
-| #{D} | #{A} | FRONTEND | {score} | ${cost} | Blocked (waits for #{A} only) |
-| #{E} | — | DATABASE | {score} | ${cost} | Ready (dispatches 4th by score) |
-| #{F} | #{E} | DATABASE | {score} | ${cost} | Blocked (serialized — waits for #{E}) |
+| Issue | Predecessors | Domain | Score | Est. Cost | Source-PR Hint | Status |
+|-------|-------------|--------|-------|-----------|-----------------|--------|
+| #{A} | — | FRONTEND | {score} | ${cost} | — | Ready (dispatches 1st by score) |
+| #{B} | — | BILLING | {score} | ${cost} | — | Ready (dispatches 2nd by score) |
+| #{C} | — | WORKER | {score} | ${cost} [ε] | — | Ready (dispatches 3rd — ε-reserve) |
+| #{D} | #{A} | FRONTEND | {score} | ${cost} | — | Blocked (waits for #{A} only) |
+| #{E} | — | DATABASE | {score} | ${cost} | — | Ready (dispatches 4th by score) |
+| #{F} | #{E} | DATABASE | {score} | ${cost} | — | Blocked (serialized — waits for #{E}) |
+| #{G} | — | INFRA | {score} | ${cost} | likely-moot (PR #{N} closed unmerged — verify first) | Ready (dispatches 5th by score) |
 
 **[ε]** = no cost prior; eligible for exploration reserve (10% of budget guaranteed for these)
+**Source-PR Hint** = `${ISSUE_LIKELY_MOOT[$NUM]:-unknown}` rendered as `—` when `unknown`/absent, or `likely-moot (PR #{ISSUE_SOURCE_PR[$NUM]} closed unmerged — verify first)` when `yes`. Never affects `Status` or row inclusion — see `phase-1-resolve.md`'s "Source-PR Triage Hint" step for how this is computed and why it stays a hint.
 
 **Score** = value / estimated_cost (value = priority_weight × danger_zone_weight; higher = dispatches first within the ready-set)
 **Est. Cost** = cost-prior mean for (task_type × module), or label heuristic if no prior