forgedock 1.1.1 → 1.1.2

package/commands/autopilot.md

@@ -1,6 +1,7 @@
 ---
 description: Autonomous platform improvement cycle — recon, triage, fix, report. Runs recon+triage by default; pass --fix to also pick up and fix top issues. Human gates all deploys.
-argument-hint: [--fix | --recon-only | --fix --limit 5 | --dry-run]
+argument-hint: [--fix | --recon-only | --fix --limit 5 | --dry-run | --fix --yes]
+install: extras
 ---
 
 # /autopilot — Recursive Platform Improvement Cycle
@@ -19,13 +20,18 @@ Resolve `{BILLING_ENABLED}` from `forge.yaml` before executing any phase:
 BILLING_ENABLED=$(yq '.billing.enabled // false' "$(git rev-parse --show-toplevel)/forge.yaml" 2>/dev/null || echo 'false')
 ```
 
+**NEVER use plan mode (EnterPlanMode).**
+**NEVER use the Agent tool** — autopilot dispatches work via `Skill(skill="work-on", ...)` only. The Agent tool bypasses the Skill pipeline's label state machine, investigation comments, and structured review — leaving no audit trail.
+
+<!-- FORGE:SPEC_LOADED — autopilot.md loaded and active. Agent is bound by this spec. -->
+
 You are an autonomous improvement engine for this project. Your job is to **find what's wrong, create trackable issues, and optionally fix the highest-impact ones** — all in a single cycle. Every cycle leaves the platform measurably better than before.
 
 **This is designed to run repeatedly.** Each cycle builds on the last — issues created in cycle N get fixed in cycle N+1. The platform compounds improvements over time.
 
 **NEVER use plan mode (EnterPlanMode)** — it breaks execution context.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`. User can override with `--model <name>`. Pass the resolved model in every `Agent`/`Task` tool call. Each agent prompt is scoped to a specific data source or issue — the model executes the explicit steps without needing broad inference.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. User can override with `--model <name>`. Pass model explicitly in every `Agent`/`Task` tool call. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 
 ---
 
@@ -38,6 +44,7 @@ You are an autonomous improvement engine for this project. Your job is to **find
 | `--fix --limit N` | Fix at most N issues (default: 3) |
 | `--recon-only` | Phase 1 only (data collection, no issue creation) |
 | `--dry-run` | Run everything but don't create issues or PRs — just report what would happen |
+| `--fix --yes` | Auto-approve low-risk fixes (P3, single-file, non-sensitive domain); P0/P1, multi-file, and sensitive-domain fixes still require confirmation |
 
 Parse `$ARGUMENTS` and set these variables:
 ```
@@ -45,6 +52,7 @@ MODE = "full" | "recon-only" | "fix"    # derived from flags
 DO_FIX = true if --fix present
 FIX_LIMIT = N from --limit N, default 3
 DRY_RUN = true if --dry-run present
+AUTO_YES = true if --yes present
 ```
 
 ---
@@ -356,22 +364,47 @@ gh issue list --state open --label "bug" --limit 50 --json number,title,labels,c
 
 **MANDATORY CHECKPOINT — do NOT proceed without user confirmation.**
 
+**Exception**: when `AUTO_YES = true`, classify each fix target by risk tier before prompting. Low-risk fixes are auto-approved; high-risk fixes still require confirmation.
+
+**Risk classification** (evaluate per-issue at this step):
+
+```
+LOW_RISK = all of the following are true:
+  - Priority is P2 or P3 (not P0 or P1)
+  - Affects only a single file (from issue body or recon finding)
+  - No sensitive-domain labels: auth, billing, database, security, payments, gdpr
+
+HIGH_RISK = any of the following:
+  - Priority P0 or P1
+  - Multi-file change (2+ files)
+  - Has a sensitive-domain label (auth, billing, database, security, payments, gdpr)
+  - Issue has `needs-human` label
+```
+
+When `AUTO_YES = true`:
+- **LOW_RISK issues**: auto-approve, log `[AUTO-APPROVED: low-risk]`, proceed to 4B.5/4C without waiting.
+- **HIGH_RISK issues**: present the checkpoint below and wait for user response. If user skips, remove from fix targets and continue with remaining low-risk issues.
+
+When `AUTO_YES = false` (default): present the full checkpoint for ALL fix targets and wait.
+
 ```markdown
 ## Autopilot Fix Plan
 
 I'll run `/work-on` for these {N} issues:
 
-| # | Title | Priority | Estimated Scope |
-|---|-------|----------|-----------------|
-| {number} | {title} | {priority} | {small/medium/large} |
+| # | Title | Priority | Estimated Scope | Risk Tier |
+|---|-------|----------|-----------------|-----------|
+| {number} | {title} | {priority} | {small/medium/large} | LOW / HIGH |
 
 Each issue goes through: investigate → validate → build → review → merge to staging.
 Nothing merges to `main` — you deploy when ready.
 
+{If AUTO_YES and any HIGH_RISK: "Note: {N_low} low-risk issues were auto-approved. The {N_high} high-risk issue(s) above require your confirmation."}
+
 **Proceed?** (yes / adjust / skip)
 ```
 
-Wait for user response. If they adjust, re-select. If they skip, end the cycle.
+Wait for user response on high-risk issues. If they adjust, re-select. If they skip all, end the cycle.
 
 ### 4B.5: Spec-Edit Impact Analysis (MANDATORY before any spec-touching fix) <!-- Added: forge#870 -->
 
@@ -484,6 +517,44 @@ FIX_RESULTS.push({
 When ready to deploy, merge `staging` → `main` via GitHub.
 ```
 
+### 4E: Deploy Train Check <!-- Added: forge#1332 -->
+
+After fixes are merged to staging, check the deploy train state. The deploy train is the single rolling staging→main PR — one per deploy cycle. Do NOT open a new staging→main PR if one is already open.
+
+```bash
+# Check for an open staging→main deploy PR (the current train)
+TRAIN_PR=$(gh pr list {GH_FLAG} \
+  --head "{STAGING_BRANCH}" \
+  --base "{DEFAULT_BRANCH}" \
+  --state open \
+  --json number,url \
+  --jq '.[0] // empty' 2>/dev/null)
+
+TRAIN_PR_NUMBER=$(echo "$TRAIN_PR" | jq -r '.number // empty')
+
+if [ -n "$TRAIN_PR_NUMBER" ]; then
+  # Train exists — check if it is held by open findings
+  HELD_BY_COUNT=$(gh issue list {GH_FLAG} \
+    --label "review-finding" \
+    --state open \
+    --search "PR #${TRAIN_PR_NUMBER}" \
+    --json number --jq '. | length' 2>/dev/null || echo 0)
+
+  if [ "$HELD_BY_COUNT" -gt 0 ]; then
+    echo "Deploy train PR #${TRAIN_PR_NUMBER} is HELD by ${HELD_BY_COUNT} open finding(s)."
+    echo "The fixes merged in this autopilot cycle may resolve some of them."
+    echo "Re-run /review-pr-staging ${TRAIN_PR_NUMBER} to re-evaluate the train gate."
+  else
+    echo "Deploy train PR #${TRAIN_PR_NUMBER} is CLEAR — no open findings. Ready to merge when you authorize."
+  fi
+else
+  echo "No open staging→main PR found. The merged fixes are queued in staging."
+  echo "Run /review-pr-staging to open a new train PR when ready."
+fi
+```
+
+**Deploy policy**: Autopilot NEVER merges staging→main. It merges issue fixes TO staging only. The train PR is a human-gated merge — the user decides when to ship.
+
 ---
 
 ## Safety Rules
@@ -497,7 +568,7 @@ When ready to deploy, merge `staging` → `main` via GitHub.
 7. **If a fix fails, move on** — don't retry. Log it and let the next cycle or human handle it.
 8. **DRY_RUN means NO side effects** — no issues created, no PRs, no label changes. Report only.
 9. **P0 overrides everything** — if P0 exists, skip normal recon and fix P0 immediately.
-10. **Always gate fixes on user approval** — Phase 4B checkpoint is non-negotiable.
+10. **Always gate high-risk fixes on user approval** — Phase 4B checkpoint is non-negotiable for P0/P1, multi-file, or sensitive-domain changes. `--yes` only auto-approves LOW_RISK tier (P2/P3, single-file, non-sensitive).
 
 ---
 
@@ -525,4 +596,5 @@ The platform gets better every cycle. Issues that aren't picked up age and rise
 - **Runtime**: Recon-only ~3-5 min. Full cycle with fixes ~15-45 min depending on issue count.
 - **Token budget**: Recon is cheap (mostly MCP + API calls). Fixes are expensive (full /work-on per issue).
 - **Idempotent**: Safe to run multiple times — dedup prevents duplicate issues, /work-on resumes from checkpoints.
-- **Pairs with /loop**: Run `/loop 4h /autopilot` for continuous improvement, or `/loop 4h /autopilot --fix --limit 2` for autonomous fixing with a human checkpoint every cycle.
+- **Pairs with /loop**: Run `/loop 4h /autopilot` for continuous improvement, `/loop 4h /autopilot --fix --limit 2` for autonomous fixing with a human checkpoint every cycle, or `/loop 4h /autopilot --fix --yes` for fully unattended low-risk fixes (high-risk issues still surface for approval).
+- **Event-driven complement**: `/autopilot` is a periodic cycle. When a specific production signal fires (metric regression, incident, GEO gap), use `/signal-planner` instead — it converts the signal into a dependency-ordered issue DAG, executes via `/orchestrate`, and verifies the originating signal is resolved after the work merges. Use `/autopilot` for scheduled health sweeps; use `/signal-planner` for targeted signal-driven response.

package/commands/changelog.md

@@ -1,6 +1,7 @@
 ---
 description: Auto-generate release notes from merged PRs and FORGE:TRAJECTORY annotations — grouped by conventional commit type
 argument-hint: [v1.0.0..v1.1.0 | since:YYYY-MM-DD | last-N]
+install: extras
 ---
 
 # /changelog — Release Notes Generator
@@ -9,7 +10,7 @@ argument-hint: [v1.0.0..v1.1.0 | since:YYYY-MM-DD | last-N]
 
 Generate a structured markdown changelog from merged PRs and their FORGE:TRAJECTORY annotations. Groups entries by conventional commit type (feat, fix, refactor, docs, chore) and enriches each entry with task type and investigation verdict from the pipeline's annotation layer.
 
-**Agent model policy**: Default `model: "sonnet"`. Fallback: `model: "opus"` if Sonnet is rate-limited.
+**Agent model policy**: `model: "haiku"`, `effort: low` (mechanical tier — annotation reading, changelog generation). Fallback: `model: "sonnet"` if rate-limited. Feature gate: pass `effort` only on Claude Code >= 2.1.154.
 
 **NEVER use plan mode (EnterPlanMode)** — it breaks execution context.
 

package/commands/ci-audit.md

@@ -1,6 +1,7 @@
 ---
 description: Stack-aware CI gap detection — audits a project's GitHub Actions workflows against its declared tech stack and files issues for missing config validation checks
 argument-hint: [--repo <prefix>] [--dry-run]
+install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -29,7 +30,7 @@ This command is designed to be run:
 
 This is NOT a PR review — it does not approve or block. It creates issues for each CI gap found.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
 
 ---

package/commands/cleanup.md

@@ -1,6 +1,7 @@
 ---
 description: Sweep closed issues for stale labels, missing workflow state, and Project board gaps — plus prune worktrees, branches, and milestones
 argument-hint: [labels | branches | milestones | board | orphans | all]
+install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -44,11 +45,12 @@ All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{STAGING_BRANCH}`, `{PROJECT_BOARD
 
 | Input | Action |
 |-------|--------|
-| `labels` or empty | Fix stale/missing workflow labels on closed issues |
+| `labels` or empty | Fix stale/missing workflow labels on closed issues; detect OPEN issues stuck in intermediate states (Phase 1D) |
 | `orphans` | Close open issues whose PRs are already merged |
 | `branches` | Prune worktrees and remote branches for merged PRs |
 | `milestones` | Report milestones with 0 open issues (advisory — never closes) |
 | `board` | Sync closed issues to Project board with correct terminal state |
+| `batch-p3` | Sweep: fold stale unbatched P3 review findings into domain-grouped batch issues |
 | `all` | All of the above, in order |
 
 ---
@@ -105,6 +107,46 @@ gh issue list {GH_FLAG} --state closed --limit 200 --json number,title,labels \
 
 These were closed outside the pipeline. Report count but don't fix (not necessarily wrong).
 
+### 1D: Detect stale OPEN issues in intermediate workflow states
+
+Open issues stuck in `workflow:building`, `workflow:in-review`, or `workflow:investigating` beyond a configurable threshold indicate a stalled agent. These are invisible to Phase 1A–1C (which only query closed issues).
+
+```bash
+# Configurable threshold — override by setting STALE_THRESHOLD_HOURS before invoking /cleanup
+STALE_THRESHOLD_HOURS=${STALE_THRESHOLD_HOURS:-48}
+
+# Compute cutoff datetime — GNU date (Linux) with BSD date (macOS) fallback
+CUTOFF=$(date -d "${STALE_THRESHOLD_HOURS} hours ago" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+  || date -v-${STALE_THRESHOLD_HOURS}H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+  || echo "")
+
+echo "=== Stale-Open Intermediate Issues (threshold: ${STALE_THRESHOLD_HOURS}h) ==="
+
+STALE_OPEN_COUNT=0
+
+for LABEL in "workflow:building" "workflow:in-review" "workflow:investigating"; do
+  ISSUES=$(gh issue list {GH_FLAG} \
+    --state open \
+    --label "$LABEL" \
+    --limit 100 \
+    --json number,title,updatedAt,labels \
+    --jq --arg threshold "$CUTOFF" --arg label "$LABEL" \
+    '[.[] | select($threshold == "" or .updatedAt < $threshold)] |
+     .[] | "#\(.number) — \(.title[:60]) [label: \($label)] [last update: \(.updatedAt[:10])] → resume: /work-on \(.number)"' \
+    2>/dev/null || echo "")
+
+  if [ -n "$ISSUES" ]; then
+    echo "$ISSUES"
+    COUNT=$(echo "$ISSUES" | grep -c '^#' 2>/dev/null || echo 0)
+    STALE_OPEN_COUNT=$((STALE_OPEN_COUNT + COUNT))
+  fi
+done
+
+echo "Total stale-open intermediate issues: $STALE_OPEN_COUNT"
+```
+
+These are **report-only** — no automatic action is taken. Use `/work-on <n>` (idempotent) to resume a stalled issue. Priority issues (P1/P2) should be actioned first.
+
 ---
 
 ## Phase 2: Orphaned Issues (open issues with merged PRs)
@@ -278,6 +320,111 @@ Do NOT call `gh api ... -X PATCH -f state=closed` on any milestone. This phase i
 
 ---
 
+## Phase 4B: P3 Batch Sweep (if `batch-p3` or `all`)
+
+<!-- Added: forge#1333 -->
+
+**Purpose**: Fold stale unbatched P3 review findings into domain-grouped batch issues. Reduces pipeline overhead from individual per-finding full-pipeline runs.
+
+**Skip if**: Input is not `batch-p3` and not `all`.
+
+### Step 4B.1: Fetch open batchable P3 findings
+
+```bash
+# Find all open P3 review findings that carry the FORGE:BATCHABLE annotation
+# and are not already members of a batch (no "batch" label)
+UNBATCHED_P3=$(gh issue list {GH_FLAG} \
+  --state open \
+  --label "review-finding,priority:P3" \
+  --limit 500 \
+  --json number,title,body,labels,createdAt \
+  --jq '.[] | select(.body | test("<!-- FORGE:BATCHABLE -->"))
+         | select(([.labels[].name] | any(. == "batch")) | not)
+         | select(([.labels[].name] | any(. == "security" or . == "billing")) | not)
+         | select((.title | test("security|billing|payment|stripe"; "i")) | not)')
+
+echo "Unbatched batchable P3 findings: $(echo "$UNBATCHED_P3" | jq -s 'length')"
+```
+
+### Step 4B.2: Group by domain
+
+For each finding, extract the domain from the first affected file path under `## Affected Files`:
+
+```bash
+# Domain = top-level directory of the first affected file
+# e.g., "services/api/auth/login.py" → "services/api/auth"
+#        "commands/review-pr.md"     → "commands"
+# Exclude findings where the domain contains "billing" or "security"
+
+# Group findings by domain, track oldest creation timestamp per group
+declare -A DOMAIN_ISSUES
+declare -A DOMAIN_OLDEST
+
+echo "$UNBATCHED_P3" | jq -c '.[]' | while read -r issue; do
+  NUM=$(echo "$issue" | jq -r '.number')
+  CREATED=$(echo "$issue" | jq -r '.createdAt')
+  BODY=$(echo "$issue" | jq -r '.body')
+
+  # Extract first affected file path from body
+  FIRST_FILE=$(echo "$BODY" | sed -n '/^## Affected Files/,/^## /p' | grep -oP '`[^`]+`' | head -1 | tr -d '`')
+  if [ -z "$FIRST_FILE" ]; then
+    FIRST_FILE=$(echo "$BODY" | grep -oP '(?<=\`)[^`]+\.(?:py|ts|tsx|js|go|rs|java|sh|md)(?=\`)' | head -1 || echo "unknown")
+  fi
+  DOMAIN=$(echo "$FIRST_FILE" | cut -d/ -f1,2,3 | sed 's|/[^/]*$||')
+  [ -z "$DOMAIN" ] && DOMAIN="general"
+
+  echo "${NUM}:${DOMAIN}:${CREATED}"
+done
+```
+
+### Step 4B.3: Apply batching threshold
+
+For each domain group:
+- **Trigger**: 5+ unbatched batchable P3 findings in the domain, **OR** the oldest finding in the domain is > 72 hours old
+- **No trigger**: fewer than 5 findings AND none older than 72 hours → skip (no batch created)
+
+```bash
+NOW_EPOCH=$(date +%s)
+HOURS_72=$((72 * 3600))
+
+# For each domain group that meets the threshold, create a batch issue
+# (max 10 members per batch — if more, create multiple batches of ≤ 10 each)
+
+# Exclude domains with "security" or "billing" in the domain path
+echo "$DOMAIN_ISSUES" | while IFS=: read -r domain issue_list; do
+  echo "$domain" | grep -qiE 'security|billing' && continue
+
+  COUNT=$(echo "$issue_list" | tr ',' '\n' | wc -l)
+  OLDEST_EPOCH=$(echo "$DOMAIN_OLDEST[$domain]" | date -d "$..." +%s 2>/dev/null || echo "$NOW_EPOCH")
+  AGE_SECS=$((NOW_EPOCH - OLDEST_EPOCH))
+
+  if [ "$COUNT" -ge 5 ] || [ "$AGE_SECS" -ge "$HOURS_72" ]; then
+    echo "Batching $COUNT P3 findings in domain: ${domain}"
+    # Create batch issues (in chunks of ≤ 10)
+    # See orchestrate.md Phase 1 for the batch creation template
+  fi
+done
+```
+
+**Batch creation** uses the same template as `orchestrate.md Phase 1 → P3 Review-Finding Batching`. After creating the batch issue, add the `batch` label to each member issue to prevent re-batching on the next sweep.
+
+### Step 4B.4: Report
+
+```
+## P3 Batch Sweep
+
+| Domain | Unbatched P3s | Threshold Met | Action |
+|--------|--------------|---------------|--------|
+| {domain} | {N} | ≥5 issues | Created batch #{NUM} ({M} members) |
+| {domain} | {N} | Oldest > 72h | Created batch #{NUM} ({M} members) |
+| {domain} | {N} | Below threshold | No action |
+
+Total batch issues created: {N}
+Total P3 findings batched: {N}
+```
+
+---
+
 ## Phase 5: Sync Project Board (if `board` or `all`)
 
 **Skip if `project_board` is not configured** — check resolved vars before proceeding:
@@ -320,6 +467,13 @@ fi
 | workflow:investigating → cleaned | {N} |
 | needs-validation removed | {N} |
 
+### Stale-Open Intermediate Issues (Phase 1D)
+| Issue | Label | Last Update | Action |
+|-------|-------|-------------|--------|
+| #{N} | workflow:X | YYYY-MM-DD | `/work-on {N}` to resume |
+
+*Total stale-open: {N} (threshold: {STALE_THRESHOLD_HOURS}h)*
+
 ### Orphaned Issues Closed
 | Issue | Merged PR | Action |
 |-------|-----------|--------|
@@ -345,4 +499,10 @@ fi
 
 ### Still Missing Workflow Label
 {N} closed issues have no workflow label (closed outside pipeline — no action needed)
+
+### P3 Batch Sweep Results
+| Domain | Unbatched P3s | Action |
+|--------|--------------|--------|
+| {domain} | {N} | Created batch #{NUM} with {M} members |
+| {domain} | {N} | Below threshold — no action (< 5 findings, none > 72h) |
 ```

package/commands/compat-audit.md

@@ -1,6 +1,7 @@
 ---
 description: On-demand Claude Code compatibility and feature parity report — compares installed version against the breakpoints registry and lists affected ForgeDock features
 argument-hint: [--refresh]
+install: extras
 ---
 
 # /compat-audit — Claude Code Compatibility Report
@@ -9,7 +10,7 @@ argument-hint: [--refresh]
 
 You are the ForgeDock compatibility auditor. Produce a point-in-time advisory report that shows whether the user's installed Claude Code version is current and which ForgeDock features may behave differently on their runtime. This command is **non-blocking** — it never aborts the session. All output is advisory.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
 
 ---

package/commands/deploy-info.md

@@ -1,6 +1,7 @@
 ---
 description: Show what will deploy next — diff staging vs main with issue/PR summary, risk assessment, and deploy checklist
 argument-hint: [staging | milestone/{slug} | compare {branch}]
+install: extras
 ---
 
 # /deploy-info — Pre-Deploy Summary
@@ -15,10 +16,12 @@ argument-hint: [staging | milestone/{slug} | compare {branch}]
 
 You are the pipeline's deploy awareness layer. Before the user merges staging → main (triggering CI/CD deployment), this command shows exactly what's going out: which PRs, which issues, what changed, and what risks exist.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`. User can override with `--model <name>`.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. User can override with `--model <name>`. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 
 **NEVER use plan mode (EnterPlanMode)** — it breaks execution context.
 
+<!-- FORGE:SPEC_LOADED — deploy-info.md loaded and active. Agent is bound by this spec. -->
+
 ---
 
 ## Phase 0: Review-Finding Readiness Check
@@ -278,6 +281,52 @@ gh workflow run {deploy.workflow} --ref main -f {deploy.workflow_inputs.services
 
 ---
 
+## Phase 4B: Deploy Train State <!-- Added: forge#1332 -->
+
+**Purpose**: Report the current state of the rolling staging→main deploy candidate (the "merge train"). One deploy PR should stay open per deploy cycle — this phase shows whether a candidate exists, what is holding it, and what is queued behind it.
+
+```bash
+git fetch origin {STAGING_BRANCH} {DEFAULT_BRANCH} 2>/dev/null
+
+# Step 1: Find the current open staging→main deploy PR (the "train")
+TRAIN_PR=$(gh pr list {GH_FLAG} \
+  --head "{STAGING_BRANCH}" \
+  --base "{DEFAULT_BRANCH}" \
+  --state open \
+  --json number,title,headRefOid,createdAt,reviewRequests \
+  --jq '.[0] // empty' 2>/dev/null)
+
+TRAIN_PR_NUMBER=$(echo "$TRAIN_PR" | jq -r '.number // empty')
+TRAIN_PR_SHA=$(echo "$TRAIN_PR" | jq -r '.headRefOid // empty' | cut -c1-7)
+TRAIN_PR_CREATED=$(echo "$TRAIN_PR" | jq -r '.createdAt // empty')
+
+if [ -z "$TRAIN_PR_NUMBER" ]; then
+  TRAIN_STATUS="NO_TRAIN — no open staging→main PR. Run /review-pr-staging to open one."
+else
+  # Step 2: Check whether the train is held (has blocking findings)
+  HELD_BY=$(gh issue list {GH_FLAG} \
+    --label "review-finding" \
+    --state open \
+    --search "PR #${TRAIN_PR_NUMBER}" \
+    --limit 20 \
+    --json number,title \
+    --jq '[.[] | "#\(.number): \(.title)"] | join("\n")' 2>/dev/null || true)
+
+  if [ -n "$HELD_BY" ]; then
+    TRAIN_STATUS="HELD"
+  else
+    TRAIN_STATUS="CLEAR — ready to merge"
+  fi
+
+  # Step 3: Count commits queued (commits in staging not yet in main)
+  QUEUED_COMMITS=$(git rev-list --count origin/{DEFAULT_BRANCH}..origin/{STAGING_BRANCH} 2>/dev/null || echo "?")
+fi
+```
+
+Train state is included in the Phase 5 output summary.
+
+---
+
 ## Phase 5: Output Summary
 
 ```
@@ -285,6 +334,14 @@ gh workflow run {deploy.workflow} --ref main -f {deploy.workflow_inputs.services
 
 **Commits**: {N} | **PRs**: {N} | **Issues closed**: {N} | **Files changed**: {N}
 
+### Deploy Train State
+**Train PR**: #{TRAIN_PR_NUMBER} (SHA: {TRAIN_PR_SHA}, opened: {TRAIN_PR_CREATED})
+**Status**: {TRAIN_STATUS}
+{If HELD: "**Held by**: {count} open finding(s) — fix and push to unblock:\n{HELD_BY}"}
+{If CLEAR: "**Ready to merge**: no open findings on the train PR"}
+{If NO_TRAIN: "No open staging→main PR — run /review-pr-staging to open one"}
+**Queued commits**: {QUEUED_COMMITS} (commits in staging not yet in main)
+
 ### Services Affected
 | Service | Files Changed | Rebuild Required |
 |---------|---------------|-----------------|

package/commands/design-bench.md

@@ -22,6 +22,10 @@ live there — this command is the executable workflow over that methodology.
 **No application runtime.** ForgeDock is a set of command specs. This command is a step-by-step procedure an
 agent executes; the only executable helper is the deterministic aggregator `scripts/bench-scorecard.mjs`.
 
+**NEVER use plan mode (EnterPlanMode).**
+
+<!-- FORGE:SPEC_LOADED — design-bench.md loaded and active. Agent is bound by this spec. -->
+
 ---
 
 ## The three arms (one variable)
@@ -128,7 +132,7 @@ The aggregator (see `scripts/bench-scorecard.mjs`):
   generated arm is a judge defect, not a harness win — treat those runs as suspect.
 
 Post the result as a `FORGE:BENCH_SCORECARD` annotation (registered in
-[`docs/FORGE-PROTOCOL.md`](../docs/FORGE-PROTOCOL.md)) on the tracking issue:
+[`docs/spec/forge-protocol-v1.md`](../docs/spec/forge-protocol-v1.md)) on the tracking issue:
 
 ```bash
 gh issue comment <ISSUE> --body "<!-- FORGE:BENCH_SCORECARD -->

package/commands/design-render-critique-loop.md

@@ -82,7 +82,7 @@ real reference*. They must never be the same judge. This is also distinct from t
 
 ## `FORGE:CRITIQUE` annotation
 
-Registered in [FORGE-PROTOCOL](../docs/FORGE-PROTOCOL.md). One per iteration, so the improvement trajectory is an
+Registered in [FORGE Annotation Protocol](../docs/spec/forge-protocol-v1.md). One per iteration, so the improvement trajectory is an
 auditable artifact:
 
 ```markdown

package/commands/diagnose.md

@@ -1,6 +1,7 @@
 ---
 description: Trace a failed or stalled pipeline run — identify which FORGE annotation is missing or malformed, diagnose the failure point, and suggest specific remediation steps
 argument-hint: [issue number] [--repo prefix]
+install: extras
 ---
 
 # /diagnose — Pipeline Failure Tracer
@@ -9,7 +10,7 @@ argument-hint: [issue number] [--repo prefix]
 
 **NEVER use plan mode (EnterPlanMode)** — it breaks execution context.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 
 You are the pipeline's diagnostic layer. Given a single GitHub issue number, you reconstruct the full FORGE annotation chain for that pipeline run, identify the exact failure point, and suggest specific remediation steps. This command is **read-only** — it never mutates GitHub state.
 

package/commands/explain.md

@@ -1,6 +1,7 @@
 ---
 description: Plain-English breakdown of what happened on a GitHub issue — translates FORGE pipeline annotations into a human-readable narrative for teammates and PMs
 argument-hint: <issue number or PR#N> [--repo prefix]
+install: extras
 ---
 
 # /explain — FORGE Annotation Translator
@@ -9,7 +10,7 @@ argument-hint: <issue number or PR#N> [--repo prefix]
 
 You translate the FORGE pipeline's machine-readable annotations on a GitHub issue or PR into a clear, plain-English narrative that anyone can understand — no pipeline knowledge required. This is a read-only command: it never writes to GitHub, never changes labels, and never modifies any state.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
 
 ---