forgedock 1.0.22 → 1.1.2

package/commands/quality-gate.md

@@ -13,7 +13,10 @@ You are a quality gate that runs AFTER implementation but BEFORE commit. Your jo
 
 You do NOT post to GitHub. You do NOT create issues. You return findings directly to the builder agent that spawned you.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
+**NEVER use plan mode (EnterPlanMode).**
+
+<!-- FORGE:SPEC_LOADED — quality-gate.md loaded and active. Agent is bound by this spec. -->
 
 ---
 
@@ -39,16 +42,17 @@ 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 |
 | ROUTER_BUG | Router Python files where gate conditions are narrowed |
 | FORGE_GRAPH | `commands/*.md` specs or `scripts/*` files change (ForgeDock self-consistency) |
 | CONFIG_SCHEMA | Config files for external tools (`traefik/`, `infra/nginx/`, `k8s/`, `terraform/`, `*.conf`, `*.toml` in infra paths, or `docker-compose*.yml` with service definition changes) |
+| BILLING | Files under `billing/`, `credits/`, `subscription`, `ledger`, or `payment` paths |
 
 **Stack-agnostic coverage**: The example domains above reflect common patterns caught in production; they are not requirements. A Go or Ruby project benefits from SECURITY checks. A Node.js project benefits from FRONTEND, PROXY, and DEPLOY checks. Any project benefits from DATABASE and WORKFLOW checks when those file types are present. The stack-specific examples (Python routers, SOPS secrets chain, FastAPI layouts, appleboy SSH deploys) are illustrative — the domain detection system applies the applicable subset to any codebase.
 
@@ -88,14 +92,15 @@ Before running checks, classify the changed files into domains. This avoids runn
 | `*.py` in `routers/` or `route.ts` handlers | AUTH |
 | `*.py`, `*.ts`, `*.tsx`, `*.sh` (any code file) | SECURITY (always) |
 | Files containing `os.getenv` or `process.env` | DEPLOY |
-| `*.sql` or files in `migrations/` | DATABASE |
+| `*.sql`, files in `migrations/`, or `*migrations/*.py` (Alembic) | DATABASE |
+| Files under `billing/`, `credits/`, `subscription`, `ledger`, or `payment` paths | BILLING |
 | `*.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 |
@@ -116,7 +121,10 @@ DOMAINS=""
 IFS=' ' read -ra CHANGED_FILES_ARR <<< "{CHANGED_FILES}"
 for f in "${CHANGED_FILES_ARR[@]}"; do
     case "$f" in
-        *.sql|*migrations/*) DOMAINS="$DOMAINS DATABASE" ;;
+        *.sql|*migrations/*|*migrations/*.py) DOMAINS="$DOMAINS DATABASE" ;;
+    esac
+    case "$f" in
+        *billing/*|*credits/*|*subscription*|*ledger*|*payment*) DOMAINS="$DOMAINS BILLING" ;;
     esac
     case "$f" in
         *router*|*route.ts) DOMAINS="$DOMAINS AUTH" ;;
@@ -131,7 +139,12 @@ for f in "${CHANGED_FILES_ARR[@]}"; 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
@@ -149,10 +162,15 @@ 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
-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/')
+# 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"
@@ -226,6 +244,9 @@ Run ONLY the checks whose domain was identified in Step 1.5. Skip checks for dom
 - **2N (Runtime UID × filesystem write)**: Run if `INFRA` in DOMAINS
 - **2O (Residual pattern check)**: Run if `ROUTER_BUG` in DOMAINS
 - **2P (External tool config schema)**: Run if `CONFIG_SCHEMA` in DOMAINS
+- **2Q (Billing)**: Run if `BILLING` in DOMAINS
+- **2R (Registry checks)**: ALWAYS run — executes all promoted checks from `scripts/check-registry/manifest.json` <!-- Added: forge#1331 -->
+- **2S (Test failure classification)**: Run if any Step 2 check invoked a test suite and it failed — classifies the failure as PRE_BROKEN, FLAKY, or REAL using `scripts/flaky-quarantine.sh` <!-- Added: forge#1336 -->
 
 ### 2A: Security (ALL files)
 
@@ -266,14 +287,26 @@ 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
+# 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
-    grep -nE "CurrentUser|SessionUser|Depends\(get_" "$f" 2>/dev/null
+    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 < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E 'router|route')
 ```
@@ -286,20 +319,26 @@ 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
 ```
 
-### 2D: Database quality (SQL migration files)
+### 2D: Database quality (SQL migration files and Alembic Python migrations)
 
-For each `.sql` file:
+For each `.sql` file or Alembic migration `.py` file:
 1. **NOT NULL without DEFAULT**: `ALTER TABLE ... ADD COLUMN ... NOT NULL` without `DEFAULT` locks table and fails on existing rows
 2. **DROP without IF EXISTS**: Fails on fresh databases
 3. **Missing indexes**: New columns used in WHERE/JOIN without indexes
 4. **Unbounded queries**: SELECT without LIMIT or time-bound WHERE clause
 5. **Migration number collision**: Check against origin branch
+6. **IF NOT EXISTS guard**: `CREATE TABLE`/`CREATE INDEX` without `IF NOT EXISTS` guard fails on re-run
 
 ```bash
 while IFS= read -r f; do
@@ -307,30 +346,39 @@ while IFS= read -r f; do
     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 < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep '\.sql$')
+    # IF NOT EXISTS guard check — CREATE TABLE/INDEX without guard fails on replay or repeated apply
+    grep -nE "^\s*(CREATE TABLE|CREATE INDEX|CREATE UNIQUE INDEX)\b" "$f" | grep -iv "IF NOT EXISTS" && \
+        echo "DB-GUARD | MEDIUM | $f | CREATE TABLE/INDEX without IF NOT EXISTS guard — statement will fail on re-run or fresh database replay. Add IF NOT EXISTS."
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.sql$')
+
+# Also run structural checks on Alembic Python migration files
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    # Check for op.create_table / op.create_index without if_not_exists or checkfirst guard
+    grep -nE "\bop\.create_table\b|\bop\.create_index\b" "$f" | grep -iv "if_not_exists\|checkfirst" && \
+        echo "DB-GUARD | MEDIUM | $f | op.create_table/op.create_index without if_not_exists/checkfirst guard — will fail on replay. Add if_not_exists=True or checkfirst=True."
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E 'migrations/.*\.py$')
 
 # 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 or Alembic Python migration file changed. Scans the configured
+# migrations directory for duplicate numeric prefixes (both .sql and .py files).
+# Duplicate prefixes can cause ordering conflicts during deploy.
+# <!-- Updated: forge#1349 — removed stale validate-migration-order.sh reference (script does not exist) -->
+# <!-- Updated: forge#1329 — extended collision scan to cover .py Alembic migration files -->
 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 \
+    # Find duplicate numeric prefixes across all migration files (.sql and .py)
+    DUPLICATE_PREFIXES=$( { ls "$MIGRATIONS_DIR"/*.sql 2>/dev/null; ls "$MIGRATIONS_DIR"/*.py 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
 ```
@@ -393,10 +441,29 @@ done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.tsx?$' | grep -v 'route
 
 ### 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
+# 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*[`"'"'"']/api/v1/' "$f" 2>/dev/null && echo "PROXY: direct /api/v1/ call in $f — must use /api/ proxy"
+    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$')
 ```
 
@@ -578,9 +645,11 @@ done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$')
 
 ---
 
-### 2J: String literal consistency (anti-detection/scraping code)
+### 2J: String literal consistency (anti-detection/scraping code) *(Scraping Pack — opt-in)*
 
-**Triggered when**: changed files include Python files in `anti_detection/`, `consumers/`, `browser/`, or `shared/detection/` directories.
+> **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 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.
 
@@ -670,9 +739,11 @@ done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$' | grep -E 'anti_de
 
 ---
 
-### 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.
 
@@ -956,6 +1027,219 @@ fi
 
 **Separation of concerns**: ForgeDock reasons about architecture, logic, and security; CI runs deterministic tool validators with zero token cost. The quality gate enforces that the CI layer is complete — it does not replace it.
 
+### 2Q: Billing domain checks (billing/credits/subscription/ledger/payment code)
+
+**Triggered when**: BILLING domain is set (changed files are under `billing/`, `credits/`, `subscription`, `ledger`, or `payment` paths).
+
+**Why this matters**: Billing code has three reliably grep-detectable defect classes that account for ~27% of review findings in the AlterLab health window: (1) `org_id` not propagated to debit/refund ledger write paths (silent data ownership loss — charges appear with wrong tenant); (2) `asyncio.sleep` / blocking sleep called inside an advisory-lock or open-transaction scope (holds DB connection/lock for the full sleep duration, causing connection exhaustion and deadlocks under load); (3) stdlib `logging.*()` calls passed structlog-style keyword arguments (`event=`, named context keys) that are not valid stdlib kwargs — crashes at runtime with `TypeError: unexpected keyword argument`. <!-- Added: forge#1329 --> <!-- allowlist: AlterLab -->
+
+**2Q-1: org_id propagation in ledger write functions**
+
+```bash
+# Grep billing Python files for ledger write function definitions missing an org_id parameter.
+# Heuristic: functions named debit/refund/charge/credit/apply_credit/record_usage whose
+# signature (def line) does not contain org_id are flagged as MEDIUM — reviewer verifies
+# with full context whether org_id is pulled from a passed object instead.
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    grep -nE "^\s*def (debit|refund|charge|credit|apply_credit|record_usage|create_invoice|issue_credit)\b" "$f" 2>/dev/null | while IFS=: read -r lineno rest; do
+        # Read the full function signature (up to 3 lines to cover multi-line sigs)
+        sig=$(sed -n "${lineno},$((lineno+2))p" "$f" 2>/dev/null)
+        echo "$sig" | grep -qE '\borg_id\b' || \
+            echo "BILLING-1 | MEDIUM | $f:$lineno | Ledger write function '$(echo "$rest" | grep -oE 'def \w+' | head -1)' signature does not include org_id parameter — verify org_id is propagated to all debit/refund paths (AlterLab#25348 pattern)" <!-- allowlist: AlterLab -->
+    done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$')
+```
+
+**2Q-2: Blocking sleep inside advisory-lock or open-transaction scope**
+
+```bash
+# Grep billing Python files for asyncio.sleep / time.sleep called inside an advisory-lock
+# or open-transaction context (within 20 lines after lock acquisition or BEGIN/session open).
+# Holding a lock or DB connection across a sleep starves the connection pool and causes
+# deadlocks under concurrent load (AlterLab#25725 pattern). <!-- allowlist: AlterLab -->
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    grep -nE "\basyncio\.sleep\b|\btime\.sleep\b" "$f" 2>/dev/null | while IFS=: read -r lineno rest; do
+        start=$((lineno > 20 ? lineno - 20 : 1))
+        window=$(sed -n "${start},$((lineno-1))p" "$f" 2>/dev/null)
+        echo "$window" | grep -qE 'advisory_lock|BEGIN\b|async with.*session|async with.*conn|async with.*transaction|with.*engine\b' && \
+            echo "BILLING-2 | HIGH | $f:$lineno | asyncio.sleep/time.sleep inside advisory-lock or open-transaction scope — holds DB connection/lock for full sleep duration, causing connection exhaustion and deadlocks under load (AlterLab#25725 pattern). Move sleep outside lock/transaction scope." <!-- allowlist: AlterLab -->
+    done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$')
+```
+
+**2Q-3: stdlib logging calls with structlog-style kwargs**
+
+```bash
+# Grep changed Python files for logging.*()/logger.*() calls that pass keyword arguments
+# that are NOT valid stdlib logging kwargs (exc_info, stack_info, stacklevel, extra).
+# Structlog-style kwargs (event=, extra_=, named context keys) are NOT accepted by stdlib
+# Logger methods and crash at runtime with TypeError: unexpected keyword argument.
+# (AlterLab#25715, #25837, #25819 pattern) <!-- allowlist: AlterLab -->
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    # Match logging.info/warning/error/debug/critical and logger.info/etc. calls with
+    # non-stdlib kwargs. Valid stdlib kwargs: exc_info, stack_info, stacklevel, extra.
+    # Flag any named kwarg that is NOT one of those four.
+    grep -nE "\b(logging|logger)\.(info|warning|error|debug|critical|exception)\s*\(.*\b\w+\s*=" "$f" 2>/dev/null | \
+        grep -vE "\b(exc_info|stack_info|stacklevel|extra)\s*=" | \
+        grep -v "^\s*#" && \
+        echo "BILLING-3 | HIGH | $f | stdlib logging call with non-stdlib keyword argument detected — stdlib Logger.info/warning/error/etc. only accept exc_info, stack_info, stacklevel, extra as kwargs. Structlog-style kwargs (event=, named context keys) cause TypeError at runtime (AlterLab#25715 pattern). Use structlog.get_logger() instead of logging if structlog kwargs are needed." <!-- allowlist: AlterLab -->
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$')
+```
+
+**Flag as findings**:
+- Ledger write function missing `org_id` parameter: **MEDIUM** — heuristic; reviewer verifies whether org_id is obtained from a passed object. Silent data ownership loss if omitted.
+- `asyncio.sleep`/`time.sleep` inside advisory-lock or transaction scope: **HIGH** — guaranteed connection/lock starvation under concurrent load.
+- stdlib `logging.*()` with non-stdlib kwargs: **HIGH** — guaranteed `TypeError` crash at runtime when the log call is reached.
+
+**Note**: 2Q-3 (stdlib logging check) fires on ALL changed Python files regardless of path — stdlib logger misuse is not specific to billing paths and is a universal crash class. 2Q-1 and 2Q-2 fire only on billing-domain files.
+
+### 2R: Registry checks (ALWAYS — promoted patterns from recurring review findings)
+
+<!-- Added: forge#1331 -->
+
+**Purpose**: Run all checks that have been promoted from recurring review findings into the registry. These are deterministic scripts that catch in milliseconds what previously required a full review cycle to detect. Each check was generated once by an LLM after the same defect class appeared 3+ times — thereafter it runs forever at zero LLM cost.
+
+**Registry location**: `scripts/check-registry/manifest.json` (relative to repo root)
+
+```bash
+REGISTRY_FILE="{WORKTREE_PATH}/scripts/check-registry/manifest.json"
+REGISTRY_FINDINGS=""
+
+if [ ! -f "$REGISTRY_FILE" ]; then
+    echo "2R: No check registry found at $REGISTRY_FILE — skipping registry checks."
+else
+    # Parse manifest and run each registered check
+    CHECK_COUNT=$(jq '.checks | length' "$REGISTRY_FILE" 2>/dev/null || echo 0)
+
+    if [ "$CHECK_COUNT" -eq 0 ]; then
+        echo "2R: Registry is empty — no promoted checks to run."
+    else
+        echo "2R: Running $CHECK_COUNT registered check(s)..."
+        CHECK_INDEX=0
+        while [ "$CHECK_INDEX" -lt "$CHECK_COUNT" ]; do
+            SCRIPT=$(jq -r ".checks[$CHECK_INDEX].script" "$REGISTRY_FILE" 2>/dev/null)
+            SLUG=$(jq -r ".checks[$CHECK_INDEX].slug" "$REGISTRY_FILE" 2>/dev/null)
+            SEVERITY=$(jq -r ".checks[$CHECK_INDEX].severity" "$REGISTRY_FILE" 2>/dev/null)
+
+            if [ -z "$SCRIPT" ] || [ "$SCRIPT" = "null" ]; then
+                CHECK_INDEX=$((CHECK_INDEX + 1))
+                continue
+            fi
+
+            SCRIPT_PATH="{WORKTREE_PATH}/$SCRIPT"
+
+            if [ ! -x "$SCRIPT_PATH" ]; then
+                echo "2R: WARN — registry check $SLUG script not found or not executable at $SCRIPT_PATH"
+                CHECK_INDEX=$((CHECK_INDEX + 1))
+                continue
+            fi
+
+            # Run the check; pass changed files list and worktree path
+            CHECK_OUTPUT=$("$SCRIPT_PATH" "{CHANGED_FILES}" "{WORKTREE_PATH}" 2>/dev/null)
+            CHECK_EXIT=$?
+
+            if [ "$CHECK_EXIT" -eq 1 ]; then
+                # Check fired — append to findings
+                while IFS= read -r line; do
+                    [ -z "$line" ] && continue
+                    REGISTRY_FINDINGS="${REGISTRY_FINDINGS}
+${line}"
+                done <<< "$CHECK_OUTPUT"
+                echo "2R: FAIL — $SLUG matched ($SEVERITY)"
+            elif [ "$CHECK_EXIT" -eq 0 ] || [ "$CHECK_EXIT" -eq 2 ]; then
+                echo "2R: PASS — $SLUG"
+            else
+                echo "2R: WARN — $SLUG exited with unexpected code $CHECK_EXIT"
+            fi
+
+            CHECK_INDEX=$((CHECK_INDEX + 1))
+        done
+    fi
+fi
+```
+
+If any registry check produces findings, include them in the Step 3 findings list under the check's slug (e.g. `REGISTRY-migration-number-collision | HIGH | ...`). HIGH-severity registry findings are blocking; MEDIUM are advisory.
+
+---
+
+## Step 2S: Test failure classification (run when tests fail in Step 2)
+
+<!-- Added: forge#1336 -->
+
+**Triggered when**: any domain check in Step 2 invokes a test suite command and that command exits non-zero.
+
+**Why this matters**: Builders and reviewers waste cycles on test failures that pre-exist the PR or are intermittently caused by fixture-state races. A test that fails on both the PR branch and the base branch is *pre-broken* and must not block an unrelated PR. A test that fails then passes on retry is *flaky* and should be quarantined, not "fixed" by the builder.
+
+### Classification protocol
+
+For each failing test ID (or test command) surfaced in Step 2:
+
+```bash
+# PR_BASE is the target branch (e.g. "staging", "main", or "milestone/slug")
+# FAILING_TEST is the individual test identifier or re-runnable command
+# GH_REPO is owner/repo from forge.yaml (used to file the quarantine issue)
+# PR_ISSUE_NUMBER is the issue this quality gate was invoked from (optional)
+
+CLASSIFIER="${FORGEDOCK_SCRIPTS:-scripts}/flaky-quarantine.sh"
+[ -f "$CLASSIFIER" ] || CLASSIFIER="{WORKTREE_PATH}/scripts/flaky-quarantine.sh"
+
+if [ -f "$CLASSIFIER" ]; then
+    RESULT=$(bash "$CLASSIFIER" \
+        --test   "{FAILING_TEST}" \
+        --base   "{PR_BASE}" \
+        --worktree "{WORKTREE_PATH}" \
+        --repo   "{GH_REPO}" \
+        --issue  "{PR_ISSUE_NUMBER}" \
+        --retries 3 \
+        2>&1)
+    echo "$RESULT"
+    CLASSIFICATION=$(echo "$RESULT" | grep '^CLASSIFICATION:' | awk '{print $2}')
+else
+    # Script not present — fall back to treating all test failures as real.
+    CLASSIFICATION="REAL"
+    echo "NOTE: scripts/flaky-quarantine.sh not found — treating test failure as REAL (no classification)"
+fi
+```
+
+### Classification outcomes
+
+| Classification | Meaning | Gate behaviour |
+|---|---|---|
+| `PRE_BROKEN` | Fails on base branch — broken before this PR | **Does not block the gate.** Log as advisory. Quarantine manifest entry written; issue filed once. |
+| `FLAKY` | Intermittent — fails then passes on retry | **Does not block the gate.** Log as advisory. Quarantine manifest entry written; issue filed once. |
+| `REAL` | Deterministic on PR, passes on base | **Blocks the gate** — treated as a regression caused by this PR. |
+
+### Gate behaviour
+
+```
+if CLASSIFICATION == "PRE_BROKEN" or CLASSIFICATION == "FLAKY":
+    # Test does not block the gate — record in findings as advisory only.
+    # Emit a LOW finding so the builder and reviewer see it in the report.
+    emit: "TEST-QUARANTINE | LOW | {FAILING_TEST} | classified {CLASSIFICATION} — quarantine entry recorded; does not block this PR"
+    # Do NOT re-run the test or count it as a gate failure.
+
+elif CLASSIFICATION == "REAL":
+    # Test failure is caused by this PR — block the gate as before.
+    emit: "TEST-REAL | HIGH | {FAILING_TEST} | deterministic failure on PR branch; passes on base — this PR introduced the regression"
+```
+
+### Quarantine manifest
+
+The manifest lives at `.forgedock/quarantine.jsonl` in the project root (or at the path set in `FORGEDOCK_QUARANTINE_MANIFEST`). Each line is a JSON object:
+
+```json
+{"test":"<id>","classification":"PRE_BROKEN|FLAKY","base":"<branch>","pr_branch":"<branch>","issue":"<num>","repo":"<owner/repo>","first_seen":"<ISO-8601>","runs_pr":3,"failures_pr":3,"runs_base":1,"failures_base":1}
+```
+
+The manifest is append-only. Duplicate entries (same test already quarantined) are skipped. A corresponding GitHub issue is filed automatically when the script has `--repo` and `gh` is authenticated.
+
+**Reviewers**: when the manifest exists, read it during Phase 2 of `review-pr.md` to avoid re-filing known-quarantined tests as new findings.
+
+---
+
 ## Step 3: Compile findings
 
 Format findings as a structured list:

package/commands/replay.md

@@ -1,6 +1,7 @@
 ---
 description: Read-only playback of a completed pipeline run — shows FORGE annotations phase by phase with timestamps
 argument-hint: <issue-number>
+install: extras
 ---
 
 # /replay — Pipeline Run Playback
@@ -9,7 +10,7 @@ argument-hint: <issue-number>
 
 Replay a completed pipeline run. Fetches all FORGE annotations posted during the pipeline and displays them chronologically — phase headings, timestamps, and key structured fields. Read-only: nothing is written, no labels changed.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 
 ---