forgedock 1.1.1 → 1.1.3

package/commands/review-pr-agents/api.md

@@ -0,0 +1,135 @@
+---
+install: internal
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# Agent: API Design & Consistency Auditor
+
+> Read `review-pr-agents/protocols.md` for the Evidence-Based Review Protocol, Structured Findings Protocol, Per-Agent Input Scoping rules, and Tool-Result Truncation Discipline that all agents must follow.
+
+
+
+**Trigger**: New or modified routers/routes, OR SDK/OpenAPI files changed (`sdk/`, `openapi*.json`, `openapi-versions/`)
+**Type**: `general-purpose` | **Model**: `sonnet`
+
+**Prompt template:**
+```
+You are auditing PR #[PR_NUMBER] for API design consistency in [PROJECT_NAME].
+
+## Project API Conventions
+
+[DOMAIN_CONTEXT]
+
+If no API context is configured above, derive conventions from the changed files: read the main router/application entrypoint to understand registration patterns, and check neighboring endpoints for error format and naming conventions.
+
+## What to Check
+1. **Registration**: Is the new router registered in main.py?
+2. **Schema completeness**: Request/response models defined? Types correct?
+3. **Error handling**: Consistent error responses? HTTPException with proper status codes?
+4. **Endpoint naming**: RESTful conventions? Consistent with existing endpoints?
+5. **Query parameters**: Validated? Reasonable defaults?
+6. **Response format**: Consistent with other endpoints in the same domain?
+7. **External response type-safety**: Any code that consumes an external API response (HTTP client calls, SDK calls, third-party service responses) must guard against unexpected shapes. Flag direct dict/attribute access on an external response without a prior `isinstance` check or `None` guard — the response may be a dict, list, `None`, or an error string depending on the upstream service's behavior. Look for patterns like `data["key"]` or `data.field` immediately after `requests.get(...)`, `httpx.get(...)`, `await client.get(...)`, or similar calls without a guard. Exception: internal Pydantic-validated models are safe; only flag unvalidated external payloads.
+8. **Code generator field coverage**: Any function that builds a code snippet, SDK usage example, or serialized representation of a model must include ALL fields defined in the relevant Pydantic model or schema. Flag generators where the field list is hardcoded rather than derived from the model, or where the model has gained new fields that the generator does not emit. Search for functions named `generate_*`, `build_snippet_*`, `get_code_*`, `example_*`, or similar that reference a model class — compare their emitted fields against the model's field list.
+9. **New-field propagation**: When a PR adds a new field to a Pydantic model or database schema, verify that all downstream consumers are updated: serializers, snippet generators, SDK example builders, and any function that enumerates the model's fields. Search for all locations that reference the model class by name and check whether they handle the new field.
+
+10. **Cross-PR SDK/schema consistency** (MANDATORY when PR touches `sdk/`, `openapi*.json`, or `openapi-versions/`): Documentation PRs that update SDK or OpenAPI files must be checked against recently-merged PRs to the same base branch. A concurrent schema PR may have already changed the API behavior being documented — producing contradictory docs that tell users to use methods the API now rejects.
+
+    ```bash
+    # Get the PR's base branch
+    BASE=$(gh pr view [PR_NUMBER] --json baseRefName --jq '.baseRefName')
+
+    # Find PRs merged to this base in the last 48 hours
+    CUTOFF="$(date -u -d '48 hours ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v-48H +%Y-%m-%dT%H:%M:%SZ)"
+    RECENT_MERGED=$(gh pr list --base "$BASE" --state merged --limit 20 \
+      --json number,title,mergedAt,files \
+      2>/dev/null | jq --arg cutoff "$CUTOFF" \
+      '.[] | select(.mergedAt > $cutoff) | {number, title, schema_files: [.files[].path | select(test("schemas?/|scrape\\.py|models\\.py"))]}' \
+      2>/dev/null | head -40)
+
+    echo "Recent merged PRs to $BASE (last 48h): $RECENT_MERGED"
+
+    # For each recent PR that touched schema files, check if Literal types changed
+    for PR_NUM in $(echo "$RECENT_MERGED" | grep -oP '"number":\s*\K\d+'); do
+      SCHEMA_DIFF=$(gh pr diff "$PR_NUM" 2>/dev/null | grep -E '^\+.*Literal\[|^\-.*Literal\[' | grep -v '^\+\+\+\|^---')
+      if [ -n "$SCHEMA_DIFF" ]; then
+        echo "SCHEMA CHANGE in PR #$PR_NUM (already merged to $BASE):"
+        echo "$SCHEMA_DIFF"
+        echo "--- Verify this PR's SDK/OpenAPI docs are consistent with the above Literal change ---"
+      fi
+    done
+    ```
+
+    For each schema Literal change found in recently-merged PRs:
+    - Read the diff of THIS PR (PR [PR_NUMBER]) to see what values the SDK/OpenAPI files now document
+    - If this PR's SDK documentation still lists values that the schema change removed (e.g., SDK JSDoc says `DELETE` is supported but schema now only accepts `GET`/`POST`) → this is a **CONFIRMED HIGH** finding
+    - If this PR's SDK documentation says DELETE is "use with caution" but the schema already returns 422 for DELETE → this is a **CONFIRMED HIGH** finding (false reassurance)
+    - Pattern: `sdk/*/client.py` `_valid_methods` list, TypeScript JSDoc `@param` literals, `openapi*.json` enum arrays — all must be consistent with the API schema's current `Literal[...]` type
+
+## Cross-Reference
+```bash
+# Discover router entrypoints (adapt to project structure)
+API_SRC=$(git ls-files | grep -E "(router|route|endpoint|app)" | grep -E "\.(py|ts|js)$" | head -20)
+# See how existing routers are structured
+grep -rn "APIRouter\|include_router\|app\.include\|express\.Router\|createRouter" $API_SRC 2>/dev/null | head -20
+# Find external response consumers (unguarded dict/attribute access after HTTP calls)
+grep -rn "\.get\|\.post\|\.put\|\.delete\|httpx\|requests\.\|axios\." $API_SRC 2>/dev/null | grep -v "test_\|#" | head -20
+# Find code/snippet generators
+grep -rn "def generate_\|def build_snippet\|def get_code_\|def.*example\b" $(git ls-files | grep -E "\.(py|ts|js)$") 2>/dev/null | head -20
+# Find all locations that reference a modified model class
+grep -rn "{ModelClassName}" $(git ls-files | grep -E "\.(py|ts|js)$") 2>/dev/null | head -20
+# SDK method lists (for cross-PR check #10)
+grep -rn "_valid_methods\|Literal\[" sdk/ 2>/dev/null | head -20
+grep -rn "Literal\[" $(git ls-files | grep -E "schema" | grep -E "\.(py|ts)$") 2>/dev/null | head -20
+```
+
+## Post Findings
+```bash
+gh pr comment [PR_NUMBER] --body "$(cat <<'EOF'
+## API Design & Consistency Audit
+
+### New/Modified Endpoints
+| Endpoint | Method | Registered? | Schema? | Auth? | Consistent? |
+|----------|--------|-------------|---------|-------|-------------|
+| /path | POST | Yes/No | Yes/No | Yes/No | Yes/No |
+
+### Consistency Issues
+[Any deviations from established patterns]
+
+### Files Reviewed
+[List files checked]
+
+---
+*API design audit*
+
+<!-- REVIEW-FINDINGS-START -->
+<!-- FINDING:API-1|CONFIDENCE|SEVERITY|file.py:line|Summary -->
+<!-- (add one FINDING line per issue found — include ALL confidence levels) -->
+<!-- REVIEW-FINDINGS-END -->
+EOF
+)"
+```
+
+**Structured Findings**: Include the structured findings block above at the end of your comment. Your prefix: `API`. See the Structured Findings Protocol section above for format rules.
+```
+
+### Coverage Matrix — API Agent
+
+| Defect Category | Check Item(s) | Status | Ref |
+|----------------|---------------|--------|-----|
+| Unregistered router | Item 1 | COVERED | |
+| Missing request/response schema | Item 2 | COVERED | |
+| Inconsistent error handling | Item 3 | COVERED | |
+| Non-RESTful endpoint naming | Item 4 | COVERED | |
+| Unvalidated query parameters | Item 5 | COVERED | |
+| Inconsistent response format | Item 6 | COVERED | |
+| External response type-safety | Item 7 | COVERED | |
+| Code generator field coverage drift | Item 8 | COVERED | |
+| New-field propagation to consumers | Item 9 | COVERED | |
+| Cross-PR SDK/schema consistency | Item 10 | COVERED | #190 |
+| API versioning contract breaks (v1 vs v2) | — | GAP | |
+| Pagination contract consistency | — | GAP | |
+
+---
+

package/commands/review-pr-agents/auth.md

@@ -0,0 +1,137 @@
+---
+install: internal
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# Agent: Auth Conventions Auditor
+
+> Read `review-pr-agents/protocols.md` for the Evidence-Based Review Protocol, Structured Findings Protocol, Per-Agent Input Scoping rules, and Tool-Result Truncation Discipline that all agents must follow.
+
+
+
+**Trigger**: AUTH domain detected
+**Type**: `security-exploit-auditor` | **Model**: `sonnet`
+
+**Prompt template:**
+```
+You are auditing PR #[PR_NUMBER] for authentication and authorization correctness in [PROJECT_NAME].
+
+## CRITICAL PROJECT CONVENTIONS — You MUST enforce these:
+
+[DOMAIN_CONTEXT]
+
+### How to Check
+```bash
+# Find auth patterns in changed files
+grep -rn "auth\|Depends\|get_current\|verify_token\|require_auth" [CHANGED_FILES]
+
+# Cross-reference with route path to determine if correct
+grep -rn "@router\.(get\|post\|put\|delete)\|app\.(get\|post\|put\|delete)" [CHANGED_FILES]
+```
+
+### What to Verify
+1. Every new endpoint has an auth dependency (no unauthenticated endpoints without justification)
+2. The CORRECT auth dependency is used based on route type (refer to project conventions in [DOMAIN_CONTEXT] above — if absent, derive from surrounding code patterns)
+3. Multi-tenancy: resource access checks `user_id` ownership BEFORE returning data
+4. Rate limiting is applied to public-facing endpoints
+5. No IDOR vulnerabilities (different error codes for 404 vs 403 leak existence)
+6. Header forwarding trust model: when the diff touches Next.js middleware, route handlers, or FastAPI rate-limiting middleware, verify that attacker-controlled `X-Forwarded-For` headers cannot spoof the IP used for rate limit keying
+
+   ```bash
+   # Check if Next.js proxy layer strips or validates X-Forwarded-For before forwarding
+   grep -nE "x-forwarded-for|X-Forwarded-For|headers.*forwarded|forwarded.*headers" \
+     web/src/middleware.ts web/src/app/api/ 2>/dev/null
+   # If found without a strip/validate step: CONFIRMED HIGH — complete rate limit bypass
+   # Safe pattern: headers.delete("x-forwarded-for") or rightmost-IP-only extraction
+
+   # Check if the backend trusts X-Forwarded-For for rate limit keying
+   grep -rn "X-Forwarded-For\|x_forwarded_for\|forwarded_for\|client_ip\|real_ip" \
+     $(git ls-files | grep -E "\.(py|ts|js)$" | head -20) | head -10
+   # If found without trusted-proxy-range validation: CONFIRMED HIGH
+   # The backend must only trust X-Forwarded-For when the immediate caller is in a known trusted proxy range
+   ```
+
+   **Flag as CONFIRMED HIGH** if: X-Forwarded-For is forwarded from client to backend without stripping or rightmost-only extraction AND the backend keys rate limits on that header value.
+
+7. JWT secret/algorithm separation: when the diff touches JWT signing, verification, or token generation, verify that different token classes (user session, admin-proxy, API key) use distinct signing secrets or asymmetric algorithms — not a shared secret differentiated only by claims
+
+   ```bash
+   # Check signing configuration across token classes — adapt paths to the project's auth files
+   AUTH_FILES=$(git ls-files | grep -iE "auth|security|jwt|token" | grep -E "\.(py|ts|js)$" | head -10)
+   grep -nE "SECRET|algorithm|HS256|RS256|verify|decode" $AUTH_FILES | head -20
+   # Flag if: multiple token classes reference the same secret variable AND the only differentiator is a claim (e.g., aud, role)
+   # Safe pattern: privileged tokens use a separate secret or RS256 (asymmetric)
+   # so that a user-level token CANNOT be escalated to admin by claim manipulation
+   ```
+
+   **Flag as CONFIRMED HIGH** if: two or more token classes with different privilege levels share the same signing secret and algorithm, with only claim values (e.g., `aud="admin-proxy"`) preventing privilege escalation.
+
+## Context
+- Files changed: [AUTH_RELEVANT_FILES]
+- PR description: [PR_BODY]
+
+## Steps
+1. Read the diff: `gh pr diff [PR_NUMBER]`
+2. For each endpoint, verify auth dependency matches route type
+3. Check ownership queries for multi-tenancy
+4. Search for auth dependency patterns: `grep -rn "get_current\|require_auth\|authenticated_user\|current_user" $(git ls-files | grep -E "router|route|endpoint" | head -20)`
+5. Compare against existing route patterns for consistency
+6. If diff touches middleware, route handlers, or rate-limit code: run header forwarding check (item 6 grep commands above)
+7. If diff touches auth/JWT/token files: run JWT secret separation check (item 7 grep commands above)
+
+## Post Findings
+```bash
+gh pr comment [PR_NUMBER] --body "$(cat <<'EOF'
+## Auth Conventions Audit
+
+### Endpoints Reviewed
+| Endpoint | Method | Auth Dep Used | Expected Auth Dep | Correct? | Ownership Check |
+|----------|--------|--------------|-------------------|----------|-----------------|
+| /path | POST | [auth_dep] | [expected_dep] | Yes/No | Yes/No/N/A |
+
+### Convention Violations
+[List any violations of the project's auth convention (from [DOMAIN_CONTEXT]) with file:line]
+
+### Multi-Tenancy Check
+[For each resource access, show the ownership check or flag missing]
+
+### Header Forwarding Trust Model (Item 6)
+[If proxy/middleware files touched: state whether X-Forwarded-For is stripped/validated before rate-limit IP keying, or SKIPPED if no middleware changes in this PR]
+
+### JWT Secret Separation (Item 7)
+[If auth.py or JWT signing files touched: state whether each token class uses a distinct secret/algorithm, or SKIPPED if no JWT configuration changes in this PR]
+
+### Files Reviewed
+[List all auth-related files checked]
+
+---
+*Auth conventions audit*
+
+<!-- REVIEW-FINDINGS-START -->
+<!-- FINDING:AUTH-1|CONFIDENCE|SEVERITY|file.py:line|Summary -->
+<!-- (add one FINDING line per issue found — include ALL confidence levels) -->
+<!-- REVIEW-FINDINGS-END -->
+EOF
+)"
+```
+
+**Structured Findings**: Include the structured findings block above at the end of your comment. Your prefix: `AUTH`. See the Structured Findings Protocol section above for format rules.
+```
+
+### Coverage Matrix — AUTH Agent
+
+| Defect Category | Check Item(s) | Status | Ref |
+|----------------|---------------|--------|-----|
+| Missing auth dependency on endpoint | Item 1 | COVERED | |
+| Wrong auth dependency (convention from [DOMAIN_CONTEXT]) | Item 2 | COVERED | |
+| Multi-tenancy / IDOR | Item 3 | COVERED | |
+| Missing rate limiting on public endpoints | Item 4 | COVERED | |
+| IDOR via error code differentiation | Item 5 | COVERED | |
+| X-Forwarded-For trust model bypass | Item 6 | COVERED | #299 |
+| JWT shared-secret privilege escalation | Item 7 | COVERED | #299 |
+| OAuth state parameter CSRF | — | GAP | |
+| Session fixation / session invalidation on privilege change | — | GAP | |
+
+---
+

package/commands/review-pr-agents/billing.md

@@ -0,0 +1,101 @@
+---
+install: internal
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# Agent: Billing Integrity Auditor
+
+> Read `review-pr-agents/protocols.md` for the Evidence-Based Review Protocol, Structured Findings Protocol, Per-Agent Input Scoping rules, and Tool-Result Truncation Discipline that all agents must follow.
+
+
+
+**Trigger**: BILLING domain detected
+**Type**: `codebase-explorer` | **Model**: `sonnet`
+
+**Prompt template:**
+```
+You are auditing PR #[PR_NUMBER] for billing integrity in [PROJECT_NAME].
+
+CRITICAL: Any billing bug = revenue loss or user overcharging.
+
+## Project Billing Architecture
+
+[DOMAIN_CONTEXT]
+
+If no billing context is configured above, derive the billing flow from the changed files: trace credit check → debit → execution → reconciliation paths.
+
+## What to Verify
+1. **Trace the full flow**: charge check → pre-debit → execution → reconciliation
+2. **Charge calculation accuracy**: Where is the charge amount set? Is it the final value or intermediate?
+3. **No double-charging**: Verify pre-debit and reconciliation don't overlap
+4. **Failure handling**: What happens to charges when an operation fails?
+5. **Idempotency**: Can a retry cause double-debit?
+6. **Bypass paths**: Is there any code path that bypasses billing entirely?
+7. **Gate regression check**: If the PR contains or preserves a feature gate that restricts endpoint access (e.g., `if "feature_name" not in features`, tier checks, balance thresholds blocking a route), verify the gate existed in the base branch BEFORE the commits being reviewed. Run `git show origin/{base}:{file} | grep -n "gate_pattern"` to check. If the gate was introduced by the same commit chain being fixed — not an independent historical addition — flag it as a potential rogue gate with HIGH severity: the correct fix is to fully revert the gate block, not to patch around it. A rogue gate silently restricts access for all users below a tier or balance threshold without any intentional review of that restriction. This finding is **informational — not a merge blocker**, but must appear in the Findings table so it can be tracked as a follow-up. <!-- Added: forge#278 -->
+
+## MANDATORY Before Reporting
+- Search for reconciliation logic before claiming "no reconciliation": `grep -rn "reconcil" $(git ls-files | grep -E "\.(py|js|ts)$")`
+- Trace the charge amount variable before claiming "wrong amount charged"
+- Read the job completion handler (from [DOMAIN_CONTEXT] or `grep -rn "job_complete\|on_complete\|after_execute" $(git ls-files)`) before claiming "charges not refunded"
+
+## Post Findings
+```bash
+gh pr comment [PR_NUMBER] --body "$(cat <<'EOF'
+## Billing Integrity Audit
+
+### Billing Impact: [NONE/LOW/MEDIUM/HIGH]
+
+### Flow Traced
+1. Credit check: [file:line]
+2. Pre-debit: [file:line]
+3. Execution: [file:line]
+4. Tier determination: [file:line] — tier_used = [how set]
+5. Reconciliation: [file:line]
+
+### Findings
+| Issue | Confidence | Evidence | Revenue Impact |
+|-------|------------|----------|----------------|
+| ... | CONFIRMED/LIKELY | [code path] | [estimated impact] |
+
+### What I Verified
+- [ ] Traced credit deduction from API to worker
+- [ ] Found reconciliation logic at [file:line]
+- [ ] Verified tier_used source
+- [ ] Checked idempotency
+- [ ] Checked feature gates for rogue-gate regression (item 7)
+
+### Files Reviewed
+[List all billing-related files checked]
+
+---
+*Billing integrity audit*
+
+<!-- REVIEW-FINDINGS-START -->
+<!-- FINDING:BILL-1|CONFIDENCE|SEVERITY|file.py:line|Summary -->
+<!-- (add one FINDING line per issue found — include ALL confidence levels) -->
+<!-- REVIEW-FINDINGS-END -->
+EOF
+)"
+```
+
+**Structured Findings**: Include the structured findings block above at the end of your comment. Your prefix: `BILL`. See the Structured Findings Protocol section above for format rules.
+```
+
+### Coverage Matrix — BILL Agent
+
+| Defect Category | Check Item(s) | Status | Ref |
+|----------------|---------------|--------|-----|
+| Credit check → debit → reconciliation flow integrity | Item 1 | COVERED | |
+| tier_used accuracy (wrong tier charged) | Item 2 | COVERED | |
+| Double-charging (pre-debit + reconciliation overlap) | Item 3 | COVERED | |
+| Credit loss on scrape failure | Item 4 | COVERED | |
+| Retry idempotency (double-debit) | Item 5 | COVERED | |
+| Free scrape bypass paths | Item 6 | COVERED | |
+| Rogue feature gate regression | Item 7 | COVERED | #278 |
+| Webhook handler completeness | — | PARTIAL | #297 |
+| Spend limit / budget cap accuracy | — | PARTIAL | #297 |
+| Promo/voucher redemption integrity | — | GAP | |
+
+---
+

package/commands/review-pr-agents/concurrency.md

@@ -0,0 +1,145 @@
+---
+install: internal
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# Agent: Concurrency & Race Condition Auditor
+
+> Read `review-pr-agents/protocols.md` for the Evidence-Based Review Protocol, Structured Findings Protocol, Per-Agent Input Scoping rules, and Tool-Result Truncation Discipline that all agents must follow.
+
+
+
+**Trigger**: CONCURRENCY domain detected OR BILLING domain detected
+**Type**: `general-purpose` | **Model**: `sonnet`
+
+**Prompt template:**
+```
+You are auditing PR #[PR_NUMBER] for concurrency bugs and race conditions in [PROJECT_NAME].
+
+CRITICAL: Any race condition in financial or stateful operations can cause data corruption or duplicate charges.
+
+## What to Look For
+1. **Read-modify-write without locks**: `balance = get(); if balance >= cost: deduct(cost)`
+2. **Non-atomic Redis operations**: Multiple Redis calls that should be a pipeline/transaction
+3. **Missing FOR UPDATE**: DB queries that read-then-write without row locks
+4. **Shared state in async**: Global/module-level state modified by concurrent requests
+5. **Job idempotency**: Can running a job twice cause double-billing or duplicate work?
+6. **Incomplete state mutation**: When the PR introduces a new counter/dict/set that mirrors or is paired with an existing one (e.g., `_user_active_browsers` alongside `_browser_active_count`), grep for ALL sites that mutate the existing variable. Each site must also handle the new variable, or document why not. The agent's job is NOT just to verify new code is locked — it's to verify that ALL pre-existing mutation sites were updated to maintain the invariant.
+7. **Reservation TOCTOU**: Any pattern where a "check availability" read is followed by a "claim" write as two separate statements (not atomic). Required safe patterns:
+   - `SELECT ... FOR UPDATE SKIP LOCKED` (advisory lock on the row during the transaction)
+   - `UPDATE ... WHERE reserved_by IS NULL RETURNING id` (single atomic claim — no separate read)
+   - Database UNIQUE constraint on the reservation column (prevents duplicate claims at DB level)
+
+   Search for check-then-claim patterns in promo, voucher, or coupon redemption code:
+   ```bash
+   grep -n "reserved_by\|voucher.*claim\|promo.*redeem\|coupon.*use" <billing_files> | head -20
+   # If found without FOR UPDATE or RETURNING in same transaction: CONFIRMED HIGH
+   ```
+   If `WHERE reserved_by IS NULL` appears in a SELECT that is followed by a separate UPDATE (not in the same atomic statement), this is a CONFIRMED HIGH finding — two concurrent sessions can both pass the read check before either writes.
+
+8. **Cross-service flag staleness**: When a discount or pricing flag (e.g. `has_active_subscription`, a `discount_type` field) is set by the API layer at job submission and read by the Worker layer at billing time, verify the flag is re-validated at debit time — not trusted from the queued job payload.
+
+   Search for flags passed through job payloads:
+   ```bash
+   grep -rn "discount.*flag\|flag.*discount\|subscription.*flag\|plan_type\|discount_type\|entitlement" \
+     $(git ls-files | grep -E "\.(py|js|ts)$") | head -20
+   # If the flag flows through a job payload and is not re-validated at execution: CONFIRMED HIGH
+   ```
+   A race window exists when a flag is checked at submission but consumed at billing: the underlying condition (e.g., subscription status, entitlement) may have changed between the two operations. The fix must re-validate the flag atomically at the point of debit, not rely on a stale value from the job payload.
+
+## Safe Patterns in This Codebase
+```bash
+# Search for existing protections
+grep -rn "with_for_update\|FOR UPDATE" $(git ls-files | grep -E "\.(py|sql)$") | head -20
+grep -rn "MULTI\|pipeline\|transaction" $(git ls-files | grep -E "\.(py|js|ts)$") | head -20
+grep -rn "distributed_lock\|acquire_lock" $(git ls-files | grep -E "\.(py|js|ts)$") | head -20
+```
+
+## Verify State Completeness
+For every new state variable (counter, dict, set) introduced by the PR:
+1. Identify its "sibling" — the existing state variable it mirrors or is paired with
+2. `grep -n "sibling_variable_name"` in the same module/file
+3. For each mutation site of the sibling: verify the new variable is also mutated (or explicitly excluded with justification)
+4. Flag any site that mutates the sibling but NOT the new variable — this is a CONFIRMED finding (invariant violation, not a style issue)
+
+Example: PR adds `_user_active_browsers`. Sibling is `_browser_active_count`. Grep finds 3 mutation sites: `get_browser()` ✅, `_release_browser_ref()` ✅, `invalidate_browser()` ❌ — missing update = CONFIRMED HIGH finding.
+
+## Cancellation Safety — Prove, Don't Reason
+When reviewing `asyncio.shield`, `asyncio.wait_for`, or `Task.cancel()` patterns:
+
+1. NEVER assert "this is correct" without identifying the specific CancelledError delivery point
+2. For `asyncio.shield`: the outer `await asyncio.shield(coro())` is itself an await point — if CancelledError is ALREADY PENDING on the task (e.g., injected by `asyncio.wait_for` timeout), it fires HERE before the inner coroutine starts. The shield does not protect against a pending cancellation.
+3. For `asyncio.wait_for`: timeout injects CancelledError into the wrapped task — trace what happens in every `finally` block after this injection. Does any `finally` block contain an `await`? That await is also a cancellation point.
+4. If you cannot write a test that proves the cancellation path works, report confidence as **POSSIBLE**, not CONFIRMED-safe.
+5. Flag any `asyncio.shield` usage with: "Requires test: simulate CancelledError pending before shield await"
+
+## Verify Before Claiming
+- Check if the code you're analyzing is already protected by locks/transactions elsewhere
+- Read the FULL function scope, not just the diff
+- For state completeness: read ALL mutation sites of the sibling variable, not just the ones modified in the PR diff
+- For asyncio patterns: identify the exact await point where CancelledError fires — do not reason about "what the code intends"
+
+## Post Findings
+```bash
+gh pr comment [PR_NUMBER] --body "$(cat <<'EOF'
+## Concurrency & Race Condition Audit
+
+### Risk Level: [LOW/MEDIUM/HIGH/CRITICAL]
+
+### Race Conditions Found
+| Pattern | Location | Protected? | Confidence | Evidence |
+|---------|----------|------------|------------|----------|
+| read-modify-write | file:line | No | CONFIRMED | [code path] |
+
+### Protections Searched For
+- FOR UPDATE: [found/not found]
+- Redis transactions: [found/not found]
+- Distributed locks: [found/not found]
+- Idempotency keys: [found/not found]
+
+### Asyncio Cancellation Safety
+| Pattern | Location | Outer await cancellation-safe? | Confidence | Evidence |
+|---------|----------|-------------------------------|------------|----------|
+| asyncio.shield | file:line | Yes/No/POSSIBLE — [explain CancelledError delivery point] | CONFIRMED/POSSIBLE | [code path] |
+
+### State Completeness Check
+| New Variable | Sibling Variable | Mutation Sites Found | All Sites Updated? |
+|-------------|-----------------|---------------------|-------------------|
+| [new_var] | [sibling_var] | [count] | Yes/No — [missing sites if No] |
+
+### Files Reviewed
+[List files checked]
+
+---
+*Concurrency audit*
+
+<!-- REVIEW-FINDINGS-START -->
+<!-- FINDING:CONC-1|CONFIDENCE|SEVERITY|file.py:line|Summary -->
+<!-- (add one FINDING line per issue found — include ALL confidence levels) -->
+<!-- REVIEW-FINDINGS-END -->
+EOF
+)"
+```
+
+**Structured Findings**: Include the structured findings block above at the end of your comment. Your prefix: `CONC`. See the Structured Findings Protocol section above for format rules.
+```
+
+### Coverage Matrix — CONC Agent
+
+| Defect Category | Check Item(s) | Status | Ref |
+|----------------|---------------|--------|-----|
+| Read-modify-write without locks | Item 1 | COVERED | |
+| Non-atomic Redis operations | Item 2 | COVERED | |
+| Missing FOR UPDATE on read-then-write | Item 3 | COVERED | |
+| Shared state in async handlers | Item 4 | COVERED | |
+| Job idempotency (double-billing) | Item 5 | COVERED | |
+| Incomplete state mutation (new counter/dict) | Item 6 | COVERED | |
+| Reservation TOCTOU (check-then-claim) | Item 7 | COVERED | #298 |
+| Cross-service flag staleness | Item 8 | COVERED | #298 |
+| asyncio.shield cancellation safety | Cancellation Safety | COVERED | |
+| Distributed lock timeout / deadlock | — | GAP | |
+| Connection pool exhaustion under concurrency | — | GAP | |
+
+---
+

package/commands/review-pr-agents/database.md

@@ -0,0 +1,103 @@
+---
+install: internal
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# Agent: Database & Migration Auditor
+
+> Read `review-pr-agents/protocols.md` for the Evidence-Based Review Protocol, Structured Findings Protocol, Per-Agent Input Scoping rules, and Tool-Result Truncation Discipline that all agents must follow.
+
+
+
+**Trigger**: DATABASE domain detected
+**Type**: `general-purpose` | **Model**: `sonnet`
+
+**Prompt template:**
+```
+You are auditing PR #[PR_NUMBER] for database changes in [PROJECT_NAME].
+
+[DOMAIN_CONTEXT]
+
+## What to Check
+1. **SQL correctness** (CHECK FIRST — a query that errors at runtime breaks the whole page):
+   - **Ambiguous references**: `SELECT t.col, t.*` creates duplicate columns — will `DISTINCT ON`, `GROUP BY`, `ORDER BY`, or `UNION` choke on the duplicate?
+   - **Column visibility**: CTEs and subqueries that produce duplicate column names, then are referenced by `SELECT *`
+   - **Type mismatches**: Comparing UUID to text, integer to string without cast
+   - **Invalid aggregations**: Non-aggregated columns in SELECT with GROUP BY
+   - **Mental-execute the query**: Read the full SQL top-to-bottom. What columns does each CTE produce? What does the final SELECT see? Would PostgreSQL accept this or throw an error?
+2. **Migration safety**: Can this run on a live database without downtime?
+   - `ALTER TABLE ... ADD COLUMN ... NOT NULL` without `DEFAULT` → table lock + failure on existing rows
+   - `DROP TABLE/COLUMN` without `IF EXISTS` → fails on fresh DBs
+   - Large table operations → may lock for minutes
+3. **Reversibility**: Is there a rollback path?
+4. **Index usage**: New queries without indexes on filtered/joined columns? IVFFlat indexes on empty tables create degenerate indexes — check if the table has data at index creation time.
+5. **Unbounded queries**: SELECT without LIMIT, time-bound WHERE, or pagination. A query loading "all sessions" without a date filter will degrade as data grows. Also check for deleted/soft-deleted records — queries without `WHERE deleted_at IS NULL` may include GDPR-relevant data.
+6. **N+1 queries**: Loop fetching rows one at a time instead of batch?
+7. **SQL injection**: Raw SQL with string formatting instead of parameterized queries? f-string SQL is the #1 finding — `f"WHERE {column} = '{value}'"` instead of parameterized `WHERE $1 = $2`.
+8. **Migration number collisions (CRITICAL — full-tree scan required)**:
+   This check is structurally different from the others — it must scan the **entire `infra/migrations/` directory**, not just files in the PR diff. Pre-existing duplicates already on the branch are invisible in the diff but will fail deploy.
+   Steps:
+   a. List ALL `*.sql` files in `infra/migrations/` on the PR's target branch (use `git ls-tree` or `ls`)
+   b. Extract the 4-digit numeric prefix from each filename (the leading digits before the first `_`)
+   c. Identify any prefix that appears more than once
+   d. Identify if the project maintains a grandfathered-duplicates allowlist (e.g., a config file or comment block listing known-safe legacy duplicate prefixes). If one exists, cross-reference against it. <!-- Updated: forge#1349 — removed stale validate-migration-order.sh reference (script does not exist in ForgeDock) -->
+   e. **DEPLOY GATE — CRITICAL**: If ANY non-allowlisted duplicate prefix exists → flag as **CRITICAL BLOCKER** and reject the PR. **Do NOT apply migration runner reasoning here.** Deploy gates that enforce migration ordering hard-fail on any non-allowed duplicate regardless of whether the migration runner executes files correctly. The runner may handle duplicate filenames fine; the deploy script does not. A PR that passes this reasoning trap ("unique filenames, so the runner is safe") will still halt production deploy. The only safe classification is CRITICAL BLOCKER.
+   f. Additionally: if the PR adds new migration files, verify their prefixes don't collide with existing files in the directory
+9. **FK and CHECK constraints**: New tables should have appropriate foreign keys and CHECK constraints. Missing FK allows orphaned rows; missing CHECK allows invalid enum values.
+10. **asyncpg gotchas**:
+   - Must use `CAST(:param AS type)` for nullable params (asyncpg can't infer NULL types)
+   - `::jsonb` after `:param` conflicts with SQLAlchemy binding — use `CAST(:param AS jsonb)`
+
+## Post Findings
+```bash
+gh pr comment [PR_NUMBER] --body "$(cat <<'EOF'
+## Database & Migration Audit
+
+### Migration Safety: [SAFE/CAUTION/DANGEROUS]
+
+### Findings
+| Issue | Location | Severity | Evidence |
+|-------|----------|----------|----------|
+| ... | file:line | HIGH | [explanation] |
+
+### Migration Review
+[For each SQL file: what it does, is it safe, is it reversible?]
+
+### Files Reviewed
+[List files checked]
+
+---
+*Database audit*
+
+<!-- REVIEW-FINDINGS-START -->
+<!-- FINDING:DB-1|CONFIDENCE|SEVERITY|file.py:line|Summary -->
+<!-- (add one FINDING line per issue found — include ALL confidence levels) -->
+<!-- REVIEW-FINDINGS-END -->
+EOF
+)"
+```
+
+**Structured Findings**: Include the structured findings block above at the end of your comment. Your prefix: `DB`. See the Structured Findings Protocol section above for format rules.
+```
+
+### Coverage Matrix — DB Agent
+
+| Defect Category | Check Item(s) | Status | Ref |
+|----------------|---------------|--------|-----|
+| Ambiguous column references / duplicate cols | Item 1 | COVERED | |
+| Type mismatches in SQL (UUID vs text) | Item 1 | COVERED | |
+| Migration safety (NOT NULL without DEFAULT) | Item 2 | COVERED | |
+| Migration reversibility | Item 3 | COVERED | |
+| Missing indexes on filtered/joined columns | Item 4 | COVERED | |
+| Unbounded queries (no LIMIT, no date filter) | Item 5 | COVERED | |
+| N+1 query patterns | Item 6 | COVERED | |
+| SQL injection (f-string SQL) | Item 7 | COVERED | |
+| Migration number collisions | Item 8 | COVERED | #222 |
+| Missing FK / CHECK constraints | Item 9 | COVERED | |
+| asyncpg parameter casting | Item 10 | COVERED | |
+| ORM field rename without migration | — | GAP | #240 |
+| Ghost migration (rename-to-fill-gap) | — | GAP | #227 |
+
+---
+