forgedock 1.1.1 → 1.1.2

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

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

@@ -0,0 +1,89 @@
+---
+install: internal
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# Agent: Frontend Quality 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**: WEB service touched
+**Type**: `codebase-explorer` | **Model**: `sonnet`
+
+**Prompt template:**
+```
+You are auditing PR #[PR_NUMBER] for frontend quality in [PROJECT_NAME].
+
+## Project Frontend Conventions
+
+[DOMAIN_CONTEXT]
+
+If no frontend context is configured above, derive conventions from the changed files: check package.json for framework versions and look at existing patterns in surrounding components.
+
+## What to Check
+1. **Server vs Client components**: Is 'use client' used appropriately? Could this be a Server Component instead?
+2. **React lifecycle**: Missing useEffect cleanup (subscriptions, timers, AbortControllers not cancelled on unmount). This is the #1 frontend defect — causes memory leaks and stale state.
+3. **useCallback/useMemo deps**: Dependencies must be stable values (ids, primitives), NOT full objects (SWR responses, arrays). An unstable dep causes infinite re-render loops.
+4. **Data fetching**: Loading/error states handled, stale data invalidated, race conditions in parallel fetches
+5. **Type safety**: Zod schemas match API response types, no `any` types. Check that component props match what the parent passes — wrong prop types (e.g., passing a component reference instead of a rendered element) cause build failures.
+6. **Component imports**: Verify imported components actually exist. Check `@/components/ui/*` imports against what's installed via shadcn. Missing components pass `tsc` if types exist but fail `next build`.
+7. **XSS**: User input rendered with `dangerouslySetInnerHTML` without sanitization
+8. **Accessibility**: Interactive elements have proper labels, keyboard navigation works
+9. **Performance**: Large bundles, unnecessary client-side rendering, missing dynamic imports
+10. **Hook provider scope**: For any new `useX()` hook call added to a component, verify the hook is safe to call outside its provider. If `useX` internally calls `useContext(XContext)` and throws when context is undefined (i.e., the hook contains `if (!ctx) throw new Error(...)`), check ALL mount sites of the component across the codebase. If the component is used in both authenticated routes (e.g., `app/dashboard/`) AND public routes (e.g., `app/(public)/`, `app/playground/`) that do not wrap children in the provider, the hook call will crash the public route with a React error boundary cascade. Flag as CONFIRMED HIGH if a public mount site exists without the provider. <!-- Added: forge#381 -->
+
+## Post Findings
+```bash
+gh pr comment [PR_NUMBER] --body "$(cat <<'EOF'
+## Frontend Quality Audit
+
+### Quality Level: [GOOD/ACCEPTABLE/NEEDS WORK]
+
+### Findings
+| Category | Issue | File:Line | Severity |
+|----------|-------|-----------|----------|
+| React | missing useEffect dep | file:line | MEDIUM |
+| A11y | button without label | file:line | LOW |
+
+### Component Architecture
+[Server vs Client component usage assessment]
+
+### Files Reviewed
+[List files checked]
+
+---
+*Frontend quality audit*
+
+<!-- REVIEW-FINDINGS-START -->
+<!-- FINDING:FE-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: `FE`. See the Structured Findings Protocol section above for format rules.
+```
+
+### Coverage Matrix — FE Agent
+
+| Defect Category | Check Item(s) | Status | Ref |
+|----------------|---------------|--------|-----|
+| Unnecessary 'use client' directive | Item 1 | COVERED | |
+| Missing useEffect cleanup (memory leaks) | Item 2 | COVERED | |
+| Unstable useCallback/useMemo dependencies | Item 3 | COVERED | |
+| Missing loading/error states | Item 4 | COVERED | |
+| Type safety (Zod schema / prop mismatch) | Item 5 | COVERED | |
+| Missing component imports (shadcn) | Item 6 | COVERED | |
+| XSS via dangerouslySetInnerHTML | Item 7 | COVERED | |
+| Accessibility (labels, keyboard nav) | Item 8 | COVERED | |
+| Performance (bundle size, dynamic imports) | Item 9 | COVERED | |
+| Hook outside provider scope (crash on public routes) | Item 10 | COVERED | forge#381 |
+| Server Component data leakage to client | — | GAP | |
+| Next.js App Router caching pitfalls | — | GAP | |
+
+---
+