/phase-1-resolve

user-invocable: false

install: core

<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios --> <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

/orchestrate — Phase 1: Resolve the Issue Set

> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.

Phase 1: Resolve the Issue Set

Batch-Start Timestamp (T0) — capture FIRST, before any resolution

<!-- Added: forge#2628 -->

Before parsing `$ARGUMENTS` or resolving anything, capture the batch's start timestamp once:

BATCH_T0=$(date -u +%Y-%m-%dT%H:%M:%SZ)
echo "Batch start T0: ${BATCH_T0}"

`BATCH_T0` is the anchor for the run-spawned-vs-backlog cascade distinction used throughout this file's "Cascade / Review-Finding Resolution" section below and by `phase-4-execution.md` Step 4C. Persist it alongside `ORIGINATING_QUERY_KIND`/`ORIGINATING_QUERY_PATTERN`/`ORIGINATING_QUERY_ARGS` (see "Predicate Persistence" below) in the batch's in-memory/report state so Phase 4 reads the same value this step captured — it must never independently re-derive its own T0 from "now" at whatever later moment Step 4A.pre happens to run, which would silently widen the window past what this run actually spawned. If a session resumes mid-run without `BATCH_T0` in context (e.g. after compaction), Phase 4's Step 4A.pre falls back to capturing its own timestamp — see that section's note — but this is a degraded fallback, not the normal path.

Parse `$ARGUMENTS` to determine which issues to work on:

Input Patterns

| Input | Resolution | |-------|------------| | `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 (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 (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 | | `cascade`, `review-findings`, or `findings` (optionally `--include-deferred` / `--allow-gen2` / `--include-backlog`) | `review-finding` issues created at/after this batch's T0 (default repo, or repo-scoped e.g. `mcp:cascade`) — i.e. empty unless combined with a run that has already spawned findings, or `--include-backlog` is passed. See "Cascade / Review-Finding Resolution" below for the run-spawned-vs-backlog distinction and the generation-depth admission on top of it (`orchestration.cascade.max_generation`, default 1). <!-- Added: forge#2231, forge#2234, forge#2628 -->| | `<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, T0-scoping added: forge#2628 -->

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.

**Two modes — run-spawned cascade (default) vs. whole-backlog sweep (explicit opt-in only):**

There are two different things an operator can mean by "cascade," and this resolve step must not silently conflate them:

• **(a) Run-spawned cascade (default)** — recursively work the `review-finding` issues *this batch*

produces. Bounded to findings created at/after `BATCH_T0` (captured at the very top of this file, before any resolution runs). This is the safe default: combined with an ordinary scoped batch (e.g. `<no:milestone set>` + `cascade`), it expresses "follow through on what this run's own `/review-pr` agents find" — not "also adopt every other open finding already sitting in the repo." Because `BATCH_T0` is captured at batch start, a bare `cascade` invocation with nothing yet spawned legitimately resolves to an **empty set** at Phase 1 — new findings admitted by this mode are picked up as they're created via `phase-4-execution.md` Step 4C's mid-run sweep (which uses the same `BATCH_T0` anchor), not via this one-shot Phase 1 fetch.

• **(b) Whole-backlog sweep (explicit opt-in only)** — work every open `review-finding` in the repo,

regardless of when it was created. This is what the pre-#2628 default silently did on every `cascade`/`review-findings`/`findings` invocation. It is still available, but now requires the explicit `--include-backlog` flag (e.g. `cascade --include-backlog`, `review-findings --include-backlog`) — adding `cascade` to an already-scoped batch never implies it.

# BATCH_T0 was captured at the top of this file (Phase 1, "Batch-Start Timestamp (T0)"),
# before any resolution ran — reuse it here, do not recapture.

# --include-backlog opts into mode (b): the full open review-finding backlog, no created-date
# filter. Without it (the default, mode (a)), only findings created at/after BATCH_T0 are fetched
# — i.e. issues this batch itself could plausibly have spawned so far.
if echo "{ARGUMENTS}" | grep -qE -- '--include-backlog'; then
  CASCADE_MODE="backlog-sweep"
  CASCADE_SEARCH="label:review-finding"
else
  CASCADE_MODE="run-spawned"
  CASCADE_SEARCH="label:review-finding created:>=${BATCH_T0}"
fi
echo "Cascade mode: ${CASCADE_MODE