forgedock 1.3.0 → 1.5.0

package/bin/watch-utils.mjs

@@ -0,0 +1,258 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * Pure, independently-testable helpers for `forgedock watch` (bin/forgedock.mjs).
+ *
+ * Extracted out of watch()/render() (forge#2235) so the label-derivation,
+ * findings-lane classification, priority normalization, satellite-repo
+ * parsing, and heartbeat-batching logic can be unit tested without spawning
+ * `gh` subprocesses. None of these functions perform I/O themselves — the
+ * caller in forgedock.mjs reads files / shells out and passes the results in.
+ */
+
+import { existsSync, readFileSync } from "fs";
+
+/**
+ * Conservative built-in fallback for the watched label set, used only when
+ * bin/labels.json is missing or unreadable. Historically this was the ONLY
+ * label set watch() ever used (forge#2235) — kept here so a broken/missing
+ * manifest degrades to the old (narrow but working) behavior instead of
+ * watch() going fully blind.
+ */
+export const FALLBACK_WORKFLOW_LABELS = [
+  "workflow:investigating",
+  "workflow:ready-to-build",
+  "workflow:building",
+  "workflow:in-review",
+  "needs-human",
+];
+
+/**
+ * The label that marks a review-finding issue, watched in its own lane
+ * (forge#2235) independent of workflow:* state — a finding is born without
+ * any workflow:* label and may never acquire one (deferred/PERMANENT_DEFERRED
+ * findings), so it must not depend on the in-flight label set to be visible.
+ */
+export const FINDINGS_LANE_LABEL = "review-finding";
+
+/**
+ * Derive the watched "in-flight" label set from the canonical bin/labels.json
+ * manifest instead of a hardcoded literal (forge#2235). Returns every label
+ * whose name starts with "workflow:", plus "needs-human" (the terminal-stall
+ * pipeline label, not itself prefixed workflow: but part of the same family).
+ *
+ * Falls back to FALLBACK_WORKFLOW_LABELS if the manifest is absent, unreadable,
+ * or malformed, so a broken manifest never makes watch() go silent.
+ *
+ * @param {string} labelsJsonPath - absolute path to bin/labels.json
+ * @returns {string[]}
+ */
+export function deriveWorkflowLabels(labelsJsonPath) {
+  try {
+    if (!existsSync(labelsJsonPath)) return FALLBACK_WORKFLOW_LABELS;
+    const raw = readFileSync(labelsJsonPath, "utf-8");
+    const all = JSON.parse(raw);
+    if (!Array.isArray(all)) return FALLBACK_WORKFLOW_LABELS;
+    const derived = all
+      .map((l) => l && l.name)
+      .filter((name) => typeof name === "string" && (name.startsWith("workflow:") || name === "needs-human"));
+    return derived.length > 0 ? derived : FALLBACK_WORKFLOW_LABELS;
+  } catch {
+    return FALLBACK_WORKFLOW_LABELS;
+  }
+}
+
+/**
+ * Normalize a mixed label array (strings or {name} objects, as returned by
+ * `gh issue list --json labels`) into a plain array of name strings.
+ * @param {Array<string|{name: string}>} labels
+ * @returns {string[]}
+ */
+function labelNames(labels) {
+  if (!Array.isArray(labels)) return [];
+  return labels.map((l) => (typeof l === "string" ? l : l && l.name)).filter(Boolean);
+}
+
+/**
+ * Classify a review-finding issue's render status in the findings lane from
+ * its full label set (forge#2235). Callers should only invoke this for
+ * issues that do NOT carry a workflow:* label — those are in-flight and
+ * belong in the main table, not the findings lane, to avoid double-rendering
+ * the same issue in two places.
+ *
+ * - "validated"      — confirmed as a real issue (label: validated)
+ * - "false-positive" — dismissed (label: false-positive)
+ * - "queued"         — awaiting human validation (label: needs-validation)
+ * - "deferred"       — bare review-finding with none of the above; this is
+ *                       the previously-invisible "PERMANENT_DEFERRED" bucket
+ *
+ * @param {Array<string|{name: string}>} labels
+ * @returns {"validated"|"false-positive"|"queued"|"deferred"}
+ */
+export function classifyFindingStatus(labels) {
+  const names = labelNames(labels);
+  if (names.includes("validated")) return "validated";
+  if (names.includes("false-positive")) return "false-positive";
+  if (names.includes("needs-validation")) return "queued";
+  return "deferred";
+}
+
+/**
+ * True if the given label set carries any workflow:*-family label (i.e. the
+ * issue is "in-flight" per deriveWorkflowLabels()'s family, not just the
+ * literal "workflow:" prefix check — needs-human counts too).
+ *
+ * @param {Array<string|{name: string}>} labels
+ * @param {string[]} workflowLabels - the label set returned by deriveWorkflowLabels()
+ * @returns {boolean}
+ */
+export function hasWorkflowLabel(labels, workflowLabels) {
+  const names = new Set(labelNames(labels));
+  return workflowLabels.some((wl) => names.has(wl));
+}
+
+/**
+ * Normalize a priority label to a short display form ("P0".."P3"), accepting
+ * both the canonical `priority:P<n>` form and the bare `P<n>` form used by
+ * some consumer repos (forge#2232 established this same dual-form handling
+ * for priority extraction elsewhere in the pipeline; forge#2235 applies it to
+ * watch's render rows).
+ *
+ * Canonical `priority:P<n>` wins if both happen to be present.
+ *
+ * @param {Array<string|{name: string}>} labels
+ * @returns {string|null} e.g. "P1", or null if no priority label found
+ */
+export function normalizePriority(labels) {
+  const names = labelNames(labels);
+  const canonical = names.find((n) => /^priority:P[0-3]$/.test(n));
+  if (canonical) return canonical.replace("priority:", "");
+  const bare = names.find((n) => /^P[0-3]$/.test(n));
+  return bare || null;
+}
+
+/**
+ * Parse `repos.satellites[].repo` entries out of a forge.yaml file's raw
+ * text, without a YAML parser dependency — consistent with the rest of
+ * forgedock.mjs's regex-based forge.yaml reads (resolveLabelsRepo,
+ * stall_timeout_minutes, etc.). Returns [] when no `satellites:` section is
+ * present, so callers degrade to exactly the previous single-repo behavior.
+ *
+ * @param {string} forgeYamlText
+ * @returns {string[]} "owner/repo" strings
+ */
+export function parseSatelliteRepos(forgeYamlText) {
+  if (typeof forgeYamlText !== "string") return [];
+  const idx = forgeYamlText.indexOf("satellites:");
+  if (idx === -1) return [];
+  const tail = forgeYamlText.slice(idx + "satellites:".length);
+  // Stop at the next non-indented (top-level) key so an unrelated later
+  // section's `repo:` field is never picked up as a satellite.
+  const stopMatch = tail.match(/\n[^\s#][^\n]*/);
+  const section = stopMatch ? tail.slice(0, stopMatch.index) : tail;
+  const repos = [];
+  // Anchor to a YAML key boundary (line start, optional indentation, optional
+  // `-` list-item marker) so a future suffixed key like `staging_repo:` can
+  // never be matched as a trailing substring of an unrelated key (forge#2457).
+  const re = /^[ \t]*(?:-[ \t]*)?repo:\s*["']?([^\s"'#]+)["']?/gm;
+  let m;
+  while ((m = re.exec(section)) !== null) {
+    repos.push(m[1]);
+  }
+  return repos;
+}
+
+/**
+ * Escape a value for safe interpolation inside a double-quoted GraphQL
+ * string literal (forge#2307). Backslash MUST be escaped first — escaping
+ * `"` before `\` would double-escape the backslashes just introduced by the
+ * quote-escaping step. A value with no special characters round-trips
+ * unchanged, so this is a no-op for the overwhelming common case (plain
+ * alphanumeric owner/repo names).
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeGraphQLString(value) {
+  return String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+/**
+ * Build a single GraphQL query batching FORGE:HEARTBEAT comment lookups for
+ * many issues into one `gh api graphql` round-trip instead of one REST call
+ * per issue (forge#2235 — de-N+1). The caller is responsible for chunking
+ * issueNumbers to stay under GraphQL query complexity limits (a chunk size
+ * of ~25 is safe).
+ *
+ * Fetches only the last 20 comments per issue (heartbeats are appended, so
+ * the latest one is always near the end) rather than the full comment
+ * history, to keep the response small.
+ *
+ * `owner`/`repo` are escaped (forge#2307) before interpolation into the
+ * double-quoted GraphQL string literal so a value containing `"` or `\`
+ * cannot break out of the literal and alter the query structure. In
+ * practice these values come from trusted local input (forge.yaml or a
+ * `--repo` CLI flag — see bin/forgedock.mjs resolveLabelsRepo/watch()), not
+ * issue/PR content, but the query builder itself should not depend on that
+ * being true forever.
+ *
+ * @param {string} owner
+ * @param {string} repo
+ * @param {number[]} issueNumbers
+ * @returns {string} GraphQL query document
+ */
+export function buildHeartbeatBatchQuery(owner, repo, issueNumbers) {
+  const aliases = issueNumbers
+    .map(
+      (n, i) =>
+        `i${i}: issue(number: ${Number(n)}) { number comments(last: 20) { nodes { body } } }`,
+    )
+    .join("\n    ");
+  return `query {
+  repository(owner: "${escapeGraphQLString(owner)}", name: "${escapeGraphQLString(repo)}") {
+    ${aliases}
+  }
+}`;
+}
+
+/**
+ * Extract the latest FORGE:HEARTBEAT comment body per issue number from a
+ * parsed `gh api graphql` response built against buildHeartbeatBatchQuery().
+ *
+ * @param {object} graphqlJson - parsed JSON response from `gh api graphql`
+ * @returns {Map<number, string|null>} issue number -> latest heartbeat body, or null if none found
+ */
+export function parseHeartbeatBatchResponse(graphqlJson) {
+  const result = new Map();
+  const repoData = graphqlJson && graphqlJson.data && graphqlJson.data.repository;
+  if (!repoData) return result;
+  for (const key of Object.keys(repoData)) {
+    const issue = repoData[key];
+    if (!issue || typeof issue.number !== "number") continue;
+    const nodes = (issue.comments && issue.comments.nodes) || [];
+    let heartbeat = null;
+    for (let i = nodes.length - 1; i >= 0; i--) {
+      if (nodes[i] && typeof nodes[i].body === "string" && nodes[i].body.includes("FORGE:HEARTBEAT")) {
+        heartbeat = nodes[i].body;
+        break;
+      }
+    }
+    result.set(issue.number, heartbeat);
+  }
+  return result;
+}
+
+/**
+ * Chunk an array into fixed-size slices (helper for GraphQL batch sizing).
+ * @param {Array<*>} arr
+ * @param {number} size
+ * @returns {Array<Array<*>>}
+ */
+export function chunkArray(arr, size) {
+  const out = [];
+  for (let i = 0; i < arr.length; i += size) {
+    out.push(arr.slice(i, i + size));
+  }
+  return out;
+}

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,14 +389,43 @@ 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 -->
+# Safety-exclusion alternation is word-boundary anchored (not bare substrings)
+# and the body scan strips the review-finding template's attribution
+# boilerplate (**Confidence**/**Severity**/**Review comment** — see forge#2477
+# note below for why **Source**/**Agent** are deliberately excluded from this
+# list) before matching — identical fix mirrored across all three sweep
+# sites so `authority_source` and a Security-agent-attributed finding no
+# longer false-positive, while a genuine auth/billing/security/anti-bot
+# finding still excludes. <!-- forge#2423 -->
+# Each stripped alternative is anchored to the field's real generator-output
+# shape (enum for Confidence/Severity, URL for Review comment) rather than a
+# bare label-prefix + `.*$` — matching on label shape alone lets
+# attacker-controlled body text on one of these lines get stripped along with
+# the label, smuggling banned keywords past the scan below. Source/Agent are
+# deliberately NOT stripped: both hold genuinely free-text generator output (a
+# PR title; an agent's self-description) with no fixed vocabulary, so no shape
+# bound can distinguish legitimate attribution from attacker-authored payload
+# placed in the same position — a length-bounded free-text alternative for
+# either field re-opens the exact smuggling gap this fix closes (an attacker
+# need only prefix their payload with a fake "PR #N — " or agent name to
+# satisfy the bound). Leaving them unstripped trades a narrow, already-known
+# false-positive (forge#2423's Agent-line case; a P3 finding whose Source/Agent
+# text happens to mention a domain keyword is not auto-batched) for closing a
+# real bypass — the safe direction for a security-relevant exclusion.
+# <!-- forge#2477 -->
 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)
-         | 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)
+  --jq '.[] | select([.labels[].name] | any(test("^(priority:)?P3$")))
+         | select(([.labels[].name] | any(. == "batch")) | not)
+         | select((.title | test("\\b(security|billing|anti-bot|auth|authentication|authorization|authn|authz)\\b"; "i")) | not)
+         | (.body | gsub("(?m)^\\*\\*(?:Confidence\\*\\*: (?:CONFIRMED|LIKELY|POSSIBLE)|Severity\\*\\*: (?:CRITICAL|HIGH|MEDIUM|LOW|INFO)|Review comment\\*\\*: https?://\\S+)$"; "")) as $stripped_body
+         | select($stripped_body | test("## Problem[\\s\\S]{0,500}\\b(security|billing|anti-bot|auth|authentication|authorization|authn|authz)\\b"; "i") | not)
          | select(([.labels[].name] | any(. == "security" or . == "billing" or . == "anti-bot" or . == "auth")) | not)')
 
 echo "Unbatched batchable P3 findings: $(echo "$UNBATCHED_P3" | jq -s 'length')"

package/commands/issue.md

@@ -31,6 +31,7 @@ You create GitHub issues with the exact structure the `/work-on` pipeline expect
 | `--body-file <path>` | Supplies the final issue body by reading it from a file (programmatic mode only). Mutually exclusive with `--body`. |
 | `--label "..."` | Adds one label. Repeatable (`--label bug --label P2`) — labels accumulate. Programmatic mode only. |
 | `--milestone "..."` | Supplies the milestone title directly, skipping the Phase 2E milestone lookup. Programmatic mode only, optional. |
+| `--exclude "N,N,..."` | Comma-separated issue numbers to exclude from the Phase 2D dedup candidate set. Programmatic mode only, optional. Forwarded verbatim to `scripts/issue-dedup.sh --exclude`. NOT a `--force` equivalent — narrows the candidate set, does not disable the gate. See Phase 2D. <!-- Added: forge#2432 --> |
 
 ```bash
 DRY_RUN=false
@@ -39,6 +40,7 @@ PROGRAMMATIC_BODY=""
 PROGRAMMATIC_BODY_FILE=""
 PROGRAMMATIC_LABELS=()
 PROGRAMMATIC_MILESTONE=""
+PROGRAMMATIC_EXCLUDE=""
 
 # Positional/flag parsing. $ARGUMENTS is a single opaque string (the invoking
 # agent's raw args, e.g. from `Skill(skill="issue", args="--title \"fix: ...\" ...")`)
@@ -107,7 +109,7 @@ rm -f "$ARGS_TMP"
 LOOKS_LIKE_FLAG_MODE=false
 for arg in "${ARGS[@]}"; do
   case "$arg" in
-    --dry-run|--title|--body|--body-file|--label|--milestone)
+    --dry-run|--title|--body|--body-file|--label|--milestone|--exclude)
       LOOKS_LIKE_FLAG_MODE=true
       break
       ;;
@@ -119,7 +121,7 @@ while [ "$LOOKS_LIKE_FLAG_MODE" = "true" ] && [ $i -lt ${#ARGS[@]} ]; do
   arg="${ARGS[$i]}"
   case "$arg" in
     --dry-run) DRY_RUN=true ;;
-    --title|--body|--body-file|--label|--milestone)
+    --title|--body|--body-file|--label|--milestone|--exclude)
       # Each of these flags requires a value token immediately after it. A flag
       # with no following token (e.g. --title as the last argument) is a usage
       # error, not an empty value — fail loudly instead of silently proceeding
@@ -136,6 +138,7 @@ while [ "$LOOKS_LIKE_FLAG_MODE" = "true" ] && [ $i -lt ${#ARGS[@]} ]; do
         --body-file) PROGRAMMATIC_BODY_FILE="${ARGS[$i]}" ;;
         --label) PROGRAMMATIC_LABELS+=("${ARGS[$i]}") ;;
         --milestone) PROGRAMMATIC_MILESTONE="${ARGS[$i]}" ;;
+        --exclude) PROGRAMMATIC_EXCLUDE="${ARGS[$i]}" ;;
       esac
       ;;
     --*)
@@ -177,7 +180,7 @@ fi
 For callers that have already composed a title, body, labels, and (optionally) a milestone — audit tools, `/work-on` decomposition, pipeline-health proposals, review-finding creation, and similar automation — pass `--title` to activate programmatic mode. This bypasses Phase 1 (free-text parsing) and Phase 3 (LLM drafting) entirely; Phase 2D (dedup) and body validation still run.
 
 **Required**: `--title "TEXT"` and exactly one of `--body "TEXT"` / `--body-file <path>`.
-**Optional**: `--label "NAME"` (repeatable, zero or more), `--milestone "TITLE"`, `--dry-run`.
+**Optional**: `--label "NAME"` (repeatable, zero or more), `--milestone "TITLE"`, `--dry-run`, `--exclude "N,N,..."` (see Phase 2D — narrows the dedup candidate set, not a `--force` equivalent).
 
 If `--title` is present but neither `--body` nor `--body-file` is supplied, or both are supplied, this is a usage error: print `ERROR: programmatic mode requires exactly one of --body or --body-file` and STOP — do not fall through to Phase 2D or Phase 4B.
 
@@ -340,7 +343,12 @@ Run the deterministic dedup script first (authoritative check), then fall back t
 
 ```bash
 # Authoritative deterministic check — uses token overlap algorithm (see scripts/issue-dedup.sh)
-DEDUP_RESULT=$(scripts/issue-dedup.sh "{PROPOSED_TITLE}" {GH_FLAG} 2>&1)
+# In programmatic mode, forward $PROGRAMMATIC_EXCLUDE (if set) as --exclude — see the
+# "Exclusion mechanism" note below. In interactive mode $PROGRAMMATIC_EXCLUDE is always
+# empty, so this is a no-op for that path.
+DEDUP_EXCLUDE_ARGS=()
+[ -n "$PROGRAMMATIC_EXCLUDE" ] && DEDUP_EXCLUDE_ARGS=(--exclude "$PROGRAMMATIC_EXCLUDE")
+DEDUP_RESULT=$(scripts/issue-dedup.sh "{PROPOSED_TITLE}" {GH_FLAG} "${DEDUP_EXCLUDE_ARGS[@]}" 2>&1)
 DEDUP_EXIT=$?
 
 if [ "$DEDUP_EXIT" -eq 1 ]; then
@@ -369,6 +377,8 @@ If a duplicate exists:
 - **Closed duplicate found (regression)**: Create the issue but reference the prior issue in the body: "Regression of #{N}."
 - **User wants to override**: Pass `--force` to the dedup script — this is an explicit human override path. Agents MUST NOT pass `--force` without user authorization. <!-- Added: forge#1335 -->
 
+**Exclusion mechanism (`--exclude`, programmatic mode only)**: A caller that already knows a set of open issue numbers this new issue is a deliberate supersede of — not an accidental duplicate — can pass `--exclude "N,N,..."` to `/issue` (forwarded to `scripts/issue-dedup.sh --exclude`). The canonical example is `phase-1-resolve.md`'s P3 review-finding batching: a batch issue restates its own member findings' subject matter by construction, so without exclusion it always collides with them under the token-overlap algorithm. `--exclude` removes those specific issue numbers from Phase 2D's candidate set BEFORE matching runs — it is **NOT a `--force` equivalent**: it narrows the candidate set, it does not disable the check, and it requires no human authorization (unlike `--force`, which agents MUST NOT pass without one). Any OTHER open issue — one not in the exclusion list — is still matched normally, so a title that happens to duplicate an unrelated existing issue still trips the STOP. <!-- Added: forge#2432 -->
+
 ### 2E: Check for milestone context
 
 ```bash

package/commands/orchestrate/config.md

@@ -54,9 +54,51 @@ 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" for generation *depth*, while `--max-generation`/`--policy` express finer-grained depth policy (e.g. "admit gen-2, stop at gen-3").
+
+**Time scope is a separate axis from depth** (forge#2628): by default, `cascade`/`review-findings`/`findings` only resolves `review-finding` issues created at/after this batch's start (T0) — see `phase-1-resolve.md` "Cascade / Review-Finding Resolution" for the run-spawned-vs-backlog distinction. None of the depth flags/config above widen that time window. `--include-backlog` is the only flag that does — it opts into the whole open-backlog sweep regardless of when issues were created, and must be requested explicitly; it is never implied by adding `cascade` to an already-scoped batch.
 
 ---