forgedock 1.0.16 → 1.0.17

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,38 @@ If `UNEXPECTED_GROWTH > 500`, report the alert clearly before launching the next
 
 ---
 
+### 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 +728,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.

package/commands/pipeline-health.md

@@ -2,6 +2,8 @@
 description: Self-analysis — measures pipeline performance, correlates with prompt changes, proposes improvements
 argument-hint: [project repo slug or "all"]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # /pipeline-health — Forge Self-Analysis
 
@@ -541,6 +543,57 @@ fi
 
 **Why this matters**: Outcome metrics (findings per PR, fix-up rate) measure what the pipeline produces. Orchestration efficiency measures how much wasted motion occurs getting there. An agent that takes 40 minutes to do 8 minutes of actual work has 80% idle time — all of which is pipeline overhead. Reducing stall time directly improves throughput without changing code quality. This is the only metric that reveals whether the routing loop in `work-on.md` is functioning or causing agents to stop and wait.
 
+**Step 4 — Batch stall rate (from FORGE:STALL_DETECTED annotations)**:
+
+Query issues that received a `<!-- FORGE:STALL_DETECTED -->` comment within the analysis window. This measures how often the orchestrator's time-based stall detector fired — distinct from the resume-cycle count (which comes from completion-event stalls).
+
+```bash
+# Denominator: issues that entered the pipeline in the window (have any workflow:* label)
+# Using pipeline-active issues avoids inflating the denominator with all 500 issues in window
+BATCH_TOTAL=$(gh issue list -R $GH_REPO \
+  --state all --limit 500 \
+  --json number,createdAt,labels \
+  --jq "[.[] | select(.createdAt > \"$SINCE\") | select(.labels | map(.name) | any(startswith(\"workflow:\")))] | length" \
+  2>/dev/null || echo 0)
+
+# Enumerate pipeline-active issue numbers for per-issue comment queries
+PIPELINE_ISSUE_NUMS=$(gh issue list -R $GH_REPO \
+  --state all --limit 500 \
+  --json number,createdAt,labels \
+  --jq "[.[] | select(.createdAt > \"$SINCE\") | select(.labels | map(.name) | any(startswith(\"workflow:\"))) | .number]" \
+  2>/dev/null || echo "[]")
+
+# Count issues with at least one FORGE:STALL_DETECTED comment
+# Use wc -l pattern (not variable accumulation) to avoid bash subshell scope loss
+STALL_COUNT=$(echo "$PIPELINE_ISSUE_NUMS" | jq -r '.[]' | while read -r NUM; do
+  STALL_COMMENTS=$(gh api repos/$GH_REPO/issues/${NUM}/comments \
+    --jq '[.[] | select(.body | contains("FORGE:STALL_DETECTED"))] | length' 2>/dev/null || echo 0)
+  [ "$STALL_COMMENTS" -gt 0 ] && echo "$NUM"
+done | wc -l)
+
+# Count issues that escalated (2+ stall comments = auto-resume exhausted)
+ESCALATED_COUNT=$(echo "$PIPELINE_ISSUE_NUMS" | jq -r '.[]' | while read -r NUM; do
+  STALL_COMMENTS=$(gh api repos/$GH_REPO/issues/${NUM}/comments \
+    --jq '[.[] | select(.body | contains("FORGE:STALL_DETECTED"))] | length' 2>/dev/null || echo 0)
+  [ "$STALL_COMMENTS" -ge 2 ] && echo "$NUM"
+done | wc -l)
+
+# Compute batch stall rate
+if [ "$BATCH_TOTAL" -gt 0 ]; then
+  BATCH_STALL_RATE=$(echo "scale=1; $STALL_COUNT * 100 / $BATCH_TOTAL" | bc 2>/dev/null || echo "N/A")
+  echo "Batch stall rate: ${BATCH_STALL_RATE}% (${STALL_COUNT}/${BATCH_TOTAL} pipeline issues stalled) — target: < 10%"
+  echo "Escalated to needs-human: ${ESCALATED_COUNT} issues"
+else
+  BATCH_STALL_RATE="N/A"
+  echo "Batch stall rate: N/A (no pipeline issues in window or FORGE:STALL_DETECTED not yet deployed)"
+fi
+export BATCH_STALL_RATE STALL_COUNT BATCH_TOTAL ESCALATED_COUNT
+```
+
+**Target**: `BATCH_STALL_RATE` < 10% (stalled issues / total issues in window). A rate above 10% indicates systemic pipeline unreliability — agents stopping without reaching terminal state frequently enough to require orchestrator intervention.
+
+**Note**: `BATCH_STALL_RATE` requires `FORGE:STALL_DETECTED` comments, which are written by the stall detector in `/orchestrate` Step 4B.5. If the stall detector is not deployed, this metric returns N/A and falls back to the resume-cycle proxy from Step 3.
+
 ### 2L: Post-deploy failure metrics (pipeline escape signal)
 
 `/audit` creates `audit-finding` labeled issues in the Forge repo whenever a defect escapes the pipeline and reaches staging or production. Each finding is tagged with a `**Failure point**:` field indicating which pipeline phase failed (INVESTIGATION, IMPLEMENTATION, REVIEW, REVIEW_FALSE_NEG, DEPLOY_GATE, etc.). Aggregating these reveals the post-deploy defect rate and review escape rate — signals invisible to the pre-merge metrics above.
@@ -2100,6 +2153,8 @@ gh issue create -R $FORGE_REPO \
 | — Avg agent idle% | ?% | < 30% | ✅/⚠️/❌ |
 | — Avg resume cycles per agent | ? | < 1 | ✅/⚠️/❌ |
 | — Clean agent rate | ?% | > 60% | ✅/⚠️/❌ |
+| — Batch stall rate | ?% (?/? issues) | < 10% | ✅/⚠️/❌ |
+| — Escalated to needs-human | ? issues | 0 | ✅/⚠️/❌ |
 | Original work ratio | ?% | > 70% | ✅/⚠️/❌ |
 | Milestone merge success | ?% | 80%+ | ✅/⚠️/❌ |
 | Issue close velocity | ? days | < 2 days | ✅/⚠️/❌ |
@@ -2123,13 +2178,15 @@ _If no trajectory data available in window: "No FORGE:TRAJECTORY comments found
 
 ## Orchestration Efficiency
 
-_From Phase 2K — persisted FORGE:AUDIT-AGENTS summaries ([N] sessions, [M] agents total)_
+_From Phase 2K — persisted FORGE:AUDIT-AGENTS summaries ([N] sessions, [M] agents total) + FORGE:STALL_DETECTED annotations_
 
 | Metric | Value | Target | Status |
 |--------|-------|--------|--------|
 | Avg agent idle% | ?% | < 30% | ✅/⚠️/❌ |
 | Avg resume cycles per agent | ? | < 1 | ✅/⚠️/❌ |
 | Clean agent rate | ?% | > 60% | ✅/⚠️/❌ |
+| Batch stall rate | ?% (?/? issues) | < 10% | ✅/⚠️/❌ |
+| Escalated to needs-human | ? issues | 0 | ✅/⚠️/❌ |
 
 **Top stall boundaries** (phase transitions causing the most stalls):
 | Boundary | Occurrences |
@@ -2140,6 +2197,8 @@ _From Phase 2K — persisted FORGE:AUDIT-AGENTS summaries ([N] sessions, [M] age
 
 _If no FORGE:AUDIT-AGENTS data available: "No persisted audit-agents summaries found in window. Run \`audit-agents --persist\` after orchestration runs to enable this metric. Proxy: [N] issues had resume/stall anomalies in trajectory data."_
 
+_Batch stall rate: sourced from \`FORGE:STALL_DETECTED\` comments (requires \`/orchestrate\` Step 4B.5 to be active). N/A if stall detector is not deployed._
+
 ## Transcript Flow Metrics
 
 _From Phase 2N — JSONL transcript analytics ([N] pipeline sessions, [M] subagent sessions in window)_

package/commands/qa-sweep.md

@@ -2,6 +2,8 @@
 description: Full platform QA sweep — auto-discovers every page, tests every UI element via browser automation, creates GitHub issues for all findings
 argument-hint: [all | dashboard | marketing | page <route> | journey | visual | functional | a11y]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # /qa-sweep — Platform-Wide QA Testing