forgedock 1.0.21 → 1.1.1

package/commands/review-pr-agents.md

@@ -31,6 +31,11 @@ gh pr diff [PR_NUMBER] --name-only
 gh pr diff [PR_NUMBER]
 ```
 
+**Hot-spot prior**:
+[CHURN_CONTEXT]
+
+If a file you are reviewing is listed above as a hot-spot, apply deeper scrutiny to it — high historical churn correlates with defect density. Prefer tracing that file's full code paths (Evidence-Based Review Protocol §2) over a quick pattern scan, and weight ambiguous findings in hot-spot files toward LIKELY rather than POSSIBLE.
+
 ### 2. Dynamic Exploration
 - From each changed file, follow imports and function calls
 - Trace data flows across service boundaries (API → Redis → Worker)
@@ -201,9 +206,10 @@ For each changed file, check:
 
    FastAPI's default validation error response exposes internal field names, types, and constraints. Attackers can enumerate the complete request schema by sending malformed payloads.
    ```bash
-   for f in $MODEL_FILES; do
+   while IFS= read -r f; do
+       [ -z "$f" ] && continue
        grep -rn "RequestValidationError\|validation_exception_handler\|@app.exception_handler" services/api/app/main.py services/api/app/ 2>/dev/null | head -5
-   done
+   done <<< "$MODEL_FILES"
    # If no custom handler found AND the PR adds new Pydantic models or FastAPI endpoints:
    #   LIKELY MEDIUM — FastAPI default exposes internal field names/types/constraints to any caller
    #   Safe pattern: catch RequestValidationError and return only {"detail": "Invalid request"} or a sanitized message
@@ -216,12 +222,13 @@ For each changed file, check:
 
    Unauthenticated health endpoints are expected to be public — the Auth agent's auth-dependency check does not apply. The relevant question is whether they reveal more than `{"status": "ok"}`.
    ```bash
-   for f in $HEALTH_FILES; do
+   while IFS= read -r f; do
+       [ -z "$f" ] && continue
        # Find unauthenticated endpoints (no Depends() in signature) and check return content
        grep -A25 "@router\.\(get\|head\)\|async def health\|async def ping\|async def live\|async def ready\|async def status" "$f" | \
            grep -iE "version|host|port|redis|postgres|db_url|tesseract|pillow|PIL\.__version__|software|engine|server" && \
            echo "SEC: health endpoint in $f returns operational details. Reveals software versions (enables CVE targeting) or connectivity state (enables DoS confirmation). Safe pattern: return only {\"status\": \"ok\"} or {\"status\": \"degraded\"} — no version strings, no host/port, no connectivity details."
-   done
+   done <<< "$HEALTH_FILES"
    ```
    **Confidence**: `LIKELY` — version strings may be intentionally scoped to internal-only endpoints; verify auth status of the endpoint.
    **Severity**: MEDIUM for software version strings (direct CVE targeting input); LOW for DB/Redis connectivity state (useful for DoS confirmation, not exploit).
@@ -231,10 +238,11 @@ For each changed file, check:
 
    Git SHAs and deployment topology exposed via response headers enable targeted CVE research and attack planning.
    ```bash
-   for f in $MIDDLEWARE_FILES; do
+   while IFS= read -r f; do
+       [ -z "$f" ] && continue
        grep -nE "X-App-Version|X-Deployment-Color|X-.*-SHA|X-.*-Build|X-.*-Commit|Server:|X-Powered-By" "$f" 2>/dev/null && \
            echo "SEC: response header in $f leaks infrastructure details. Git SHA enables targeted CVE diffing against public commits. Deployment color reveals blue/green topology. Safe pattern: omit these headers or gate them behind an internal-only middleware."
-   done
+   done <<< "$MIDDLEWARE_FILES"
    ```
    **Confidence**: `LIKELY` — header may be intentional for internal observability tooling behind an auth gate; verify it applies to all responses.
    **Severity**: LOW — information disclosure accelerates other attacks but is not directly exploitable without an additional vulnerability.
@@ -259,11 +267,12 @@ CONFIG_FILES=$(gh pr diff [PR_NUMBER] --name-only | grep -E "(traefik/|infra/ngi
 
 **A. Port bind address audit** (when `docker-compose*.yml` is in diff — trigger: `$INFRA_FILES` non-empty)
 ```bash
-for f in $INFRA_FILES; do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     # Flag non-web ports bound to 0.0.0.0 (no explicit host binding = binds to 0.0.0.0 by default)
     grep -nE "^\s+- \"[0-9]+:[0-9]+\"" "$f" | grep -v "127\.0\.0\.1\|::1" | grep -vE "\"(80|443):" && \
         echo "SEC: port published on 0.0.0.0 in $f — verify UFW/firewall is the ONLY protection. Docker daemon restart can reset iptables and expose the port directly."
-done
+done <<< "$INFRA_FILES"
 ```
 **Confidence**: `LIKELY` — a firewall rule may exist that provides protection; flag for verification rather than hard-block.
 **Severity**: HIGH for database/internal service ports (5432, 6432, 6379); MEDIUM for other non-web ports.
@@ -271,10 +280,11 @@ done
 
 **B. Missing USER directive** (when any `Dockerfile` is in diff — trigger: `$DOCKERFILE_FILES` non-empty)
 ```bash
-for f in $DOCKERFILE_FILES; do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     grep -q "^USER " "$f" || \
         echo "SEC: CONFIRMED — no USER directive in $f. Container runs as UID 0. For services that process user-supplied URLs or untrusted input (worker, Playwright), running as root significantly lowers the bar for container escape."
-done
+done <<< "$DOCKERFILE_FILES"
 ```
 **Confidence**: `CONFIRMED` — absence of USER directive is an objective, verifiable fact.
 **Severity**: HIGH for services processing untrusted input; MEDIUM for internal-only services.
@@ -282,10 +292,11 @@ done
 
 **C. Response header information disclosure** (when Python middleware/main.py adds response headers — trigger: `$HEADER_FILES` non-empty)
 ```bash
-for f in $HEADER_FILES; do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     grep -nE "X-App-Version|X-Deployment-Color|Server:|X-Powered-By|X-.*-SHA|X-.*-Build" "$f" 2>/dev/null && \
         echo "SEC: response header in $f leaks infrastructure details. Git SHA enables targeted CVE diffing against public commits. Deployment color reveals blue/green topology to attackers."
-done
+done <<< "$HEADER_FILES"
 ```
 **Confidence**: `CONFIRMED` — header name reveals infra details by definition.
 **Severity**: MEDIUM — information disclosure accelerates other attacks but is not directly exploitable.
@@ -293,11 +304,12 @@ done
 
 **D. CI security scan gating** (when `.github/workflows/*.yml` is in diff — trigger: `$WORKFLOW_FILES` non-empty)
 ```bash
-for f in $WORKFLOW_FILES; do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     # Find security scanner steps with continue-on-error: true
     grep -B5 "continue-on-error: true" "$f" | grep -iE "trivy|snyk|security|cve|scan|grype|dockle" && \
         echo "SEC: security scanner in $f has continue-on-error: true — CVEs will be logged but will NEVER block a deploy. Remove continue-on-error or add a severity threshold."
-done
+done <<< "$WORKFLOW_FILES"
 ```
 **Confidence**: `CONFIRMED` — `continue-on-error: true` on a security scanner step is objectively a non-blocking scan.
 **Severity**: HIGH — security scanner provides zero protection when it cannot block.
@@ -305,10 +317,11 @@ done
 
 **E. In-memory rate limiter** (when TypeScript files are in diff — trigger: `$TS_FILES` non-empty)
 ```bash
-for f in $TS_FILES; do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     grep -nE "new Map\(\)|=\s*\{\}|= new Map" "$f" 2>/dev/null | grep -iE "rate|limit|attempt|count|throttle|window" && \
         echo "SEC: in-memory rate limiter detected in $f — resets on every container restart, not shared across blue/green replicas. Use Redis (via Upstash, ioredis, or the existing Redis client) for distributed rate limiting."
-done
+done <<< "$TS_FILES"
 ```
 **Confidence**: `LIKELY` — in-memory store may be intentional for non-critical paths; flag for verification.
 **Severity**: MEDIUM — bypass requires restarting the container or hitting a different replica; not trivially exploitable but provides no protection in blue/green deploys.
@@ -316,10 +329,11 @@ done
 
 **F. Cookie security flags** (when TypeScript files are in diff — trigger: `$TS_FILES` non-empty)
 ```bash
-for f in $TS_FILES; do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     grep -nE "httpOnly:\s*false|secure:\s*false|sameSite.*['\"]none['\"]" "$f" 2>/dev/null && \
         echo "SEC: cookie in $f has weakened security flag. httpOnly: false exposes cookie to JS (XSS risk). secure: false allows transmission over HTTP. sameSite: none without Secure enables CSRF."
-done
+done <<< "$TS_FILES"
 ```
 **Confidence**: `CONFIRMED` — explicit `false`/`none` values are objective findings.
 **Severity**: HIGH for `httpOnly: false` (direct XSS vector for session cookies); MEDIUM for `secure: false` or `sameSite: none`.
@@ -327,33 +341,36 @@ done
 
 **G. Fallback credential scan in config files** (when config files are in diff — trigger: `$CONFIG_FILES` non-empty)
 ```bash
-for f in $CONFIG_FILES; do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     # Shell-style fallback: ${VAR:-default} — flag non-trivial fallback values that may be credentials
     grep -nE "\$\{[A-Z_]+:-[^}]{4,}\}" "$f" | grep -ivE "(localhost|127\.0\.0\.1|0\.0\.0\.0|true|false|^[0-9]+$|/tmp|/var|/etc)" && \
         echo "SEC: potential credential fallback in $f — verify fallback value is safe if env var is absent"
-done
+done <<< "$CONFIG_FILES"
 ```
 For each hit: read the fallback value.
 - Contains `$apr1$`, `$2b$`, `$bcrypt$`, `$argon2`, or hash-like long alphanumeric with `$` separators: **CONFIRMED HIGH** — htpasswd/bcrypt placeholder; active if env var is absent.
 - Is `admin`, `password`, `changeme`, `secret`, `test`, or similar weak string: **CONFIRMED HIGH** — default credential.
 - Is empty string (`${VAR:-}` or `${VAR:-""}`): **CONFIRMED HIGH** if field controls authentication.
 
-**Required cross-checks when a credential fallback is found**: (1) Is the env var required in `app/env_validation.py`? (2) Is it in `scripts/decrypt-secrets.sh` ENV_MAPPING? (3) Is it marked required in `.env.example`? If ANY missing: the insecure fallback may be active in some environments.
+**Required cross-checks when a credential fallback is found**: (1) Is the env var required in `app/env_validation.py`? (2) Is it in `scripts/decrypt-secrets.sh` ENV_MAPPING (if configured in your SOPS deploy chain — skip if absent)? (3) Is it marked required in `.env.example`? If ANY missing: the insecure fallback may be active in some environments.
 **Confidence**: `CONFIRMED` — fallback value is objectively verifiable.
 **Severity**: HIGH — insecure fallback credential is equivalent to a hardcoded credential for any environment missing the env var.
 **Evidence**: Config files commonly use `${VAR:-placeholder}` patterns during development, where the placeholder is a sample credential or hash. If the env var is absent in any environment (staging, non-production, first deploy before secrets are injected), the placeholder becomes the active credential. Also covered by INFRA agent item 13 (deployment context + ENV_MAPPING cross-check); this item extends coverage to PRs not classified as INFRA domain.
 
 **H. Runtime UID × volume ownership** (when any Dockerfile is in diff AND diff contains `USER`, `su-exec`, `gosu`, or `setuid` — trigger: `$DOCKERFILE_FILES` non-empty AND UID change detected)
 ```bash
-UID_CHANGE=$(for f in $DOCKERFILE_FILES; do
+UID_CHANGE=$(while IFS= read -r f; do
+    [ -z "$f" ] && continue
     gh pr diff [PR_NUMBER] -- "$f" 2>/dev/null | grep -E '^\+.*(USER\s+[^0]|su-exec|gosu|setuid)' | grep -v '^+++' && break
-done)
+done <<< "$DOCKERFILE_FILES")
 if [ -n "$UID_CHANGE" ]; then
     echo "UID change detected — cross-referencing named volume mounts..."
     COMPOSE_FILES=$(find . -maxdepth 2 -name "docker-compose*.yml" 2>/dev/null | sort)
-    for cf in $COMPOSE_FILES; do
+    while IFS= read -r cf; do
+        [ -z "$cf" ] && continue
         grep -A2 "volumes:" "$cf" | grep -E "^\s+\w.*:" | grep -v "^--$" && echo "  ^ in $cf"
-    done
+    done <<< "$COMPOSE_FILES"
 fi
 ```
 For each named volume found: determine its container mount point. Named volumes are created as **root-owned** by Docker at first use — a privilege drop (root → UID N) without a `chown` before the drop will silently break any service path that calls `mkdir`, `write_bytes`, `open(... 'w')`, or `os.makedirs` under that mount point.
@@ -784,14 +801,14 @@ CRITICAL: This is a billing system. Double-spend = revenue loss.
    ```
    If `WHERE reserved_by IS NULL` appears in a SELECT that is followed by a separate UPDATE (not in the same atomic statement), this is a CONFIRMED HIGH finding — two concurrent sessions can both pass the read check before either writes.
 
-8. **Cross-service flag staleness**: When a discount or pricing flag (`is_byop`, `has_active_subscription`, `byop_discount`) is set by the API layer at job submission and read by the Worker layer at billing time, verify the flag is re-validated at debit time — not trusted from the queued job payload.
+8. **Cross-service flag staleness**: When a discount or pricing flag (e.g. `has_active_subscription`, a `discount_type` field) is set by the API layer at job submission and read by the Worker layer at billing time, verify the flag is re-validated at debit time — not trusted from the queued job payload.
 
    Search for discount flags passed through Redis/job payloads:
    ```bash
-   grep -rn "is_byop\|byop_discount\|discount.*flag\|flag.*discount" services/api/app/ services/worker/worker/ | head -20
+   grep -rn "discount.*flag\|flag.*discount\|subscription.*flag\|plan_type\|discount_type" services/api/ services/worker/ | head -20
    # If the flag flows through a job payload and is not re-validated at billing: CONFIRMED HIGH
    ```
-   A race window exists when a flag is checked at submission but consumed at billing: the underlying condition (e.g., proxy existence, subscription status) may have changed between the two operations. The fix must re-validate the flag atomically at the point of debit, not rely on a stale value from the job payload.
+   A race window exists when a flag is checked at submission but consumed at billing: the underlying condition (e.g., subscription status, entitlement) may have changed between the two operations. The fix must re-validate the flag atomically at the point of debit, not rely on a stale value from the job payload.
 
 ## Safe Patterns in This Codebase
 ```bash
@@ -1300,8 +1317,8 @@ You are auditing PR #[PR_NUMBER] for database changes in [PROJECT_NAME].
    a. List ALL `*.sql` files in `infra/migrations/` on the PR's target branch (use `git ls-tree` or `ls`)
    b. Extract the 4-digit numeric prefix from each filename (the leading digits before the first `_`)
    c. Identify any prefix that appears more than once
-   d. Cross-reference against the `GRANDFATHERED_DUPLICATES` list in `scripts/validate-migration-order.sh` — these are known-safe legacy duplicates
-   e. **DEPLOY GATE — CRITICAL**: If ANY non-grandfathered duplicate prefix exists → flag as **CRITICAL BLOCKER** and reject the PR. **Do NOT apply migration runner reasoning here.** The deploy gate (`deploy-production.yml`) runs `validate-migration-order.sh` with no `continue-on-error` — it hard-fails on any non-grandfathered duplicate regardless of whether the migration runner executes files correctly. The runner may handle duplicate filenames fine; the deploy script does not. A PR that passes this reasoning trap ("unique filenames, so the runner is safe") will still halt production deploy and waste a 30-minute CI compute cycle. The only safe classification is CRITICAL BLOCKER.
+   d. Identify if the project maintains a grandfathered-duplicates allowlist (e.g., a config file or comment block listing known-safe legacy duplicate prefixes). If one exists, cross-reference against it. <!-- Updated: forge#1349 — removed stale validate-migration-order.sh reference (script does not exist in ForgeDock) -->
+   e. **DEPLOY GATE — CRITICAL**: If ANY non-allowlisted duplicate prefix exists → flag as **CRITICAL BLOCKER** and reject the PR. **Do NOT apply migration runner reasoning here.** Deploy gates that enforce migration ordering hard-fail on any non-allowed duplicate regardless of whether the migration runner executes files correctly. The runner may handle duplicate filenames fine; the deploy script does not. A PR that passes this reasoning trap ("unique filenames, so the runner is safe") will still halt production deploy. The only safe classification is CRITICAL BLOCKER.
    f. Additionally: if the PR adds new migration files, verify their prefixes don't collide with existing files in the directory
 9. **FK and CHECK constraints**: New tables should have appropriate foreign keys and CHECK constraints. Missing FK allows orphaned rows; missing CHECK allows invalid enum values.
 10. **asyncpg gotchas**:
@@ -1414,17 +1431,19 @@ If no infra context is configured above, derive the deployment model from the ch
    OLD_VALUES=$(gh pr diff [PR_NUMBER] | grep "^\-" | grep -oP '"status"\s*:\s*"\K[^"]+' | sort -u)
 
    # Search all non-application consumer locations for those old values
-   for val in $OLD_VALUES; do
+   while IFS= read -r val; do
+       [ -z "$val" ] && continue
        echo "=== Searching for old response value: $val ==="
        grep -rn "$val" scripts/ infra/ .github/ traefik/ 2>/dev/null | grep -v "^Binary"
        grep -rn "$val" docker-compose*.yml 2>/dev/null
-   done
+   done <<< "$OLD_VALUES"
 
    # Also search for endpoint path references in consumer locations
    HEALTH_PATHS=$(gh pr diff [PR_NUMBER] | grep "^\+" | grep -oP '@\w+\.(?:get|post)\("\K[^"]+(?:health|status|ping|ready|live|readiness|liveness)[^"]*')
-   for path in $HEALTH_PATHS; do
+   while IFS= read -r path; do
+       [ -z "$path" ] && continue
        grep -rn "$path" scripts/ infra/ .github/ traefik/ docker-compose*.yml 2>/dev/null | grep -v "^Binary"
-   done
+   done <<< "$HEALTH_PATHS"
    ```
 
    **For each hit, classify:**
@@ -1522,13 +1541,14 @@ If no infra context is configured above, derive the deployment model from the ch
 
    **Scan ALL `{{` occurrences in every `script:` block of every `appleboy/ssh-action` step in changed files:**
    ```bash
-   for f in $(gh pr diff [PR_NUMBER] --name-only | grep -E '\.github/workflows/.*\.yml$'); do
+   while IFS= read -r f; do
+       [ -z "$f" ] && continue
        if grep -q "appleboy/ssh-action" "$f"; then
            echo "=== appleboy/ssh-action found in $f ==="
            # Show all {{ occurrences with line numbers
            grep -n "{{" "$f"
        fi
-   done
+   done < <(gh pr diff [PR_NUMBER] --name-only | grep -E '\.github/workflows/.*\.yml$')
    ```
 
    **For every `{{` found, classify and flag:**
@@ -1549,10 +1569,11 @@ If no infra context is configured above, derive the deployment model from the ch
    **Scan changed config files for credential fallbacks:**
    ```bash
    CONFIG_FILES=$(gh pr diff [PR_NUMBER] --name-only | grep -E "(traefik/|infra/nginx/|infra/|\.github/workflows/).*(\.ya?ml|\.toml|\.json|\.conf|\.ini)$" | head -20)
-   for f in $CONFIG_FILES; do
+   while IFS= read -r f; do
+       [ -z "$f" ] && continue
        # Shell-style fallback: ${VAR:-default} — filter out safe non-credential defaults
        grep -nE "\$\{[A-Z_]+:-[^}]{4,}\}" "$f" | grep -ivE "(localhost|127\.0\.0\.1|0\.0\.0\.0|true|false|^[0-9]+$|/tmp|/var|/etc)" | head -20
-   done
+   done <<< "$CONFIG_FILES"
    ```
 
    **For each hit, classify the fallback value:**
@@ -1567,7 +1588,7 @@ If no infra context is configured above, derive the deployment model from the ch
 
    **Cross-check when a credential fallback is found:**
    1. Is the corresponding env var required (not optional) in `app/env_validation.py` (or equivalent startup validation)?
-   2. Is the env var in `scripts/decrypt-secrets.sh` ENV_MAPPING (delivered from SOPS to `.env.production`)?
+   2. Is the env var in `scripts/decrypt-secrets.sh` ENV_MAPPING (if configured in your SOPS deploy chain — skip if absent; delivered from SOPS to `.env.production`)?
    3. Is the env var documented with a "REQUIRED" note in `.env.example`?
 
    If ANY of these three are missing: the env var may legitimately be absent in some environments, making the insecure fallback active. Flag as **CONFIRMED HIGH** with all three cross-check results.
@@ -1588,9 +1609,10 @@ If no infra context is configured above, derive the deployment model from the ch
    **Scan for host-side database tool invocations:**
    ```bash
    DEPLOY_FILES=$(gh pr diff [PR_NUMBER] --name-only | grep -E "(\.github/workflows/.*\.yml$|scripts/deploy.*\.sh$|docker-entrypoint.*\.sh$)")
-   for f in $DEPLOY_FILES; do
+   while IFS= read -r f; do
+       [ -z "$f" ] && continue
        grep -n "\bpsql\b\|\bcreatedb\b\|\bpg_dump\b\|\bpg_restore\b" "$f" | grep -v "docker exec" | head -20
-   done
+   done <<< "$DEPLOY_FILES"
    ```
 
    **For each match, classify:**
@@ -1633,15 +1655,17 @@ If no infra context is configured above, derive the deployment model from the ch
    COMPOSE_INFRA_FILES=$(gh pr diff [PR_NUMBER] --name-only | grep -E "docker-compose.*\.yml$")
 
    # For each config file: read the full file (not just the diff) to understand the structure
-   for f in $CONFIG_TOOL_FILES; do
+   while IFS= read -r f; do
+       [ -z "$f" ] && continue
        echo "=== Reading full config structure: $f ==="
        cat "$f"
-   done
+   done <<< "$CONFIG_TOOL_FILES"
 
    # Identify tool version from docker-compose (for version-aware schema reasoning)
-   for f in $COMPOSE_INFRA_FILES; do
+   while IFS= read -r f; do
+       [ -z "$f" ] && continue
        grep -E "image:\s*(traefik|nginx|haproxy|envoy|caddy|terraform):" "$f" 2>/dev/null && echo "  ^ in $f"
-   done
+   done <<< "$COMPOSE_INFRA_FILES"
    ```
 
    **Severity classification**:

package/commands/review-pr.md

@@ -147,7 +147,7 @@ echo "=== DOMAINS ==="
 echo "$DIFF" | grep -cE "SessionUser|CurrentUser|get_current_user|jwt|oauth|login|logout|Depends\(get_|x.forwarded.for|x_forwarded_for|forwarded_for|rate.limit.*ip|ip.*rate.limit|algorithm.*HS256|algorithm.*RS256|NEXTAUTH_SECRET|JWT_SECRET|admin.proxy" && echo "AUTH" || true
 echo "$DIFF" | grep -cE "credit|balance|debit|reconcil|tier_cost|pricing|charge|refund|stripe|subscription" && echo "BILLING" || true
 echo "$DIFF" | grep -cE "scrape|tier.*escalat|proxy|anti_bot|stealth|playwright|playbook" && echo "SCRAPING" || true
-echo "$DIFF" | grep -cE "FOR UPDATE|atomic|transaction|pipeline|MULTI|distributed_lock|acquire_lock|reserved_by|promo.*claim|voucher.*redeem|is_byop|byop_discount" && echo "CONCURRENCY" || true
+echo "$DIFF" | grep -cE "FOR UPDATE|atomic|transaction|pipeline|MULTI|distributed_lock|acquire_lock|reserved_by|promo.*claim|voucher.*redeem" && echo "CONCURRENCY" || true
 echo "$FILES" | grep -cE "migration|\.sql$" && echo "DATABASE" || true
 echo "$DIFF" | grep -cE "create_async_engine|AsyncSession|connect_args|pool_size|prepared_statement|engine_from_config|sessionmaker" && echo "DB_CONFIG" || true
 echo "$FILES" | grep -cE "router|routes" && echo "API_DESIGN" || true
@@ -397,7 +397,7 @@ For each changed file, identify its **activation path** — how does execution r
 
 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:
+**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) are the ForgeDock install defaults:
 
 | `forge.yaml` key | Default | Used in table as |
 |-----------------|---------|-----------------|
@@ -461,6 +461,23 @@ if [ "$BASH_AVAILABLE" = "true" ]; then
     # Output is structured: "BLOCKING: ...", "WARNING: ...", "OK: ..." per line.
 
     # 1. Route/router/middleware/shared-module/component registration
+    # Export forge.yaml layout overrides so verify-route-registration.sh uses project-configured
+    # paths instead of project defaults. The script supports these env vars (lines 36-44 of
+    # verify-route-registration.sh) but requires the caller to set them. <!-- Added: forge#1349 -->
+    if [ -f "$REPO_ROOT/forge.yaml" ]; then
+        _PAGES_ROOT=$(grep -A10 'layout:' "$REPO_ROOT/forge.yaml" 2>/dev/null \
+            | grep -E '^\s*pages:' | head -1 | sed 's/.*pages:[[:space:]]*//' | tr -d '"' | tr -d "'" | xargs)
+        _API_ROUTERS=$(grep -A10 'layout:' "$REPO_ROOT/forge.yaml" 2>/dev/null \
+            | grep -E '^\s*api_routers_dir:' | head -1 | sed 's/.*api_routers_dir:[[:space:]]*//' | tr -d '"' | tr -d "'" | xargs)
+        _API_MAIN=$(grep -A10 'layout:' "$REPO_ROOT/forge.yaml" 2>/dev/null \
+            | grep -E '^\s*api_main:' | head -1 | sed 's/.*api_main:[[:space:]]*//' | tr -d '"' | tr -d "'" | xargs)
+        _API_MIDDLEWARE=$(grep -A10 'layout:' "$REPO_ROOT/forge.yaml" 2>/dev/null \
+            | grep -E '^\s*api_middleware_dir:' | head -1 | sed 's/.*api_middleware_dir:[[:space:]]*//' | tr -d '"' | tr -d "'" | xargs)
+        [ -n "$_PAGES_ROOT" ] && export FORGE_PAGES_ROOT="$_PAGES_ROOT"
+        [ -n "$_API_ROUTERS" ] && export FORGE_API_ROUTERS_DIR="$_API_ROUTERS"
+        [ -n "$_API_MAIN" ] && export FORGE_API_MAIN="$_API_MAIN"
+        [ -n "$_API_MIDDLEWARE" ] && export FORGE_API_MIDDLEWARE_DIR="$_API_MIDDLEWARE"
+    fi
     echo "=== Running: verify-route-registration.sh ==="
     bash "$FORGE_HOME/scripts/verify-route-registration.sh" "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
 
@@ -612,7 +629,7 @@ Format: `INTEG-N|CONFIRMED|HIGH|file:line|Changed code may be unreachable: {reas
 DIFF=$(gh pr diff $ARGUMENTS)
 FILES=$(gh pr diff $ARGUMENTS --name-only)
 echo "=== RISK SIGNALS ==="
-echo "$DIFF" | grep -cE "subprocess|exec|eval|system\(|popen|heredoc|EMEMO_EOF|LLM_|llm_" && echo "  UNTRUSTED_INPUT_PROCESSING" || true
+echo "$DIFF" | grep -cE "subprocess|exec|eval|system\(|popen|heredoc" && echo "  UNTRUSTED_INPUT_PROCESSING" || true
 echo "$DIFF" | grep -cE "\.sh$|bash|shell|cron" && echo "  SHELL_SCRIPT" || true
 echo "$DIFF" | grep -cE "credit|balance|debit|charge|refund|stripe" && echo "  FINANCIAL" || true
 echo "$DIFF" | grep -cE "SessionUser|CurrentUser|jwt|oauth|password|token|secret|x.forwarded.for|x_forwarded_for|forwarded_for|rate.limit.*ip|ip.*rate.limit|algorithm.*HS256|algorithm.*RS256|NEXTAUTH_SECRET|JWT_SECRET|admin.proxy" && echo "  AUTH_SENSITIVE" || true
@@ -624,6 +641,36 @@ echo "$DIFF" | grep -cE "subprocess|os\.system|eval\(|exec\(|pickle|yaml\.load[^
 echo "$FILES" | grep -cE "^sdk/|openapi.*\.json$|openapi-versions/" && echo "  SDK_OPENAPI" || true
 ```
 
+**Churn (hot-spot) signal**: The signals above are all derived from the current diff content — none of them measure historical change frequency, which is one of the strongest empirical predictors of defect density. Compute a bounded per-file churn tier for the PR's changed files only (never repo-wide) and carry it forward as `CHURN_CONTEXT` for Phase 3C:
+
+```bash
+CHURN_WINDOW="90 days ago"   # named constant — must match the same window used in architect.md Phase A5
+CHURN_CONTEXT=""
+# Herestring (not a piped `| while read`) — a pipe would run the loop body in a
+# subshell in bash, silently discarding CHURN_CONTEXT once the loop exits. $FILES
+# is one path per line (gh pr diff --name-only), so `read -r` per line is safe
+# even when a path contains embedded spaces.
+while IFS= read -r FILE; do
+  [ -z "$FILE" ] && continue
+  COMMITS=$(git log --oneline --since="$CHURN_WINDOW" -- "$FILE" 2>/dev/null | wc -l)
+  if [ "$COMMITS" -ge 15 ]; then
+    # Real newline appended via $'\n' (ANSI-C quoting), not a literal backslash-n.
+    # A literal "\n" would only be interpreted by `echo -e` — it survives
+    # unprocessed into Phase 3C's raw template substitution ([CHURN_CONTEXT] ->
+    # $CHURN_CONTEXT), which does not reprocess escapes, so with 2+ HOT files
+    # multi-hotspot PRs would render squished in the agent prompt. A real
+    # newline here makes the variable correct for every consumer.
+    CHURN_CONTEXT="${CHURN_CONTEXT}${FILE} (${COMMITS} commits in last 90 days — HOT)"$'\n'
+  fi
+done <<< "$FILES"
+if [ -z "$CHURN_CONTEXT" ]; then
+  CHURN_CONTEXT="No hot-spot files detected (all changed files under 15 commits in the last 90 days)."
+fi
+echo "$CHURN_CONTEXT"
+```
+
+Tiers (fixed thresholds, identical to `architect.md` Phase A5): **HOT** = 15+ commits / 90 days, **MEDIUM** = 5–14, **LOW** = 0–4. Only HOT-tier files are listed in `CHURN_CONTEXT` — this keeps the agent prompt signal short and high-value rather than dumping a churn count for every file. This does not change agent selection (3B) — it is a scrutiny prior surfaced to whichever agents are already selected, substituted as `[CHURN_CONTEXT]` in Phase 3C.
+
 ### 3B: Select Agents
 
 | Risk Signal | Required Agents |
@@ -687,8 +734,9 @@ This file contains the Evidence-Based Review Protocol, Structured Findings Proto
 2. Substitute: `[PR_NUMBER]`, `[REVIEW_SHA]`, `[REVIEW_SHA_SHORT]`, `[TITLE]`, relevant files list
 3. Substitute: `[PROJECT_NAME]` → `$PROJECT_NAME`, `[PROJECT_CONTEXT]` → `$PROJECT_CONTEXT`, `[TECH_STACK]` → `$TECH_STACK`
 4. Substitute per-agent domain context: `[DOMAIN_CONTEXT]` → the agent's matching key from `forge.yaml → review.domains` (e.g., `$DOMAIN_CONTEXT_AUTH` for the auth agent, `$DOMAIN_CONTEXT_BILLING` for the billing agent)
-5. If Phase 2.5 found broken assumptions, append them to the agent's prompt as "Pre-found integration issues to verify"
-6. Launch via `Task` tool with the resolved model (default `"sonnet"`, fallback `"opus"` if rate-limited)
+5. Substitute the shared hot-spot prior: `[CHURN_CONTEXT]` → `$CHURN_CONTEXT` (computed once in Phase 3A, same value for every agent — this is a PR-level fact, not a per-domain config value, so it is NOT read from `forge.yaml`)
+6. If Phase 2.5 found broken assumptions, append them to the agent's prompt as "Pre-found integration issues to verify"
+7. Launch via `Task` tool with the resolved model (default `"sonnet"`, fallback `"opus"` if rate-limited)
 
 **CRITICAL**: Launch ALL selected agents in a SINGLE message using multiple Task tool calls. Each agent posts findings directly to the PR via `gh pr comment`.
 
@@ -1062,7 +1110,7 @@ else
 fi
 ```
 
-**Important**: Phase 8 ONLY merges the PR. It does NOT close the issue, update labels, or clean up worktrees. When invoked via `/work-on`, those responsibilities belong to `work-on/close.md` — which runs after the router detects state 4 (MERGE_COMPLETE: PR merged + issue open). Doing them here would cause the router to hit TERMINAL_MERGED (state 1) and skip the close phase entirely.
+**Important**: Phase 8 ONLY merges the PR. It does NOT close the issue, update labels, or clean up worktrees. When invoked via `/work-on`, those responsibilities belong to `work-on/close.md` (work-on.md Phase 6 — triggered when PR is merged and issue is still open). Doing them here would cause the issue to be closed with `workflow:merged` before Phase 6 runs, skipping the close phase entirely.
 
 ### 8B: Post-Merge Review Finding Demilestoning (Milestone PRs Only)
 

package/commands/scope.md

@@ -79,13 +79,21 @@ Limit `DOMAIN_TERMS` to the 10 most specific (skip generic words: "fix", "bug",
 Search `REPO_PATH` for each keyword to find candidate files:
 
 ```bash
+# {TARGET_FILES} and {DOMAIN_TERMS} are space-separated arguments (same contract
+# as {AFFECTED_FILES} elsewhere) — split explicitly on IFS=' ' into arrays instead
+# of a bare `for x in {PLACEHOLDER}`, which word-splits on the shell's default IFS
+# (space, tab, AND newline) and would corrupt any file path or compound domain
+# term containing a space.
+IFS=' ' read -ra TARGET_FILES_ARR <<< "{TARGET_FILES}"
+IFS=' ' read -ra DOMAIN_TERMS_ARR <<< "{DOMAIN_TERMS}"
+
 # For each file explicitly named in the issue
-for file in {TARGET_FILES}; do
+for file in "${TARGET_FILES_ARR[@]}"; do
   find "$REPO_PATH" -name "$file" -not -path "*/.git/*" -not -path "*/node_modules/*" 2>/dev/null
 done
 
 # For each domain term: grep for references
-for term in {DOMAIN_TERMS}; do
+for term in "${DOMAIN_TERMS_ARR[@]}"; do
   grep -rl "$term" "$REPO_PATH" \
     --include="*.py" --include="*.ts" --include="*.tsx" \
     --include="*.md" --include="*.yml" --include="*.yaml" \
@@ -96,7 +104,7 @@ done
 
 # Git log — files recently changed alongside the named files
 if [ -n "{TARGET_FILES}" ]; then
-  for file in {TARGET_FILES}; do
+  for file in "${TARGET_FILES_ARR[@]}"; do
     git -C "$REPO_PATH" log --oneline -20 -- "$file" \
       --name-only --format="" 2>/dev/null | grep -v "^$" | sort -u | head -10
   done

package/commands/security-audit.md

@@ -110,13 +110,14 @@ fi
 **Check**:
 ```bash
 DOCKER_COMPOSE_FILES=$(find "$REPO_PATH" -name "docker-compose*.yml" -not -path "*/.git/*" 2>/dev/null)
-for f in $DOCKER_COMPOSE_FILES; do
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
   HITS=$(grep -n '0\.0\.0\.0:[0-9]' "$f" 2>/dev/null | grep -v '^\s*#' || true)
   if [ -n "$HITS" ]; then
     echo "FINDING [1A] $f:"
     echo "$HITS"
   fi
-done
+done <<< "$DOCKER_COMPOSE_FILES"
 ```
 
 **Confirm**: For each hit, verify the port is NOT a web-facing port (80, 443, 8080, 3000). Ports like 6432 (PgBouncer), 6379 (Redis), 5432 (Postgres), 27017 (MongoDB) bound to `0.0.0.0` are confirmed findings.
@@ -134,12 +135,13 @@ done
 **Check**:
 ```bash
 DOCKERFILES=$(find "$REPO_PATH" -name "Dockerfile*" -not -path "*/.git/*" 2>/dev/null)
-for f in $DOCKERFILES; do
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
   # Skip if USER directive is present (anywhere in the file, case-insensitive)
   if ! grep -iq '^\s*USER\s' "$f" 2>/dev/null; then
     echo "FINDING [1B] $f: no USER directive — container runs as root"
   fi
-done
+done <<< "$DOCKERFILES"
 ```
 
 **Confirm**: Check if the Dockerfile is for a long-running service (not a one-shot build image). If service container with no USER → confirmed finding.
@@ -157,14 +159,15 @@ done
 **Check**:
 ```bash
 DOCKER_COMPOSE_FILES=$(find "$REPO_PATH" -name "docker-compose*.yml" -not -path "*/.git/*" 2>/dev/null)
-for f in $DOCKER_COMPOSE_FILES; do
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
   # Redis without requirepass
   REDIS_NO_AUTH=$(grep -A5 'image:.*redis' "$f" 2>/dev/null | grep -v 'requirepass\|password' | grep -c 'redis' || true)
   # Postgres without POSTGRES_PASSWORD
   PG_NO_AUTH=$(awk '/image:.*postgres/{found=1} found && /POSTGRES_PASSWORD/{found=0} found && /^[[:space:]]*-[[:space:]]*[A-Z]/{print}' "$f" 2>/dev/null | grep -v 'POSTGRES_PASSWORD' | head -3 || true)
 
   [ -n "$PG_NO_AUTH" ] && echo "FINDING [1C] $f: Postgres service may lack POSTGRES_PASSWORD"
-done
+done <<< "$DOCKER_COMPOSE_FILES"
 ```
 
 **Manual review**: Check for `POSTGRES_PASSWORD` and `requirepass` in compose environment sections. Flag any service using a blank/trivial password as a documented value.
@@ -184,7 +187,8 @@ done
 **Check**:
 ```bash
 WORKFLOW_FILES=$(find "$REPO_PATH/.github/workflows" -name "*.yml" 2>/dev/null)
-for f in $WORKFLOW_FILES; do
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
   # Find security scanner steps then check if continue-on-error follows within 5 lines
   awk '
     /trivy|snyk|owasp|dependency.check|gitleaks|semgrep|gosec|bandit/ {
@@ -195,7 +199,7 @@ for f in $WORKFLOW_FILES; do
       print FILENAME ":" NR ": continue-on-error: true near security scanner at line " scanner_line
     }
   ' FILENAME="$f" "$f" 2>/dev/null || true
-done
+done <<< "$WORKFLOW_FILES"
 ```
 
 **Confirm**: Verify the flagged step is indeed a security scanner step (not a notification or deploy step). Confirmed if scanner produces failure exit codes that are being swallowed.
@@ -213,10 +217,11 @@ done
 **Check**:
 ```bash
 CONFIG_FILES=$(find "$REPO_PATH/infra" "$REPO_PATH/services" -name "*.conf" -o -name "*.yml" -o -name "nginx.conf" 2>/dev/null | grep -v '.git')
-for f in $CONFIG_FILES; do
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
   HITS=$(grep -n '^\s*#.*\(deny\|allow\s\|auth_basic\|auth_request\|satisfy all\|limit_req\|access_by_lua\)' "$f" 2>/dev/null || true)
   [ -n "$HITS" ] && echo "FINDING [2B] $f:" && echo "$HITS"
-done
+done <<< "$CONFIG_FILES"
 ```
 
 **Confirm**: Distinguish intentional comments (documentation) from disabled access control rules. Confirmed if the commented line is a functional directive that would restrict access.
@@ -236,10 +241,11 @@ done
 **Check**:
 ```bash
 CSP_FILES=$(grep -rl "Content-Security-Policy\|script-src" "$REPO_PATH" --include="*.js" --include="*.ts" --include="*.json" --include="*.conf" --include="*.yml" 2>/dev/null | grep -v '.git' | grep -v node_modules)
-for f in $CSP_FILES; do
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
   HITS=$(grep -n "script-src.*unsafe-inline\|unsafe-inline.*script-src" "$f" 2>/dev/null || true)
   [ -n "$HITS" ] && echo "FINDING [3A] $f:" && echo "$HITS"
-done
+done <<< "$CSP_FILES"
 ```
 
 **Confirm**: Verify the CSP header applies to the production site (not just dev/storybook). Check if a nonce-based approach is already in use (nonce + unsafe-inline is still a finding but lower severity).
@@ -257,10 +263,11 @@ done
 **Check**:
 ```bash
 HEADER_FILES=$(grep -rl "X-App-Version\|X-Deployment-Color\|X-Git-Sha\|X-Build-Id\|Server:" "$REPO_PATH" --include="*.py" --include="*.ts" --include="*.js" --include="*.conf" 2>/dev/null | grep -v '.git' | grep -v node_modules)
-for f in $HEADER_FILES; do
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
   HITS=$(grep -n '"X-App-Version"\|"X-Deployment-Color"\|"X-Git-Sha"\|"X-Build-Id"\|"Server:' "$f" 2>/dev/null || true)
   [ -n "$HITS" ] && echo "FINDING [3B] $f:" && echo "$HITS"
-done
+done <<< "$HEADER_FILES"
 ```
 
 **Confirm**: Check if the header is set in a response (not just read). If set in outbound responses → confirmed finding. Internal-only APIs (not publicly routed) are `priority:P3`; public APIs are `priority:P2`.
@@ -435,14 +442,15 @@ payment_intent.payment_failed
 **Check**:
 ```bash
 WEBHOOK_FILES=$(grep -rl "stripe\|webhook" "$REPO_PATH/services" --include="*.py" 2>/dev/null | grep -v '.git' | head -10)
-for f in $WEBHOOK_FILES; do
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
   REQUIRED_EVENTS="customer.subscription.deleted invoice.payment_failed charge.refunded charge.dispute.created"
   for event in $REQUIRED_EVENTS; do
     if ! grep -q "\"$event\"\|'$event'" "$f" 2>/dev/null; then
       echo "FINDING [4A] $f: Stripe event '$event' not handled"
     fi
   done
-done
+done <<< "$WEBHOOK_FILES"
 ```
 
 **Confirm**: Verify the event type appears in a handler dispatch (not just a comment). Confirmed if the event would change user entitlements or financial state but has no handler.

package/commands/sync-ecosystem.md

@@ -444,7 +444,7 @@ npm version {minor|patch|major} --no-git-tag-version
 # 3. Commit the version bump
 NEW_VERSION=$(grep '"version"' package.json | grep -oP '\d+\.\d+\.\d+')
 git add package.json package-lock.json
-git commit -m "chore: bump version to ${NEW_VERSION}"
+git commit -s -m "chore: bump version to ${NEW_VERSION}"
 git push origin main
 
 # 4. Create GitHub Release (triggers {PUBLISH_WORKFLOW} automatically)
@@ -495,7 +495,7 @@ cd {SUBPATH} && npm version {minor|patch} --no-git-tag-version && cd -
 
 # Commit and push
 git add {SUBPATH}/pyproject.toml {SUBPATH}/package.json {SUBPATH}/package-lock.json
-git commit -m "chore({COMPONENT}): bump version to {NEW_VERSION}"
+git commit -s -m "chore({COMPONENT}): bump version to {NEW_VERSION}"
 git push origin fix/{COMPONENT}-version-bump
 
 # Create PR to {STAGING_BRANCH}, merge, then trigger publish from main