forgedock 1.1.1 → 1.1.2

package/commands/orchestrate/phase-4-execution.md

@@ -0,0 +1,962 @@
+---
+install: internal
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# /orchestrate — Phase 4: Streaming DAG Execution
+
+## Phase 4: Streaming DAG Execution
+
+### 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. 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**: 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 initial staging baseline before first dispatch
+git fetch origin
+if [ "$DEFAULT_BRANCH" = "$STAGING_BRANCH" ]; then
+  STAGING_LINES_BASELINE=0
+  echo "Staging baseline: skipped — single-branch repo (staging == default)"
+else
+  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: ${STAGING_LINES_BASELINE} lines ahead of $DEFAULT_BRANCH"
+fi
+
+# Track cumulative expected growth from merged PRs
+CUMULATIVE_EXPECTED_DELTA=0
+```
+
+**Per-agent-completion integrity check** (run in Step 4B after each agent merges a PR targeting staging):
+
+```bash
+# After agent completes and its PR merges to staging:
+git fetch origin
+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_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_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."
+    # Do NOT auto-stop — alert the user and let them decide
+  fi
+fi
+```
+
+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 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 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 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 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. Run this command's blocks under bash 4+. <!-- Added: forge#901 -->
+
+```bash
+# 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 ready issues
+declare -A SEEN_MILESTONE_SLUG
+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
+
+  # Slugify — IDENTICAL to classify-lane.sh: lowercase → spaces-to-hyphens →
+  # strip non-[a-z0-9-] → collapse hyphens → strip leading/trailing hyphens.
+  SLUG=$(echo "$MILESTONE_TITLE" \
+    | tr '[:upper:]' '[:lower:]' \
+    | tr ' ' '-' \
+    | tr -cd 'a-z0-9-' \
+    | sed 's/--*/-/g' \
+    | sed 's/^-//;s/-$//')
+
+  # Empty-slug guard (matches classify-lane.sh): a title with no ASCII letters/digits/hyphens
+  # would produce "milestone/", an invalid ref. Skip and let classify-lane surface the error.
+  if [ -z "$SLUG" ]; then
+    echo "WARN: milestone title '$MILESTONE_TITLE' (issue #$NUM) produced an empty slug — skipping pre-creation; classify-lane will hard-fail." >&2
+    continue
+  fi
+
+  # De-dupe: only attempt creation once per milestone
+  [ -n "${SEEN_MILESTONE_SLUG[$SLUG]:-}" ] && continue
+  SEEN_MILESTONE_SLUG[$SLUG]=1
+
+  LANE="milestone/$SLUG"
+  if git ls-remote --exit-code origin "$LANE" >/dev/null 2>&1; then
+    echo "Milestone branch '$LANE' already exists on origin — no action."
+    continue
+  fi
+
+  # Create-if-absent from the default branch (matches /milestone create).
+  # $DEFAULT_BRANCH is resolved from forge.yaml at the top of this command.
+  echo "Pre-creating milestone branch '$LANE' from origin/$DEFAULT_BRANCH …"
+  if git push origin "origin/$DEFAULT_BRANCH:refs/heads/$LANE" 2>/dev/null; then
+    echo "Created milestone branch '$LANE'."
+  elif git ls-remote --exit-code origin "$LANE" >/dev/null 2>&1; then
+    # A concurrent orchestrator (or an agent) created it first — harmless. Never force-push.
+    echo "Milestone branch '$LANE' was created concurrently — proceeding with the existing branch."
+  else
+    echo "ERROR: failed to pre-create milestone branch '$LANE' from origin/$DEFAULT_BRANCH." >&2
+    echo "       classify-lane.sh will hard-fail for issues in this milestone until the branch exists." >&2
+  fi
+done
+```
+
+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 dispatching agents)
+
+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
+# (installed by `npx forgedock` — see bin/forgedock.mjs linkScripts step)
+# Fallback: bash "$FORGE_HOME/scripts/classify-lane.sh" if ~/.claude/scripts/ is unavailable
+
+declare -A ISSUE_LANE
+declare -A ISSUE_PR_BASE
+
+# 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
+    continue
+  }
+  # Derive LANE label from PR_BASE
+  if [ "$PR_BASE" = "staging" ]; then
+    LANE="fast-lane"
+  else
+    LANE="feature-lane"
+  fi
+  ISSUE_LANE[$NUM]="$LANE"
+  ISSUE_PR_BASE[$NUM]="$PR_BASE"
+  echo "#$NUM → lane=$LANE, PR_BASE=$PR_BASE"
+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: 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 **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.
+
+**Copy this template. Fill in variables. Do not modify the structure:**
+
+```
+Agent(
+  subagent_type="general-purpose",
+  model="sonnet",
+  description="Work on {PROJECT_PREFIX}#{NUMBER}",
+  run_in_background=true,
+  prompt="You are working on GitHub issue #{NUMBER} 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 '{PROJECT_PREFIX}{NUMBER}'. 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='{NUMBER}')`
+  - For satellite repo issues: `Skill(skill='work-on', args='{SATELLITE_PREFIX}:{NUMBER}')` (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 on **low-risk domains**, merge anyway and create follow-up issues. For complex findings on **high-risk domains** (AUTH, BILLING, DATABASE, or any domain tagged as security-critical in Step 3B), add the `needs-human` label and stop — do NOT merge. High-risk `needs-human` halts are surfaced as `⚠ Blocked` in the Phase 5 completion report.
+
+**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 {NUMBER} -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='{NUMBER}')` 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**: {LANE} (PR target: {PR_BASE})
+**Issue title**: {ISSUE_TITLE}
+{GIST_CONTEXT}
+"
+)
+```
+
+**`{GIST_CONTEXT}` generation**: For each issue being dispatched, build the context block. **Prefer the deconflicted `FORGE:SYNTHESIS_BRIEF` (from Phase 2.5) when one exists** — it is a per-issue, already-reconciled brief that carries only the arbitration decisions and sibling investigation Gists relevant to *this* issue. Injecting it instead of the full aggregated milestone-index gist means the agent does not re-arbitrate the same contradictions (less token spend, less nondeterminism). Only when Phase 2.5 did not run (0/1 investigations — no brief exists) does this fall back to the raw parent-investigation + milestone-index gist behavior. <!-- Added: forge#1192 -->
+
+```bash
+# Build GIST_CONTEXT for an issue
+GIST_CONTEXT=""
+
+# Preferred path: a deconflicted per-issue synthesis brief from Phase 2.5.
+SYNTHESIS_BRIEF=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '[.[] | select(.body | contains("<!-- FORGE:SYNTHESIS_BRIEF -->"))] | last | .body // ""' 2>/dev/null)
+
+if [ -n "$SYNTHESIS_BRIEF" ]; then
+  # Phase 2.5 ran and reconciled competing recommendations for this issue.
+  # Inject the deconflicted brief INSTEAD of the raw milestone-index gist dump.
+  GIST_CONTEXT="
+**RECONCILED CONTEXT (orchestrate Phase 2.5 synthesis brief)**: Competing investigation recommendations affecting this issue have already been reconciled. Use this deconflicted brief as your primary cross-investigation context — do NOT independently re-arbitrate the underlying investigations.
+${SYNTHESIS_BRIEF}"
+else
+  # Fallback: Phase 2.5 did not run (0/1 investigations). Use the raw gist behavior.
+  PARENT_INV=$(gh issue view {NUMBER} -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
+
+  # Include milestone index URL if available (from Step 2C.5)
+  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
+fi
+```
+
+If `GIST_CONTEXT` is empty (no synthesis brief, no parent investigation, and no milestone index found), the variable resolves to a blank line in the template — no impact on the agent prompt. <!-- Updated: forge#341, forge#1192 -->
+
+**Hot-copy CONTRACT context** (extends `{GIST_CONTEXT}` for milestone-lane issues where the parent issue already carries a `FORGE:CONTRACT` annotation): <!-- Added: forge#1277 -->
+
+When a DAG node issue was spawned from a decomposition (parent issue has `workflow:decomposed` label and the child issue body references `**Parent**: #NNN`), the parent issue may already have a `FORGE:CONTRACT` annotation that was posted before decomposition. Inject a scoped excerpt into the child's prompt so the child does not re-fetch it.
+
+```bash
+# Hot-copy: inject parent CONTRACT annotation excerpt into GIST_CONTEXT (milestone lane only)
+PARENT_NUM=$(gh issue view {NUMBER} -R {GH_REPO} --json body --jq '.body' \
+  | grep -oP '(?i)\*\*Parent\*\*[: ]*#\K\d+' | head -1)
+
+if [ -n "$PARENT_NUM" ]; then
+  PARENT_CONTRACT=$(gh api repos/{GH_REPO}/issues/${PARENT_NUM}/comments \
+    --jq '[.[] | select(.body | contains("<!-- FORGE:CONTRACT -->"))] | last | .body // ""' 2>/dev/null \
+    | head -40)  # Scope: first 40 lines — Proposed Approach + Deliverables table only
+
+  if [ -n "$PARENT_CONTRACT" ]; then
+    GIST_CONTEXT="${GIST_CONTEXT}
+
+**HOT COPY — PARENT FORGE:CONTRACT** (from parent issue #${PARENT_NUM}; do not re-fetch — durable record is on that issue):
+${PARENT_CONTRACT}"
+  fi
+fi
+```
+
+If the issue has no parent reference, or the parent has no `FORGE:CONTRACT` annotation, this block produces no output and `GIST_CONTEXT` is unchanged. The hot-copy is an optimization — the durable annotation on the parent issue remains the authoritative record for compaction recovery.
+
+**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()>
+```
+
+`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.
+
+**Successor dispatch latency is measured from `agent_completed`, not from orchestrator polling.** The moment you receive an `agent_completed` notification for issue N, that is t=0 for dispatching N's successors. Any successor whose predecessors are all now terminal MUST be dispatched in the same response that processes the notification — not after a poll cycle, not after a sleep. This is the design property that makes streaming DAG execution faster than wave-based execution. <!-- Added: forge#1251 -->
+
+**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:
+   ```bash
+   # Check final workflow state — only workflow:merged or workflow:invalid means truly done
+   FINAL_STATE=$(gh issue view $NUM -R {GH_REPO} --json labels,state --jq '{state: .state, workflow: [.labels[].name | select(startswith("workflow:"))]}')
+   echo "#{NUM}: $FINAL_STATE"
+   ```
+
+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_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."
+   )
+   ```
+   **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 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. **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')
+   if [ "$LABELS" -eq 0 ] || [ "$COMMENTS" -eq 0 ]; then
+     echo "PIPELINE FAILURE: #{NUM} — agent bypassed /work-on (no labels or structured comments)"
+   fi
+   ```
+   If an agent bypassed the pipeline, report it as a **failure** regardless of whether a PR exists.
+
+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)
+   ⏳ 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
+
+**Purpose**: Catches agents that have stopped responding WITHOUT exiting (e.g., rate-limited, context-frozen, or silently hung). The reactive check in Step 4B only fires on agent completion — this check catches agents that never complete at all.
+
+**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 agents..." status update to the user
+
+**Do NOT poll on a timer. Do NOT use sleep. Run at these two trigger points only.**
+
+**Read stall timeout from config**:
+```bash
+STALL_TIMEOUT=$(yq '.pipeline.stall_timeout_minutes // 15' forge.yaml 2>/dev/null || echo 15)
+```
+
+**For each non-terminal agent in the current batch**:
+```bash
+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')
+  [ "$TERMINAL" -gt 0 ] && continue
+
+  # Get last activity timestamp — prefer last comment (catches FORGE:HEARTBEAT updates)
+  LAST_ACTIVITY=$(gh api repos/{GH_REPO}/issues/${NUM}/comments \
+    --jq '.[-1].updated_at // empty' 2>/dev/null)
+  # Fall back to issue updated_at if no comments
+  if [ -z "$LAST_ACTIVITY" ]; then
+    LAST_ACTIVITY=$(gh issue view $NUM -R {GH_REPO} --json updatedAt --jq '.updatedAt')
+  fi
+
+  # Compute elapsed minutes (GNU date — adjust for macOS: date -j -f "%Y-%m-%dT%H:%M:%SZ")
+  LAST_EPOCH=$(date -d "$LAST_ACTIVITY" +%s 2>/dev/null \
+    || date -j -f "%Y-%m-%dT%H:%M:%SZ" "$LAST_ACTIVITY" +%s 2>/dev/null)
+  NOW_EPOCH=$(date +%s)
+  ELAPSED_MIN=$(( (NOW_EPOCH - LAST_EPOCH) / 60 ))
+
+  if [ "$ELAPSED_MIN" -gt "$STALL_TIMEOUT" ]; then
+    # Count prior stall events on this issue
+    STALL_COUNT=$(gh api repos/{GH_REPO}/issues/${NUM}/comments \
+      --jq '[.[] | select(.body | contains("FORGE:STALL_DETECTED"))] | length')
+
+    CURRENT_STATE=$(gh issue view $NUM -R {GH_REPO} --json labels \
+      --jq '[.labels[].name | select(startswith("workflow:"))] | .[0] // "unknown"')
+
+    if [ "$STALL_COUNT" -lt 2 ]; then
+      # Auto-resume: post stall annotation and re-invoke /work-on
+      RESUME_ATTEMPT=$(( STALL_COUNT + 1 ))
+      gh issue comment $NUM -R {GH_REPO} --body "<!-- FORGE:STALL_DETECTED -->
+## Stall Detected
+
+**Issue**: #${NUM}
+**Elapsed since last activity**: ${ELAPSED_MIN} min (threshold: ${STALL_TIMEOUT} min)
+**Current workflow state**: ${CURRENT_STATE}
+**Auto-resume attempt**: ${RESUME_ATTEMPT} of 2
+**Timestamp**: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+      # Resume the agent — collect all resumes and launch in a single message (see Step 4B rule)
+      # STALL_RESUME_LIST is accumulated and launched in parallel after the loop
+      STALL_RESUME_LIST="$STALL_RESUME_LIST $NUM"
+    else
+      # 2+ prior stalls — auto-resume exhausted, escalate to needs-human
+      gh issue edit $NUM -R {GH_REPO} --add-label "needs-human"
+      gh issue comment $NUM -R {GH_REPO} --body "<!-- FORGE:STALL_DETECTED -->
+## Stall Escalated — Needs Human Intervention
+
+Issue #${NUM} has been auto-resumed ${STALL_COUNT} times without reaching a terminal state. Auto-resume limit (2) exhausted. Manual intervention required.
+
+**Last workflow state**: ${CURRENT_STATE}
+**Total elapsed since last activity**: ${ELAPSED_MIN} min
+**Timestamp**: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+      echo "STALL ESCALATED: #{NUM} → needs-human (${STALL_COUNT} prior resumes)"
+    fi
+  fi
+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_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 agents
+
+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_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 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)\")]"
+```
+
+**If review-finding issues were spawned:**
+
+**Cascade control (MANDATORY — run before folding findings into the DAG):**
+
+For each spawned finding, determine whether it should be **executed** or **deferred**:
+
+**Evaluation order** (first matching rule wins):
+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 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 the DAG) if rules 1, 3, or 4 match.
+
+**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 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)
+# Use the same extraction pattern as Step 3C Layer 1
+ALL_BATCH_FILES=""
+for NUM in {all_batch_issue_numbers}; do
+  # Try INVESTIGATOR comment first (most reliable source of affected files)
+  FILES=$(gh api repos/{GH_REPO}/issues/${NUM}/comments \
+    --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body' 2>/dev/null \
+    | grep -oP '`[^`]*\.(py|tsx?|jsx?|sql|json|ya?ml|sh|md)`' | tr -d '`' | sort -u)
+  # Fall back to issue body if no investigator comment
+  if [ -z "$FILES" ]; then
+    FILES=$(gh issue view $NUM -R {GH_REPO} --json body --jq '.body' \
+      | grep -oP '`[^`]*\.(py|tsx?|jsx?|sql|json|ya?ml|sh|md)`' | tr -d '`' | sort -u)
+  fi
+  ALL_BATCH_FILES=$(printf '%s\n%s' "$ALL_BATCH_FILES" "$FILES")
+done
+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}')
+
+  PRIORITY=$(echo "$FINDING_DATA" | jq -r '.labels[] | select(startswith("priority:P")) | ltrimstr("priority:")' | head -1)
+  TITLE=$(echo "$FINDING_DATA" | jq -r '.title')
+
+  # Heuristic 1: Generation check — source issue has review-finding label (always defer, even for P1/P2)
+  if SOURCE_NUM=$(echo "$FINDING_DATA" | jq -r '.body' | grep -oP '(?i)spawned from issue #\K\d+|source issue[: #]+\K\d+' | head -1) && \
+       [ -n "$SOURCE_NUM" ] && \
+       gh issue view $SOURCE_NUM -R {GH_REPO} --json labels --jq '[.labels[].name]' 2>/dev/null | grep -q "review-finding"; then
+    DEFER=true; DEFER_REASON="generation >= 2 (source #${SOURCE_NUM} is also a review-finding)"
+  # Priority override: P1 or P2 always execute — skip remaining heuristics
+  elif [ "$PRIORITY" = "P1" ] || [ "$PRIORITY" = "P2" ]; then
+    DEFER=false
+  # Heuristic 2: Comment/typo keyword (only applies to P3 and below)
+  elif echo "$TITLE" | grep -qi "comment\|typo"; then
+    DEFER=true; DEFER_REASON="comment/typo heuristic"
+  # Heuristic 3: P3 + same-file overlap
+  elif [ "$PRIORITY" = "P3" ]; then
+    # Extract file target from finding body (look for code block or backtick path)
+    FINDING_FILE=$(echo "$FINDING_DATA" | jq -r '.body' | grep -oP '`[^\`]+\.(py|ts|tsx|sh|md)`' | head -1 | tr -d '`')
+    if [ -n "$FINDING_FILE" ] && echo "$ALL_BATCH_FILES" | grep -qF "$FINDING_FILE"; then
+      DEFER=true; DEFER_REASON="P3 + same file as batch: $FINDING_FILE"
+    else
+      DEFER=false
+    fi
+  else
+    DEFER=false
+  fi
+
+  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)
+  fi
+done
+```
+
+**For queued (non-deferred) findings:**
+
+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:**
+   ```
+   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)
+   ```
+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:**
+
+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 monitoring for the next agent completion.
+
+### 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 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.
+for NUM in {all_batch_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
+
+  SLUG=$(echo "$MILESTONE_TITLE" \
+    | tr '[:upper:]' '[:lower:]' \
+    | tr ' ' '-' \
+    | tr -cd 'a-z0-9-' \
+    | sed 's/--*/-/g' \
+    | sed 's/^-//;s/-$//')
+  [ -z "$SLUG" ] && continue
+  EXPECTED_BASE="milestone/$SLUG"
+
+  # Collect the base branch of every PR that closes an issue in this milestone.
+  # Iterate the milestone's issues and read each one's linked PR base.
+  # Exclude CLOSED-unmerged PRs: a closed-but-not-merged PR is a superseded/abandoned
+  # routing attempt and does NOT reflect the live lane. Keep only OPEN (in-flight) and
+  # MERGED (landed) PRs. `gh pr list --state` cannot combine open+merged, so query all
+  # and drop CLOSED in jq.
+  BASES=$(gh pr list -R {GH_REPO} --state all --search "milestone:\"$MILESTONE_TITLE\"" \
+    --json baseRefName,state --jq '.[] | select(.state != "CLOSED") | .baseRefName' 2>/dev/null | sort -u)
+  # Fallback: if PR search by milestone is unavailable, derive from the issues' linked PRs.
+  if [ -z "$BASES" ]; then
+    BASES=$(for IN in {all_batch_issue_numbers}; do
+      IM=$(gh issue view "$IN" -R {GH_REPO} --json milestone --jq '.milestone.title // empty' 2>/dev/null)
+      [ "$IM" = "$MILESTONE_TITLE" ] || continue
+      gh pr list -R {GH_REPO} --state all --search "$IN in:body" \
+        --json baseRefName,state --jq '.[] | select(.state != "CLOSED") | .baseRefName' 2>/dev/null
+    done | sort -u)
+  fi
+
+  STRAY_BASES=$(echo "$BASES" | grep -v "^${EXPECTED_BASE}\$" | grep -v '^$' || true)
+  if [ -n "$STRAY_BASES" ]; then
+    echo "ALERT: milestone '$MILESTONE_TITLE' has feature-lane PRs split across multiple base branches." >&2
+    echo "       Expected base: $EXPECTED_BASE" >&2
+    echo "       Found bases:" >&2
+    echo "$BASES" | sed 's/^/         - /' >&2
+    echo "       This indicates a branch-routing split — reconcile the stray PRs onto $EXPECTED_BASE" >&2
+    echo "       (rebase/cherry-pick the stray branch onto the milestone branch) before the milestone ships." >&2
+    # Do NOT auto-stop or auto-resolve — surface the alert and let the user decide.
+  else
+    echo "Lane-consistency OK: all '$MILESTONE_TITLE' PRs target $EXPECTED_BASE."
+  fi
+done
+```
+
+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 — periodic for milestone batches)
+
+**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 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.
+
+```bash
+# Read toolchain commands from forge.yaml
+TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
+TS_BUILD=$(yq '.verification.commands.typescript.build // ""' forge.yaml 2>/dev/null || echo '')
+PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
+
+# Check if this is a milestone batch with TypeScript changes
+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): batch checkpoint ==="
+    cd {REPO_PATH}
+    git fetch origin ${MILESTONE_BRANCH}
+    git checkout origin/${MILESTONE_BRANCH} --detach 2>/dev/null
+
+    if [ -n "$TS_TYPECHECK" ]; then
+        eval "$TS_TYPECHECK" 2>&1 | head -30
+        TSC_EXIT=$?
+    else
+        echo "SKIPPED — typescript.typecheck not configured in verification.commands"
+        TSC_EXIT=0
+    fi
+
+    if [ "$TSC_EXIT" -eq 0 ] && [ -n "$TS_BUILD" ]; then
+        eval "$TS_BUILD" 2>&1 | tail -30
+        BUILD_EXIT=$?
+    elif [ -z "$TS_BUILD" ]; then
+        echo "SKIPPED — typescript.build not configured in verification.commands"
+        BUILD_EXIT=0
+    fi
+
+    git checkout - 2>/dev/null
+
+    if [ "$TSC_EXIT" -ne 0 ]; then
+        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 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): batch checkpoint ==="
+    cd {REPO_PATH}
+    git checkout origin/${MILESTONE_BRANCH} --detach 2>/dev/null
+
+    if [ -n "$PYTHON_FORMAT" ]; then
+        eval "$PYTHON_FORMAT" 2>&1 | tail -10
+        FORMAT_EXIT=$?
+    else
+        echo "SKIPPED — python.format not configured in verification.commands"
+        FORMAT_EXIT=0
+    fi
+
+    git checkout - 2>/dev/null
+
+    if [ "$FORMAT_EXIT" -ne 0 ]; then
+        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 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.
+
+### 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's *fallback* (raw-gist) path.
+    # The Phase 2.5 FORGE:SYNTHESIS_BRIEF preference is intentionally NOT applied here:
+    # sweep findings are freshly-created review-finding issues that never received a
+    # synthesis brief (Phase 2.5 runs only over the original batch's investigations), so
+    # there is nothing to prefer. Keep this block in sync with 4A's fallback branch only.
+    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 on **low-risk domains**, merge anyway and create follow-up issues. For complex findings on **high-risk domains** (AUTH, BILLING, DATABASE, or any domain tagged as security-critical in Step 3B), add the `needs-human` label and stop — do NOT merge. High-risk `needs-human` halts are surfaced as `⚠ Blocked` in the Phase 5 completion report.
+
+**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.
+
+---
+