forgedock 1.0.20 → 1.0.22

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)
@@ -142,6 +147,7 @@ Append this block at the very end of your comment (after the `---` footer line,
 | API Design | `API` |
 | Database & Migration | `DB` |
 | Infrastructure | `INFRA` |
+| Config Schema | `CFG` |
 
 ### Example
 
@@ -200,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
@@ -215,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).
@@ -230,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.
@@ -258,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.
@@ -270,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.
@@ -281,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.
@@ -292,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.
@@ -304,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.
@@ -315,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`.
@@ -326,11 +341,12 @@ 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.
@@ -344,15 +360,17 @@ For each hit: read the fallback value.
 
 **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.
@@ -1413,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:**
@@ -1521,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:**
@@ -1548,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:**
@@ -1587,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:**
@@ -1605,6 +1628,54 @@ If no infra context is configured above, derive the deployment model from the ch
 
    Host-side port bindings to Docker containers are unreliable in SSH deploy contexts. Deploy scripts that invoke database tools directly cannot depend on `localhost:5432` being reachable; the same operation via `docker exec` bypasses the host network entirely and always succeeds when the container is running. <!-- Added: forge#322 -->
 
+15. **External tool config schema validation** (when any config file consumed by an external tool is in the diff — trigger: files under `traefik/`, `infra/nginx/`, `k8s/`, `terraform/`, `*.conf`, `*.toml`, or any `docker-compose*.yml` with non-trivial changes to service definitions):
+
+   **Principle: Logical correctness ≠ structural correctness.** A config can have the right values in the wrong nesting and be silently rejected by the external tool — producing zero error logs in some tools (e.g. Traefik v3 ignores unrecognized nesting silently). The INFRA agent must verify both dimensions:
+   - **Logical correctness** (covered by existing checks): Are the values coherent? Do names match across files? Is the wiring consistent with the deploy pipeline?
+   - **Structural correctness** (this check): Does the YAML/TOML/HCL structure match what the tool's actual schema expects? Are directives nested at the correct depth? Do required parent keys exist?
+
+   **For each external tool config file in the diff**:
+
+   1. **Identify the tool and version**: Read the `image:` tag in `docker-compose*.yml` for the tool (e.g., `traefik:v3.1`, `nginx:1.25`). If the tool version cannot be determined from the diff, note it as unknown.
+
+   2. **Reason about the schema**: Ask — "Does this change's structure match what `{tool} {version}` actually expects?" Key questions:
+      - Is this directive/key nested under the correct parent section?
+      - Does this version of the tool use a different config syntax than a prior version? (Version migrations often change required nesting — e.g., Traefik v2 → v3 moved many config keys to different parent sections)
+      - Are any required sibling keys missing from the changed section?
+      - Does the tool expect this value at file scope, or under a named block?
+
+   3. **Cross-reference against sibling config files**: If the project uses dynamic config loading (e.g., `traefik/dynamic/`), verify that a key defined in the static config is not also required in the dynamic config (or vice versa) for the feature to activate.
+
+   4. **Flag structural mismatches**: If any key or nesting does not match the tool's expected schema for the declared version, flag as **CONFIRMED HIGH**. Structural config mismatches are silently rejected at runtime — no startup crash, no error log, the feature simply does not activate.
+
+   ```bash
+   # Identify tool config files in the diff
+   CONFIG_TOOL_FILES=$(gh pr diff [PR_NUMBER] --name-only | grep -E \
+     "(traefik/|infra/nginx/|k8s/|terraform/|.*\.conf$|.*\.toml$)" | head -20)
+   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
+   while IFS= read -r f; do
+       [ -z "$f" ] && continue
+       echo "=== Reading full config structure: $f ==="
+       cat "$f"
+   done <<< "$CONFIG_TOOL_FILES"
+
+   # Identify tool version from docker-compose (for version-aware schema reasoning)
+   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 <<< "$COMPOSE_INFRA_FILES"
+   ```
+
+   **Severity classification**:
+   - Config key present but under wrong parent section: **CONFIRMED HIGH** — key is silently ignored; feature does not activate
+   - Required sibling key missing from changed section: **CONFIRMED HIGH** — partial config is silently incomplete
+   - Version mismatch (config uses v2 syntax on v3 tool): **CONFIRMED HIGH** — v3 silently ignores v2 keys in most tools
+   - Structural ambiguity (key could plausibly be correct but version cannot be determined): **LIKELY MEDIUM** — flag for human verification with schema reference
+
+   **Do NOT rely solely on logical correctness checks when structural correctness has not been verified.** A config that names services correctly, uses coherent values, and matches the deploy script's expectations can still be silently rejected if the nesting does not match the tool's schema. Both dimensions must be verified independently. <!-- Added: forge#1104 -->
+
 ## Post Findings
 ```bash
 gh pr comment [PR_NUMBER] --body "$(cat <<'EOF'
@@ -1679,5 +1750,6 @@ EOF
 | appleboy/ssh-action Go template safety | Item 12 | COVERED | #226 |
 | Insecure config file defaults | Item 13 | COVERED | #301 |
 | Host-side database tool invocations | Item 14 | COVERED | #322 |
+| External tool config schema validation (structural correctness) | Item 15 | COVERED | #1104 |
 | Docker image tag pinning (mutable tags) | — | GAP | |
 | Network policy / inter-container isolation | — | GAP | |

package/commands/review-pr.md

@@ -624,6 +624,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 +717,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`.
 

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

package/commands/work-on/build/architect.md

@@ -176,6 +176,11 @@ if [ -n "$DEVDOCS_PATH" ] && [ -f "$INDEX_PATH" ]; then
   ISSUE_LABELS=$(gh issue view {NUMBER} -R {GH_REPO} --json labels \
     --jq '[.labels[].name] | join(" ")' 2>/dev/null || echo "")
   echo "Issue labels: ${ISSUE_LABELS:-none}"
+  # Separate newline-joined list for the loop below — GitHub label names CAN
+  # contain spaces (e.g. "good first issue"), so the space-joined $ISSUE_LABELS
+  # above is only safe for display, never for iteration.
+  ISSUE_LABELS_LIST=$(gh issue view {NUMBER} -R {GH_REPO} --json labels \
+    --jq '.labels[].name' 2>/dev/null || echo "")
 
   # Read index content
   INDEX_CONTENT=$(cat "$INDEX_PATH" 2>/dev/null || echo "")
@@ -190,7 +195,12 @@ if [ -n "$DEVDOCS_PATH" ] && [ -f "$INDEX_PATH" ]; then
 
   # Extract domain blocks matching any issue label keyword
   DOMAIN_PATHS=""
-  for label in $ISSUE_LABELS; do
+  # $ISSUE_LABELS_LIST is one label per line — herestring (not a piped
+  # `| while read`, which would run the loop body in a subshell and discard
+  # DOMAIN_PATHS once the loop exits) preserves newline-safety for labels
+  # containing spaces.
+  while IFS= read -r label; do
+    [ -z "$label" ] && continue
     KEYWORD=$(echo "$label" | sed 's/^workflow://; s/^priority://; s/^review-finding$//')
     [ -z "$KEYWORD" ] && continue
     # Sanitize KEYWORD before AWK injection — strip chars that would break awk regex delimiters
@@ -207,7 +217,7 @@ if [ -n "$DEVDOCS_PATH" ] && [ -f "$INDEX_PATH" ]; then
       echo "Domain '${SAFE_KEYWORD}' matched — adding docs: $(echo "$BLOCK_PATHS" | tr '\n' ' ')"
       DOMAIN_PATHS="${DOMAIN_PATHS}${BLOCK_PATHS}"$'\n'
     fi
-  done
+  done <<< "$ISSUE_LABELS_LIST"
 
   # Combine always_load + domain paths (deduplicate)
   ALL_PATHS=$(printf "%s\n%s" "$ALWAYS_LOAD_PATHS" "$DOMAIN_PATHS" \
@@ -448,11 +458,45 @@ For each non-obvious interaction or potential failure mode:
 - Suggest a mitigation or check
 
 Focus on:
-- Files that have changed recently (check `git log --oneline -10 -- {FILE}`)
+- Churn / hot-spot files (see below) — high historical change frequency correlates with defect density
 - Paths that are called in both sync and async contexts
 - Any place where the change touches a serialization boundary (JSON in/out, DB read/write)
 - Unused or dormant code that the change might activate
 
+### Churn (Hot-Spot) Signal
+
+Recency alone (did the file appear in the last N commits?) is a weak, binary proxy. Compute a bounded per-file **churn tier** instead — how often each affected file has actually changed over a fixed window — and fold it into the risk table below.
+
+For each file in `{AFFECTED_FILES}` (never repo-wide — this must stay O(affected files) to fit the Phase A0–A5 time budget):
+
+```bash
+CHURN_WINDOW="90 days ago"   # named constant — must match the same window used in review-pr.md Phase 3A
+
+# {AFFECTED_FILES} is a space-separated argument (see --files contract at the top
+# of this file), not newline-separated like review-pr.md's $FILES — so a herestring
+# `while read` line-loop would misparse it as a single line. Split explicitly on
+# IFS=' ' into an array instead of relying on a bare `for FILE in {AFFECTED_FILES}`
+# (which word-splits on the shell's default IFS — space, tab, AND newline). This
+# keeps the existing space-separated contract intact while narrowing the splitting
+# surface to spaces only.
+IFS=' ' read -ra AFFECTED_FILES_ARR <<< "{AFFECTED_FILES}"
+for FILE in "${AFFECTED_FILES_ARR[@]}"; do
+  COMMITS=$(git log --oneline --since="$CHURN_WINDOW" -- "$FILE" | wc -l)
+  if [ "$COMMITS" -ge 15 ]; then TIER="HOT"
+  elif [ "$COMMITS" -ge 5 ]; then TIER="MEDIUM"
+  else TIER="LOW"
+  fi
+  echo "$FILE: $TIER ($COMMITS commits in last 90 days)"
+done
+```
+
+**Tiers** (fixed thresholds — keep identical to `review-pr.md` Phase 3A so both phases agree on what "hot" means):
+- **HOT**: 15+ commits in the window
+- **MEDIUM**: 5–14 commits in the window
+- **LOW**: 0–4 commits in the window
+
+Any file classified **HOT** MUST get an explicit row in the Risk Assessment table below (e.g. "High historical churn — {N} commits in last 90 days — changes here have a higher defect-density prior"), rated at least MEDIUM severity, with a mitigation such as "extra reviewer scrutiny" or "prefer smaller, isolated diffs to this file." MEDIUM-tier files may be noted inline without a dedicated row. LOW-tier files need no mention.
+
 ---
 
 ## Output Format