tribunal-kit 9.2.5 → 9.2.7

package/skills/backend-performance-auditor/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: backend-performance-auditor
+description: "Use when auditing backend latency, throughput, memory consumption, and concurrency bottlenecks. Covers Node.js/Python event loop profiling, connection pool starvation, memory leaks, serialization overhead, and CPU hot paths."
+version: 6.0.0
+last-updated: 2026-09-29
+skills:
+  - performance-profiling
+  - backend-security-expert
+  - resilience-reviewer
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Backend Performance & Throughput Audit Mastery
+
+## Activation Boundaries
+- **Activate when:** Use when auditing backend latency, throughput, memory consumption, and concurrency bottlenecks. Covers Node.js/Python event loop profiling, connection pool starvation, memory leaks, serialization overhead, and CPU hot paths.
+- **DO NOT activate when:** The task falls outside the `backend-performance-auditor` domain or is managed by a different dedicated specialist agent.
+
+
+## 🔁 Multi-Pass Execution Protocol
+
+| Pass | Phase | Core Action | Adaptive Depth |
+|:---|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
+| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
+| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
+| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
+| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |
+
+
+## Mandatory Pre-Flight Context Inspection
+1. **Critical Path Identification**: Locate the primary request-response lifecycle and database access points.
+2. **Event Loop Non-Blocking**: Verify zero synchronous blocking calls (`fs.readFileSync`, `crypto.pbkdf2Sync`, `time.sleep`) inside request handlers.
+3. **Database Concurrency Bounds**: Check connection pool configurations (`max_connections`, `pool_size`, `idle_timeout`).
+4. **Serialization & Payload Size**: Identify large object serializations (e.g. stringifying 50MB JSON objects in memory).
+5. **Streaming vs Buffering**: Ensure large file downloads or bulk exports stream data instead of buffering into RAM.
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+### 1. Event Loop Blocking Detection & Offloading
+```typescript
+// ❌ CRITICAL BOTTLENECK: CPU-heavy JSON parsing or hashing on main event loop
+app.post('/api/compute-hash', (req, res) => {
+  const hash = crypto.pbkdf2Sync(req.body.password, 'salt', 100000, 64, 'sha512');
+  res.json({ hash: hash.toString('hex') });
+});
+
+// ✅ NON-BLOCKING: Offload to libuv threadpool via async API or Worker Threads
+import { promisify } from 'util';
+const pbkdf2Async = promisify(crypto.pbkdf2);
+
+app.post('/api/compute-hash', async (req, res) => {
+  const hash = await pbkdf2Async(req.body.password, 'salt', 100000, 64, 'sha512');
+  res.json({ hash: hash.toString('hex') });
+});
+```
+
+### 2. Stream-Based Bulk Data Export
+```typescript
+// ❌ OOM HAZARD: Buffering 100,000 rows into Node.js memory before sending
+app.get('/api/export-orders', async (req, res) => {
+  const rows = await db.orders.findMany(); // Loads entire table into heap
+  res.json(rows);
+});
+
+// ✅ MEMORY CONSTANT: Streaming directly to response pipeline
+import { pipeline } from 'stream/promises';
+import JSONStream from 'JSONStream';
+
+app.get('/api/export-orders', async (req, res) => {
+  res.setHeader('Content-Type', 'application/json');
+  const cursor = db.orders.findCursor();
+  await pipeline(cursor, JSONStream.stringify(), res);
+});
+```
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **Connection Pool Starvation** | Unbounded concurrent requests exhaust database connection pool, hanging API | Enforce request rate limiting, configure bounded pool size, and set short checkout timeouts |
+| **Unbounded In-Memory Cache** | Key-value cache maps without eviction grow until process crashes with OOM | Always use LRU cache libraries with strict `max: 5000` item boundaries and TTLs |
+| **DNS Resolution Latency** | Resolving external microservice DNS per request adds 20-100ms latency | Enable HTTP Agent connection keep-alive (`keepAlive: true`) and local DNS caching |
+
+## 🏛️ Tribunal Verification & Guardrails
+- **Active Reviewers:** `performance-optimizer`, `backend-specialist`, `throughput-optimizer`
+- **Evidence Standard:** All audit claims must state `[OBSERVED]` execution bottlenecks, `[INFERRED]` p99 latency impacts, and `[UNVERIFIED]` load conditions.
+
+## 🤖 LLM-Specific Traps Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **Unchecked Payload Cast** | Casting request bodies to TypeScript types without runtime schema validation | Parse request payloads through Zod/Pydantic schemas before business logic |
+| **Silent Error Swallowing** | Catching errors with empty catch blocks or logging without rethrowing | Propagate structured errors with status codes and contextual stack traces |
+| **Unparameterized Query** | Concatenating user inputs into SQL/Prisma query strings | Always use parameterized bindings or type-safe ORM query builders |

package/skills/backend-postgresql/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: backend-postgresql
+description: "Use when analyzing, designing, optimizing, and securing PostgreSQL databases. Covers B-Tree/GIN/BRIN indexing, query plans (EXPLAIN ANALYZE), connection pooling with PgBouncer, transactions, MVCC, locking, and JSONB optimization."
+version: 6.0.0
+last-updated: 2026-09-29
+skills:
+  - database-design
+  - sql-pro
+  - backend-security-expert
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# PostgreSQL Mastery — High-Performance & Hardened Architecture
+
+## 🔁 Multi-Pass Execution Protocol
+
+| Pass | Phase | Core Action | Adaptive Depth |
+|:---|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
+| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
+| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
+| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
+| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |
+
+
+## Mandatory Pre-Flight Context Inspection
+Before running or proposing PostgreSQL schema changes or queries, inspect:
+1. **Active Engine & Version**: Verify PostgreSQL major version (14, 15, 16+) and connection pooling (PgBouncer in transaction vs session mode).
+2. **Schema Definition**: Read the canonical DDL / migration files; never guess column names, types, or foreign key cascades.
+3. **Index Cardinality**: Check existing indices before proposing new indices; avoid duplicate or overlapping composite indices.
+4. **Transaction Boundaries**: Identify read-only vs read-write transactions; ensure non-interactive transactions commit immediately.
+5. **Execution Proof**: Verify query plans using `EXPLAIN (ANALYZE, BUFFERS)` in a safe non-production environment.
+
+## Activation Boundaries
+- **Activate when:** Designing schemas, writing complex SQL, optimizing slow queries, resolving lock contention, or securing PostgreSQL against SQLi.
+- **DO NOT activate when:** The target database is MongoDB, Redis, or SQLite, or the task is purely client-side UI.
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+### 1. Zero-Downtime Safe Index Creation
+```sql
+-- ❌ BAD: Locks entire table against writes during build
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+
+-- ✅ PRODUCTION SAFE: Builds concurrently without locking writes
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_orders_user_id ON orders(user_id);
+```
+
+### 2. Composite Index Left-Prefix Ordering & Filtered Indexing
+```sql
+-- Composite index for: WHERE tenant_id = $1 AND status = 'ACTIVE' ORDER BY created_at DESC
+-- Column order rule: Equality columns first (tenant_id, status), then range/sort columns (created_at)
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_orders_tenant_status_created 
+ON orders (tenant_id, status, created_at DESC);
+
+-- Partial index for high-skew tables (only index actionable rows)
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_jobs_pending 
+ON background_jobs (priority, scheduled_at) 
+WHERE status = 'PENDING';
+```
+
+### 3. Concurrency & Pessimistic Row Locking
+```sql
+-- Prevent double-spend or duplicate reservation without blocking unrelated rows
+BEGIN;
+SELECT id, balance 
+FROM accounts 
+WHERE id = $1 
+FOR UPDATE;
+
+UPDATE accounts 
+SET balance = balance - $2, updated_at = NOW() 
+WHERE id = $1;
+COMMIT;
+```
+
+### 4. High-Performance JSONB Querying with GIN
+```sql
+-- JSONB containment indexing
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_events_payload_gin 
+ON event_logs USING gin (payload jsonb_path_ops);
+
+-- Query using containment operator (@>) to utilize the index
+SELECT id, payload 
+FROM event_logs 
+WHERE payload @> '{"event_type": "checkout_completed"}';
+```
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **PgBouncer Transaction Pooling** | Prepared statements fail with `prepared statement does not exist` | Configure named prepared statements off, or use PgBouncer 1.21+ with statement prep support |
+| **Long-Running Transaction** | Bloats MVCC dead tuples, prevents autovacuum cleanup, table bloat | Set `idle_in_transaction_session_timeout = '15s'` and `statement_timeout = '30s'` |
+| **Table Lock on Heavy ALTER** | Adding column with default in PG < 11 rewrites table, blocking all traffic | Add column as NULL, backfill in batches, then set default and NOT NULL |
+| **Integer Overflow on PK** | 32-bit INT maxes out at 2.14B rows, causing system write freeze | Always define surrogate primary keys as `BIGINT GENERATED ALWAYS AS IDENTITY` |
+
+## 🤖 LLM-Specific Traps Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **`SELECT *` in Production** | Fetches all columns including heavy TOAST/JSONB data | Explicitly select only necessary columns to minimize network and memory IO |
+| **Unparameterized String SQL** | Interpolating template literals `WHERE email = '${email}'` | Use parameterized placeholders ($1, $2) or type-safe query builders |
+| **Missing Foreign Key Indexes** | Assuming `FOREIGN KEY` creates an index automatically | PostgreSQL does NOT index FKs automatically; always create matching index to avoid full table locks on DELETE |
+
+## 🏛️ Tribunal Verification & Guardrails
+- **Active Reviewers:** `database-architect`, `sql-pro`, `security-auditor`, `resilience-reviewer`
+- **Evidence Requirement:** Every finding must explicitly state:
+  - `[OBSERVED]`: Concrete table, column, and SQL statement from repository.
+  - `[INFERRED]`: Anticipated query plan behavior or locking risk.
+  - `[UNVERIFIED]`: Runtime metrics absent from static code.
+- **Verification Command:** Run `EXPLAIN ANALYZE` or execute DB migration linter.

package/skills/backend-redis/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: backend-redis
+description: "Use when analyzing, designing, and optimizing Redis usage for caching, distributed locking, rate limiting, session storage, and queues. Covers memory limits, eviction policies, atomic Lua scripts, TTL enforcement, and connection pooling."
+version: 6.0.0
+last-updated: 2026-09-29
+skills:
+  - backend-security-expert
+  - resilience-reviewer
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Redis Engineering — High-Speed Caching, Concurrency & State
+
+## 🔁 Multi-Pass Execution Protocol
+
+| Pass | Phase | Core Action | Adaptive Depth |
+|:---|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
+| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
+| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
+| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
+| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |
+
+
+## Mandatory Pre-Flight Context Inspection
+1. **Topology & Mode**: Verify standalone, Redis Sentinel, or Redis Cluster setup.
+2. **Eviction Policy**: Check `maxmemory-policy` (`volatile-lru`, `allkeys-lru`, `noeviction`).
+3. **Key Namespace & TTL**: Ensure every key uses structured namespaces (`{namespace}:{entity}:{id}`) and explicit expiration.
+4. **Serialization Overhead**: Inspect payload format; use lightweight binary (Protobuf/MessagePack) or compressed JSON.
+5. **Connection Lifecycles**: Ensure Redis clients reuse a singleton pool and handle disconnects without unhandled rejections.
+
+## Activation Boundaries
+- **Activate when:** Implementing cache layers, distributed locks, sliding-window rate limiters, session stores, or Pub/Sub.
+- **DO NOT activate when:** Persistent relational storage or multi-table ACID joins are needed.
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+### 1. Production-Grade Distributed Locking with Atomic Release
+```typescript
+import { randomUUID } from 'crypto';
+import Redis from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL);
+
+// Lua script guarantees lock is ONLY deleted if the secret value matches (prevents releasing expired locks held by others)
+const RELEASE_LOCK_LUA = `
+  if redis.call("get", KEYS[1]) == ARGV[1] then
+    return redis.call("del", KEYS[1])
+  else
+    return 0
+  end
+`;
+
+export async function withDistributedLock<T>(
+  lockKey: string,
+  ttlMs: number,
+  operation: () => Promise<T>
+): Promise<T> {
+  const lockToken = randomUUID();
+  // NX = Only set if not exists, PX = millisecond TTL
+  const acquired = await redis.set(`lock:${lockKey}`, lockToken, 'PX', ttlMs, 'NX');
+  if (!acquired) {
+    throw new Error(`Failed to acquire lock for: ${lockKey}`);
+  }
+
+  try {
+    return await operation();
+  } finally {
+    await redis.eval(RELEASE_LOCK_LUA, 1, `lock:${lockKey}`, lockToken);
+  }
+}
+```
+
+### 2. Atomic Sliding-Window Rate Limiter (Lua Script)
+```lua
+-- KEYS[1]: rate_limit:{identifier}
+-- ARGV[1]: current_timestamp_ms
+-- ARGV[2]: window_size_ms
+-- ARGV[3]: max_requests
+local key = KEYS[1]
+local now = tonumber(ARGV[1])
+local window = tonumber(ARGV[2])
+local limit = tonumber(ARGV[3])
+local clearBefore = now - window
+
+-- Clean old hits
+redis.call('ZREMRANGEBYSCORE', key, 0, clearBefore)
+local currentHits = redis.call('ZCARD', key)
+
+if currentHits < limit then
+  redis.call('ZADD', key, now, now)
+  redis.call('PEXPIRE', key, window)
+  return 1 -- Allowed
+else
+  return 0 -- Denied
+end
+```
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **Cache Stampede (Thundering Herd)** | Expensive key expires; hundreds of concurrent requests crush the database | Use probabilistic early expiration (XFetch algorithm) or a distributed lock around cache population |
+| **Hot Key Saturation** | Single key accessed millions of times saturates a single Redis shard CPU | Replicate hot keys with random salt (`key:shard_{0..3}`) or use in-process L1 cache (LRU) |
+| **Silent OOM Write Refusal** | Memory reaches `maxmemory` under `noeviction`, causing `OOM command not allowed` | Configure `allkeys-lru` or `volatile-lru`; monitor memory watermark alerts at 75% |
+
+## 🤖 LLM-Specific Traps Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **`KEYS *` in Production** | Running `KEYS pattern*` which blocks the single-threaded Redis event loop | Always use cursor-based non-blocking `SCAN` iteration with bounded `COUNT` |
+| **Missing Expiration on Keys** | Writing session or cache keys without TTL | Every ephemeral key MUST have a defined TTL (`EX` or `PX`) |
+| **Sequential Network Roundtrips** | Running 10 `await redis.get()` in a loop | Batch independent requests using Redis Pipelines (`redis.pipeline().get().get().exec()`) |
+
+## 🏛️ Tribunal Verification & Guardrails
+- **Active Reviewers:** `backend-specialist`, `resilience-reviewer`, `performance-optimizer`
+- **Evidence Standard:** Mark statements as `[OBSERVED]` (concrete Redis calls in code), `[INFERRED]` (caching efficiency), or `[UNVERIFIED]`.

package/skills/backend-security-expert/SKILL.md

@@ -1,26 +1,51 @@
----
-name: backend-security-expert
-description: "Use when Backend security auditing for modern server-side architectures. Focuses on Next.js Server Actions, Node.js/Edge APIs, JWT & Session architectures, ORM injection (Prisma/Drizzle), and RBAC implementation."
-version: 5.0.0
-last-updated: 2026-09-13
-skills:
-  - frontend-security-expert
-  - api-security-auditor
-  - vulnerability-scanner
-tools: Read, Grep, Glob, Bash, Edit, Write
-scripts-binding:
-  - .agent/scripts/lint_runner.js
-  - .agent/scripts/verify_all.js
----
-
-# Backend Security Expert — Modern Server Architectures
-
----
-
-## 🛠️ Technical Architecture & Reference Recipes
-
+---
+name: backend-security-expert
+description: "Use when designing, implementing, auditing, and hardening backend security expert server logic, APIs, background jobs, and error boundaries."
+version: 6.0.0
+last-updated: 2026-09-29
+skills:
+  - frontend-security-expert
+  - api-security-auditor
+  - vulnerability-scanner
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Backend Security Expert — Modern Server Architectures
+
+## Mandatory Pre-Flight Context Inspection
+Before reading, generating, or refactoring code in the `backend-security-expert` domain, inspect these 5 critical parameters:
+1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
+2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
+3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
+4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
+5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
+
+
+## Activation Boundaries
+- **Activate when:** Use when designing, implementing, auditing, and hardening backend security expert server logic, APIs, background jobs, and error boundaries.
+- **DO NOT activate when:** The task falls outside the `backend-security-expert` domain or is managed by a different dedicated specialist agent.
+
+
+## 🔁 Multi-Pass Execution Protocol
+
+| Pass | Phase | Core Action | Adaptive Depth |
+|:---|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
+| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
+| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
+| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
+| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |
+
+
 ---
 
+## 🛠️ Technical Architecture & Reference Recipes
+
 ## 2026 Backend Security & Cryptography Invariants
 
 1. **Timing-Safe Equality**:
@@ -70,4 +95,40 @@ Server Actions create implicit API endpoints. They must be treated like raw REST
 ## 4. Headers & Server Hardening
 
 - **CORS**: Never use wildcard `Access-Control-Allow-Origin: *` for authenticated routes.
-- **Security Headers**: Ensure Helmet (or equivalent Next.js headers config) is active for HSTS, X-Frame-Options, and Content-Type-Options.
+- **Security Headers**: Ensure Helmet (or equivalent Next.js headers config) is active for HSTS, X-Frame-Options, and Content-Type-Options.
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
+| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
+| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
+| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
+| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
+
+
+## 🏛️ Tribunal Verification & Guardrails
+
+**Active Reviewers:** `logic-reviewer` · `security-auditor` · `api-architect` · `resilience-reviewer`
+**Slash Command:** `/review` or `/tribunal-full`
+
+### 🔬 Evidence Standard (Tri-State Verification)
+Every finding, audit statement, or completion claim must classify its factual certainty:
+- **`[OBSERVED]`**: Directly confirmed in the codebase or verified via executed terminal command.
+- **`[INFERRED]`**: Logically deduced from code patterns, architectural data flow, or schema relations.
+- **`[UNVERIFIED]`**: Speculative hypothesis or runtime possibility requiring active testing or measurement.
+
+### ✅ Pre-Flight Self-Audit Checklist
+```
+✅ Are all inputs and boundary payloads validated against schemas (Zod/Pydantic)?
+✅ Are SQL and database queries parameterized with zero string concatenation?
+✅ Are error boundaries and timeout/retry policies explicitly declared?
+✅ Are authentication and object-level authorization (IDOR/BOLA) checked before business logic?
+✅ Did I verify that imported dependencies exist in package manifests?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing test suites, compiler success, or equivalent operational proof) that your output works as intended.

package/skills/backend-sqlalchemy/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: backend-sqlalchemy
+description: "Use when analyzing, writing, and optimizing SQLAlchemy 2.0+ ORM and Core code in Python. Covers modern select() syntax, async sessions, relationship loading strategies (selectinload, joinedload), session lifecycles, and N+1 prevention."
+version: 6.0.0
+last-updated: 2026-09-29
+skills:
+  - python-pro
+  - database-design
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# SQLAlchemy 2.0+ Mastery — Async ORM & Core Architecture
+
+## Activation Boundaries
+- **Activate when:** Use when analyzing, writing, and optimizing SQLAlchemy 2.0+ ORM and Core code in Python. Covers modern select() syntax, async sessions, relationship loading strategies (selectinload, joinedload), session lifecycles, and N+1 prevention.
+- **DO NOT activate when:** The task falls outside the `backend-sqlalchemy` domain or is managed by a different dedicated specialist agent.
+
+
+## 🔁 Multi-Pass Execution Protocol
+
+| Pass | Phase | Core Action | Adaptive Depth |
+|:---|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
+| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
+| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
+| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
+| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |
+
+
+## Mandatory Pre-Flight Context Inspection
+1. **SQLAlchemy Version**: Confirm version is 2.0+; reject legacy 1.x patterns (`session.query(Model)` is deprecated).
+2. **Sync vs Async Engine**: Identify whether `create_async_engine` or synchronous `create_engine` is in use.
+3. **Session Lifecycle**: Verify session scope; in web frameworks (FastAPI/Flask), ensure sessions are bound to request lifecycles.
+4. **Relationship Loading Strategy**: Inspect model relationships for lazy loading (`lazy="select"`) which causes async greenlet errors.
+5. **Connection Pool Bounds**: Check `pool_size`, `max_overflow`, and `pool_pre_ping=True`.
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+### 1. Modern SQLAlchemy 2.0 Async Session & Loading Pattern
+```python
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
+from sqlalchemy import select, and_
+from sqlalchemy.orm import selectinload, DeclarativeBase, Mapped, mapped_column, relationship
+
+class Base(DeclarativeBase):
+    pass
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(unique=True)
+    orders: Mapped[list["Order"]] = relationship(back_populates="user")
+
+class Order(Base):
+    __tablename__ = "orders"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
+    user: Mapped[User] = relationship(back_populates="orders")
+
+# ✅ Modern 2.0 query with eager loading (Prevents N+1 and Async MissingGreenlet error)
+async def get_user_with_orders(session: AsyncSession, user_id: int) -> User | None:
+    stmt = (
+        select(User)
+        .options(selectinload(User.orders))  # Eager load 1:N via separate SELECT IN
+        .where(User.id == user_id)
+    )
+    result = await session.execute(stmt)
+    return result.scalar_one_or_none()
+```
+
+### 2. Transaction Management & Unit of Work Context
+```python
+async def transfer_credits(session: AsyncSession, from_id: int, to_id: int, amount: int) -> None:
+    async with session.begin():  # Manages BEGIN and COMMIT/ROLLBACK automatically
+        sender = await session.get(User, from_id, with_for_update=True)
+        recipient = await session.get(User, to_id, with_for_update=True)
+        
+        if not sender or sender.credits < amount:
+            raise ValueError("Insufficient balance")
+            
+        sender.credits -= amount
+        recipient.credits += amount
+```
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **Async MissingGreenlet Exception** | Accessing unloaded relationship attribute in async handler crashes runtime | Always explicitly specify `selectinload()` or `joinedload()` in query options |
+| **Session Leak Across Requests** | Unclosed sessions starve the connection pool, locking new requests | Use dependency injection context manager (`async with get_session() as session:`) |
+| **ExpiredOnCommit Attribute Access** | Accessing model attributes after `session.commit()` triggers unexpected DB query | Set `expire_on_commit=False` in `async_sessionmaker` |
+
+## 🤖 LLM-Specific Traps Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **Legacy `session.query()`** | Generating deprecated `session.query(User).filter(...)` | Use 2.0 syntax `select(User).where(...)` executed via `session.execute()` |
+| **Unparameterized Raw SQL** | Using `text(f"SELECT * FROM users WHERE id = {user_id}")` | Use bound parameters: `text("SELECT * FROM users WHERE id = :id"), {"id": user_id}` |
+
+## 🏛️ Tribunal Verification & Guardrails
+- **Active Reviewers:** `database-architect`, `python-pro`, `resilience-reviewer`
+- **Evidence Standard:** Categorize findings into `[OBSERVED]`, `[INFERRED]`, and `[UNVERIFIED]`.

package/skills/backend-sqlite/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: backend-sqlite
+description: "Use when configuring, analyzing, and optimizing SQLite in backend, desktop, mobile, and embedded systems. Covers WAL mode, busy timeout, transaction concurrency, connection pooling singletons, and SQLite limitations."
+version: 6.0.0
+last-updated: 2026-09-29
+skills:
+  - database-design
+  - sql-pro
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# SQLite Architecture & Embedded Concurrency Mastery
+
+## Activation Boundaries
+- **Activate when:** Use when configuring, analyzing, and optimizing SQLite in backend, desktop, mobile, and embedded systems. Covers WAL mode, busy timeout, transaction concurrency, connection pooling singletons, and SQLite limitations.
+- **DO NOT activate when:** The task falls outside the `backend-sqlite` domain or is managed by a different dedicated specialist agent.
+
+
+## 🔁 Multi-Pass Execution Protocol
+
+| Pass | Phase | Core Action | Adaptive Depth |
+|:---|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
+| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
+| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
+| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
+| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |
+
+
+## Mandatory Pre-Flight Context Inspection
+1. **Journal Mode**: Verify `PRAGMA journal_mode = WAL` is enabled; default rollback journal serializes readers and writers.
+2. **Busy Timeout**: Ensure `PRAGMA busy_timeout = 5000` is configured to avoid instant `SQLITE_BUSY` locks under contention.
+3. **Connection Lifecycle**: Verify database connection is managed as a singleton per process; multi-connection write pools cause deadlocks.
+4. **Foreign Key Enforcement**: Confirm `PRAGMA foreign_keys = ON` is executed on every opened connection (off by default in SQLite).
+5. **Batch Transactions**: Wrap bulk insertions inside an explicit transaction (`BEGIN IMMEDIATE ... COMMIT`).
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+### 1. Production Initialization Pragma Baseline
+```typescript
+import Database from 'better-sqlite3';
+
+export function createDatabase(filePath: string): Database.Database {
+  const db = new Database(filePath);
+
+  // Critical SQLite Production Pragmas
+  db.pragma('journal_mode = WAL');         // Enable Write-Ahead Logging for concurrent reads
+  db.pragma('busy_timeout = 5000');        // Wait up to 5s before throwing SQLITE_BUSY
+  db.pragma('synchronous = NORMAL');       // Fast and safe under WAL mode
+  db.pragma('foreign_keys = ON');          // Enforce relational foreign keys
+  db.pragma('cache_size = -64000');        // 64MB memory page cache
+  db.pragma('temp_store = MEMORY');        // Store temporary tables and indices in RAM
+
+  return db;
+}
+```
+
+### 2. Immediate Transaction for Concurrent Write Safety
+```typescript
+// Prevent upgrading read lock to write lock mid-transaction (which triggers SQLITE_BUSY)
+const transfer = db.transaction((fromAccount: string, toAccount: string, amount: number) => {
+  // BEGIN IMMEDIATE acquires write lock up front
+  db.prepare('UPDATE accounts SET balance = balance - ? WHERE id = ?').run(amount, fromAccount);
+  db.prepare('UPDATE accounts SET balance = balance + ? WHERE id = ?').run(amount, toAccount);
+});
+
+// Execute transaction
+transfer('acc_1', 'acc_2', 100);
+```
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **Multiple Write Connections** | Concurrent connections attempting writes cause `SQLITE_BUSY: database is locked` | Restrict SQLite writes to a single connection queue or thread; read connections can scale |
+| **Network Filesystem (NFS/SMB)** | SQLite locking mechanisms break on network shares, corrupting database | Never mount SQLite DB files over NFS/CIFS; keep storage on local NVMe/SSD |
+| **WAL File Unbounded Growth** | Checkpoint never completes due to long continuous readers | Execute periodic `PRAGMA wal_checkpoint(TRUNCATE)` or set checkpoint limits |
+
+## 🤖 LLM-Specific Traps Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **Insert Loop without Transaction** | Executing 1,000 `INSERT` statements individually (takes seconds) | Wrap in a single transaction `BEGIN ... COMMIT` (takes 10 milliseconds) |
+| **ALTER TABLE Incompatibilities** | Attempting complex column drops/renames in older SQLite versions | Use 12-step table migration: create new table, copy data, drop old, rename new |
+
+## 🏛️ Tribunal Verification & Guardrails
+- **Active Reviewers:** `database-architect`, `sql-pro`, `resilience-reviewer`
+- **Evidence Standard:** Differentiate `[OBSERVED]` pragmas, `[INFERRED]` locking behaviors, and `[UNVERIFIED]` runtime metrics.