forgedock 1.0.21 → 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)
@@ -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,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.
@@ -345,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.
@@ -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:**
@@ -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

@@ -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