forgedock 1.0.21 → 1.1.1

package/commands/quality-gate.md

@@ -39,10 +39,10 @@ This quality gate uses **domain detection** to adapt to your project's actual te
 | FRONTEND | `.tsx`/`.ts` files in client component paths |
 | PROXY | Client components using `fetch`/`useSWR`/`apiFetch` |
 | SHELL | `.sh` files or scripts using `curl`/`wget` |
-| STRING_SETS | Python files in anti-detection or browser automation paths |
+| STRING_SETS | *(scraping pack — opt-in)* Python files in anti-detection or browser automation paths. Enable via `forge.yaml → quality_gate.optional_domains: [STRING_SETS]` |
 | CONCURRENCY | Python files using `asyncio.shield`, `asyncio.wait_for`, or `Task.cancel` |
 | STATE | Python files with new module-level mutable variable assignments |
-| CAPACITY | Worker/infra Python files with new size/limit/threshold constants |
+| CAPACITY | *(scraping pack — opt-in)* Worker/infra Python files with new size/limit/threshold constants. Enable via `forge.yaml → quality_gate.optional_domains: [CAPACITY]` |
 | WORKFLOW | `.yml` files in `.github/workflows/` |
 | IMPORT_RESOLUTION | Python files with new `from app.*` imports added outside `try:` blocks |
 | INFRA | Dockerfiles or entrypoints with runtime UID changes |
@@ -92,10 +92,10 @@ Before running checks, classify the changed files into domains. This avoids runn
 | `*.tsx`, `*.ts` in `web/src/` (excluding `route.ts`) | FRONTEND |
 | `*.tsx`, `*.ts` client components with fetch/useSWR | PROXY |
 | `*.sh` files or scripts with `curl`/`wget` | SHELL |
-| `*.py` in `anti_detection/`, `consumers/`, `browser/`, or `shared/detection/` | STRING_SETS |
+| `*.py` in `anti_detection/`, `consumers/`, `browser/`, or `shared/detection/` | STRING_SETS *(scraping pack — opt-in, see 2J)* |
 | `*.py` containing `asyncio.shield`, `asyncio.wait_for`, or `Task.cancel` | CONCURRENCY |
 | `*.py` files with new module-level `dict`, `set`, `Counter`, `Lock`, or `defaultdict` assignments | STATE |
-| `*.py` in `services/worker/`, `infra/`, or `browser/` with new assignments to variables containing `MB`, `SIZE`, `MAX`, `LIMIT`, `THRESHOLD`, or `TIMEOUT` | CAPACITY |
+| `*.py` in `services/worker/`, `infra/`, or `browser/` with new assignments to variables containing `MB`, `SIZE`, `MAX`, `LIMIT`, `THRESHOLD`, or `TIMEOUT` | CAPACITY *(scraping pack — opt-in, see 2K)* |
 | `*.yml` in `.github/workflows/` | WORKFLOW |
 | `*.py` with new `from app.` import statements added outside `try:` blocks | IMPORT_RESOLUTION |
 | `Dockerfile*` or `entrypoint*.sh` with added/changed `USER`, `su-exec`, `gosu`, or `setuid` | INFRA |
@@ -109,7 +109,12 @@ Before running checks, classify the changed files into domains. This avoids runn
 # Initialize domain flags
 DOMAINS=""
 
-for f in {CHANGED_FILES}; do
+# {CHANGED_FILES} is a space-separated argument (same contract as {AFFECTED_FILES}
+# in architect.md) — split explicitly on IFS=' ' into an array instead of relying
+# on a bare `for f in {CHANGED_FILES}`, which word-splits on the shell's default
+# IFS (space, tab, AND newline) and would corrupt any path containing a space.
+IFS=' ' read -ra CHANGED_FILES_ARR <<< "{CHANGED_FILES}"
+for f in "${CHANGED_FILES_ARR[@]}"; do
     case "$f" in
         *.sql|*migrations/*) DOMAINS="$DOMAINS DATABASE" ;;
     esac
@@ -126,7 +131,12 @@ for f in {CHANGED_FILES}; do
     esac
     case "$f" in
         *anti_detection/*|*consumers/*|*browser/*|*shared/detection/*)
-            echo "$f" | grep -qE '\.py$' && DOMAINS="$DOMAINS STRING_SETS"
+            # STRING_SETS is a scraping-pack domain — opt-in via forge.yaml → quality_gate.optional_domains
+            # <!-- Updated: forge#1349 — not enabled by default; scraping-product-specific -->
+            if echo "$f" | grep -qE '\.py$'; then
+                _OPT_DOMAINS=$(grep -A5 'optional_domains:' "{WORKTREE_PATH}/forge.yaml" 2>/dev/null | grep -oE 'STRING_SETS' | head -1 || true)
+                [ -n "$_OPT_DOMAINS" ] && DOMAINS="$DOMAINS STRING_SETS"
+            fi
             ;;
     esac
     case "$f" in
@@ -144,34 +154,45 @@ grep -lE "asyncio\.shield|asyncio\.wait_for|Task\.cancel" {CHANGED_FILES} 2>/dev
 grep -lE "^\w+ = (\{\}|\[\]|set\(\)|Lock\(\)|defaultdict|Counter)" {CHANGED_FILES} 2>/dev/null | grep -qE '\.py$' && DOMAINS="$DOMAINS STATE"
 
 # Check for capacity constants in worker/infra/browser Python files
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'services/worker/|infra/|browser/'); do
-    git diff HEAD -- "$f" 2>/dev/null | grep -qE '^\+[A-Za-z_]\w*(MB|SIZE|MAX|LIMIT|THRESHOLD|TIMEOUT)\w*\s*=' && DOMAINS="$DOMAINS CAPACITY" && break
-done
+# CAPACITY is a scraping-pack domain — opt-in via forge.yaml → quality_gate.optional_domains
+# <!-- Updated: forge#1349 — not enabled by default; scraping-product-specific -->
+_OPT_CAPACITY=$(grep -A5 'optional_domains:' "{WORKTREE_PATH}/forge.yaml" 2>/dev/null | grep -oE 'CAPACITY' | head -1 || true)
+if [ -n "$_OPT_CAPACITY" ]; then
+    while IFS= read -r f; do
+        [ -z "$f" ] && continue
+        git diff HEAD -- "$f" 2>/dev/null | grep -qE '^\+[A-Za-z_]\w*(MB|SIZE|MAX|LIMIT|THRESHOLD|TIMEOUT)\w*\s*=' && DOMAINS="$DOMAINS CAPACITY" && break
+    done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'services/worker/|infra/|browser/')
+fi
 
 # Check for env var usage in changed files
 grep -lE "os\.getenv|process\.env" {CHANGED_FILES} 2>/dev/null && DOMAINS="$DOMAINS DEPLOY"
 
 # Check for new app.* imports added outside try: blocks in Python files
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     NEW_IMPORTS=$(git diff HEAD -- "$f" 2>/dev/null | grep -E '^\+\s*(from app\.|import app\.)' | grep -v '^+++')
     if [ -n "$NEW_IMPORTS" ]; then
         DOMAINS="$DOMAINS IMPORT_RESOLUTION"
         break
     fi
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$')
 
 # Check for runtime UID changes in Dockerfiles or entrypoint scripts
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -iE 'Dockerfile|entrypoint.*\.sh'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     git diff HEAD -- "$f" 2>/dev/null | grep -E '^\+.*(USER\s+[^0]|su-exec|gosu|setuid)' | grep -v '^+++' | grep -q . && DOMAINS="$DOMAINS INFRA" && break
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -iE 'Dockerfile|entrypoint.*\.sh')
 
 # Check for gate condition narrowing in router Python files (condition removal = fix may be incomplete across siblings)
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'router'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     git diff HEAD -- "$f" 2>/dev/null | grep -E '^-.*\bif\b.*\bor\b' | grep -v '^---' | grep -q . && DOMAINS="$DOMAINS ROUTER_BUG" && break
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'router')
 
 # Check for external tool config files (structural schema validation advisory)
-for f in {CHANGED_FILES}; do
+# {CHANGED_FILES} is space-separated (see array-split note above) — reuse the
+# same CHANGED_FILES_ARR built above instead of re-splitting.
+for f in "${CHANGED_FILES_ARR[@]}"; do
     case "$f" in
         traefik/*|infra/nginx/*|k8s/*|terraform/*)
             DOMAINS="$DOMAINS CONFIG_SCHEMA" && break ;;
@@ -228,7 +249,11 @@ For every changed file, check:
 
 ```bash
 # Quick automated checks
-for f in {CHANGED_FILES}; do
+# {CHANGED_FILES} is a space-separated argument — split explicitly on IFS=' '
+# into an array instead of a bare `for f in {CHANGED_FILES}` (see Step 1.5 for
+# the full rationale; this is a separate bash block so the array is rebuilt here).
+IFS=' ' read -ra CHANGED_FILES_ARR <<< "{CHANGED_FILES}"
+for f in "${CHANGED_FILES_ARR[@]}"; do
     # f-string SQL
     grep -nE "f['\"].*SELECT|f['\"].*INSERT|f['\"].*UPDATE|f['\"].*DELETE|f['\"].*WHERE" "$f" 2>/dev/null && echo "SEC: f-string SQL in $f"
     # Hardcoded secrets
@@ -251,15 +276,28 @@ done
 ### 2B: Auth conventions (Python routers, TypeScript route handlers)
 
 For new/modified endpoints:
-1. Which auth dependency is used — `SessionUser` or `CurrentUser`?
-2. Does the route path match? Dashboard routes (`/api/dashboard/*`) must use `SessionUser`. Public API routes (`/api/v1/*`) must use `CurrentUser`.
-3. Does the endpoint check resource ownership (`user_id`) before returning data?
+1. Which auth dependency is used? Read `forge.yaml → review.domains.auth` for the configured dependency name(s). If absent, skip the naming check and fall back to generic resource-ownership verification only.
+2. Does the endpoint check resource ownership (`user_id` or equivalent) before returning data?
+
+Route-path-to-dependency convention (e.g. "dashboard routes must use X, public routes must use Y") is project-specific. Configure it in `forge.yaml → review.domains.auth` if your project uses one. Do not enforce a hard-coded convention universally. <!-- Updated: forge#1349 — removed hardcoded SessionUser/CurrentUser rule -->
 
 ```bash
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E 'router|route'); do
-    grep -nE "CurrentUser|SessionUser|Depends\(get_" "$f" 2>/dev/null
+# Read configured auth dependency names from forge.yaml (if present)
+AUTH_DEPS=""
+if [ -f "{WORKTREE_PATH}/forge.yaml" ]; then
+    AUTH_DEPS=$(grep -A5 'domains:' "{WORKTREE_PATH}/forge.yaml" 2>/dev/null \
+        | grep -A3 'auth:' | grep -oE '[A-Za-z_]+User|[A-Za-z_]+Auth|get_[a-z_]+' | sort -u | tr '\n' '|' | sed 's/|$//')
+fi
+
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    if [ -n "$AUTH_DEPS" ]; then
+        grep -nE "($AUTH_DEPS)|Depends\(get_" "$f" 2>/dev/null
+    else
+        grep -nE "Depends\(get_" "$f" 2>/dev/null
+    fi
     grep -nE "@router\.(get|post|put|delete)" "$f" 2>/dev/null
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E 'router|route')
 ```
 
 ### 2C: Deploy chain (when new env vars are introduced)
@@ -270,8 +308,13 @@ if [ -n "$NEW_ENVS" ]; then
     for var in $NEW_ENVS; do
         # Check if it exists in .env.example
         grep -q "$var" .env.example 2>/dev/null || echo "DEPLOY: $var not in .env.example"
-        # Check if it's in decrypt-secrets.sh ENV_MAPPING
-        grep -q "$var" scripts/decrypt-secrets.sh 2>/dev/null || echo "DEPLOY: $var not in decrypt-secrets.sh ENV_MAPPING"
+        # Check decrypt-secrets.sh ENV_MAPPING only when the SOPS mapping script exists.
+        # Emitting a finding for a file that doesn't exist in the repo produces false BLOCKINGs
+        # on non-SOPS repos. Use verify-sops-chain.sh for the full SOPS chain check instead.
+        # <!-- Updated: forge#1349 — gate on file presence -->
+        if [ -f "{WORKTREE_PATH}/scripts/decrypt-secrets.sh" ]; then
+            grep -q "$var" "{WORKTREE_PATH}/scripts/decrypt-secrets.sh" 2>/dev/null || echo "DEPLOY: $var not in decrypt-secrets.sh ENV_MAPPING"
+        fi
     done
 fi
 ```
@@ -286,34 +329,31 @@ For each `.sql` file:
 5. **Migration number collision**: Check against origin branch
 
 ```bash
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep '\.sql$'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     grep -nE "ADD COLUMN.*NOT NULL" "$f" | grep -v "DEFAULT" && echo "DB: NOT NULL without DEFAULT in $f"
     grep -nE "DROP (TABLE|COLUMN|INDEX)" "$f" | grep -v "IF EXISTS" && echo "DB: DROP without IF EXISTS in $f"
     grep -nE "SELECT.*FROM" "$f" | grep -v "LIMIT" | grep -v "WHERE.*created_at" && echo "DB: possibly unbounded query in $f"
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep '\.sql$')
 
 # Migration prefix collision scan (Deploy Gate — HIGH)
-# Runs whenever any SQL file changed. Scans the full infra/migrations/ tree for duplicate
-# numeric prefixes not in GRANDFATHERED_DUPLICATES. Duplicates not in the allowlist WILL
-# hard-fail deploy-production.yml's validate-migration-order.sh gate.
+# Runs whenever any SQL file changed. Scans the configured migrations directory for
+# duplicate numeric prefixes. Duplicate prefixes can cause ordering conflicts during deploy.
+# <!-- Updated: forge#1349 — removed stale validate-migration-order.sh reference (script does not exist) -->
 MIGRATIONS_DIR="{WORKTREE_PATH}/infra/migrations"
+# Support configured migration directory from forge.yaml (if set)
+if [ -f "{WORKTREE_PATH}/forge.yaml" ]; then
+    _CONFIGURED_MIGRATIONS=$(grep -E '^\s*migrations_dir:' "{WORKTREE_PATH}/forge.yaml" 2>/dev/null \
+        | head -1 | sed 's/.*migrations_dir:[[:space:]]*//' | tr -d '"' | tr -d "'" | xargs)
+    [ -n "$_CONFIGURED_MIGRATIONS" ] && MIGRATIONS_DIR="{WORKTREE_PATH}/${_CONFIGURED_MIGRATIONS}"
+fi
 if [ -d "$MIGRATIONS_DIR" ]; then
-    # Extract grandfathered prefixes from validate-migration-order.sh if it exists
-    GRANDFATHER_SCRIPT="{WORKTREE_PATH}/scripts/validate-migration-order.sh"
-    GRANDFATHERED=""
-    if [ -f "$GRANDFATHER_SCRIPT" ]; then
-        GRANDFATHERED=$(grep -oE '[0-9]{4}' "$GRANDFATHER_SCRIPT" | sort -u | tr '\n' ' ')
-    fi
     # Find duplicate numeric prefixes across all migration files
     DUPLICATE_PREFIXES=$(ls "$MIGRATIONS_DIR"/*.sql 2>/dev/null \
         | sed 's|.*/\([0-9]*\)_.*|\1|' \
         | sort | uniq -d)
     for prefix in $DUPLICATE_PREFIXES; do
-        if echo "$GRANDFATHERED" | grep -qw "$prefix"; then
-            echo "DB: migration prefix $prefix is duplicated but grandfathered (INFO)"
-        else
-            echo "DB-COLLISION | HIGH | infra/migrations/ | Duplicate migration prefix $prefix is NOT grandfathered — will hard-fail deploy-production.yml validate-migration-order.sh gate. Classify as CRITICAL BLOCKER."
-        fi
+        echo "DB-COLLISION | HIGH | $MIGRATIONS_DIR | Duplicate migration prefix $prefix — ordering conflict will occur during deploy. Classify as CRITICAL BLOCKER."
     done
 fi
 ```
@@ -330,7 +370,8 @@ For each `.tsx`/`.ts` client component:
 7. **Rules of Hooks**: Do function components avoid early returns before hook calls?
 
 ```bash
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.tsx?$' | grep -v 'route\.ts'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     # Check for useEffect without cleanup (basic heuristic)
     grep -c "useEffect" "$f" 2>/dev/null
     grep -c "return.*cleanup\|return.*\(\) =>" "$f" 2>/dev/null
@@ -370,15 +411,35 @@ for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.tsx?$' | grep -v 'rou
         }
         in_component && /\buse[A-Z]/ { found_hook=1 }
     ' FILENAME="$f" "$f" 2>/dev/null
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.tsx?$' | grep -v 'route\.ts')
 ```
 
 ### 2F: Frontend proxy wiring (client-side fetch calls)
 
+The direct-backend path prefix to flag is read from `forge.yaml → review.layout.direct_api_prefix`.
+If absent, defaults to `/api/v1/` (backward compatible). This prevents false findings on projects
+that use a different API path scheme. <!-- Updated: forge#1349 — gate on forge.yaml, not hardcoded prefix -->
+
 ```bash
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.(tsx?|jsx?)$' | grep -v 'route\.ts$'); do
-    grep -nE '(fetch|useSWR|apiFetch)\s*[(<]\s*[`"'"'"']/api/v1/' "$f" 2>/dev/null && echo "PROXY: direct /api/v1/ call in $f — must use /api/ proxy"
-done
+# Read configured direct API prefix from forge.yaml, fall back to /api/v1/
+DIRECT_API_PREFIX="/api/v1/"
+if [ -f "{WORKTREE_PATH}/forge.yaml" ]; then
+    _CONFIGURED_PREFIX=$(grep -E '^\s*direct_api_prefix:' "{WORKTREE_PATH}/forge.yaml" 2>/dev/null \
+        | head -1 | sed 's/.*direct_api_prefix:[[:space:]]*//' | tr -d '"' | tr -d "'" | xargs)
+    # Also check under review.layout section
+    if [ -z "$_CONFIGURED_PREFIX" ]; then
+        _CONFIGURED_PREFIX=$(grep -A 10 'layout:' "{WORKTREE_PATH}/forge.yaml" 2>/dev/null \
+            | grep -E '^\s*direct_api_prefix:' \
+            | head -1 | sed 's/.*direct_api_prefix:[[:space:]]*//' | tr -d '"' | tr -d "'" | xargs)
+    fi
+    [ -n "$_CONFIGURED_PREFIX" ] && DIRECT_API_PREFIX="$_CONFIGURED_PREFIX"
+fi
+ESCAPED_PREFIX=$(printf '%s' "$DIRECT_API_PREFIX" | sed 's|/|\\/|g')
+
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    grep -nE "(fetch|useSWR|apiFetch)\\s*[(<]\\s*[\`\"']${ESCAPED_PREFIX}" "$f" 2>/dev/null && echo "PROXY: direct ${DIRECT_API_PREFIX} call in $f — must use /api/ proxy (configure review.layout.direct_api_prefix in forge.yaml to change the flagged prefix)"
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.(tsx?|jsx?)$' | grep -v 'route\.ts$')
 ```
 
 ### 2G: Cross-service integration (shell scripts with curl/wget)
@@ -413,7 +474,8 @@ The script `verify-host-headers.sh` checks for the `FORGE_INTERNAL_PATTERNS` env
 **Why this matters**: Every DB connection function in a deploy script must use `${POSTGRES_HOST:-localhost}` (or equivalent env var interpolation), not a bare `"localhost"` string literal. A hardcoded `"localhost"` works in local development but fails in any environment where PostgreSQL runs on a separate host. The pattern is reliably grep-detectable. <!-- Added: forge#303 -->
 
 ```bash
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.sh$'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
   # Only check files that contain DB connection tools
   if grep -qE "PGPASSWORD|createdb|psql|pg_dump|pg_restore" "$f" 2>/dev/null; then
     # Look for new/modified lines with hardcoded localhost in variable assignments
@@ -428,7 +490,7 @@ for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.sh$'); do
       echo "$HARDCODED"
     fi
   fi
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.sh$')
 ```
 
 Report any hit as **HIGH** — the DB connection will fail in any environment where PostgreSQL is not on `127.0.0.1:5432`.
@@ -494,7 +556,8 @@ Report each conflict as **HIGH** — a shadowed native command is a silent user-
 **Severity**: MEDIUM (flags for review, not auto-blocking). The review agent's concurrency auditor verifies with full context.
 
 ```bash
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     # asyncio.shield usage — outer await may be reached with pending CancelledError
     grep -nE "asyncio\.shield" "$f" 2>/dev/null && \
         echo "ASYNC: asyncio.shield in $f — verify outer await isn't reachable with pending CancelledError. Prefer loop.create_task() for fire-and-forget."
@@ -509,7 +572,7 @@ for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$'); do
         sed -n "$((LINENO+1)),$((LINENO+5))p" "$f" | grep -q "await" && \
             echo "ASYNC: await in except/finally block at $f:$LINENO — may fail if CancelledError is pending"
     done
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$')
 ```
 
 
@@ -532,7 +595,8 @@ For each new module-level state variable in the diff:
    ```
 
 ```bash
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     # Find new module-level state variables introduced in the diff
     NEW_VARS=$(git diff HEAD -- "$f" 2>/dev/null | grep -E '^\+[A-Za-z_]\w* = (\{\}|\[\]|set\(\)|Lock\(\)|defaultdict|Counter)' | grep -oE '^[+][A-Za-z_]\w*' | tr -d '+' | sort -u)
     for new_var in $NEW_VARS; do
@@ -549,16 +613,18 @@ for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$'); do
             done
         done
     done
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$')
 ```
 
 **Severity**: MEDIUM — missing a mutation site is usually a latent bug, not an immediate crash, but it causes incorrect behavior under concurrent load.
 
 ---
 
-### 2J: String literal consistency (anti-detection/scraping code)
+### 2J: String literal consistency (anti-detection/scraping code) *(Scraping Pack — opt-in)*
+
+> **This domain is opt-in and disabled by default.** It is specific to scraping/anti-detection products and produces false findings on general repos. Enable it by adding `STRING_SETS` to `forge.yaml → quality_gate.optional_domains`. <!-- Added: forge#1349 -->
 
-**Triggered when**: changed files include Python files in `anti_detection/`, `consumers/`, `browser/`, or `shared/detection/` directories.
+**Triggered when**: changed files include Python files in `anti_detection/`, `consumers/`, `browser/`, or `shared/detection/` directories AND `STRING_SETS` is in `forge.yaml → quality_gate.optional_domains`.
 
 **Why this matters**: Detection keyword sets (e.g., `CHALLENGE_KEYWORDS`, `COMMON_COOKIES`) across related modules share a domain truth — if Akamai adds a new cookie marker, it must appear in ALL related sets. A typo or omission in one set silently breaks detection for that service path. This check catches both inter-file inconsistencies and intra-file comment/code drift.
 
@@ -567,11 +633,12 @@ For each changed file in the anti-detection/scraping domains:
 **1. Identify modified string identifier sets** (frozensets, tuples, or lists of string literals used for detection):
 
 ```bash
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'anti_detection/|consumers/|browser/|shared/detection/'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     echo "=== String sets in $f ==="
     # Find named constants that are frozenset/tuple/list of strings
     grep -nE "^[A-Z_]+ = (frozenset|tuple|set)\(\[?['\"]|^[A-Z_]+ = \(['\"]|^[A-Z_]+ = \[['\"]" "$f" 2>/dev/null
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'anti_detection/|consumers/|browser/|shared/detection/')
 ```
 
 **2. For each string in a modified set, check if it appears in sibling detection files:**
@@ -579,7 +646,8 @@ done
 ```bash
 SERVICE_DIR=$(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E 'anti_detection/|consumers/|browser/' | head -1 | grep -oE '^services/[^/]+/[^/]+' || echo "services/worker/worker")
 
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'anti_detection/|consumers/|browser/|shared/detection/'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     # Extract string values from detection sets in this file
     STRINGS=$(grep -oE "'[a-z_][a-z0-9_-]*'" "$f" 2>/dev/null | tr -d "'" | sort -u)
     for s in $STRINGS; do
@@ -587,13 +655,14 @@ for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'anti_
         FOUND=$(grep -rl "\"$s\"\|'$s'" $SERVICE_DIR/ 2>/dev/null | grep -v "^$f$" | grep '\.py$' | head -1)
         [ -z "$FOUND" ] && echo "STR: '$s' in $f appears NOWHERE else in $SERVICE_DIR — possible typo or dead entry"
     done
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'anti_detection/|consumers/|browser/|shared/detection/')
 ```
 
 **3. Check for identifiers mentioned in comments/docstrings of the SAME file that are NOT in the actual set** (catches the `abck` vs `_abck` class of bug):
 
 ```bash
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'anti_detection/|consumers/|browser/|shared/detection/'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     echo "=== Comment/code drift in $f ==="
     # Extract string literals from actual sets (remove quotes)
     SET_STRINGS=$(grep -oE "frozenset\(\[([^]]+)\]\)" "$f" 2>/dev/null | grep -oE "'[^']+'" | tr -d "'" | sort -u)
@@ -605,20 +674,25 @@ for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'anti_
     for ref in $COMMENT_REFS; do
         echo "$SET_STRINGS" | grep -q "^${ref}$" || echo "STR: '$ref' mentioned in comment in $f but NOT found in any string set — possible omission or typo"
     done
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'anti_detection/|consumers/|browser/|shared/detection/')
 ```
 
 **4. Cross-reference sibling sets in related modules** (the primary inter-file check):
 
 ```bash
 # Find all detection-related Python files in the same service
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'anti_detection/|consumers/|browser/'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     SIBLINGS=$(find $(dirname "$f")/../ -name "*.py" -path "*/anti_detection/*" -o -name "*.py" -path "*/consumers/*" -o -name "*.py" -path "*/browser/*" 2>/dev/null | grep -v "^$f$" | head -10)
 
     # Extract detection set names from the changed file
     SET_NAMES=$(grep -oE "^[A-Z_]+ = (frozenset|tuple|set)" "$f" 2>/dev/null | grep -oE "^[A-Z_]+")
 
-    for sib in $SIBLINGS; do
+    # $SIBLINGS is one file path per line (`find`) — herestring (not a piped
+    # `| while read`, which would run the loop body in a subshell and discard
+    # any accumulator set inside it) preserves newline-safety for paths with spaces.
+    while IFS= read -r sib; do
+        [ -z "$sib" ] && continue
         # Extract strings from sibling detection sets
         SIB_STRINGS=$(grep -oE "'[a-z_][a-z0-9_-]*'" "$sib" 2>/dev/null | tr -d "'" | sort -u)
 
@@ -629,8 +703,8 @@ for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'anti_
             echo "$SIB_STRINGS" | grep -q "^${s}$" || \
                 echo "STR: '$s' in $f not found in sibling file $sib — verify if cross-module consistency is required"
         done
-    done
-done
+    done <<< "$SIBLINGS"
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'anti_detection/|consumers/|browser/')
 ```
 
 **Flag as findings**:
@@ -640,16 +714,19 @@ done
 
 ---
 
-### 2K: Capacity constant validation (worker/infra code)
+### 2K: Capacity constant validation (worker/infra code) *(Scraping Pack — opt-in)*
+
+> **This domain is opt-in and disabled by default.** It is specific to scraping/browser-pool products and produces false findings on general repos. Enable it by adding `CAPACITY` to `forge.yaml → quality_gate.optional_domains`. <!-- Added: forge#1349 -->
 
-**Triggered when**: changed Python files in `services/worker/`, `infra/`, or `browser/` introduce new assignments to variables whose names contain `MB`, `SIZE`, `MAX`, `LIMIT`, `THRESHOLD`, or `TIMEOUT`.
+**Triggered when**: changed Python files in `services/worker/`, `infra/`, or `browser/` introduce new assignments to variables whose names contain `MB`, `SIZE`, `MAX`, `LIMIT`, `THRESHOLD`, or `TIMEOUT` AND `CAPACITY` is in `forge.yaml → quality_gate.optional_domains`.
 
 **Why this matters**: Hardcoded capacity constants (e.g., `_BROWSER_ESTIMATED_MB = 200`) are design-time guesses that drift from production reality. When used in guard conditions (e.g., "5 × 200 MB = 1000 MB peak"), a wrong constant directly limits system throughput and may never be caught until a slot fails to spawn. A constant is correctly-typed and correctly-used but factually wrong — logic checks pass, the bug ships.
 
 For each new or modified capacity constant in the diff:
 
 ```bash
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'services/worker/|infra/|browser/'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     # Find new capacity constant assignments introduced by this diff
     NEW_CAPS=$(git diff HEAD -- "$f" 2>/dev/null | grep -E '^\+[A-Za-z_]\w*(MB|SIZE|MAX|LIMIT|THRESHOLD|TIMEOUT)\w*\s*=' | grep -oE '^[+][A-Za-z_]\w+' | tr -d '+' | sort -u)
     for cap_var in $NEW_CAPS; do
@@ -667,7 +744,7 @@ for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'servi
         git log --all -15 --oneline --grep="memory" 2>/dev/null | head -5
         git log --all -15 --oneline --grep="$(echo $keywords | cut -d' ' -f1)" 2>/dev/null | head -5
     done
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'services/worker/|infra/|browser/')
 ```
 
 **Flag as findings**:
@@ -685,7 +762,8 @@ done
 **Why this matters**: `appleboy/ssh-action` processes every `script:` field through Go's `text/template` engine **client-side, before SSH transmission**. Any `{{` in the script — including in comments, `docker ps --format` strings, and `docker inspect --format` strings — is interpreted as a Go template directive. If the expression does not resolve against the action's data context (which is an empty map for `appleboy/ssh-action`), the step exits with status 1 **before the script reaches the remote shell**. Shell error handlers (`|| fallback`, `2>/dev/null`, `set -e`) are completely bypassed. `continue-on-error: true` masks the failure silently, producing apparent deploy success with no remote shell output.
 
 ```bash
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.github/workflows/.*\.yml$'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     if grep -q "appleboy/ssh-action" "$f"; then
         TEMPLATE_HITS=$(grep -n "{{" "$f")
         if [ -n "$TEMPLATE_HITS" ]; then
@@ -702,7 +780,7 @@ for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.github/workflows/.*\.
             echo "  docker ps --format json | jq -r '.Status'"
         fi
     fi
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.github/workflows/.*\.yml$')
 ```
 
 Report any hit as **CONFIRMED HIGH** — the step will exit 1 before reaching the remote shell.
@@ -718,7 +796,8 @@ Go template directives in `appleboy/ssh-action` `script:` blocks are preprocesse
 ```bash
 PR_BASE="${PR_BASE:-staging}"
 
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     # Extract new app.* import statements added in the diff
     # Only consider lines added (starting with +), skip diff headers (+++)
     NEW_IMPORTS=$(git diff HEAD -- "$f" 2>/dev/null | grep -E '^\+\s*(from app\.|import app\.)' | grep -v '^+++' | sed 's/^+//')
@@ -752,7 +831,7 @@ for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$'); do
             fi
         fi
     done
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$')
 ```
 
 **Flag as findings**:
@@ -775,20 +854,24 @@ A builder agent working in a milestone-branch worktree has access to milestone-o
 # Step 1: Identify the service directory from the changed Dockerfile/entrypoint path
 # e.g. services/worker/Dockerfile → service root = services/worker/
 SERVICE_DIR=""
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -iE 'Dockerfile|entrypoint.*\.sh'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     SERVICE_DIR=$(dirname "$f")
     break
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -iE 'Dockerfile|entrypoint.*\.sh')
 
 if [ -n "$SERVICE_DIR" ]; then
     # Step 2: Find volume mount points for this service in any docker-compose*.yml
     COMPOSE_FILES=$(find . -maxdepth 3 -name "docker-compose*.yml" 2>/dev/null | sort)
     VOLUME_MOUNTS=""
-    for cf in $COMPOSE_FILES; do
+    # $COMPOSE_FILES is one path per line (`find`) — herestring, not a piped
+    # `| while read`, so VOLUME_MOUNTS remains visible after the loop exits.
+    while IFS= read -r cf; do
+        [ -z "$cf" ] && continue
         # Extract named volume mount points (lines like: - volume_name:/container/path)
         MOUNTS=$(grep -oE '[a-z_-]+:/[^: ]+' "$cf" 2>/dev/null | grep -v '^#' | cut -d: -f2)
         VOLUME_MOUNTS="$VOLUME_MOUNTS $MOUNTS"
-    done
+    done <<< "$COMPOSE_FILES"
 
     # Step 3: Grep the service directory for filesystem write operations
     WRITE_OPS=$(grep -rn "mkdir\|write_bytes\|open(.*['\"]w\|makedirs\|shutil\.copy\|shutil\.move" \
@@ -818,7 +901,8 @@ fi
 ```bash
 PR_BASE="${PR_BASE:-staging}"
 
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'router'); do
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     # Extract removed condition lines from the diff (lines starting with -)
     REMOVED_CONDITIONS=$(git diff HEAD -- "$f" 2>/dev/null | grep -E '^-.*\bif\b' | grep -v '^---' | sed 's/^-//' | sed 's/^\s*//' | head -5)
 
@@ -841,7 +925,7 @@ for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'route
             fi
         done
     fi
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'router')
 ```
 
 **Flag as findings**:
@@ -872,7 +956,11 @@ if [ -n "$TOOL_FILES" ]; then
     WORKFLOW_DIR="{WORKTREE_PATH}/.github/workflows"
     CI_MISSING=""
 
-    for f in $TOOL_FILES; do
+    # $TOOL_FILES is one path per line (already newline-split above via `tr`) —
+    # herestring, not a piped `| while read`, so CI_MISSING remains visible
+    # after the loop exits.
+    while IFS= read -r f; do
+        [ -z "$f" ] && continue
         case "$f" in
             traefik/*)
                 grep -rlE "traefik.*validate|traefik.*check" "$WORKFLOW_DIR" 2>/dev/null | grep -q . || \
@@ -892,7 +980,7 @@ if [ -n "$TOOL_FILES" ]; then
                     CI_MISSING="$CI_MISSING terraform"
                 ;;
         esac
-    done
+    done <<< "$TOOL_FILES"
 
     # Deduplicate
     CI_MISSING=$(echo "$CI_MISSING" | tr ' ' '\n' | sort -u | grep -v '^$' | tr '\n' ' ')