forgedock 1.0.19 → 1.0.21

package/commands/orchestrate.md

@@ -13,9 +13,9 @@ argument-hint: [milestone <slug> | #1 #2 #3 | next <N> | fast-lane | priority:P0
 
 1. **Every agent MUST invoke `/work-on` via the Skill tool.** You do NOT write implementation prompts. You copy the Phase 4A template verbatim and fill in the `{VARIABLES}`. Nothing else. No custom prompts. No "just read and edit" shortcuts. The Skill tool invocation is what triggers labels, investigation comments, structured review, and trajectory tracking. Without it, the agent's work has no paper trail and is worthless.
 
-2. **You are a dispatcher, not a builder.** You resolve issues, plan waves, spawn agents, and report results. You NEVER read code, edit files, or implement fixes yourself.
+2. **You are a dispatcher, not a builder.** You resolve issues, build the dependency DAG, spawn agents, and report results. You NEVER read code, edit files, or implement fixes yourself.
 
-3. **After each wave, verify agents used `/work-on`.** Check that completed issues have `workflow:*` labels and structured comments. If an agent bypassed the pipeline, report it as a failure.
+3. **After each agent completes, verify it used `/work-on`.** Check that completed issues have `workflow:*` labels and structured comments. If an agent bypassed the pipeline, report it as a failure.
 
 ---
 
@@ -131,7 +131,7 @@ If a `workflow:decomposed` issue is found, automatically expand it to its open s
 **What the orchestrator SHOULD do:**
 - If two issues look related, add a note in the agent prompt: "Note: #{OTHER} has similar symptoms — investigate whether this is the same root cause or a different code path"
 - Let both agents run independently — if one finds it's truly a duplicate, `/work-on`'s investigation phase will close it as invalid with evidence
-- Flag potential overlap in the wave plan for the user's awareness, but NEVER act on it
+- Flag potential overlap in the DAG plan for the user's awareness, but NEVER act on it
 
 **Why**: Surface-level similarity hides critical differences. #3842 (api_key.id lazy load) and #4039 (user.id lazy load) had identical error messages but targeted completely different ORM objects. Closing #4039 as a "duplicate" would have left a customer-impacting P0 bug unfixed.
 
@@ -274,7 +274,7 @@ done
 
 ### Step 3B: Domain estimation
 
-For each issue, estimate which domains it touches based on title, body, and labels. This improves wave planning — issues in the same domain likely touch the same files and should be sequential.
+For each issue, estimate which domains it touches based on title, body, and labels. This improves DAG construction — issues in the same domain likely touch the same files and should be serialized (one becomes a predecessor of the other).
 
 ```bash
 for NUM in {issue_numbers}; do
@@ -291,11 +291,11 @@ for NUM in {issue_numbers}; do
 done
 ```
 
-**Use domain info for wave planning:**
-- Issues in the SAME domain (especially WORKER, BILLING, DATABASE) are more likely to touch the same files → prefer sequential within a wave or adjacent waves
+**Use domain info for DAG edge construction:**
+- Issues in the SAME domain (especially WORKER, BILLING, DATABASE) are more likely to touch the same files → add predecessor edges to serialize them
 - Issues in DIFFERENT domains are more likely independent → safe to parallelize
 - BILLING + AUTH issues should be prioritized early (security-critical)
-- **DATABASE issues are ALWAYS serialized — hard rule, no exceptions.** Multiple agents writing migrations simultaneously will produce duplicate migration numbers (e.g., two `0067_*.sql` files), which breaks the migration runner. Every DATABASE issue must be in its own wave. If 3 DATABASE issues are in a batch: Wave 1 runs issue A, Wave 2 runs issue B, Wave 3 runs issue C.
+- **DATABASE issues are ALWAYS serialized — hard rule, no exceptions.** Multiple agents writing migrations simultaneously will produce duplicate migration numbers (e.g., two `0067_*.sql` files), which breaks the migration runner. DATABASE issues form a linear predecessor chain in the DAG. If 3 DATABASE issues are in a batch: A has no predecessors, B has {A} as predecessor, C has {B} as predecessor.
 
 **Store domain tags per issue** for use in the plan presentation (Step 3E).
 
@@ -323,9 +323,9 @@ gh issue view $NUM --json body --jq '.body' | grep -oP '`[^`]*\.(py|tsx?|jsx?|sq
 ```
 
 **Cross-reference all extracted file lists:**
-- If two issues share ANY affected file → they MUST be in separate waves (sequential)
+- If two issues share ANY affected file → one MUST be a predecessor of the other (serialized)
 - The issue with lower issue number goes first (stable ordering), unless an explicit `Depends on #` says otherwise
-- Add a conflict note to the wave plan: "#{A} and #{B} both modify `{file}` — serialized"
+- Add a conflict note to the DAG plan: "#{A} and #{B} both modify `{file}` — #{A} is predecessor of #{B}"
 
 #### Layer 2: Directory-proximity detection
 
@@ -395,10 +395,10 @@ When file extraction yields **fewer than 2 file paths** for an issue (common for
 
 **Rules:**
 - If an issue has 0-1 extracted file paths AND shares a domain tag (from Step 3B) with another issue → serialize them
-- If an issue has 0 extracted file paths AND no domain tag could be determined → serialize it with the immediately preceding wave (safest default)
+- If an issue has 0 extracted file paths AND no domain tag could be determined → add it as a predecessor of the next same-domain issue, or if no domain match exists, serialize it after the most recently added issue (safest default)
 - Add a note to the plan: "#{N} — low file-extraction confidence, serialized conservatively"
 
-**Rationale**: The cost of a false-negative (two agents conflict → one fails with merge error, wasting the full agent run) far exceeds the cost of a false-positive (an issue waits one extra wave before starting). Always err toward serialization when uncertain.
+**Rationale**: The cost of a false-negative (two agents conflict → one fails with merge error, wasting the full agent run) far exceeds the cost of a false-positive (an issue waits for one predecessor before starting). Always err toward serialization when uncertain.
 
 #### Combining all layers
 
@@ -413,29 +413,148 @@ Build the final conflict graph by merging signals from all four layers:
 | Layer 3: High-fan-in file touched | **Probable conflict** | Serialize with same-service issues |
 | Layer 3: Shared model/init pattern | **Probable conflict** | Serialize |
 | Layer 4: Low confidence + same domain | **Conservative** | Serialize |
-| Layer 4: Low confidence + no domain | **Conservative** | Serialize with prior wave |
+| Layer 4: Low confidence + no domain | **Conservative** | Add predecessor edge to most recent issue |
 
 **This supplements, not replaces, the domain keyword estimation.** Domain tags still help with broad sequencing decisions. Multi-layer conflict detection catches the specific cases keywords miss (e.g., two issues that both modify files in `services/api/app/models/` where one is labeled WORKER and the other BILLING — Layer 2 catches this even though Layer 1 shows no direct file overlap).
 
-### Step 3D: Build the execution plan
+### Step 3D: Build the dependency DAG
 
-Organize issues into **waves** (groups that can run in parallel):
+Build a **directed acyclic graph (DAG)** of per-issue dependencies. Each issue gets a `predecessors` set — the specific issues that must reach a terminal state before this issue can dispatch. This replaces the previous wave-grouping model where all issues in a wave had to complete before any issue in the next wave could start.
 
-**Wave rules:**
-- Investigation issues already ran in Wave 0 (Phase 2) — they are NOT included in these waves
-- Issues with NO dependencies and NO file overlap → same wave (parallel)
-- Issues that depend on other issues in the set → later wave (after dependency completes)
-- **No artificial agent limit per wave** — spawn as many parallel agents as there are independent issues. The only constraint is file overlap and explicit dependencies.
-- Issues that touch the **same files** must be in separate waves (sequential) to avoid merge conflicts
-- If unsure about conflicts, err on the side of parallel — each agent works in its own worktree
+**DAG construction rules:**
+- Investigation issues already ran in Phase 2 — they are NOT included in this DAG
+- Each issue starts with an empty predecessor set
+- **Explicit dependencies**: If issue B says "Depends on #A" or "Blocked by #A", add A to B's predecessors
+- **File-conflict edges**: If two issues share affected files (from Step 3C Layer 1), add a directed edge: lower issue number → higher issue number (unless explicit deps say otherwise). The later issue has the earlier issue in its predecessors.
+- **Domain serialization edges**: DATABASE issues form a linear chain (each has the previous DATABASE issue as its predecessor). Same-small-directory issues (Layer 2) and high-fan-in file issues (Layer 3) get directed edges as per Step 3C rules.
+- **Conservative fallback edges**: Low-confidence issues (Layer 4) get edges to same-domain issues as per Step 3C rules.
+- **No artificial concurrency limit** — all issues with empty predecessor sets dispatch simultaneously. The only constraints are file overlap and explicit dependencies.
 
-**Example plan:**
+**Terminology:**
+- **Ready issues**: Issues whose predecessor set is empty (all predecessors have reached terminal state or were never added)
+- **Blocked issues**: Issues with one or more unresolved predecessors
+- **Critical path**: The longest chain of dependent issues in the DAG — determines minimum wall-clock time
+
+**Example DAG:**
 ```
-Wave 0 (already done): #2644 (investigation) → spawned #2645, #2646, #2647
-Wave 1 (parallel): #2633 (orphaned queues), #2636 (invalidation sub), #2645 (new finding), #2646 (new finding)
-Wave 2 (after deps): #2634 (enable daemon — after #2633 fixes memory leak), #2647 (depends on #2645)
+Phase 2 (already done): #2644 (investigation) → spawned #2645, #2646, #2647
+
+Dependency graph:
+  #2633 (orphaned queues)     → predecessors: {}          ← READY
+  #2636 (invalidation sub)    → predecessors: {}          ← READY
+  #2645 (new finding)         → predecessors: {}          ← READY
+  #2646 (new finding)         → predecessors: {}          ← READY
+  #2634 (enable daemon)       → predecessors: {#2633}     ← blocked until #2633 completes
+  #2647 (depends on #2645)    → predecessors: {#2645}     ← blocked until #2645 completes
+
+Critical path: #2633 → #2634 (2 steps) or #2645 → #2647 (2 steps)
+Initial dispatch: #2633, #2636, #2645, #2646 (all ready — launched simultaneously)
 ```
 
+**Key advantage over waves**: When #2633 completes, #2634 dispatches immediately — it does not wait for #2636, #2645, or #2646 to finish. Similarly, when #2645 completes, #2647 dispatches immediately regardless of other issues' status.
+
+### Step 3D.5: Cycle Detection (MANDATORY) <!-- Added: forge#1085 -->
+
+**Run immediately after Step 3D's DAG edge construction, before presenting the plan (Step 3E).** This step validates that the predecessor graph is acyclic. Without it, mutual `Depends on` declarations (e.g., A depends on B AND B depends on A) cause both issues to remain permanently blocked in Step 4B's dispatch loop — no error, no timeout, indefinite deadlock.
+
+**Algorithm**: Kahn's topological sort. Runs in O(V+E) — negligible overhead for typical batch sizes.
+
+```bash
+# --- Step 3D.5: Cycle Detection ---
+# Inputs:
+#   ISSUES[]         — array of all issue numbers in the DAG
+#   PREDECESSORS[N]  — space-separated list of predecessor issue numbers for issue N
+
+# Step 1: Compute in-degree for each issue
+declare -A IN_DEGREE
+for NUM in "${ISSUES[@]}"; do
+  IN_DEGREE[$NUM]=0
+done
+for NUM in "${ISSUES[@]}"; do
+  for PRED in ${PREDECESSORS[$NUM]:-}; do
+    IN_DEGREE[$NUM]=$(( ${IN_DEGREE[$NUM]:-0} + 1 ))
+  done
+done
+
+# Step 2: Seed the queue with zero-in-degree issues (no predecessors)
+KAHN_QUEUE=()
+for NUM in "${ISSUES[@]}"; do
+  [ "${IN_DEGREE[$NUM]}" -eq 0 ] && KAHN_QUEUE+=("$NUM")
+done
+
+# Step 3: Process queue — reduce successor in-degrees, enqueue newly freed issues
+PROCESSED_COUNT=0
+PROCESSED_ORDER=()
+while [ "${#KAHN_QUEUE[@]}" -gt 0 ]; do
+  # Dequeue
+  CURRENT="${KAHN_QUEUE[0]}"
+  KAHN_QUEUE=("${KAHN_QUEUE[@]:1}")
+  PROCESSED_ORDER+=("$CURRENT")
+  PROCESSED_COUNT=$(( PROCESSED_COUNT + 1 ))
+
+  # Reduce in-degree of all issues that depend on CURRENT (i.e., CURRENT is in their PREDECESSORS)
+  for SUCCESSOR in "${ISSUES[@]}"; do
+    for PRED in ${PREDECESSORS[$SUCCESSOR]:-}; do
+      if [ "$PRED" = "$CURRENT" ]; then
+        IN_DEGREE[$SUCCESSOR]=$(( ${IN_DEGREE[$SUCCESSOR]} - 1 ))
+        [ "${IN_DEGREE[$SUCCESSOR]}" -eq 0 ] && KAHN_QUEUE+=("$SUCCESSOR")
+      fi
+    done
+  done
+done
+
+# Step 4: Any issue not processed has in-degree > 0 — part of a cycle
+CYCLE_ISSUES=()
+EXCLUDED_CYCLE=()
+for NUM in "${ISSUES[@]}"; do
+  FOUND=false
+  for P in "${PROCESSED_ORDER[@]}"; do [ "$P" = "$NUM" ] && FOUND=true && break; done
+  [ "$FOUND" = "false" ] && CYCLE_ISSUES+=("$NUM")
+done
+
+# Step 5: Handle cycles
+if [ "${#CYCLE_ISSUES[@]}" -gt 0 ]; then
+  echo "CYCLE DETECTED in dependency graph — the following issues form a circular dependency:"
+  for C in "${CYCLE_ISSUES[@]}"; do
+    echo "  #${C}: predecessors=[${PREDECESSORS[$C]}]"
+    # Label each cyclic issue needs-human
+    gh issue edit "$C" -R {GH_REPO} --add-label "needs-human" 2>/dev/null || true
+    gh issue comment "$C" -R {GH_REPO} --body "**Cycle detected by /orchestrate**: This issue is part of a circular dependency chain involving issues: ${CYCLE_ISSUES[*]/#/#}. The orchestrator cannot dispatch it automatically. Please fix the \`Depends on\` declarations so that no cycle exists, then re-run /orchestrate." 2>/dev/null || true
+    # Remove from DAG — store in EXCLUDED_CYCLE for Step 3E reporting
+    EXCLUDED_CYCLE+=("$C")
+    # Remove from ISSUES array for all downstream processing
+    # Use exact-match filter loop — pattern substitution (${array[@]/pattern}) leaves blank
+    # slots and corrupts partial matches (e.g., removing 100 changes 1000 to 0).
+    NEW_ISSUES=()
+    for I in "${ISSUES[@]}"; do
+      [ "$I" != "$C" ] && NEW_ISSUES+=("$I")
+    done
+    ISSUES=("${NEW_ISSUES[@]}")
+  done
+  echo ""
+  echo "These issues have been labeled needs-human and excluded from the DAG."
+  echo "Fix their dependency declarations and re-run /orchestrate."
+else
+  echo "DAG cycle check: PASS — no cycles detected. Proceeding with ${#PROCESSED_ORDER[@]} issues."
+fi
+
+# Guard: if all issues were cyclic, ISSUES[] is now empty — abort before presenting an empty plan
+if [ "${#ISSUES[@]}" -eq 0 ]; then
+  echo ""
+  echo "ERROR: All issues in this batch form circular dependencies and have been excluded."
+  echo "Every issue has been labeled needs-human."
+  echo "Fix the Depends on / Blocked by declarations so no cycle exists, then re-run /orchestrate."
+  exit 1
+fi
+# --- End Step 3D.5 ---
+```
+
+**After this step**:
+- `ISSUES[]` contains only acyclic issues — safe to dispatch
+- `EXCLUDED_CYCLE[]` contains cyclic issue numbers — reported in Step 3E, never dispatched
+- If `EXCLUDED_CYCLE` is non-empty, report it clearly in the Step 3E plan before asking for user confirmation
+- If `ISSUES[]` is empty after cycle exclusion (all issues were cyclic), the guard above aborts with `exit 1` — Step 3E is never reached with an empty plan <!-- Added: forge#1110 -->
+
 ### Step 3E: Present the plan to the user
 
 ```
@@ -443,103 +562,117 @@ Wave 2 (after deps): #2634 (enable daemon — after #2633 fixes memory leak), #2
 
 **Scope**: {milestone name / "N issues" / "fast-lane"}
 **Total issues**: {count} ({investigation_count} investigations + {implementation_count} implementations)
-**Estimated waves**: {wave_count} (Wave 0 = investigations, then implementation waves)
+**Execution model**: Dependency-graph streaming (issues dispatch as predecessors complete)
 
 {IF investigations exist:}
-### Wave 0 — Investigations (run first, may spawn new issues)
+### Investigations (run first, may spawn new issues)
 | # | Title | Expected Output |
 |---|-------|----------------|
-| #{INV1} | {title} | New issues → folded into subsequent waves |
+| #{INV1} | {title} | New issues → folded into dependency graph |
 
-### Implementation Waves (after investigations complete)
+### Implementation (after investigations complete)
 {END IF}
 
 ### Domain Distribution
 | Domain | Issues | Notes |
 |--------|--------|-------|
 | FRONTEND | {N} | {Independent pages / Shared components} |
-| BILLING | {N} | {Critical — prioritize in Wave 1} |
-| DATABASE | {N} | {Sequential — migration order matters} |
-| AUTH | {N} | {Critical — Wave 1} |
+| BILLING | {N} | {Critical — dispatches immediately} |
+| DATABASE | {N} | {Serialized chain — migration order matters} |
+| AUTH | {N} | {Critical — dispatches immediately} |
 | WORKER | {N} | {High overlap risk within worker service} |
 | AI | {N} | {Independent} |
 | INFRA | {N} | {Independent} |
 
 (Omit rows with 0 issues. Add project-specific domain rows from forge.yaml → review.domains.)
 
-### Implementation Waves
+### Dependency Graph
 
-| Wave | Issues | Strategy |
-|------|--------|----------|
-| 1 | #{A}, #{B}, #{C} | Parallel (no deps, different domains) |
-| 2 | #{D} (after #{A}), #{E} | Parallel (D waits for A) |
-| 3 | #{F} (after #{D}) | Sequential |
+| Issue | Predecessors | Domain | Status |
+|-------|-------------|--------|--------|
+| #{A} | — | FRONTEND | Ready (dispatches immediately) |
+| #{B} | — | BILLING | Ready (dispatches immediately) |
+| #{C} | — | WORKER | Ready (dispatches immediately) |
+| #{D} | #{A} | FRONTEND | Blocked (waits for #{A} only) |
+| #{E} | — | DATABASE | Ready (dispatches immediately) |
+| #{F} | #{E} | DATABASE | Blocked (serialized — waits for #{E}) |
 
-**Note**: Wave 0 investigations may create additional issues that will be automatically added to the implementation waves. The final wave plan will be confirmed after investigations complete.
+**Critical path**: #{E} → #{F} (2 steps, determines minimum wall-clock time)
+**Initial dispatch**: #{A}, #{B}, #{C}, #{E} (all predecessors resolved)
+**Streaming**: #{D} dispatches as soon as #{A} completes — does NOT wait for #{B}, #{C}, or #{E}
+
+**Note**: Investigations may create additional issues that will be automatically added to the dependency graph. The final graph will be confirmed after investigations complete.
 
 **Excluded** (already in progress / ineligible):
 - #{X} — {reason}
 
+{IF EXCLUDED_CYCLE is non-empty:}
+### ⚠ Circular Dependencies Detected — Manual Fix Required
+
+The following issues form a circular dependency chain and **cannot be dispatched** until the cycle is resolved:
+
+| Issue | Depends On | Problem |
+|-------|------------|---------|
+{rows: each EXCLUDED_CYCLE issue, its predecessor list, "mutual dependency — forms cycle with #{other}"}
+
+**Action required**: Edit each issue's body to remove or correct the `Depends on` / `Blocked by` declarations so no cycle exists. Each issue has been labeled `needs-human`. After fixing, re-run `/orchestrate` to dispatch them.
+{END IF}
+
 Proceed? (yes / adjust / pick specific issues)
 ```
 
 **Wait for user confirmation before spawning agents.** This is the checkpoint — once agents launch, they run autonomously.
 
-**After confirmation**: If Wave 0 exists, execute Phase 2B-E first. Then re-present the expanded plan (with newly spawned issues slotted into waves) for a quick confirmation before launching implementation waves.
+**After confirmation**: If investigations exist, execute Phase 2B-E first. Then re-present the expanded plan (with newly spawned issues added to the dependency graph) for a quick confirmation before launching implementation.
 
 ---
 
-## Phase 4: Execute Waves
+## Phase 4: Streaming DAG Execution
 
-### Step 4A-pre: Capture staging baseline (MANDATORY before each wave)
+### Step 4A-pre: Staging baseline tracking (MANDATORY — continuous)
 
-**WHY THIS EXISTS**: Milestone-code-onto-staging contamination incidents (see issue #150) produce unexpected growth on the staging branch that is otherwise invisible until after a deploy. Capturing a line-count baseline before each wave and re-checking after allows early detection of any contamination by agents in that wave.
+**WHY THIS EXISTS**: Milestone-code-onto-staging contamination incidents (see issue #150) produce unexpected growth on the staging branch that is otherwise invisible until after a deploy. In the streaming DAG model, there are no discrete wave boundaries — instead, track a running baseline and check after each agent completion.
 
-**When to run**: Before launching EVERY wave in batches that target `staging` (fast-lane or milestone→staging). Skip only for pure milestone-branch batches where `{PR_BASE}` is `milestone/*` and staging is not involved.
+**When to run**: Capture the initial baseline before the first dispatch. Then re-check after every agent that merges a PR targeting `staging`. Skip for pure milestone-branch batches where all issues target `milestone/*`.
 
 ```bash
-# Capture staging baseline before launching the wave
+# Capture initial staging baseline before first dispatch
 git fetch origin
 if [ "$DEFAULT_BRANCH" = "$STAGING_BRANCH" ]; then
-  # Single-branch repo — staging and default are the same; diff is always zero
-  STAGING_LINES_BEFORE=0
-  echo "Staging baseline before Wave {N}: skipped — single-branch repo (staging == default)"
+  STAGING_LINES_BASELINE=0
+  echo "Staging baseline: skipped — single-branch repo (staging == default)"
 else
-  STAGING_LINES_BEFORE=$(git diff --stat origin/$DEFAULT_BRANCH...origin/$STAGING_BRANCH 2>/dev/null \
+  STAGING_LINES_BASELINE=$(git diff --stat origin/$DEFAULT_BRANCH...origin/$STAGING_BRANCH 2>/dev/null \
     | tail -1 \
     | grep -oP '\d+ insertion' \
     | grep -oP '\d+' \
     || echo "0")
-  echo "Staging baseline before Wave {N}: ${STAGING_LINES_BEFORE} lines ahead of $DEFAULT_BRANCH"
+  echo "Staging baseline: ${STAGING_LINES_BASELINE} lines ahead of $DEFAULT_BRANCH"
 fi
+
+# Track cumulative expected growth from merged PRs
+CUMULATIVE_EXPECTED_DELTA=0
 ```
 
-Store `STAGING_LINES_BEFORE` per wave. After the wave completes (after Step 4C), run the integrity check:
+**Per-agent-completion integrity check** (run in Step 4B after each agent merges a PR targeting staging):
 
 ```bash
-# Check staging integrity after wave completes (run after Step 4C)
+# After agent completes and its PR merges to staging:
 git fetch origin
-if [ "$DEFAULT_BRANCH" = "$STAGING_BRANCH" ]; then
-  STAGING_LINES_AFTER=0
-  STAGING_GROWTH=0
-  echo "Staging integrity check: skipped — single-branch repo (staging == default)"
-else
-  STAGING_LINES_AFTER=$(git diff --stat origin/$DEFAULT_BRANCH...origin/$STAGING_BRANCH 2>/dev/null \
+if [ "$DEFAULT_BRANCH" != "$STAGING_BRANCH" ]; then
+  STAGING_LINES_NOW=$(git diff --stat origin/$DEFAULT_BRANCH...origin/$STAGING_BRANCH 2>/dev/null \
     | tail -1 \
     | grep -oP '\d+ insertion' \
     | grep -oP '\d+' \
     || echo "0")
-  STAGING_GROWTH=$((STAGING_LINES_AFTER - STAGING_LINES_BEFORE))
-  echo "Staging after Wave {N}: ${STAGING_LINES_AFTER} lines (+${STAGING_GROWTH} vs baseline)"
-
-  # Alert if growth exceeds expected delta
-  # Expected: only the lines from PRs merged in this wave
-  # Alert threshold: growth > 500 lines more than the sum of changed lines from wave PRs
-  # (Use 0 as threshold if no PRs merged — any growth is unexpected)
-  EXPECTED_DELTA={SUM_OF_PR_LINE_COUNTS_THIS_WAVE}  # set from PR diffs collected in 4B
-  UNEXPECTED_GROWTH=$((STAGING_GROWTH - EXPECTED_DELTA))
+  STAGING_TOTAL_GROWTH=$((STAGING_LINES_NOW - STAGING_LINES_BASELINE))
+
+  # Add this PR's line count to cumulative expected delta
+  CUMULATIVE_EXPECTED_DELTA=$((CUMULATIVE_EXPECTED_DELTA + {THIS_PR_LINE_COUNT}))
+
+  UNEXPECTED_GROWTH=$((STAGING_TOTAL_GROWTH - CUMULATIVE_EXPECTED_DELTA))
   if [ "$UNEXPECTED_GROWTH" -gt 500 ]; then
-    echo "ALERT: Staging grew by ${STAGING_GROWTH} lines (+${UNEXPECTED_GROWTH} beyond expected ${EXPECTED_DELTA})."
+    echo "ALERT: Staging grew by ${STAGING_TOTAL_GROWTH} lines (+${UNEXPECTED_GROWTH} beyond expected ${CUMULATIVE_EXPECTED_DELTA})."
     echo "This may indicate milestone-code contamination via agent merge commits."
     echo "Review: git log --oneline --merges origin/$DEFAULT_BRANCH..origin/$STAGING_BRANCH"
     echo "Do NOT merge $STAGING_BRANCH → $DEFAULT_BRANCH until the unexpected growth is investigated."
@@ -548,29 +681,29 @@ else
 fi
 ```
 
-If `UNEXPECTED_GROWTH > 500`, report the alert clearly before launching the next wave. The user confirms whether to continue.
+If `UNEXPECTED_GROWTH > 500`, report the alert clearly before dispatching any more agents. The user confirms whether to continue.
 
 ---
 
-### Step 4A.pre.0: Pre-create milestone branches for the wave (MANDATORY before classify-lane) <!-- Added: forge#901 -->
+### Step 4A.pre.0: Pre-create milestone branches for ready issues (MANDATORY before classify-lane) <!-- Added: forge#901 -->
 
-**WHY THIS EXISTS**: Feature-lane milestone branches were created lazily — by whichever feature-lane agent reached its build phase first. When a wave launches N feature-lane agents in parallel, they each run the lane check at roughly the same time. Every agent that runs before the branch is first pushed observes "branch absent" and is misrouted (hard-fail / `needs-human`, or fallback to staging in older code paths). The result is a single milestone's PRs scattered across the milestone branch and staging — a branch-routing nondeterminism that recurs under parallelism.
+**WHY THIS EXISTS**: Feature-lane milestone branches were created lazily — by whichever feature-lane agent reached its build phase first. When multiple agents are dispatched simultaneously, they each run the lane check at roughly the same time. Every agent that runs before the branch is first pushed observes "branch absent" and is misrouted (hard-fail / `needs-human`, or fallback to staging in older code paths). The result is a single milestone's PRs scattered across the milestone branch and staging — a branch-routing nondeterminism that recurs under parallelism.
 
-The fix is deterministic: create every milestone branch the wave will target **once, up front, before any agent runs `classify-lane.sh`**. After this step, every agent's lane check sees the branch and routes consistently.
+The fix is deterministic: create every milestone branch the ready issues will target **once, up front, before any agent runs `classify-lane.sh`**. After this step, every agent's lane check sees the branch and routes consistently.
 
-**When to run**: Before the classify-lane loop in Step 4A.pre, for every wave. The step is a no-op for pure fast-lane waves (no issue in the wave has a milestone).
+**When to run**: Before the classify-lane loop in Step 4A.pre, for every dispatch group (initial ready set + each subsequent batch of newly unblocked issues). The step is a no-op for pure fast-lane issues (no issue in the group has a milestone).
 
-**Requires bash 4+**: This snippet uses an associative array (`declare -A SEEN_MILESTONE_SLUG`) to de-dupe milestone slugs, so it must run under bash 4 or newer. Under a non-bash POSIX shell (`sh`/dash), `declare -A` fails and the de-dupe silently no-ops. This degrades gracefully — branch creation stays correct because the `git ls-remote --exit-code` exists-check below still skips any milestone branch that already exists; the only effect is redundant, idempotent `ls-remote`/`push` attempts for milestones referenced by more than one issue in the wave. Run this command's blocks under bash 4+. <!-- Added: forge#901 -->
+**Requires bash 4+**: This snippet uses an associative array (`declare -A SEEN_MILESTONE_SLUG`) to de-dupe milestone slugs, so it must run under bash 4 or newer. Under a non-bash POSIX shell (`sh`/dash), `declare -A` fails and the de-dupe silently no-ops. This degrades gracefully — branch creation stays correct because the `git ls-remote --exit-code` exists-check below still skips any milestone branch that already exists; the only effect is redundant, idempotent `ls-remote`/`push` attempts for milestones referenced by more than one issue. Run this command's blocks under bash 4+. <!-- Added: forge#901 -->
 
 ```bash
-# Pre-create the origin milestone branch for every distinct milestone referenced by the wave.
+# Pre-create the origin milestone branch for every distinct milestone referenced by ready issues.
 # Slugification MUST byte-match scripts/classify-lane.sh — otherwise a branch is created that
 # the classifier will not select. Keep these two slug pipelines identical.
 git fetch origin
 
-# Collect distinct milestone titles among the wave's issues
+# Collect distinct milestone titles among the ready issues
 declare -A SEEN_MILESTONE_SLUG
-for NUM in {wave_issue_numbers}; do
+for NUM in {ready_issue_numbers}; do
   MILESTONE_TITLE=$(gh issue view "$NUM" -R {GH_REPO} --json milestone --jq '.milestone.title // empty' 2>/dev/null || echo "")
   [ -z "$MILESTONE_TITLE" ] && continue  # fast-lane issue — no milestone branch needed
 
@@ -615,11 +748,11 @@ for NUM in {wave_issue_numbers}; do
 done
 ```
 
-This step is the deterministic counterpart to fix #2 (atomic create-if-absent in the classifier): by guaranteeing the branch exists before the wave's lane checks run, no agent can observe a missing branch. `classify-lane.sh`'s hard-fail is intentionally preserved as the phantom-slug gate for any path that bypasses this step.
+This step is the deterministic counterpart to fix #2 (atomic create-if-absent in the classifier): by guaranteeing the branch exists before the lane checks run, no agent can observe a missing branch. `classify-lane.sh`'s hard-fail is intentionally preserved as the phantom-slug gate for any path that bypasses this step.
 
-### Step 4A.pre: Classify lane for each issue (MANDATORY before spawning agents)
+### Step 4A.pre: Classify lane for each issue (MANDATORY before dispatching agents)
 
-Before building agent prompts, run `classify-lane.sh` for every issue in the current wave to compute `{LANE}` and `{PR_BASE}` deterministically. The script output is authoritative — the LLM MUST NOT override or reason around it.
+Before building agent prompts, run `classify-lane.sh` for every issue in the current dispatch group to compute `{LANE}` and `{PR_BASE}` deterministically. The script output is authoritative — the LLM MUST NOT override or reason around it.
 
 ```bash
 # Requires classify-lane.sh to be available at ~/.claude/scripts/classify-lane.sh
@@ -629,7 +762,15 @@ Before building agent prompts, run `classify-lane.sh` for every issue in the cur
 declare -A ISSUE_LANE
 declare -A ISSUE_PR_BASE
 
-for NUM in {wave_issue_numbers}; do
+# Batch-level accumulators for review-finding cascade control (Step 4C) and
+# Completion Sweep (Step 4F). Declared here so they persist across ALL agent
+# completions — Step 4C runs per-agent and must NOT re-initialize these.
+DEFERRED_FINDINGS=()
+QUEUED_FINDINGS=()
+declare -A DEFERRED_REASONS
+declare -A AGENT_ISSUE_MAP
+
+for NUM in {ready_issue_numbers}; do
   PR_BASE=$(bash ~/.claude/scripts/classify-lane.sh "$NUM" -R {GH_REPO}) || {
     echo "ERROR: classify-lane.sh failed for #$NUM — adding needs-human label and skipping" >&2
     gh issue edit "$NUM" -R {GH_REPO} --add-label "needs-human" 2>/dev/null || true
@@ -649,11 +790,11 @@ done
 
 Use `${ISSUE_LANE[$NUM]}` and `${ISSUE_PR_BASE[$NUM]}` to populate `{LANE}` and `{PR_BASE}` in the agent template below. Never substitute prose guesses for these values — the script output is the only valid source. <!-- Added: forge#677 -->
 
-### Step 4A: Launch a wave
+### Step 4A: Dispatch ready issues
 
 **REMINDER: You MUST use the template below verbatim. Only fill in `{VARIABLES}`. Do NOT rewrite the agent prompt. Do NOT write custom implementation instructions. The agent MUST invoke `/work-on` via the Skill tool — this is the HARD RULE from the top of this file.**
 
-For each issue in the current wave, spawn an Agent sub-agent that runs the full `/work-on` pipeline.
+For each **ready** issue (all predecessors resolved or no predecessors), spawn an Agent sub-agent that runs the full `/work-on` pipeline. On the initial dispatch, this is every issue with an empty predecessor set. On subsequent dispatches (triggered by agent completions in Step 4B), this is every newly-unblocked issue.
 
 **One agent per issue.** Do NOT group multiple issues into a single agent. `/work-on` handles branching, labels, and PRs per-issue.
 
@@ -712,7 +853,7 @@ If the label is NOT terminal (e.g., `workflow:investigating`, `workflow:ready-to
 )
 ```
 
-**`{GIST_CONTEXT}` generation**: For each issue in the wave, check if it was spawned by an investigation that has a Knowledge Gist (from Step 2C.5). If so, include the Gist URL(s) in the agent prompt:
+**`{GIST_CONTEXT}` generation**: For each issue being dispatched, check if it was spawned by an investigation that has a Knowledge Gist (from Step 2C.5). If so, include the Gist URL(s) in the agent prompt:
 
 ```bash
 # Build GIST_CONTEXT for an issue
@@ -739,12 +880,43 @@ fi
 
 If `GIST_CONTEXT` is empty (no parent investigation or milestone index found), the variable resolves to a blank line in the template — no impact on the agent prompt. <!-- Updated: forge#341 -->
 
-**Launch all agents in the current wave simultaneously** by putting multiple Agent tool calls in a single message. Use `run_in_background=true` so they execute in parallel.
+**Capture agent IDs after the batch spawn (MANDATORY)**: Each `Agent(...)` call returns an agent ID. Store each returned ID in `AGENT_ISSUE_MAP` keyed by issue number. This map is the only way to resume a stalled agent by ID in Steps 4B and 4B.5:
+
+```
+# After the single-message batch spawn, capture each returned ID:
+AGENT_ISSUE_MAP[{NUMBER}] = <agent_id returned by Agent()>
+```
 
-### Step 4B: Monitor wave completion
+`AGENT_ISSUE_MAP` starts empty and accumulates entries as agents are spawned. For parallel dispatch (all Agent() calls in one message), capture the returned IDs from the batch response — one entry per issue — before entering Step 4B's monitoring loop. Without this capture, `resume=` calls in Steps 4B and 4B.5 will have no agent ID to reference and the resume will fail. <!-- Added: forge#1083 -->
+
+**Launch all ready agents simultaneously** by putting multiple Agent tool calls in a single message. Use `run_in_background=true` so they execute in parallel.
+
+### Step 4B: Monitor completions and dispatch newly ready issues
 
 You will be automatically notified when each background agent completes. **Do NOT use `sleep` loops to poll for completion.** Instead, wait for the automatic notification. When you receive a notification that an agent completed, immediately process it.
 
+**Core streaming dispatch loop**: After processing each agent completion, check the DAG for newly unblocked issues. If any issue now has all predecessors in a terminal state, dispatch it immediately (run Steps 4A.pre.0, 4A.pre, and 4A for the newly ready issues). This is the key difference from the wave model — issues dispatch as soon as their specific predecessors complete, not after an entire group finishes.
+
+```bash
+# After each agent completion, check for newly ready issues:
+for BLOCKED_NUM in {all_blocked_issue_numbers}; do
+  ALL_PREDS_DONE=true
+  for PRED in {predecessors_of_BLOCKED_NUM}; do
+    PRED_STATE=$(gh issue view $PRED -R {GH_REPO} --json labels,state --jq '{state: .state, workflow: [.labels[].name | select(startswith("workflow:"))]}')
+    # Terminal states: workflow:merged, workflow:invalid, needs-human, or state=CLOSED
+    if ! echo "$PRED_STATE" | grep -qE 'workflow:merged|workflow:invalid|needs-human|CLOSED'; then
+      ALL_PREDS_DONE=false
+      break
+    fi
+  done
+  if [ "$ALL_PREDS_DONE" = "true" ]; then
+    echo "#{BLOCKED_NUM} is now READY — all predecessors resolved. Dispatching."
+    # Add to dispatch batch for this completion cycle
+  fi
+done
+# Run Steps 4A.pre.0 → 4A.pre → 4A for newly ready issues (batch them in a single message)
+```
+
 **CRITICAL — Stall detection and recovery**: Background agents sometimes stop mid-pipeline (`stop_reason=end_turn`) after completing a sub-phase (e.g., investigation completes but build never starts). This causes the agent to "complete" from the Agent tool's perspective even though the `/work-on` pipeline is only partially done. When you receive a completion notification:
 
 1. **Check if the agent completed the FULL pipeline** — not just one phase:
@@ -757,7 +929,7 @@ You will be automatically notified when each background agent completes. **Do NO
 2. **If the issue is NOT in a terminal state** (`workflow:merged`, `workflow:invalid`, or `needs-human`), the agent stalled mid-pipeline. **Resume it immediately**:
    ```
    Agent(
-     resume="{AGENT_ID}",
+     resume=AGENT_ISSUE_MAP[{NUMBER}],
      description="Resume #{NUMBER} pipeline",
      run_in_background=true,
      prompt="The previous /work-on invocation stopped before completing the full pipeline. The issue is currently at {CURRENT_WORKFLOW_STATE}. Continue — invoke Skill(skill='work-on', args='{NUMBER}') to resume the routing loop from the current state. /work-on will re-read GitHub state and pick up where it left off."
@@ -765,11 +937,15 @@ You will be automatically notified when each background agent completes. **Do NO
    ```
    **Resume ALL stalled agents in a single message** (parallel resume). Do not wait between resumes.
 
-3. **Track resume cycles per agent.** If an agent has been resumed 3+ times and still hasn't reached a terminal state, report it as a failure — do not resume again.
+3. **Track resume cycles per agent.** If an agent has been resumed 2+ times and still hasn't reached a terminal state, report it as a failure — do not resume again.
 
 4. **Record completed results**: Success (PR merged), Invalid (issue closed), Blocked (needs human), or Error
 
-5. **Verify pipeline compliance** — for each truly completed issue, check that the agent used `/work-on`:
+5. **Check for newly unblocked issues** — run the DAG readiness check above. If any issues are now ready, dispatch them immediately (Steps 4A.pre.0 → 4A.pre → 4A). Batch all newly ready issues into a single dispatch message.
+
+6. **Handle predecessor failures** — if a completed agent's issue FAILED (needs-human, invalid, or error), check for dependent issues in the DAG. Mark all transitive dependents as "skipped — dependency #{X} failed" and report them. Do NOT dispatch them.
+
+7. **Verify pipeline compliance** — for each truly completed issue, check that the agent used `/work-on`:
    ```bash
    LABELS=$(gh issue view $NUM -R {GH_REPO} --json labels --jq '[.labels[].name | select(startswith("workflow:"))] | length')
    COMMENTS=$(gh api repos/{GH_REPO}/issues/${NUM}/comments --jq '[.[] | select(.body | test("FORGE:INVESTIGATOR|FORGE:BUILDER"))] | length')
@@ -779,19 +955,25 @@ You will be automatically notified when each background agent completes. **Do NO
    ```
    If an agent bypassed the pipeline, report it as a **failure** regardless of whether a PR exists.
 
-6. **Post a brief status update** to the user after each agent reaches terminal state:
+8. **Post a brief status update** to the user after each agent reaches terminal state:
    ```
    ✓ #{NUMBER} — {title} → PR #{PR} merged to {target}
    ✗ #{NUMBER} — {title} → {reason for failure}
    ⚠ #{NUMBER} — {title} → PIPELINE BYPASS (no /work-on — PR invalid)
-   ⏳ Wave 1: 2/3 complete (1 resumed after stall)...
+   ⏳ Progress: {completed}/{total} complete, {active} active, {blocked} blocked
+   → Dispatched #{NEWLY_READY} (predecessor #{PRED} completed)
    ```
 
+9. **Run staging integrity check** (from Step 4A-pre) if the completed agent merged a PR targeting staging.
+
+**Termination condition**: All issues in the DAG are in a terminal state (merged, invalid, needs-human, or skipped due to dependency failure). When this condition is met, check whether deferred review-spawned findings exist (accumulated in `DEFERRED_FINDINGS` during Step 4C). If deferred findings exist → proceed to Step 4F (Completion Sweep). If no deferred findings → proceed to Phase 5.
+
 **Anti-pattern — DO NOT DO THIS:**
 - `sleep 60/120/180/300` loops to check status — you will be notified automatically
 - Spawning separate "progress check" agents — they waste tokens and add noise
 - Reading agent JSONL output files to check progress — use GitHub labels as the source of truth
 - Polling the same status check repeatedly on a timer
+- Waiting for a "batch" of completions before checking for newly ready issues — check after EVERY completion
 
 ### Step 4B.5: Time-Based Stall Detection
 
@@ -799,7 +981,7 @@ You will be automatically notified when each background agent completes. **Do NO
 
 **When to run** (NOT a sleep loop — two trigger points only):
 1. On every background agent completion event (run BEFORE the terminal-state check in Step 4B)
-2. Before posting any "waiting for wave..." status update to the user
+2. Before posting any "waiting for agents..." status update to the user
 
 **Do NOT poll on a timer. Do NOT use sleep. Run at these two trigger points only.**
 
@@ -808,9 +990,9 @@ You will be automatically notified when each background agent completes. **Do NO
 STALL_TIMEOUT=$(yq '.pipeline.stall_timeout_minutes // 15' forge.yaml 2>/dev/null || echo 15)
 ```
 
-**For each non-terminal agent in the current wave**:
+**For each non-terminal agent in the current batch**:
 ```bash
-for NUM in {active_wave_issue_numbers}; do
+for NUM in {active_issue_numbers}; do
   # Skip issues already in terminal state
   TERMINAL=$(gh issue view $NUM -R {GH_REPO} --json labels \
     --jq '[.labels[].name | select(. == "workflow:merged" or . == "workflow:invalid" or . == "needs-human")] | length')
@@ -870,26 +1052,26 @@ Issue #${NUM} has been auto-resumed ${STALL_COUNT} times without reaching a term
 done
 
 # Launch all stall resumes in parallel (single message — same rule as Step 4B)
-# For each NUM in $STALL_RESUME_LIST, call Agent(resume="{AGENT_ID}", run_in_background=true, ...)
+# For each NUM in $STALL_RESUME_LIST, call Agent(resume=AGENT_ISSUE_MAP[NUM], run_in_background=true, ...)
 ```
 
 **Resume all stalled agents in a single message** (parallel). Use the same `Agent(resume=...)` pattern as Step 4B — do not wait between individual resumes.
 
 **Track stall resume cycles separately** from completion-event resumes (Step 4B). If the same issue accumulates ≥ 2 `FORGE:STALL_DETECTED` comments AND still hasn't reached terminal state, do not resume again — the `needs-human` label is already set.
 
-### Step 4C: Collect review-finding issues from completed wave
+### Step 4C: Collect review-finding issues from completed agents
 
-When ALL agents in the current wave have completed, check if any `/work-on` runs spawned review-finding issues during their review phase. These are new work items that should be folded into the remaining waves.
+After each agent reaches a terminal state, check if its `/work-on` run spawned review-finding issues during the review phase. These are new work items that should be added to the dependency DAG and dispatched when ready.
 
 ```bash
 # Method 1: Read TRAJECTORY comments from completed issues for "Finding issues" row
-for NUM in {completed_issue_numbers_this_wave}; do
+for NUM in {completed_issue_number}; do
   gh api repos/{GH_REPO}/issues/${NUM}/comments \
     --jq '.[] | select(.body | contains("FORGE:TRAJECTORY")) | .body' 2>/dev/null \
     | grep -oP 'Finding issues\s*\|\s*#?\K\d+[^|]*' | grep -oP '\d+' | sort -u
 done
 
-# Method 2 (fallback): Check for recently created review-finding issues that reference PRs from this wave
+# Method 2 (fallback): Check for recently created review-finding issues that reference PRs from this batch
 gh issue list -R {GH_REPO} --state open --label "review-finding" --limit 20 \
   --json number,title,body,createdAt \
   --jq "[.[] | select(.createdAt > \"$(date -u -d '2 hours ago' +%Y-%m-%dT%H:%M:%SZ)\")]"
@@ -897,7 +1079,7 @@ gh issue list -R {GH_REPO} --state open --label "review-finding" --limit 20 \
 
 **If review-finding issues were spawned:**
 
-**Cascade control (MANDATORY — run before folding findings into waves):**
+**Cascade control (MANDATORY — run before folding findings into the DAG):**
 
 For each spawned finding, determine whether it should be **executed** or **deferred**:
 
@@ -905,17 +1087,17 @@ For each spawned finding, determine whether it should be **executed** or **defer
 1. **Generation ≥ 2** (always defer, even for P1/P2): Finding was spawned by an issue that was itself a review-finding. Check the source issue's labels for `review-finding` — if the source has that label, the new finding is generation 2. Always defer. Rationale: gen-2+ cascade is theoretically unbounded — cap it here.
 2. **Priority override** (P1 or P2 → always execute): If the finding is labeled P1 or P2, skip all remaining heuristics and execute. Rationale: high-priority findings must never be suppressed by keyword matching.
 3. **Comment/typo heuristic** (P3 and below only): Finding title contains the word "comment" or "typo" (case-insensitive). These are 1-line cosmetic fixes that do not block other work.
-4. **P3 + same-file overlap**: Finding is labeled `P3` AND the file it targets overlaps with ANY file already in the current or remaining batch waves. Rationale: same-file P3 findings serialize the entire remaining batch — one finding per original issue doubles wall-clock time with no proportional value.
+4. **P3 + same-file overlap**: Finding is labeled `P3` AND the file it targets overlaps with ANY file already in the current batch (active or queued in the DAG). Rationale: same-file P3 findings add predecessor edges that serialize agents — one finding per original issue increases wall-clock time with no proportional value.
 
-**Defer** (do NOT add to wave queue) if rules 1, 3, or 4 match.
+**Defer** (do NOT add to the DAG) if rules 1, 3, or 4 match.
 
-**Execute** (add to wave queue) if:
+**Execute** (add to the DAG) if:
 - Rule 2 matches (P1 or P2)
 - None of the defer rules matched (generation 1, P3 with no file overlap, not a keyword match)
 
 **Before running the loop, build the batch file list (MANDATORY for Heuristic 3):**
 
-Collect all file paths from every issue in the current batch — both completed waves and remaining queued waves. This produces `ALL_BATCH_FILES`, a newline-separated list of file paths used by Heuristic 3 to test same-file overlap.
+Collect all file paths from every issue in the current batch — both completed and remaining queued issues in the DAG. This produces `ALL_BATCH_FILES`, a newline-separated list of file paths used by Heuristic 3 to test same-file overlap.
 
 ```bash
 # Build ALL_BATCH_FILES: collect file paths from ALL batch issues (completed + queued)
@@ -938,6 +1120,8 @@ ALL_BATCH_FILES=$(echo "$ALL_BATCH_FILES" | sort -u | grep -v '^$')
 
 ```bash
 # For each finding, check its priority label and generation
+# NOTE: DEFERRED_FINDINGS, QUEUED_FINDINGS, and DEFERRED_REASONS are declared at
+# batch scope in Step 4A.pre — do NOT re-initialize them here (Step 4C runs per-agent).
 for FINDING_NUM in {spawned_finding_numbers}; do
   FINDING_DATA=$(gh issue view $FINDING_NUM -R {GH_REPO} --json labels,title,body \
     --jq '{labels: [.labels[].name], title: .title, body: .body}')
@@ -971,6 +1155,7 @@ for FINDING_NUM in {spawned_finding_numbers}; do
 
   if [ "$DEFER" = "true" ]; then
     DEFERRED_FINDINGS+=($FINDING_NUM)
+    DEFERRED_REASONS[$FINDING_NUM]="$DEFER_REASON"
     echo "Deferred #${FINDING_NUM}: $DEFER_REASON"
   else
     QUEUED_FINDINGS+=($FINDING_NUM)
@@ -980,28 +1165,27 @@ done
 
 **For queued (non-deferred) findings:**
 
-1. **Add them to the remaining wave plan.** They are implementation issues — same as issues spawned by investigations in Phase 2.
+1. **Add them to the dependency DAG.** They are implementation issues — same as issues spawned by investigations in Phase 2. Compute their predecessor sets using the same conflict detection (Step 3C Layers 1-4) against all remaining blocked/active issues.
 2. **Respect source branch context.** Review-finding issues have `**Code branch**: \`{branch}\`` in their body — the `/work-on` agent will read this and branch from the right origin. No special handling needed from the orchestrator.
 3. **Report to user:**
    ```
-   Wave {N} review spawned {count} new finding issues: #{A}, #{B}
-   Queued for execution: #{A}, #{B}
+   Agent #{COMPLETED} spawned {count} new finding issues: #{A}, #{B}
+   Added to DAG: #{A} (predecessors: {}), #{B} (predecessors: {#{X}})
    Deferred (cascade control): #{C} (P3 same-file), #{D} (comment heuristic)
-   Adding queued findings to Wave {N+1} (or new wave if no remaining waves).
    ```
-4. **Re-run file-overlap detection** (Step 3C) on the expanded issue set — finding issues may conflict with planned issues that touch the same files.
+4. **Re-run file-overlap detection** (Step 3C) on the expanded issue set — finding issues may conflict with active or queued issues that touch the same files. Ready findings dispatch immediately via the standard Step 4B dispatch loop.
 
 **For deferred findings:**
 
-They remain open in GitHub — they will be picked up by future `/orchestrate` or `/work-on` runs. Log them in the final batch summary under "deferred" so they are visible. Do NOT close or label them — leave them for the next pipeline pass.
+Track them in `DEFERRED_FINDINGS` for re-evaluation in Step 4F (Completion Sweep) after the DAG drains. Do NOT close or label them yet — the sweep will determine their final disposition.
 
-**If no review-finding issues were spawned:** Continue to next wave normally.
+**If no review-finding issues were spawned:** Continue monitoring for the next agent completion.
 
-### Step 4C.5: Milestone lane-consistency check (run after each wave) <!-- Added: forge#901 -->
+### Step 4C.5: Milestone lane-consistency check (periodic) <!-- Added: forge#901 -->
 
 **WHY THIS EXISTS**: A milestone's feature-lane PRs must all target the same milestone branch. If a branch-routing race ever scatters them — some on the milestone branch, some on staging — the milestone branch becomes incomplete relative to staging, and the split is otherwise invisible until the milestone tries to ship. Step 4A.pre.0 prevents the split deterministically; this check detects any residual split so it surfaces immediately instead of at ship time.
 
-**When to run**: After each wave completes, for any batch where at least one issue has a milestone. Skip for pure fast-lane batches. This check is **non-blocking** — it alerts; it does not auto-resolve or stop the pipeline.
+**When to run**: After every 3rd agent completion (or after all agents complete, whichever comes first), for any batch where at least one issue has a milestone. Skip for pure fast-lane batches. This check is **non-blocking** — it alerts; it does not auto-resolve or stop the pipeline.
 
 ```bash
 # For each distinct milestone in the batch, assert all of its feature-lane PRs share one base.
@@ -1051,13 +1235,13 @@ for NUM in {all_batch_issue_numbers}; do
 done
 ```
 
-Report any `ALERT` lines prominently before advancing to the next wave. Reconciliation of an existing split is a manual/`/milestone`-assisted step — this check only ensures the split is never silent.
+Report any `ALERT` lines prominently before dispatching more agents. Reconciliation of an existing split is a manual/`/milestone`-assisted step — this check only ensures the split is never silent.
 
-### Step 4D: Milestone integration build gate (MANDATORY between waves)
+### Step 4D: Milestone integration build gate (MANDATORY — periodic for milestone batches)
 
-**WHY THIS EXISTS**: Session Intelligence milestone shipped 116 PRs across multiple waves with zero integration testing. Each PR built in isolation — type errors from cross-PR interactions (wrong prop types, missing components, incompatible interfaces) were invisible until the milestone→staging merge broke the build with 4 distinct errors. This gate catches those failures early.
+**WHY THIS EXISTS**: Session Intelligence milestone shipped 116 PRs across multiple dispatches with zero integration testing. Each PR built in isolation — type errors from cross-PR interactions (wrong prop types, missing components, incompatible interfaces) were invisible until the milestone→staging merge broke the build with 4 distinct errors. This gate catches those failures early.
 
-**When to run**: After each wave completes, IF the batch targets a milestone branch AND any `.tsx`/`.ts` files were changed by agents in the completed wave.
+**When to run**: After every 3rd milestone-targeted agent completion (or when all milestone issues are complete), IF the batch targets a milestone branch AND any `.tsx`/`.ts` files were changed by agents in the completed set. Running after every single agent would be too frequent — batch the check to reduce overhead while still catching integration errors before they accumulate.
 
 All tool commands are read from `forge.yaml → verification.commands`; each step logs `SKIPPED — not configured` when the corresponding key is absent rather than silently passing.
 
@@ -1072,7 +1256,7 @@ MILESTONE_BRANCH="milestone/{milestone_slug}"
 TS_CHANGED=$(git diff origin/{DEFAULT_BRANCH}...origin/${MILESTONE_BRANCH} --name-only | grep -E '\.(tsx?|jsx?)$' | head -1)
 
 if [ -n "$TS_CHANGED" ]; then
-    echo "=== Integration Build Gate (TypeScript): Wave {N} ==="
+    echo "=== Integration Build Gate (TypeScript): batch checkpoint ==="
     cd {REPO_PATH}
     git fetch origin ${MILESTONE_BRANCH}
     git checkout origin/${MILESTONE_BRANCH} --detach 2>/dev/null
@@ -1096,18 +1280,18 @@ if [ -n "$TS_CHANGED" ]; then
     git checkout - 2>/dev/null
 
     if [ "$TSC_EXIT" -ne 0 ]; then
-        echo "BLOCKING: TypeScript errors on ${MILESTONE_BRANCH} after Wave {N}."
-        echo "Fix type errors before starting next wave."
+        echo "BLOCKING: TypeScript errors on ${MILESTONE_BRANCH} after batch checkpoint."
+        echo "Fix type errors before dispatching more milestone agents."
     elif [ "${BUILD_EXIT:-0}" -ne 0 ]; then
-        echo "BLOCKING: build failed on ${MILESTONE_BRANCH} after Wave {N}."
-        echo "Build/prerender errors — fix before starting next wave."
+        echo "BLOCKING: build failed on ${MILESTONE_BRANCH} after batch checkpoint."
+        echo "Build/prerender errors — fix before dispatching more milestone agents."
     fi
 fi
 
 # Python format check
 PY_CHANGED=$(git diff origin/{DEFAULT_BRANCH}...origin/${MILESTONE_BRANCH} --name-only | grep -E '\.py$' | head -1)
 if [ -n "$PY_CHANGED" ]; then
-    echo "=== Integration Build Gate (Python): Wave {N} ==="
+    echo "=== Integration Build Gate (Python): batch checkpoint ==="
     cd {REPO_PATH}
     git checkout origin/${MILESTONE_BRANCH} --detach 2>/dev/null
 
@@ -1122,32 +1306,234 @@ if [ -n "$PY_CHANGED" ]; then
     git checkout - 2>/dev/null
 
     if [ "$FORMAT_EXIT" -ne 0 ]; then
-        echo "WARNING: Python formatting issues on ${MILESTONE_BRANCH} after Wave {N}."
+        echo "WARNING: Python formatting issues on ${MILESTONE_BRANCH} after batch checkpoint."
         echo "Not blocking but should be fixed before milestone→staging."
     fi
 fi
 ```
 
-**If the gate fails**: Report the errors to the user. Do NOT proceed to the next wave. The accumulated milestone branch has integration errors that will only get worse with more PRs on top. Build failures are BLOCKING — SSG/prerender crashes are invisible to typecheck alone — configure `typescript.build` in `verification.commands` to catch them.
-
-### Step 4E: Advance to next wave
+**If the gate fails**: Report the errors to the user. Do NOT dispatch any more milestone-targeted agents until the integration errors are resolved. The accumulated milestone branch has integration errors that will only get worse with more PRs on top. Build failures are BLOCKING — SSG/prerender crashes are invisible to typecheck alone — configure `typescript.build` in `verification.commands` to catch them. Non-milestone (fast-lane) agents may continue dispatching normally.
 
-When wave results are processed, the integration gate passes (or is not applicable), and any new finding issues are folded in:
-
-1. Check if any failures in the current wave block the next wave (dependency failures)
-2. If a dependency failed, skip dependent issues in the next wave and report them as "skipped — dependency #{X} failed"
-3. Launch the next wave (same process as Step 4A)
-
-### Step 4F: Handle individual agent failures
+### Step 4E: Handle individual agent failures
 
 If an agent reports failure or error:
 - **Merge conflict**: Report to user, mark issue as needing human attention
 - **Invalid issue**: Already handled by the agent (closed with comment) — just report it
 - **Build/test failure**: Report the error, suggest manual intervention
 - **Agent timeout**: Report which issue timed out, suggest re-running with `/work-on #{N}`
+- **Dependency cascade**: Mark all transitive dependents in the DAG as "skipped — dependency #{X} failed"
 
 **Do NOT retry failed agents automatically.** Report the failure and let the user decide.
 
+### Step 4F: Completion Sweep (deferred review-spawned findings) <!-- Added: forge#1105 -->
+
+**When to run**: After all DAG issues reach terminal state AND `DEFERRED_FINDINGS` is non-empty. Skip if no findings were deferred during this batch.
+
+**WHY THIS EXISTS**: Deferred findings accumulate during the batch because of file-overlap and cascade-control heuristics (Step 4C). But once the DAG drains, the conditions that caused deferral often no longer apply — completed issues no longer occupy files, so same-file overlap vanishes. Without this sweep, deferred findings silently pile up across runs and never get resolved.
+
+**Step 4F.1: Classify deferred findings into permanent vs re-evaluable**
+
+```bash
+PERMANENT_DEFERRED=()
+SWEEP_CANDIDATES=()
+
+for FINDING_NUM in "${DEFERRED_FINDINGS[@]}"; do
+  DEFER_REASON="${DEFERRED_REASONS[$FINDING_NUM]}"
+
+  # Generation >= 2 deferrals are PERMANENT — unbounded cascade prevention
+  if echo "$DEFER_REASON" | grep -qi "generation"; then
+    PERMANENT_DEFERRED+=($FINDING_NUM)
+  else
+    # All other deferrals (comment/typo, P3 same-file) are re-evaluable
+    SWEEP_CANDIDATES+=($FINDING_NUM)
+  fi
+done
+
+echo "Completion sweep: ${#SWEEP_CANDIDATES[@]} re-evaluable, ${#PERMANENT_DEFERRED[@]} permanent"
+```
+
+**Step 4F.2: Re-evaluate sweep candidates**
+
+Re-run the Step 4C heuristics against the now-empty DAG. Since all original batch issues are in terminal state, the `ALL_BATCH_FILES` list for file-overlap detection is empty — P3 same-file deferrals will now pass.
+
+```bash
+SWEEP_EXECUTE=()
+SWEEP_STILL_DEFERRED=()
+
+for FINDING_NUM in "${SWEEP_CANDIDATES[@]}"; do
+  FINDING_DATA=$(gh issue view $FINDING_NUM -R {GH_REPO} --json labels,title,body,state \
+    --jq '{labels: [.labels[].name], title: .title, body: .body, state: .state}')
+
+  # Skip if already closed (resolved by another process)
+  STATE=$(echo "$FINDING_DATA" | jq -r '.state')
+  [ "$STATE" = "CLOSED" ] && continue
+
+  PRIORITY=$(echo "$FINDING_DATA" | jq -r '.labels[] | select(startswith("priority:P")) | ltrimstr("priority:")' | head -1)
+  TITLE=$(echo "$FINDING_DATA" | jq -r '.title')
+
+  # Re-apply heuristics against the drained DAG (no active batch files)
+  # Comment/typo heuristic still applies — these are cosmetic regardless of DAG state
+  if echo "$TITLE" | grep -qi "comment\|typo"; then
+    SWEEP_STILL_DEFERRED+=($FINDING_NUM)
+    echo "Sweep: #${FINDING_NUM} still deferred (comment/typo — cosmetic)"
+  else
+    # P3 same-file overlap no longer applies (DAG is drained, no active files)
+    # All other findings are safe to execute
+    SWEEP_EXECUTE+=($FINDING_NUM)
+    echo "Sweep: #${FINDING_NUM} cleared for execution (file overlap resolved)"
+  fi
+done
+```
+
+**Step 4F.3: Dispatch cleared findings**
+
+For each finding in `SWEEP_EXECUTE`, add it to a fresh sweep DAG and dispatch using the same Steps 4A.pre.0, 4A.pre, and 4A logic. Run file-overlap detection between the swept findings themselves (they may conflict with each other).
+
+**MANDATORY**: Use the full Step 4A agent template verbatim for each swept finding. Do NOT use a bare `prompt="Run /work-on N"` — that bypasses the label-state loop contract, source branch detection, and all pipeline enforcement rules. Swept findings are always `review-finding` issues that require source branch detection to route correctly.
+
+**Step 4F.3.pre: Classify lane for each sweep finding (MANDATORY before dispatching)**
+
+Run `classify-lane.sh` per finding — same pattern as Step 4A.pre:
+
+```bash
+declare -A SWEEP_LANE
+declare -A SWEEP_PR_BASE
+
+for FINDING_NUM in "${SWEEP_EXECUTE[@]}"; do
+  SWEEP_BASE=$(bash ~/.claude/scripts/classify-lane.sh "$FINDING_NUM" -R {GH_REPO}) || {
+    echo "ERROR: classify-lane.sh failed for #$FINDING_NUM — adding needs-human and skipping" >&2
+    gh issue edit "$FINDING_NUM" -R {GH_REPO} --add-label "needs-human" 2>/dev/null || true
+    continue
+  }
+  if [ "$SWEEP_BASE" = "staging" ]; then
+    SWEEP_LANE[$FINDING_NUM]="fast-lane"
+  else
+    SWEEP_LANE[$FINDING_NUM]="feature-lane"
+  fi
+  SWEEP_PR_BASE[$FINDING_NUM]="$SWEEP_BASE"
+  echo "#$FINDING_NUM → lane=${SWEEP_LANE[$FINDING_NUM]}, PR_BASE=$SWEEP_BASE"
+done
+```
+
+**Step 4F.3.dispatch: Dispatch with full Step 4A template**
+
+```bash
+if [ ${#SWEEP_EXECUTE[@]} -gt 0 ]; then
+  echo "Completion sweep: dispatching ${#SWEEP_EXECUTE[@]} cleared findings"
+
+  # Build sweep DAG — same conflict detection as Step 3C Layers 1-4
+  # but only among the swept findings (no original batch issues remain active)
+  # Dispatch ready findings, monitor completions using the same Step 4B loop
+  # This is a SINGLE pass — findings spawned during the sweep are NOT swept again
+  # (they follow the standard Step 4C triage: queued or deferred for next run)
+
+  # NOTE: Step 4A.pre.0 (milestone branch pre-creation) is intentionally skipped here.
+  # Swept findings are always review-finding issues that target an already-existing branch
+  # (staging or a milestone branch). The branch was created when the original batch ran —
+  # it always exists by the time the sweep runs.
+
+  for FINDING_NUM in "${SWEEP_EXECUTE[@]}"; do
+    # Skip any finding whose classify-lane call failed (needs-human already set above)
+    [ -z "${SWEEP_PR_BASE[$FINDING_NUM]:-}" ] && continue
+
+    FINDING_TITLE=$(gh issue view "$FINDING_NUM" -R {GH_REPO} --json title --jq '.title' 2>/dev/null || echo "")
+
+    # Build GIST_CONTEXT for sweep finding — same as Step 4A generation block
+    GIST_CONTEXT=""
+    PARENT_INV=$(gh issue view "$FINDING_NUM" -R {GH_REPO} --json body --jq '.body' \
+      | grep -oP '(?i)parent[: ]*#\K\d+|spawned from[: ]*#\K\d+' | head -1)
+
+    if [ -n "$PARENT_INV" ] && [ -n "${INVESTIGATION_GISTS[$PARENT_INV]:-}" ]; then
+      GIST_CONTEXT="
+**CONTEXT FROM PRIOR INVESTIGATION**: Investigation #${PARENT_INV} produced Knowledge Gist(s) with findings relevant to this issue:
+$(echo "${INVESTIGATION_GISTS[$PARENT_INV]}" | while IFS= read -r url; do echo "- ${url}"; done)
+Fetch the Gist content during the context-gathering phase for implementation guidance."
+    fi
+
+    if [ -n "$MILESTONE_INDEX_URL" ]; then
+      GIST_CONTEXT="${GIST_CONTEXT}
+
+**MILESTONE KNOWLEDGE INDEX**: All investigation findings for this milestone are aggregated in a single index Gist:
+- ${MILESTONE_INDEX_URL}
+The context-gathering phase can fetch this index to discover all investigation Gists for the milestone."
+    fi
+
+    # Use the full Step 4A template verbatim — copied here so sweep agents receive
+    # the complete pipeline contract. Keep in sync with Step 4A when the template changes.
+    Agent(
+      subagent_type="general-purpose",
+      model="sonnet",
+      description="Work on {PROJECT_PREFIX}#${FINDING_NUM}",
+      run_in_background=true,
+      prompt="You are working on GitHub issue #${FINDING_NUM} for the {PROJECT_NAME} project.
+
+**Project**: {PROJECT_NAME}
+**Repository**: {GH_REPO}
+**Repo path**: {REPO_PATH}
+
+**YOUR MISSION**: Invoke \`/work-on\` via the Skill tool and let it run to completion. \`/work-on\` is a self-contained routing loop that handles the ENTIRE pipeline: investigate → build (context → architect → implement → validate) → review (push → PR → /review-pr --auto-merge) → close (project board → trajectory log → worktree cleanup). Do NOT intervene, compensate, or manually close issues — \`/work-on\` handles everything including issue closure and label updates in its close phase.
+
+**CRITICAL — DO NOT STOP EARLY**: /work-on runs as a multi-phase routing loop. Each phase (investigate, build, review, close) returns an intermediate result — these are NOT completion signals. You are NOT done until the issue reaches a terminal state: \`workflow:merged\`, \`workflow:invalid\`, or \`needs-human\`. If /work-on returns after only one phase (e.g., investigation), you MUST invoke it again immediately — it will re-read GitHub state and continue to the next phase. Keep invoking /work-on until it reaches a terminal state. Never output 'done' or stop after an intermediate result.
+
+**HOW REVIEW FINDINGS WORK**: /review-pr may create GitHub issues (with \`review-finding\` label) for findings it discovers. These are NOT blockers — they are separate work items that will go through their own /work-on pipeline later. The original PR should ALWAYS merge after review. The only exception is build errors (code doesn't compile) — those must be fixed before merging.
+
+**IMPORTANT RULES**:
+- **MANDATORY**: You MUST use the Skill tool to invoke 'work-on' with args '${FINDING_NUM}'. Do NOT implement manually — /work-on handles the full pipeline including label state machine (workflow:investigating → workflow:building → workflow:in-review → workflow:merged), investigation reports, PR creation, and cleanup.
+  - For default repo issues: \`Skill(skill='work-on', args='${FINDING_NUM}')\`
+  - For satellite repo issues: \`Skill(skill='work-on', args='{SATELLITE_PREFIX}:${FINDING_NUM}')\` (prefix from forge.yaml → repos.satellites)
+- NEVER bypass /work-on with manual git/gh commands — the label updates and structured comments are critical for tracking
+- NEVER target \`main\` for PRs targeting the default repo. Use \`{STAGING_BRANCH}\` for fast-lane issues, or \`milestone/{slug}\` for milestone issues.
+- Satellite repos (MCP, n8n) have no staging branch — fast-lane PRs go to \`main\` for those.
+- If the issue is INVALID after investigation, close it with a comment explaining why
+- If you hit merge conflicts or blockers, post a comment on the issue and STOP — do not force anything
+- Do not interact with the user — you are running autonomously in the background
+- **NEVER ask the user questions** — you are a background agent. If review finds issues, auto-fix simple ones and proceed. For complex findings, merge anyway and create follow-up issues.
+
+**LABEL-STATE LOOP CONTRACT — enforce after EVERY Skill return**:
+After EVERY \`Skill(skill='work-on', ...)\` call returns, immediately check the issue's current workflow label:
+\`\`\`bash
+gh issue view ${FINDING_NUM} -R {GH_REPO} --json labels --jq '[.labels[].name | select(startswith(\"workflow:\"))]'
+\`\`\`
+**Terminal labels** (only these allow you to stop): \`workflow:merged\`, \`workflow:invalid\`
+**Terminal condition also**: \`needs-human\` label present OR issue state is \`closed\`
+If the label is NOT terminal (e.g., \`workflow:investigating\`, \`workflow:ready-to-build\`, \`workflow:building\`, \`workflow:in-review\`), invoke \`Skill(skill='work-on', args='${FINDING_NUM}')\` again immediately. The \`/work-on\` skill will re-read GitHub state and advance to the next phase. Do NOT output a summary, do NOT pause, do NOT ask for confirmation — just invoke it again.
+
+**CRITICAL — SOURCE BRANCH DETECTION**:
+- If the issue has the \`review-finding\` label, read the issue body for \`**Code branch**: \\\`{branch}\\\`\`
+- If found, that is the SOURCE_BRANCH — the code ONLY exists on that branch (e.g., \`staging\`), NOT on \`origin/main\`
+- Investigation MUST use \`git show origin/{SOURCE_BRANCH}:{filepath}\` to verify the code exists
+- Worktree MUST branch from \`origin/{SOURCE_BRANCH}\`, NOT \`origin/main\`
+- PR target is \`{SOURCE_BRANCH}\` (the fix goes back to where the code lives)
+
+**LANE**: ${SWEEP_LANE[$FINDING_NUM]} (PR target: ${SWEEP_PR_BASE[$FINDING_NUM]})
+**Issue title**: ${FINDING_TITLE}
+${GIST_CONTEXT}
+"
+    )
+  done
+
+  # Monitor sweep agents using the same Step 4B completion loop
+  # IMPORTANT: Findings spawned by sweep agents are NOT re-swept —
+  # they follow standard Step 4C triage to prevent recursive cascades
+fi
+```
+
+**Step 4F.4: Report sweep results**
+
+```
+Completion Sweep Results:
+  Dispatched: #{A}, #{B} (file overlap cleared after DAG drain)
+  Still deferred (cosmetic): #{C} (comment/typo)
+  Permanently deferred (gen2): #{D} (generation >= 2 cascade cap)
+```
+
+**After sweep agents complete** (or if no findings were dispatched): proceed to Phase 5.
+
+**Anti-patterns — DO NOT DO THIS:**
+- Re-sweeping findings spawned during the sweep itself — this creates unbounded recursion. Sweep is a single pass.
+- Overriding generation >= 2 deferrals — the cascade cap is absolute.
+- Skipping the sweep because "there are only a few" deferred findings — even one deferred finding represents unresolved work.
+
 ---
 
 ## Phase 5: Post-Batch Cleanup
@@ -1191,7 +1577,7 @@ Include the cleanup summary in the final report (Phase 6). If cleanup found prob
 
 ## Phase 6: Consolidated Report
 
-After ALL waves AND cleanup complete, present a final summary.
+After ALL issues reach terminal state AND cleanup completes, present a final summary.
 
 ### Step 6A: Collect trajectory data
 
@@ -1212,7 +1598,7 @@ Aggregate into the batch-level analytics for Step 6B.
 **Scope**: {milestone / issue list}
 **Duration**: {approximate time}
 
-### Wave 0: Investigations
+### Investigations (Phase 2)
 {IF investigations ran:}
 | # | Investigation | Issues Created | Result |
 |---|-------------|---------------|--------|
@@ -1232,17 +1618,31 @@ Aggregate into the batch-level analytics for Step 6B.
 
 ### Review-Spawned Issues
 
-{IF review findings were created during any wave:}
+{IF review findings were created during any agent run:}
 | # | Finding | Source Issue | Source PR | Status |
 |---|---------|-------------|-----------|--------|
-| #{F1} | {title} | #{A} | PR #{PR} | ✓ Merged (wave {N}) / ⏳ Open (deferred) |
+| #{F1} | {title} | #{A} | PR #{PR} | ✓ Merged (in-batch) / ✓ Swept (completion sweep) / ⏳ Deferred (cosmetic) / ⛔ Deferred (gen2 cascade cap) |
 
 {ELSE: "No review findings created during this batch."}
 
+### Completion Sweep <!-- Added: forge#1105 -->
+- **Re-evaluated**: {N} deferred findings re-checked after DAG drain
+- **Dispatched**: {N} findings cleared and executed (file overlap resolved)
+- **Still deferred (cosmetic)**: {N} comment/typo findings (low-value, safe to leave)
+- **Permanently deferred (gen2)**: {N} generation >= 2 findings (cascade cap — requires manual `/work-on`)
+
+{IF permanently deferred > 0:}
+**Action required**: The following findings were permanently deferred due to the generation >= 2 cascade cap. They will NOT be picked up automatically — run `/work-on #{N}` manually or include them in the next `/orchestrate` batch:
+{list of permanently deferred issue numbers and titles}
+
+{IF cosmetic deferred > 0:}
+**Low-priority leftovers**: The following cosmetic findings remain open. They will be picked up by future runs or can be batched with `/orchestrate #{N1} #{N2}`:
+{list of cosmetic deferred issue numbers and titles}
+
 ### Summary
 - **Investigations**: {N} completed, spawned {M} new issues
-- **Review findings**: {N} spawned, {M} resolved in-batch, {K} deferred
-- **Succeeded**: {N} issues resolved (implementation)
+- **Review findings**: {N} spawned, {M} resolved in-batch, {K} swept, {J} deferred (cosmetic), {L} deferred (gen2)
+- **Succeeded**: {N} issues resolved (implementation + sweep)
 - **Failed**: {N} issues need attention
 - **Skipped**: {N} issues (dependency failures)
 
@@ -1259,7 +1659,7 @@ Aggregate into the batch-level analytics for Step 6B.
 |-------|-------|-------|--------|-------|---------|--------------|
 {per-agent rows from audit}
 
-**Wave efficiency**: {avg_idle_pct}% idle time
+**Batch efficiency**: {avg_idle_pct}% idle time
 **Total resume cycles**: {sum_resumes} across {agent_count} agents
 **Clean agents** (no stalls): {clean_count}/{agent_count}
 
@@ -1283,7 +1683,7 @@ Aggregate into the batch-level analytics for Step 6B.
 **Systematic issues** (flag if detected):
 - False positive rate > 30% → review agents may need tuning
 - Invalidation rate < 10% or > 35% → investigation calibration off
-- Same-domain merge conflicts in 2+ waves → domain sequencing too aggressive
+- Same-domain merge conflicts between concurrent agents → domain serialization edges too loose
 - Contract divergences > 20% → investigation quality may need improvement
 - **Idle% > 50%** → agents stalling at phase boundaries; check work-on routing loop
 - **Avg resumes > 1** → orchestrator having to compensate for agent stops
@@ -1304,10 +1704,10 @@ Aggregate into the batch-level analytics for Step 6B.
 4. **Always confirm with user before launching** — Step 3E is the mandatory checkpoint
 5. **No retries** — if an agent fails, report it and move on
 6. **Respect existing work** — skip issues already being worked on (`workflow:building`, `workflow:in-review`)
-7. **Dependency failures cascade** — if A fails and B depends on A, B is skipped (not attempted)
+7. **Dependency failures cascade** — if A fails and B depends on A, all transitive dependents of A are skipped (not attempted)
 8. **Always run post-batch cleanup** — Phase 5 is mandatory. Never skip `/cleanup all` after orchestration.
 9. **NEVER close/skip issues as duplicates** — only `/work-on` investigation agents can make that call after examining the actual code. The orchestrator delegates, it does not adjudicate.
-10. **Post-wave verification** — after each wave, check that every completed issue has `workflow:*` labels and structured comments. If an agent bypassed `/work-on`, report it as a pipeline failure.
+10. **Per-completion verification** — after each agent completes, check that it has `workflow:*` labels and structured comments. If an agent bypassed `/work-on`, report it as a pipeline failure.
 
 ---
 
@@ -1315,31 +1715,38 @@ Aggregate into the batch-level analytics for Step 6B.
 
 ### "orchestrate milestone api-expansion"
 → Fetches all open issues in "API Expansion v1" milestone
-→ Analyzes deps (#1526 → #1527 → #1528 → #1529, #1530 independent)
-→ Plans 3 waves, confirms with user, executes
+→ Builds DAG: #1526 → #1527 → #1528 → #1529 (chain), #1530 (no predecessors)
+→ Confirms with user, dispatches #1526 + #1530 immediately
+→ When #1526 completes, dispatches #1527 immediately (doesn't wait for #1530)
+→ Streaming continues until all issues reach terminal state
 
 ### "orchestrate #1533 #1250"
 → Fetches those 2 issues, no deps between them
-→ Single wave, both parallel, confirms, executes
+→ DAG: both have empty predecessor sets
+→ Confirms, dispatches both simultaneously
 
 ### "orchestrate next 5"
-→ Gets top 5 priority issues, checks deps
-→ Plans waves, confirms, executes
+→ Gets top 5 priority issues, builds DAG
+→ Confirms, dispatches all ready issues immediately
+→ Dependent issues dispatch as predecessors complete
 
 ### "orchestrate P0"
 → Gets all P0 issues, runs them all (presumably urgent)
-→ Single wave if possible, confirms, executes
+→ DAG: likely all independent — dispatches simultaneously
+→ Confirms, executes
 
 ### "orchestrate fast-lane"
 → Gets all unmilestoned bugs/fixes
-→ Groups by independence, runs in waves
+→ Builds DAG from file-conflict and domain-serialization edges
+→ Dispatches all ready issues, streams dependent issues as predecessors complete
 
 ### "orchestrate milestone user-auth-v2"
 → Fetches all open issues in "User Auth v2" milestone
 → Detects #42 is an investigation issue (title: "Investigate: session expiry race condition under high concurrency")
-→ Wave 0: Runs `/work-on 42` — investigation creates 3 new issues (#55-#57)
+→ Phase 2: Runs `/work-on 42` — investigation creates 3 new issues (#55-#57)
 → Re-fetches milestone issues, now includes #55-#57
-→ Wave 1: #38 (P0 token refresh bug), #41 (session store migration), #55, #56 (all independent)
-→ Wave 2: #39 (enable refresh rotation — after #38 fixes token bug), #57 (depends on #55)
-→ Wave 3: remaining issues
-→ Final report shows investigation spawned issues and their results
+→ Builds DAG: #38, #41, #55, #56 have no predecessors (ready); #39 depends on #38; #57 depends on #55
+→ Dispatches #38, #41, #55, #56 simultaneously
+→ When #38 completes, #39 dispatches immediately (doesn't wait for #41, #55, or #56)
+→ When #55 completes, #57 dispatches immediately (doesn't wait for others)
+→ Final report shows investigation spawned issues and streaming execution results