forgedock 1.0.6 → 1.0.8

package/commands/review-pr-staging.md

@@ -14,12 +14,28 @@ Performs comprehensive review of `staging` before merging to `main`. Handles lar
 
 ---
 
+## Config Resolution
+
+Read `forge.yaml` to resolve branch names before running any commands:
+
+```bash
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
+GH_REPO=$(yq '.project.owner + "/" + .project.repo' "$CONFIG_FILE")
+GH_FLAG="-R $GH_REPO"
+DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE")
+STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
+```
+
+All `$DEFAULT_BRANCH` and `$STAGING_BRANCH` references below are populated from `forge.yaml`.
+
+---
+
 ## Evidence-Based Review Protocol (ALL Agents)
 
 ### Diff-First Approach
 ```bash
-git fetch origin main staging
-git diff origin/main...origin/staging
+git fetch origin $DEFAULT_BRANCH $STAGING_BRANCH
+git diff origin/$DEFAULT_BRANCH...origin/$STAGING_BRANCH
 ```
 
 ### Dynamic Exploration
@@ -29,9 +45,9 @@ From each changed file, follow imports and function calls. Trace data flows acro
 
 | Confidence | Criteria | Action |
 |------------|----------|--------|
-| CONFIRMED | Traced full code path, found specific proof | Report as P1 |
-| LIKELY | Pattern suggests issue, mitigations might exist | Report as P2 |
-| POSSIBLE | Suspicious but couldn't trace fully | Report as P3 |
+| CONFIRMED | Traced full code path, found specific proof | Report as priority:P1 |
+| LIKELY | Pattern suggests issue, mitigations might exist | Report as priority:P2 |
+| POSSIBLE | Suspicious but couldn't trace fully | Report as priority:P3 |
 | UNFOUNDED | Found correct handling | Do NOT report |
 
 ### Severity Decision Tree
@@ -77,17 +93,17 @@ Include ALL findings (CONFIRMED, LIKELY, POSSIBLE). One line per finding, sequen
 **Why this matters**: Review findings are filed before the originating PR merges to staging. Without this gate, a staging→main bundle can include commits with known unfixed bugs — the review system caught the issue, but the deploy path ignored it. This gate closes the gap between issue discovery and deploy execution. <!-- Added: forge#303 -->
 
 ```bash
-git fetch origin main staging
+git fetch origin $DEFAULT_BRANCH $STAGING_BRANCH
 
 # Step 1: Find all PR numbers in the staging→main bundle
 # These are the PRs whose commits are included in staging but not yet in main
-BUNDLE_PRS=$(git log origin/main..origin/staging --oneline \
+BUNDLE_PRS=$(git log origin/$DEFAULT_BRANCH..origin/$STAGING_BRANCH --oneline \
   | grep -oP '#\d+' \
   | sort -u \
   | tr -d '#')
 
 # Also extract PR numbers from merge commit subjects (most reliable)
-MERGE_PRS=$(git log origin/main..origin/staging --merges --oneline \
+MERGE_PRS=$(git log origin/$DEFAULT_BRANCH..origin/$STAGING_BRANCH --merges --oneline \
   | grep -oP '(?<=pull request #)\d+' \
   | sort -u)
 
@@ -178,10 +194,10 @@ If the gate exits with `RESULT: BLOCK DEPLOY` → **STOP**. Do NOT proceed to Ph
 ## Phase 0B: Scope Analysis
 
 ```bash
-git fetch origin main staging
-git diff origin/main...origin/staging --stat | tail -20
-git diff origin/main...origin/staging --numstat | awk '{add+=$1; del+=$2} END {print "Added:", add, "Deleted:", del, "Total:", add+del}'
-git diff origin/main...origin/staging --name-only | sort | uniq
+git fetch origin $DEFAULT_BRANCH $STAGING_BRANCH
+git diff origin/$DEFAULT_BRANCH...origin/$STAGING_BRANCH --stat | tail -20
+git diff origin/$DEFAULT_BRANCH...origin/$STAGING_BRANCH --numstat | awk '{add+=$1; del+=$2} END {print "Added:", add, "Deleted:", del, "Total:", add+del}'
+git diff origin/$DEFAULT_BRANCH...origin/$STAGING_BRANCH --name-only | sort | uniq
 ```
 
 Categorize by service (API, Worker, Web, Shared, Infra). Identify high-risk files (billing, credits, pricing, auth, security, migration, scraper).
@@ -193,26 +209,70 @@ Create review chunks by priority: Billing/Pricing (CRITICAL) → Security/Auth (
 ## Phase 1: Automated Checks
 
 ### 1A: Python Linting
+
+Read `forge.yaml → verification.commands.python` for project-specific tool commands:
+
 ```bash
-cd services/api && poetry run black --check app/ && poetry run isort --check app/
-cd services/worker && poetry run black --check worker/ && poetry run isort --check worker/
+PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
+PYTHON_LINT=$(yq '.verification.commands.python.lint // ""' forge.yaml 2>/dev/null || echo '')
+
+if [ -n "$PYTHON_FORMAT" ]; then
+    eval "$PYTHON_FORMAT" 2>&1 | head -30
+else
+    echo "SKIPPED — python.format not configured in verification.commands"
+fi
+
+if [ -n "$PYTHON_LINT" ]; then
+    eval "$PYTHON_LINT" 2>&1 | head -30
+else
+    echo "SKIPPED — python.lint not configured in verification.commands"
+fi
 ```
 
 ### 1B: TypeScript Type-Check + Build (MANDATORY)
+
+Read `forge.yaml → verification.commands.typescript` for project-specific tool commands:
+
 ```bash
-cd web && npx tsc --noEmit 2>&1
-cd web && npx next build 2>&1 | tail -50
+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 '')
+
+if [ -n "$TS_TYPECHECK" ]; then
+    eval "$TS_TYPECHECK" 2>&1
+    TS_EXIT=$?
+    [ "$TS_EXIT" -ne 0 ] && echo "BLOCKING: typecheck failed — deploy WILL fail"
+else
+    echo "SKIPPED — typescript.typecheck not configured in verification.commands"
+    TS_EXIT=0
+fi
+
+if [ -n "$TS_BUILD" ]; then
+    eval "$TS_BUILD" 2>&1 | tail -50
+    BUILD_EXIT=$?
+    [ "$BUILD_EXIT" -ne 0 ] && echo "BLOCKING: build failed — deploy WILL fail"
+else
+    echo "SKIPPED — typescript.build not configured in verification.commands"
+fi
 ```
-`next build` failure is BLOCKING — deploy WILL fail. `tsc` alone misses SSG prerender failures.
+Build failure is BLOCKING — deploy WILL fail. Typecheck alone misses SSG/prerender failures — configure `typescript.build` in `verification.commands`.
 
 ### 1C: Python Tests
+
+Read `forge.yaml → verification.commands.python.test`:
+
 ```bash
-cd services/api && poetry run pytest tests/ -x -q --tb=short 2>&1 | tail -50
+PYTHON_TEST=$(yq '.verification.commands.python.test // ""' forge.yaml 2>/dev/null || echo '')
+
+if [ -n "$PYTHON_TEST" ]; then
+    eval "$PYTHON_TEST" 2>&1 | tail -50
+else
+    echo "SKIPPED — python.test not configured in verification.commands"
+fi
 ```
 
 ### 1D: Secrets Scan
 ```bash
-git diff origin/main...origin/staging | grep -iE "(api[_-]?key|secret|password|token|credential)" | grep -vE "(#|//|\.example|placeholder)" | head -20
+git diff origin/$DEFAULT_BRANCH...origin/$STAGING_BRANCH | grep -iE "(api[_-]?key|secret|password|token|credential)" | grep -vE "(#|//|\.example|placeholder)" | head -20
 ```
 
 ### 1E: CI Status Gate (BLOCKING)
@@ -304,7 +364,7 @@ Only assign milestone if reviewing a milestone/* branch. Plain staging reviews g
 Check for open review-finding issues at same file:line → skip. Closed issues at same location → potential regression (elevate priority).
 
 ### 7F: Create Issues
-Sequential creation. Title: `Staging Review: {summary} (staging → main)`. Labels: review-finding, needs-validation, staging-review, P1/P2/P3. Body includes: source branch context (`staging`), code context, evidence, validation checklist.
+Sequential creation. Title: `Staging Review: {summary} (staging → main)`. Labels: review-finding, needs-validation, staging-review, priority:P1/priority:P2/priority:P3. Body includes: source branch context (`staging`), code context, evidence, validation checklist.
 
 **For each finding** (that passes dedup), create issue:
 ```bash

package/commands/review-pr.md

@@ -156,27 +156,78 @@ Record: services touched, domains detected, PR scope (1-2 sentences), change cat
 ## Phase 2: Automated Checks (Run ALL in Parallel)
 
 ### 2A: Python Linting (if Python changed)
+
+Read `forge.yaml → verification.commands.python` for project-specific tool commands:
+
 ```bash
-cd services/api && poetry run black --check app/
-cd services/api && poetry run isort --check app/
-cd services/worker && poetry run black --check worker/
-cd services/worker && poetry run isort --check worker/
-python3 -m py_compile <each-changed-python-file>
+# Read toolchain commands from forge.yaml
+PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
+PYTHON_LINT=$(yq '.verification.commands.python.lint // ""' forge.yaml 2>/dev/null || echo '')
+PYTHON_TYPECHECK=$(yq '.verification.commands.python.typecheck // ""' forge.yaml 2>/dev/null || echo '')
+
+# Run format check
+if [ -n "$PYTHON_FORMAT" ]; then
+    eval "$PYTHON_FORMAT" 2>&1 | head -30
+else
+    echo "SKIPPED — python.format not configured in verification.commands"
+fi
+
+# Run lint
+if [ -n "$PYTHON_LINT" ]; then
+    eval "$PYTHON_LINT" 2>&1 | head -30
+else
+    echo "SKIPPED — python.lint not configured in verification.commands"
+fi
+
+# Run typecheck
+if [ -n "$PYTHON_TYPECHECK" ]; then
+    eval "$PYTHON_TYPECHECK" 2>&1 | head -50
+else
+    echo "SKIPPED — python.typecheck not configured in verification.commands"
+fi
+
+# Always run compile check on changed Python files (fast, language-universal)
+gh pr diff $ARGUMENTS --name-only | grep '\.py$' | while IFS= read -r f; do
+    python3 -m py_compile "$f" 2>&1
+done
 ```
-**IMPORTANT**: Always `cd` into service dir and `poetry run black`. Never `pipx run black`.
 
-### 2B: TypeScript/JS (if web/ changed)
+### 2B: TypeScript/JS (if TypeScript/JS changed)
+
+Read `forge.yaml → verification.commands.typescript` for project-specific tool commands:
+
 ```bash
-cd web && npx prettier --check "src/**/*.{ts,tsx}"
-cd web && npx tsc --noEmit
-cd web && npx next lint
+TS_FORMAT=$(yq '.verification.commands.typescript.format // ""' forge.yaml 2>/dev/null || echo '')
+TS_LINT=$(yq '.verification.commands.typescript.lint // ""' forge.yaml 2>/dev/null || echo '')
+TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
+
+# Run format check
+if [ -n "$TS_FORMAT" ]; then
+    eval "$TS_FORMAT" 2>&1 | head -30
+else
+    echo "SKIPPED — typescript.format not configured in verification.commands"
+fi
+
+# Run lint
+if [ -n "$TS_LINT" ]; then
+    eval "$TS_LINT" 2>&1 | head -30
+else
+    echo "SKIPPED — typescript.lint not configured in verification.commands"
+fi
+
+# Run typecheck
+if [ -n "$TS_TYPECHECK" ]; then
+    eval "$TS_TYPECHECK" 2>&1 | head -50
+    TS_TYPECHECK_EXIT=$?
+else
+    echo "SKIPPED — typescript.typecheck not configured in verification.commands"
+    TS_TYPECHECK_EXIT=0
+fi
 ```
 
 ### 2C: Static Type Checking (if Python changed)
-```bash
-cd services/api && poetry run mypy app/ --ignore-missing-imports --no-error-summary 2>&1 | head -50
-cd services/api && poetry run ruff check app/ --select=E,W,F,B,S --ignore=E501 2>&1 | head -30
-```
+
+Covered by `PYTHON_TYPECHECK` command in 2A above. If `verification.commands.python.typecheck` is unset, this step is explicitly skipped with a log line — it does not silently pass.
 
 ### 2D: Environment Variable Audit
 ```bash
@@ -192,7 +243,7 @@ gh pr diff $ARGUMENTS | grep -oE "['\"][A-Za-z0-9+/=]{40,}['\"]" | head -10
 
 ### 2F: SQL Migration Validation (if *.sql changed)
 ```bash
-for sql_file in $(gh pr diff $ARGUMENTS --name-only | grep "\.sql$"); do
+gh pr diff $ARGUMENTS --name-only | grep "\.sql$" | while IFS= read -r sql_file; do
     grep -E "FOR UPDATE" "$sql_file" | grep -qE "(SUM|COUNT|AVG|MIN|MAX)\s*\(" && echo "ERROR: FOR UPDATE with aggregate"
     grep -qE "DROP (TABLE|COLUMN|INDEX)" "$sql_file" && ! grep -qE "IF EXISTS" "$sql_file" && echo "WARNING: DROP without IF EXISTS"
     grep -qE "ALTER TABLE.*ADD COLUMN.*NOT NULL" "$sql_file" && ! grep -qE "DEFAULT" "$sql_file" && echo "WARNING: NOT NULL without DEFAULT"
@@ -206,8 +257,27 @@ git diff origin/main...HEAD -- "**/package.json" | grep -E "^\+" | grep -v "^\+\
 ```
 
 ### 2H: Tests
+
+Read `forge.yaml → verification.commands.{lang}.test` for the project's test command:
+
 ```bash
-cd services/api && poetry run pytest tests/ -x -q --tb=short 2>&1 | tail -30
+# Check each configured language for a test command
+for lang in python typescript go rust; do
+    TEST_CMD=$(yq ".verification.commands.${lang}.test // \"\"" forge.yaml 2>/dev/null || echo '')
+    if [ -n "$TEST_CMD" ]; then
+        echo "=== Running tests (${lang}): ${TEST_CMD} ==="
+        eval "$TEST_CMD" 2>&1 | tail -30
+        TEST_EXIT=$?
+        [ "$TEST_EXIT" -ne 0 ] && echo "BLOCKING: ${lang} tests failed (exit $TEST_EXIT)"
+    fi
+done
+
+# If no test commands were configured, log explicitly
+PYTHON_TEST=$(yq '.verification.commands.python.test // ""' forge.yaml 2>/dev/null || echo '')
+TS_TEST=$(yq '.verification.commands.typescript.test // ""' forge.yaml 2>/dev/null || echo '')
+if [ -z "$PYTHON_TEST" ] && [ -z "$TS_TEST" ]; then
+    echo "SKIPPED — no test commands configured in verification.commands"
+fi
 ```
 **BLOCKING if tests fail.**
 
@@ -217,36 +287,67 @@ cd services/api && poetry run pytest tests/ -x -q --tb=short 2>&1 | tail -30
 CHANGED_FILES=$(gh pr diff $ARGUMENTS --name-only)
 HAS_TS=$(echo "$CHANGED_FILES" | grep -E '\.(tsx?|jsx?)$' | head -1)
 HAS_PY=$(echo "$CHANGED_FILES" | grep -E '\.py$' | head -1)
-IS_STAGING_TO_MAIN=$([[ "$HEAD" == "staging" && "$BASE" == "main" ]] && echo "true" || echo "false")
-IS_MILESTONE_TO_STAGING=$([[ "$HEAD" =~ ^milestone/ && "$BASE" == "staging" ]] && echo "true" || echo "false")
-REQUIRES_FULL_BUILD=$([[ "$IS_STAGING_TO_MAIN" == "true" || "$IS_MILESTONE_TO_STAGING" == "true" ]] && echo "true" || echo "false")
+# Use POSIX-portable if/else (avoid bash-only [[ ]])
+IS_STAGING_TO_MAIN="false"
+if [ "$HEAD" = "staging" ] && [ "$BASE" = "main" ]; then IS_STAGING_TO_MAIN="true"; fi
+IS_MILESTONE_TO_STAGING="false"
+case "$HEAD" in milestone/*) if [ "$BASE" = "staging" ]; then IS_MILESTONE_TO_STAGING="true"; fi ;; esac
+REQUIRES_FULL_BUILD="false"
+if [ "$IS_STAGING_TO_MAIN" = "true" ] || [ "$IS_MILESTONE_TO_STAGING" = "true" ]; then REQUIRES_FULL_BUILD="true"; fi
 ```
 
 **TypeScript files changed:**
+
+Read `forge.yaml → verification.commands.typescript.typecheck` and `.build`:
+
 ```bash
 gh pr checkout $ARGUMENTS --detach 2>/dev/null
-cd web && npx tsc --noEmit 2>&1
-TSC_EXIT=$?
-if [ "$REQUIRES_FULL_BUILD" = "true" ] || [ "$TSC_EXIT" -eq 0 ]; then
-    npx next build 2>&1 | tail -30
+
+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 '')
+
+if [ -n "$TS_TYPECHECK" ]; then
+    eval "$TS_TYPECHECK" 2>&1
+    TSC_EXIT=$?
+else
+    echo "SKIPPED — typescript.typecheck not configured in verification.commands"
+    TSC_EXIT=0
+fi
+
+if [ -n "$TS_BUILD" ] && { [ "$REQUIRES_FULL_BUILD" = "true" ] || [ "$TSC_EXIT" -eq 0 ]; }; then
+    eval "$TS_BUILD" 2>&1 | tail -30
     BUILD_EXIT=$?
+elif [ -z "$TS_BUILD" ]; then
+    echo "SKIPPED — typescript.build not configured in verification.commands"
 fi
-cd .. && git checkout - 2>/dev/null
+
+git checkout - 2>/dev/null
 ```
 
 If `TSC_EXIT != 0`: **CONFIRMED blocking** — type errors.
-If `BUILD_EXIT != 0`: **CONFIRMED blocking** — SSG prerender failure.
+If `BUILD_EXIT != 0`: **CONFIRMED blocking** — build/prerender failure.
 
-**CRITICAL**: `tsc --noEmit` alone is NOT sufficient for staging→main or milestone→staging. PR #2565 passed tsc but failed next build. PR #11637 (Session Intelligence milestone) was APPROVED without any build check because milestone→staging was excluded — 4 build errors shipped to staging.
+**CRITICAL**: typecheck alone is NOT sufficient for staging→main or milestone→staging — configure `typescript.build` in `verification.commands` to catch SSG/prerender failures that typecheck misses.
 
 **Python files changed:**
+
+Read `forge.yaml → verification.commands.python.format` and `.build`:
+
 ```bash
 gh pr checkout $ARGUMENTS --detach 2>/dev/null
-for f in $(echo "$CHANGED_FILES" | grep '\.py$'); do python3 -m py_compile "$f" 2>&1; done
+
+# Compile-check all changed Python files (language-universal — no config needed)
+echo "$CHANGED_FILES" | grep '\.py$' | while IFS= read -r f; do python3 -m py_compile "$f" 2>&1; done
+
 if [ "$REQUIRES_FULL_BUILD" = "true" ]; then
-    cd services/api && poetry run black --check app/ 2>&1
-    cd ../.. && cd services/worker && poetry run black --check worker/ 2>&1
+    PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
+    if [ -n "$PYTHON_FORMAT" ]; then
+        eval "$PYTHON_FORMAT" 2>&1
+    else
+        echo "SKIPPED — python.format not configured in verification.commands (full-build format check skipped)"
+    fi
 fi
+
 git checkout - 2>/dev/null
 ```
 
@@ -258,9 +359,9 @@ Check whether the PR's actual changes match what the builder committed to in its
 
 ```bash
 # Find the contract comment on the linked issue
-ISSUE_NUM=$(gh pr view $ARGUMENTS --json body --jq '.body' | grep -oP 'Closes #\K\d+|#\K\d+' | head -1)
+ISSUE_NUM=$(gh pr view $ARGUMENTS --json body --jq '.body | gsub("(?s).*?(?:Closes #|#)(?<n>[0-9]+).*"; "\(.n)") // empty' 2>/dev/null | head -1)
 if [ -n "$ISSUE_NUM" ]; then
-    CONTRACT_FILES=$(gh api repos/${REPO}/issues/${ISSUE_NUM}/comments --jq '[.[] | select(.body | contains("FORGE:CONTRACT"))] | .[0].body' 2>/dev/null | grep -oP '`[^`]+\.(py|tsx?|sql|sh|yml|yaml|json)`' | tr -d '`' | sort -u)
+    CONTRACT_FILES=$(gh api repos/${REPO}/issues/${ISSUE_NUM}/comments --jq '[.[] | select(.body | contains("FORGE:CONTRACT"))] | .[0].body' 2>/dev/null | grep -E '`[^`]+\.(py|tsx?|sql|sh|yml|yaml|json)`' | grep -oE '`[^`]+\.(py|tsx?|sql|sh|yml|yaml|json)`' | tr -d '`' | sort -u)
     PR_FILES=$(gh pr diff $ARGUMENTS --name-only | sort -u)
 
     # Files in PR but NOT in contract
@@ -289,17 +390,28 @@ For each changed file, identify its **activation path** — how does execution r
 
 ### Step 2.5A: Identify File Types and Their Registration Points
 
-Map each changed file to its activation requirements:
+Map each changed file to its activation requirements.
+
+**Layout path resolution** — Before applying the table below, read your project's layout from `forge.yaml → review.layout` and substitute the values into the pattern column. Defaults (used when the key is absent) match the AlterLab monorepo layout:
+
+| `forge.yaml` key | Default | Used in table as |
+|-----------------|---------|-----------------|
+| `review.layout.pages` | `web/src/app` | `{PAGES_ROOT}` |
+| `review.layout.api_routers` | `services/api/app/routers` | `{API_ROUTERS}` |
+| `review.layout.api_main` | `services/api/app/main.py` | `{API_MAIN}` |
+| `review.layout.api_middleware` | `services/api/app/middleware` | `{API_MIDDLEWARE}` |
+| `review.layout.migrations` | `infra/migrations` | `{MIGRATIONS}` |
+| `review.layout.worker` | `services/worker` | `{WORKER}` |
 
 | Changed File Pattern | Assumption | Verification Target |
 |---------------------|------------|---------------------|
-| `web/src/app/api/**/*.ts` (Route Handler) | Requests reach this handler | Check `web/next.config.js` rewrites don't shadow it; check `infra/nginx/nginx.conf` routes path to Next.js |
-| `services/api/app/routers/*.py` (API Router) | Router is registered in app | Check `services/api/app/main.py` includes this router |
-| `services/api/app/middleware/*.py` | Middleware is in the stack | Check `services/api/app/main.py` middleware registration order |
-| `infra/migrations/*.sql` | Migration runs on current schema | Check previous migration's end state matches assumptions |
+| `{PAGES_ROOT}/api/**/*.ts` (Route Handler) | Requests reach this handler | Check `web/next.config.js` rewrites don't shadow it; check `infra/nginx/nginx.conf` routes path to Next.js |
+| `{API_ROUTERS}/*.py` (API Router) | Router is registered in app | Check `{API_MAIN}` includes this router |
+| `{API_MIDDLEWARE}/*.py` | Middleware is in the stack | Check `{API_MAIN}` middleware registration order |
+| `{MIGRATIONS}/*.sql` | Migration runs on current schema | Check previous migration's end state matches assumptions |
 | `shared/**/*.py` | Imported by consumer services | Verify import paths exist in api/worker; check Docker volume mounts |
-| `services/worker/worker/*.py` (Consumer) | Queue consumer is registered | Check consumer registration in worker startup |
-| Any file using `os.getenv("NEW_VAR")` | Env var is set at runtime | Check `docker-compose.yml`, `.env.example`, `services/api/app/core/env_validation.py` |
+| `{WORKER}/**/*.py` (Consumer) | Queue consumer is registered | Check consumer registration in worker startup |
+| Any file using `os.getenv("NEW_VAR")` | Env var is set at runtime | Check `docker-compose.yml`, `.env.example`, `{API_MAIN}` env validation module |
 | `scripts/decrypt-secrets.sh` (ENV_MAPPING) | Secret reaches running container | Trace full chain: SOPS key → ENV_MAPPING → deploy workflow SCP target → merge script path → `docker-compose.prod.yml` env_file. See Step 2.5B SOPS deploy chain check. |
 | `.secrets/prod.enc.yaml` | SOPS key maps to ENV_MAPPING | Verify key path in YAML matches the tuple in `decrypt-secrets.sh` ENV_MAPPING |
 | `.github/workflows/deploy-production.yml` | Deploy paths are consistent | Verify SCP target + merge script `PROJECT` var resolve to same dir as `docker-compose.prod.yml` env_file |
@@ -317,55 +429,73 @@ Map each changed file to its activation requirements:
 
 For each changed file, execute the relevant checks using the standalone verification scripts in `$FORGE_HOME/scripts/`. These scripts can also be run independently outside the review context (e.g., from `/quality-gate` or `/work-on` builder steps).
 
+**Platform note**: The verify-*.sh scripts require bash and standard POSIX tools. On Windows without bash (Git Bash / WSL / MSYS2), these checks are skipped with an explicit message — the review continues without them.
+
 ```bash
 CHANGED_FILES=$(gh pr diff $ARGUMENTS --name-only)
 REPO_ROOT="."  # Assumes cwd is the repo root
 
-# Write changed files and diff to temp files for script consumption
-CHANGED_FILES_TMP=$(mktemp)
-DIFF_TMP=$(mktemp)
-echo "$CHANGED_FILES" > "$CHANGED_FILES_TMP"
-gh pr diff $ARGUMENTS > "$DIFF_TMP"
-
-# --- Script-based checks (reusable, testable, deterministic) ---
-# Each script exits 0 (pass), 1 (blocking findings), or 2 (warnings only).
-# Output is structured: "BLOCKING: ...", "WARNING: ...", "OK: ..." per line.
-
-# 1. Route/router/middleware/shared-module/component registration
-echo "=== Running: verify-route-registration.sh ==="
-$FORGE_HOME/scripts/verify-route-registration.sh "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
-
-# 2. Environment variable wiring (checks .env.example, docker-compose, env_validation, SOPS mapping)
-echo "=== Running: verify-env-vars.sh ==="
-$FORGE_HOME/scripts/verify-env-vars.sh "$DIFF_TMP" "$REPO_ROOT" || true
-
-# 3. Host headers in shell scripts + client-side proxy bypass check
-# Read project-specific internal service patterns from forge.yaml (if present)
-FORGE_INTERNAL_PATTERNS=""
-if [ -f "$REPO_ROOT/forge.yaml" ]; then
-    FORGE_INTERNAL_PATTERNS=$(grep -A 999 'internal_service_patterns:' "$REPO_ROOT/forge.yaml" \
-        | grep -E '^\s*-\s+' \
-        | sed 's/^\s*-\s*//' \
-        | tr -d '"'"'" \
-        | paste -sd '|' -)
+# --- Platform / bash capability guard ---
+# The verify-*.sh scripts require bash. Detect availability before invoking.
+# On Windows without Git Bash/WSL, skip gracefully rather than crash.
+BASH_AVAILABLE=false
+if command -v bash >/dev/null 2>&1 && bash -c 'echo ok' >/dev/null 2>&1; then
+    BASH_AVAILABLE=true
 fi
-export FORGE_INTERNAL_PATTERNS
-echo "=== Running: verify-host-headers.sh ==="
-$FORGE_HOME/scripts/verify-host-headers.sh "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
 
-# 4. SOPS deploy chain (ENV_MAPPING consistency, deploy path drift, hotfix sync)
-echo "=== Running: verify-sops-chain.sh ==="
-$FORGE_HOME/scripts/verify-sops-chain.sh "$DIFF_TMP" "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
+if [ "$BASH_AVAILABLE" = "true" ]; then
+    # Write changed files and diff to temp files for script consumption.
+    # Use PID-based names instead of mktemp for cross-platform compatibility.
+    CHANGED_FILES_TMP="/tmp/forge-review-changed-$$.tmp"
+    DIFF_TMP="/tmp/forge-review-diff-$$.tmp"
+    echo "$CHANGED_FILES" > "$CHANGED_FILES_TMP"
+    gh pr diff $ARGUMENTS > "$DIFF_TMP"
+
+    # --- Script-based checks (reusable, testable, deterministic) ---
+    # Each script exits 0 (pass), 1 (blocking findings), or 2 (warnings only).
+    # Output is structured: "BLOCKING: ...", "WARNING: ...", "OK: ..." per line.
+
+    # 1. Route/router/middleware/shared-module/component registration
+    echo "=== Running: verify-route-registration.sh ==="
+    bash "$FORGE_HOME/scripts/verify-route-registration.sh" "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
+
+    # 2. Environment variable wiring (checks .env.example, docker-compose, env_validation, SOPS mapping)
+    echo "=== Running: verify-env-vars.sh ==="
+    bash "$FORGE_HOME/scripts/verify-env-vars.sh" "$DIFF_TMP" "$REPO_ROOT" || true
+
+    # 3. Host headers in shell scripts + client-side proxy bypass check
+    # Read project-specific internal service patterns from forge.yaml (if present)
+    FORGE_INTERNAL_PATTERNS=""
+    if [ -f "$REPO_ROOT/forge.yaml" ]; then
+        FORGE_INTERNAL_PATTERNS=$(grep -A 999 'internal_service_patterns:' "$REPO_ROOT/forge.yaml" \
+            | grep -E '^\s*-\s+' \
+            | sed 's/^\s*-\s*//' \
+            | tr -d '"'"'" \
+            | awk 'NR>1{printf "|"}{printf $0}END{print ""}')
+    fi
+    export FORGE_INTERNAL_PATTERNS
+    echo "=== Running: verify-host-headers.sh ==="
+    bash "$FORGE_HOME/scripts/verify-host-headers.sh" "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
+
+    # 4. SOPS deploy chain (ENV_MAPPING consistency, deploy path drift, hotfix sync)
+    echo "=== Running: verify-sops-chain.sh ==="
+    bash "$FORGE_HOME/scripts/verify-sops-chain.sh" "$DIFF_TMP" "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
 
-# Cleanup temp files
-rm -f "$CHANGED_FILES_TMP" "$DIFF_TMP"
+    # Cleanup temp files
+    rm -f "$CHANGED_FILES_TMP" "$DIFF_TMP"
+else
+    echo "=== Phase 2.5B: verify-*.sh skipped — bash not available on this platform ==="
+    echo "    The verify-*.sh scripts require bash (POSIX shell)."
+    echo "    Install Git Bash (Windows) or WSL to enable these checks."
+    echo "    The review continues — integration assumptions should be verified manually."
+fi
 
 # --- Inline checks (not yet extracted to scripts) ---
 
 # Python scoping hazard check — local imports that shadow module-level names
 # A local `import X` makes X a local variable for the ENTIRE function scope.
 # Any reference to X ABOVE the local import will crash with UnboundLocalError.
-for f in $(echo "$CHANGED_FILES" | grep -E '\.py$'); do
+echo "$CHANGED_FILES" | grep -E '\.py$' | while IFS= read -r f; do
     echo "=== Python Scoping Check: $f ==="
     # Find function-scoped imports (indented import statements)
     grep -nE "^\s+import [a-z]" "$f" 2>/dev/null | while read line; do
@@ -379,7 +509,7 @@ for f in $(echo "$CHANGED_FILES" | grep -E '\.py$'); do
 done
 
 # Config file assumption check (baked into Docker image vs volume-mounted)
-for f in $(echo "$CHANGED_FILES" | grep -E "config/.*\.(json|yaml|yml)$"); do
+echo "$CHANGED_FILES" | grep -E "config/.*\.(json|yaml|yml)$" | while IFS= read -r f; do
     echo "=== Config File: $f ==="
     grep -n "$(dirname $f)" docker-compose.yml 2>/dev/null || echo "WARNING: Config dir may not be mounted — changes may require --build"
     grep -n "$(dirname $f)" services/*/Dockerfile 2>/dev/null || true
@@ -396,7 +526,9 @@ done
 # diff. Pre-existing drift is the most dangerous kind — it lurks until
 # staging→main and then blocks the deploy.
 WORKFLOW_FILES=$(echo "$CHANGED_FILES" | grep -E "^\.github/workflows/.*\.yml$" || true)
-IS_STAGING_PR=$([[ "$HEAD" == "staging" && "$BASE" == "main" ]] && echo "true" || echo "false")
+# Use POSIX-portable conditional (avoid bash-only [[ ]])
+IS_STAGING_PR="false"
+if [ "$HEAD" = "staging" ] && [ "$BASE" = "main" ]; then IS_STAGING_PR="true"; fi
 
 if [ -n "$WORKFLOW_FILES" ] || [ "$IS_STAGING_PR" = "true" ]; then
     echo "=== Sibling Workflow Drift Check (MANDATORY for staging→main) ==="
@@ -415,9 +547,14 @@ if [ -n "$WORKFLOW_FILES" ] || [ "$IS_STAGING_PR" = "true" ]; then
 
             echo "--- Comparing '$JOB' job between ci.yml and deploy-production.yml ---"
 
-            # Extract env vars from ALL steps in the job (not just pytest)
-            CI_ENVS=$(sed -n "/^  ${JOB}:/,/^  [a-z]/p" "$CI_WF" 2>/dev/null | grep -E "PYTHONPATH|DATABASE_URL|REDIS_URL|TESTING" | sed 's/^ *//' | sort)
-            DEPLOY_ENVS=$(sed -n "/^  ${JOB}:/,/^  [a-z]/p" "$DEPLOY_WF" 2>/dev/null | grep -E "PYTHONPATH|DATABASE_URL|REDIS_URL|TESTING" | sed 's/^ *//' | sort)
+            # Extract env vars from ALL steps in the job (not just pytest).
+            # Flag-based awk avoids the range-collapse bug: /pat1/,/pat2/ collapses
+            # to a single line when the header (e.g. "  test-api:") matches both
+            # patterns simultaneously. The flag form sets p=1 on the header line,
+            # prints body lines while p=1, and clears p when the next sibling job
+            # header (same indentation, lowercase start) is seen. <!-- Added: forge#310 -->
+            CI_ENVS=$(awk -v pat="^  ${JOB}:" 'BEGIN{p=0} $0~pat{p=1; print; next} p && /^  [a-z]/{p=0} p{print}' "$CI_WF" 2>/dev/null | grep -E "PYTHONPATH|DATABASE_URL|REDIS_URL|TESTING" | sed 's/^ *//' | sort)
+            DEPLOY_ENVS=$(awk -v pat="^  ${JOB}:" 'BEGIN{p=0} $0~pat{p=1; print; next} p && /^  [a-z]/{p=0} p{print}' "$DEPLOY_WF" 2>/dev/null | grep -E "PYTHONPATH|DATABASE_URL|REDIS_URL|TESTING" | sed 's/^ *//' | sort)
 
             # Check for PYTHONPATH specifically — the exact var that caused the #11356 failure
             CI_PYPATH=$(echo "$CI_ENVS" | grep "PYTHONPATH" || echo "(not set)")
@@ -430,16 +567,16 @@ if [ -n "$WORKFLOW_FILES" ] || [ "$IS_STAGING_PR" = "true" ]; then
             fi
 
             # Check for dependency installation steps that exist in one but not the other
-            CI_INSTALLS=$(sed -n "/^  ${JOB}:/,/^  [a-z]/p" "$CI_WF" 2>/dev/null | grep -c "poetry install\|pip install\|npm install" || echo 0)
-            DEPLOY_INSTALLS=$(sed -n "/^  ${JOB}:/,/^  [a-z]/p" "$DEPLOY_WF" 2>/dev/null | grep -c "poetry install\|pip install\|npm install" || echo 0)
+            CI_INSTALLS=$(awk -v pat="^  ${JOB}:" 'BEGIN{p=0} $0~pat{p=1; print; next} p && /^  [a-z]/{p=0} p{print}' "$CI_WF" 2>/dev/null | grep -c "poetry install\|pip install\|npm install" || echo 0)
+            DEPLOY_INSTALLS=$(awk -v pat="^  ${JOB}:" 'BEGIN{p=0} $0~pat{p=1; print; next} p && /^  [a-z]/{p=0} p{print}' "$DEPLOY_WF" 2>/dev/null | grep -c "poetry install\|pip install\|npm install" || echo 0)
             if [ "$CI_INSTALLS" != "$DEPLOY_INSTALLS" ]; then
                 echo "  WARNING: Different number of dependency install steps in '$JOB' — ci.yml has $CI_INSTALLS, deploy has $DEPLOY_INSTALLS"
                 echo "  ACTION: Read both files and verify all dependencies needed by tests are installed in both workflows."
             fi
 
             # Check step names — if CI has a step that deploy doesn't, flag it
-            CI_STEPS=$(sed -n "/^  ${JOB}:/,/^  [a-z]/p" "$CI_WF" 2>/dev/null | grep "- name:" | sed 's/.*- name: //' | sort)
-            DEPLOY_STEPS=$(sed -n "/^  ${JOB}:/,/^  [a-z]/p" "$DEPLOY_WF" 2>/dev/null | grep "- name:" | sed 's/.*- name: //' | sort)
+            CI_STEPS=$(awk -v pat="^  ${JOB}:" 'BEGIN{p=0} $0~pat{p=1; print; next} p && /^  [a-z]/{p=0} p{print}' "$CI_WF" 2>/dev/null | grep "- name:" | sed 's/.*- name: //' | sort)
+            DEPLOY_STEPS=$(awk -v pat="^  ${JOB}:" 'BEGIN{p=0} $0~pat{p=1; print; next} p && /^  [a-z]/{p=0} p{print}' "$DEPLOY_WF" 2>/dev/null | grep "- name:" | sed 's/.*- name: //' | sort)
             MISSING_IN_DEPLOY=$(comm -23 <(echo "$CI_STEPS") <(echo "$DEPLOY_STEPS") 2>/dev/null || true)
             if [ -n "$MISSING_IN_DEPLOY" ]; then
                 echo "  WARNING: Steps in ci.yml '$JOB' missing from deploy-production.yml:"
@@ -568,7 +705,10 @@ gh api repos/{owner}/{repo}/issues/$ARGUMENTS/comments --jq '.[-10:] | .[].body[
 **Skip if**: Only 1 agent OR total findings ≤ 3.
 
 ```bash
-ALL_FINDINGS=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" --jq '.[].body' | grep -oP '(?<=<!-- FINDING:).*?(?= -->)')
+# Extract structured finding IDs from FINDING HTML comments.
+# Uses jq's scan() (POSIX-portable, no grep -oP required).
+ALL_FINDINGS=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" \
+    --jq '[.[].body | scan("<!-- FINDING:([^>]+) -->") | .[0]] | join("\n")')
 AGENT_COUNT=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" --jq '[.[] | select(.body | test("REVIEW-FINDINGS-START"))] | length')
 FINDING_COUNT=$(echo "$ALL_FINDINGS" | grep -c '.' || echo 0)
 ```
@@ -595,9 +735,13 @@ REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
 HAS_SYNTHESIS=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" --jq '.[].body' | grep -c 'REVIEW-FINDINGS-SYNTHESIZED-START' || echo 0)
 
 if [ "$HAS_SYNTHESIS" -gt 0 ]; then
-    FINDINGS=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" --jq '.[] | select(.body | test("REVIEW-FINDINGS-SYNTHESIZED-START")) | .body' | grep -oP '(?<=<!-- FINDING:).*?(?= -->)')
+    # Extract finding IDs from synthesized block using jq scan() — no grep -oP needed
+    FINDINGS=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" \
+        --jq '[.[] | select(.body | test("REVIEW-FINDINGS-SYNTHESIZED-START")) | .body | scan("<!-- FINDING:([^>]+) -->") | .[0]] | join("\n")')
 else
-    FINDINGS=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" --jq '.[].body' | grep -oP '(?<=<!-- FINDING:).*?(?= -->)')
+    # Extract finding IDs from all agent comments using jq scan() — portable, no grep -oP
+    FINDINGS=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" \
+        --jq '[.[].body | scan("<!-- FINDING:([^>]+) -->") | .[0]] | join("\n")')
 fi
 ```
 
@@ -924,7 +1068,8 @@ fi
 
 ```bash
 CURRENT_SHA=$(gh pr view $ARGUMENTS --json headRefOid --jq '.headRefOid')
-REVIEW_IS_STALE=$([[ "$CURRENT_SHA" != "$REVIEW_SHA" ]] && echo "true" || echo "false")
+REVIEW_IS_STALE="false"
+if [ "$CURRENT_SHA" != "$REVIEW_SHA" ]; then REVIEW_IS_STALE="true"; fi
 ```
 
 ```bash