forgedock 1.0.16 → 1.0.18

package/commands/optimize.md

@@ -0,0 +1,411 @@
+---
+description: Analyze this repo and generate per-repo adaptive scripts from learned patterns, git history, and existing configuration
+argument-hint: [--dry-run | --force | --no-registry]
+---
+
+# /optimize — Per-Repo Adaptive Script Generation
+
+**Input**: $ARGUMENTS
+
+Proactively analyze the current repository and generate `.forgedock/scripts/` entries from `forge.yaml → learned:`, git commit history, and pipeline annotations — without waiting for a correction event. This is the proactive half of the learning loop; reactive capture happens in `/work-on` Phase 1D.
+
+**Agent model policy**: Default `model: "sonnet"`. Fallback: `model: "opus"` if Sonnet is rate-limited.
+**NEVER use plan mode (EnterPlanMode).**
+
+---
+
+## Argument Parsing
+
+| Flag | Effect |
+|------|--------|
+| (none) | Full run: analyze → generate → registry → report |
+| `--dry-run` | Analyze and report what would be generated; write nothing to disk |
+| `--force` | Overwrite scripts even if confidence < 0.7 |
+| `--no-registry` | Skip `registry.json` update |
+
+Parse `$ARGUMENTS` and set:
+```
+DRY_RUN   = true if --dry-run present, else false
+FORCE     = true if --force present, else false
+NO_REG    = true if --no-registry present, else false
+```
+
+---
+
+## Prerequisites
+
+### P1: Read forge.yaml
+
+```bash
+REPO_PATH=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+FORGE_YAML="$REPO_PATH/forge.yaml"
+GH_REPO=$(yq '.project.owner + "/" + .project.repo' "$FORGE_YAML" 2>/dev/null)
+SCRIPTS_DIR="$REPO_PATH/.forgedock/scripts"
+ADAPTIVE_ENABLED=$(yq '.adaptive_scripts.enabled // true' "$FORGE_YAML" 2>/dev/null || echo "true")
+ADAPTIVE_COMMIT=$(yq '.adaptive_scripts.commit // false' "$FORGE_YAML" 2>/dev/null || echo "false")
+```
+
+If `$FORGE_YAML` is missing:
+```
+STOP: forge.yaml not found. Run `npx forgedock init` to generate it, then re-run /optimize.
+```
+
+If `ADAPTIVE_ENABLED` is `false`:
+```
+STOP: adaptive_scripts.enabled is false in forge.yaml. Set it to true to use /optimize.
+```
+
+### P2: Ensure scripts directory exists
+
+```bash
+mkdir -p "$SCRIPTS_DIR"
+```
+
+If `.forgedock/scripts/` is not gitignored, note in the report (non-blocking).
+
+---
+
+## Phase 1: Pattern Analysis
+
+Read all available signal sources. Build a `PATTERNS` map — keyed by script name, value is `{evidence, confidence, value}`.
+
+**Confidence scale**:
+- `1.0` — explicit value in `forge.yaml → learned:` (authoritative)
+- `0.85` — value confirmed by 3+ independent signals (git history, FORGE:LEARNED annotations)
+- `0.7` — value confirmed by 2 independent signals
+- `0.5` — single signal (heuristic only)
+- `<0.5` — insufficient evidence; skip unless `--force`
+
+### 1A: Read forge.yaml → learned: section
+
+```bash
+LEARNED=$(yq '.learned // {}' "$FORGE_YAML" 2>/dev/null || echo '{}')
+echo "Learned section: $LEARNED"
+```
+
+Extract each known key:
+```bash
+LEARNED_STAGING=$(yq '.learned.branch_targets.staging // ""' "$FORGE_YAML" 2>/dev/null)
+LEARNED_TEST_CMDS=$(yq '.learned.test_commands // []' "$FORGE_YAML" -o json 2>/dev/null)
+LEARNED_TEST_LOCS=$(yq '.learned.test_locations // []' "$FORGE_YAML" -o json 2>/dev/null)
+LEARNED_LABEL_MAP=$(yq '.learned.label_map // {}' "$FORGE_YAML" -o json 2>/dev/null)
+LEARNED_COMMIT_STYLE=$(yq '.learned.commit_style // ""' "$FORGE_YAML" 2>/dev/null)
+```
+
+For each non-empty learned key, add to PATTERNS with confidence `1.0`:
+
+| Non-empty key | Script to generate |
+|---------------|--------------------|
+| `branch_targets.staging` | `branch-targets.sh` |
+| `test_commands` (non-empty array) | `run-tests.sh` |
+| `test_locations` (non-empty array) | `find-tests.sh` |
+| `label_map` (non-empty object) | `label-map.sh` |
+| `commit_style` | `format-commit.sh` |
+
+### 1B: Analyze git commit history
+
+```bash
+cd "$REPO_PATH"
+
+# Sample last 50 commits for style analysis
+COMMIT_SUBJECTS=$(git log --oneline -50 --format="%s" 2>/dev/null | head -50)
+echo "$COMMIT_SUBJECTS"
+```
+
+**Detect commit style**:
+```bash
+CONV_COUNT=$(echo "$COMMIT_SUBJECTS" | grep -cE '^(feat|fix|docs|chore|refactor|test|style|ci|build|perf)\(' 2>/dev/null || echo 0)
+CONV_SIMPLE=$(echo "$COMMIT_SUBJECTS" | grep -cE '^(feat|fix|docs|chore|refactor|test|style|ci|build|perf):' 2>/dev/null || echo 0)
+TOTAL=$(echo "$COMMIT_SUBJECTS" | wc -l | tr -d ' ')
+
+CONV_WITH_SCOPE_PCT=$(( (CONV_COUNT * 100) / (TOTAL + 1) ))
+CONV_SIMPLE_PCT=$(( (CONV_SIMPLE * 100) / (TOTAL + 1) ))
+```
+
+Determine `DETECTED_COMMIT_STYLE`:
+- If `CONV_WITH_SCOPE_PCT >= 60` → `"conventional-with-scope"`, confidence `0.85`
+- If `CONV_SIMPLE_PCT >= 60` → `"conventional"`, confidence `0.85`
+- If `(CONV_COUNT + CONV_SIMPLE) < 20%` → `"plain"`, confidence `0.7`
+- Otherwise → insufficient signal, skip `format-commit.sh` unless already in `learned:`
+
+**If `LEARNED_COMMIT_STYLE` is non-empty**: use it (confidence `1.0`), skip git analysis for this signal.
+
+**Detect test locations** (if `LEARNED_TEST_LOCS` is empty):
+```bash
+# Look for test directories with actual test files
+TEST_DIRS=""
+for candidate in tests/ __tests__/ test/ spec/ src/__tests__/; do
+  COUNT=$(git ls-files "$candidate" 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$COUNT" -gt "0" ]; then
+    TEST_DIRS="$TEST_DIRS $candidate"
+  fi
+done
+TEST_DIRS=$(echo "$TEST_DIRS" | xargs)  # trim
+```
+
+If `TEST_DIRS` is non-empty and differs from the default (`tests/`): add to PATTERNS for `find-tests.sh` with confidence `0.7`.
+
+### 1C: Mine FORGE:LEARNED annotations from closed issues
+
+```bash
+# Read closed issues for repeated FORGE:LEARNED annotations (last 30 closed issues)
+FORGE_LEARNED_BODIES=$(gh api "repos/$GH_REPO/issues?state=closed&per_page=30" \
+  --jq '[.[] | .number]' 2>/dev/null | jq -r '.[]' 2>/dev/null | \
+  while read -r n; do
+    gh api "repos/$GH_REPO/issues/$n/comments" \
+      --jq '.[] | select(.body | contains("FORGE:LEARNED")) | .body' 2>/dev/null
+  done | head -200)
+echo "$FORGE_LEARNED_BODIES" | head -50
+```
+
+**Extract corroborating signals from annotations**:
+- Count occurrences of each staging branch override, test command, label remap, commit style across annotations
+- Each repeated annotation (≥2 occurrences) raises confidence by `+0.15` for the matching pattern
+- Cap confidence at `1.0`
+
+**Practical limit**: Process at most 30 issues. If `gh` rate-limits, skip 1C and note in report.
+
+---
+
+## Phase 2: Script Generation
+
+For each pattern in PATTERNS with `confidence >= 0.7` (or all if `--force`):
+
+**Overwrite mode**: if a script already exists, read it first, then overwrite — never append. Log "updated" vs "created" in the report.
+
+### 2A: branch-targets.sh
+
+Trigger: `branch_targets.staging` set in `learned:` (confidence `1.0`), OR git history shows consistent use of a non-default staging branch.
+
+```bash
+cat > "$SCRIPTS_DIR/branch-targets.sh" << 'SCRIPT_EOF'
+#!/usr/bin/env bash
+# Auto-generated by /optimize — branch target overrides for this repo.
+# Source: forge.yaml → learned.branch_targets
+# Edit manually if your branch structure changes.
+
+# STAGING_BRANCH: override the default staging branch for fast-lane PRs
+echo "STAGING_BRANCH={LEARNED_STAGING_VALUE}"
+SCRIPT_EOF
+chmod +x "$SCRIPTS_DIR/branch-targets.sh"
+```
+
+Replace `{LEARNED_STAGING_VALUE}` with the actual value from `learned.branch_targets.staging`.
+
+### 2B: run-tests.sh
+
+Trigger: `test_commands` array non-empty in `learned:` (confidence `1.0`), OR FORGE:LEARNED annotations contain repeated test command corrections.
+
+```bash
+cat > "$SCRIPTS_DIR/run-tests.sh" << 'SCRIPT_EOF'
+#!/usr/bin/env bash
+# Auto-generated by /optimize — test command sequence for this repo.
+# Source: forge.yaml → learned.test_commands
+# Edit manually if your test setup changes.
+
+set -e
+
+{LEARNED_TEST_COMMANDS_EXPANDED}
+SCRIPT_EOF
+chmod +x "$SCRIPTS_DIR/run-tests.sh"
+```
+
+Expand `{LEARNED_TEST_COMMANDS_EXPANDED}` to one command per line, in array order.
+
+### 2C: find-tests.sh
+
+Trigger: `test_locations` array non-empty in `learned:` (confidence `1.0`), OR git ls-files shows non-default test directories (confidence `0.7`).
+
+```bash
+cat > "$SCRIPTS_DIR/find-tests.sh" << 'SCRIPT_EOF'
+#!/usr/bin/env bash
+# Auto-generated by /optimize — test file discovery for this repo.
+# Source: forge.yaml → learned.test_locations
+# Returns a list of test files matching this repo's actual test directory layout.
+
+set -e
+
+{FIND_COMMANDS_EXPANDED}
+SCRIPT_EOF
+chmod +x "$SCRIPTS_DIR/find-tests.sh"
+```
+
+Expand `{FIND_COMMANDS_EXPANDED}` to `find {dir} -name "*.test.*" -o -name "*.spec.*" 2>/dev/null` for each location, plus glob patterns if specified. Patterns ending in `*` are expanded with `git ls-files`.
+
+### 2D: label-map.sh
+
+Trigger: `label_map` non-empty in `learned:` (confidence `1.0`).
+
+```bash
+cat > "$SCRIPTS_DIR/label-map.sh" << 'SCRIPT_EOF'
+#!/usr/bin/env bash
+# Auto-generated by /optimize — label name remapping for this repo.
+# Source: forge.yaml → learned.label_map
+# Usage: source this file, then use map_label() to resolve canonical → repo label.
+
+# Associative array: canonical ForgeDock label → repo-specific label
+declare -A LABEL_MAP=(
+{LABEL_MAP_ENTRIES}
+)
+
+map_label() {
+  local canonical="$1"
+  echo "${LABEL_MAP[$canonical]:-$canonical}"
+}
+SCRIPT_EOF
+chmod +x "$SCRIPTS_DIR/label-map.sh"
+```
+
+Expand `{LABEL_MAP_ENTRIES}` to `["canonical"]="repo-specific"` pairs.
+
+### 2E: format-commit.sh
+
+Trigger: `commit_style` set in `learned:` (confidence `1.0`), OR git history analysis produces `confidence >= 0.7`.
+
+```bash
+cat > "$SCRIPTS_DIR/format-commit.sh" << 'SCRIPT_EOF'
+#!/usr/bin/env bash
+# Auto-generated by /optimize — commit message style enforcer for this repo.
+# Source: forge.yaml → learned.commit_style (or git history analysis)
+# Usage: ./format-commit.sh "type" "scope" "description" "issue_number"
+#   type: conventional prefix (feat, fix, refactor, docs, chore, etc.)
+#   scope: component or area being changed (e.g. auth, pipeline, commands)
+#   description: short imperative summary of the change
+#   issue_number: GitHub issue number (without #)
+#   Outputs: the correctly-formatted commit message for this repo.
+
+set -e
+
+STYLE="{COMMIT_STYLE}"
+TYPE="${1:-}"
+SCOPE="${2:-}"
+DESCRIPTION="${3:-}"
+ISSUE="${4:-}"
+
+case "$STYLE" in
+  conventional-with-scope)
+    if [ -n "$SCOPE" ]; then
+      echo "${TYPE}(${SCOPE}): ${DESCRIPTION} (#${ISSUE})"
+    else
+      echo "${TYPE:-chore}: ${DESCRIPTION} (#${ISSUE})"
+    fi
+    ;;
+  conventional)
+    echo "${TYPE:-chore}: ${DESCRIPTION} (#${ISSUE})"
+    ;;
+  plain)
+    echo "${DESCRIPTION} (#${ISSUE})"
+    ;;
+  *)
+    echo "${DESCRIPTION}"
+    ;;
+esac
+SCRIPT_EOF
+chmod +x "$SCRIPTS_DIR/format-commit.sh"
+```
+
+Replace `{COMMIT_STYLE}` with the detected or learned value.
+
+---
+
+## Phase 3: Registry Update
+
+Skip if `--no-registry`.
+
+Write (overwrite) `.forgedock/scripts/registry.json`:
+
+```bash
+GENERATED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+cat > "$SCRIPTS_DIR/registry.json" << JSON_EOF
+{
+  "schema_version": 1,
+  "generated_at": "${GENERATED_AT}",
+  "generated_by": "/optimize",
+  "scripts": {
+{REGISTRY_ENTRIES}
+  }
+}
+JSON_EOF
+```
+
+Build `{REGISTRY_ENTRIES}` from the PATTERNS map. For each generated script:
+```json
+    "branch-targets": {
+      "path": "branch-targets.sh",
+      "confidence": 1.0,
+      "evidence": "forge.yaml → learned.branch_targets.staging",
+      "generated_at": "2026-03-15T10:30:00Z"
+    }
+```
+
+Comma-separate all entries. If `--dry-run`: print the registry JSON to stdout instead of writing it.
+
+---
+
+## Phase 4: Report
+
+Output a human-readable summary. Do NOT commit anything — `adaptive_scripts.commit` is respected:
+
+```bash
+echo ""
+echo "=== /optimize Report ==="
+echo "Run at: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+echo "Repo: $GH_REPO"
+echo "Scripts dir: $SCRIPTS_DIR"
+if [ "$DRY_RUN" = "true" ]; then
+  echo "Mode: DRY RUN — no files written"
+fi
+echo ""
+echo "--- Patterns detected ---"
+```
+
+For each pattern in PATTERNS (sorted by confidence descending):
+```
+  {script_name}.sh   confidence={confidence}   source={evidence}   action={created|updated|skipped|would-create}
+```
+
+For patterns with `confidence < 0.7` that were skipped:
+```
+  {script_name}.sh   SKIPPED (confidence={confidence} < 0.7 — run with --force to generate)
+```
+
+Then:
+```
+--- Summary ---
+  Scripts created:  N
+  Scripts updated:  N
+  Scripts skipped:  N
+  Registry:         {written|skipped}
+  Commit:           NOT done (adaptive_scripts.commit=false — review scripts before committing)
+
+--- Next steps ---
+  1. Review generated scripts in .forgedock/scripts/
+  2. Run each script manually to verify output
+  3. If correct: git add .forgedock/scripts/ && git commit -m "feat(scripts): adaptive scripts from /optimize"
+  4. If not: edit scripts directly or update forge.yaml → learned: and re-run /optimize
+```
+
+If no patterns were detected at all:
+```
+No patterns detected with sufficient confidence.
+
+Possible reasons:
+  - forge.yaml → learned: is empty (no corrections captured yet)
+  - Git history is too short (< 10 commits) to detect commit style
+  - Test directories match the default (tests/) — no override needed
+
+Run /work-on on a few issues to let the pipeline capture corrections, then re-run /optimize.
+```
+
+---
+
+## Idempotency Guarantee
+
+Running `/optimize` twice produces the same output. Specifically:
+- Scripts are always overwritten, never appended to
+- `registry.json` is always overwritten with current analysis results
+- Generated timestamps in scripts and registry will update on each run (this is expected)
+- Content of scripts changes only if the underlying patterns change
+
+To verify: run `/optimize` twice and compare outputs — the only differences should be the `generated_at` timestamps.

package/commands/orchestrate.md

@@ -2,6 +2,8 @@
 description: Orchestrate parallel work on multiple issues or an entire milestone — spawns sub-agents that each run the full /work-on pipeline
 argument-hint: [milestone <slug> | #1 #2 #3 | next <N> | fast-lane | priority:P0]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # /orchestrate — Multi-Issue Parallel Orchestrator
 
@@ -550,6 +552,103 @@ If `UNEXPECTED_GROWTH > 500`, report the alert clearly before launching the next
 
 ---
 
+### Step 4A.pre.0: Pre-create milestone branches for the wave (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.
+
+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.
+
+**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).
+
+**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 -->
+
+```bash
+# Pre-create the origin milestone branch for every distinct milestone referenced by the wave.
+# 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
+declare -A SEEN_MILESTONE_SLUG
+for NUM in {wave_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 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.
+
+### Step 4A.pre: Classify lane for each issue (MANDATORY before spawning 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.
+
+```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
+
+for NUM in {wave_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: Launch a wave
 
 **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.**
@@ -694,6 +793,90 @@ You will be automatically notified when each background agent completes. **Do NO
 - 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
 
+### 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 wave..." 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 wave**:
+```bash
+for NUM in {active_wave_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_ID}", 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
 
 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.
@@ -814,6 +997,62 @@ They remain open in GitHub — they will be picked up by future `/orchestrate` o
 
 **If no review-finding issues were spawned:** Continue to next wave normally.
 
+### Step 4C.5: Milestone lane-consistency check (run after each wave) <!-- 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.
+
+```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 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.
+
 ### Step 4D: Milestone integration build gate (MANDATORY between waves)
 
 **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.