tribunal-kit 9.2.4 → 9.2.6

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

@@ -0,0 +1,101 @@
+---
+name: backend-architecture-auditor
+description: "Use when auditing backend architecture, module boundaries, domain logic separation, coupling, and circular dependencies. Evaluates layered, hexagonal, modular monolith, and microservice designs against maintainability and scale."
+version: 6.0.0
+last-updated: 2026-09-29
+skills:
+  - architecture
+  - clean-code
+  - codebase-design
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Backend Architecture & Domain Boundary Audit Mastery
+
+## Activation Boundaries
+- **Activate when:** Use when auditing backend architecture, module boundaries, domain logic separation, coupling, and circular dependencies. Evaluates layered, hexagonal, modular monolith, and microservice designs against maintainability and scale.
+- **DO NOT activate when:** The task falls outside the `backend-architecture-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. **Architectural Style**: Identify the declared architectural pattern (Layered MVC, Clean/Hexagonal, Modular Monolith, Microservices).
+2. **Dependency Flow Direction**: Verify that inner domain logic never imports outer infrastructure/framework layers.
+3. **Module Boundaries**: Inspect module exports and imports; check for tight coupling across bounded contexts.
+4. **Data Access Leaks**: Ensure database models and ORM entities do not leak directly into presentation/controller responses.
+5. **Side-Effect Isolation**: Verify external integrations (payment gateways, emails, SMS) are behind domain interfaces.
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+### 1. Hexagonal Port & Adapter Separation
+```
+┌──────────────────────────────────────────────────┐
+│                   Domain Layer                   │
+│   - Entities (Business Rules)                    │
+│   - Inbound / Outbound Ports (Interfaces)        │
+└─────────────────────────▲────────────────────────┘
+                          │ (Implements)
+┌─────────────────────────┴────────────────────────┐
+│               Infrastructure Layer               │
+│   - Adapters (PostgresRepo, StripePaymentGateway)│
+│   - Framework Handlers (FastAPI / Express)       │
+└──────────────────────────────────────────────────┘
+```
+
+### 2. Dependency Direction Enforcement
+```typescript
+// ❌ ARCHITECTURAL LEAK: Domain entity directly importing database driver or HTTP client
+import { db } from '../infra/database'; // VIOLATION
+
+// ✅ CLEAN ARCHITECTURE: Domain defines the Port (Interface), Infrastructure implements it
+// domain/ports/user_repository.ts
+export interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  save(user: User): Promise<void>;
+}
+
+// infra/adapters/postgres_user_repository.ts
+export class PostgresUserRepository implements UserRepository {
+  constructor(private readonly pool: PgPool) {}
+  async findById(id: string): Promise<User | null> { /* ... */ }
+  async save(user: User): Promise<void> { /* ... */ }
+}
+```
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **Circular Module Imports** | Modules A and B import each other, causing runtime undefined references | Extract shared contract/types into an independent domain interface package |
+| **Fat Controller Anti-Pattern** | Thousands of lines of business logic crammed into HTTP route handlers | Move domain rules into standalone Use Case / Interactor services |
+| **Distributed Monolith** | Microservices with synchronous REST dependencies failing in cascading chain | Decouple via asynchronous event queues (Kafka, RabbitMQ, SQS) |
+
+## 🏛️ Tribunal Verification & Guardrails
+- **Active Reviewers:** `system-architect`, `logic-reviewer`, `complexity-reviewer`
+- **Evidence Standard:** Every architecture finding must state:
+  - `[OBSERVED]`: Exact import statement or file boundary crossing.
+  - `[INFERRED]`: Impact on change velocity, testability, or coupling.
+  - `[UNVERIFIED]`: Runtime blast radius.
+
+## 🤖 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-mongodb/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: backend-mongodb
+description: "Use when analyzing, querying, designing, and hardening MongoDB schemas, indexes, and aggregation pipelines. Covers compound indexes, NoSQL injection prevention, schema validation, transaction boundaries, and projection safety."
+version: 6.0.0
+last-updated: 2026-09-29
+skills:
+  - database-design
+  - backend-security-expert
+  - data-validation-schemas
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# MongoDB Architecture & Security Mastery
+
+## 🔁 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. **Driver & Server Version**: Verify Mongoose or native MongoDB driver version (v5 vs v6+) and connection URI options.
+2. **Schema Models**: Inspect Mongoose schema definitions or collection validation rules (`validator: { $jsonSchema: ... }`).
+3. **Compound Index Prefixing**: Verify that queries match the equality, sort, range (ESR) rule on compound indexes.
+4. **Input Sanitization**: Inspect how incoming request parameters reach collection queries; block operator injection.
+5. **Memory Limits in Aggregations**: Ensure pipelines contain `$limit` before sorting or heavy projection stages.
+
+## Activation Boundaries
+- **Activate when:** Writing MongoDB queries, building aggregation pipelines, defining Mongoose schemas, or hardening against NoSQL injection.
+- **DO NOT activate when:** The project uses relational databases (PostgreSQL, MySQL) or client-side caching.
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+### 1. NoSQL Injection Prevention
+```typescript
+// ❌ VULNERABLE: Direct object pass allows { "$gt": "" } bypassing auth
+app.post('/api/login', async (req, res) => {
+  const { username, password } = req.body;
+  const user = await db.collection('users').findOne({ username, password });
+  if (user) generateSession(res, user);
+});
+
+// ✅ SECURE: Strict schema parsing (Zod) + casting to string primitive
+import { z } from 'zod';
+
+const LoginSchema = z.object({
+  username: z.string().min(3).max(50),
+  password: z.string().min(8)
+});
+
+app.post('/api/login', async (req, res) => {
+  const parsed = LoginSchema.safeParse(req.body);
+  if (!parsed.success) return res.status(400).json({ error: 'Invalid payload' });
+
+  const { username, password } = parsed.data;
+  const user = await db.collection('users').findOne({ 
+    username: String(username), 
+    passwordHash: await hashPassword(String(password)) 
+  });
+  if (!user) return res.status(401).json({ error: 'Unauthorized' });
+  generateSession(res, user);
+});
+```
+
+### 2. ESR Index Optimization (Equality, Sort, Range)
+```javascript
+// Query pattern: Find active orders for user, sorted by date, with amount > 100
+// db.orders.find({ userId: uid, status: 'ACTIVE', total: { $gt: 100 } }).sort({ createdAt: -1 })
+
+// ✅ ESR Index order: 
+// 1. Equality: userId, status
+// 2. Sort: createdAt
+// 3. Range: total
+db.orders.createIndex(
+  { userId: 1, status: 1, createdAt: -1, total: 1 },
+  { name: 'idx_orders_esr', background: true }
+);
+```
+
+### 3. Safe Multi-Document Transactions
+```typescript
+const session = client.startSession();
+try {
+  await session.withTransaction(async () => {
+    await orders.updateOne(
+      { _id: orderId, status: 'PENDING' },
+      { $set: { status: 'PAID', paidAt: new Date() } },
+      { session }
+    );
+    await inventory.updateOne(
+      { sku: itemSku, stock: { $gte: quantity } },
+      { $inc: { stock: -quantity } },
+      { session }
+    );
+  }, {
+    readPreference: 'primary',
+    readConcern: { level: 'local' },
+    writeConcern: { w: 'majority' }
+  });
+} finally {
+  await session.endSession();
+}
+```
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **Unbounded Projection** | Documents with massive arrays or base64 files exhaust Node.js heap memory | Always pass explicit projection `{ projection: { bio: 1, avatarUrl: 1, _id: 1 } }` |
+| **Pipeline Memory Exceeded** | Sorting >100MB in memory without index crashes with `13848 ExceededMemoryLimit` | Place `$match` and `$limit` early; index the sort field; enable `allowDiskUse: true` only when necessary |
+| **Unchecked Write Concern** | Primary writes return before replica acknowledgment, risking data loss on failover | Always use `writeConcern: { w: 'majority', j: true }` for critical state changes |
+
+## 🤖 LLM-Specific Traps Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **Blind `$where` Evaluation** | Using `$where: "this.a == this.b"` | Avoid `$where` completely; it executes arbitrary JS, introduces injection, and bypasses indexes |
+| **Missing `$limit` on Collections** | Calling `.find({}).toArray()` | Always attach bounded `.limit(PAGE_SIZE)` to prevent OOM on production scale |
+| **Nested Array Unchecked Growth** | Appending logs into a single document without boundary | Cap arrays using `$slice` or create a separate time-series / event collection |
+
+## 🏛️ Tribunal Verification & Guardrails
+- **Active Reviewers:** `database-architect`, `security-auditor`, `schema-reviewer`
+- **Evidence Standard:** Categorize each finding as `[OBSERVED]` (concrete query/schema in repo), `[INFERRED]` (index utilization hypothesis), or `[UNVERIFIED]`.

package/skills/backend-mysql/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: backend-mysql
+description: "Use when analyzing, optimizing, and securing MySQL and MariaDB databases. Covers InnoDB storage engine, composite index left-prefix rule, locking & deadlocks, transactions, connection pooling, and utf8mb4 collation."
+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
+---
+
+# MySQL & MariaDB Architecture & Performance Mastery
+
+## Activation Boundaries
+- **Activate when:** Use when analyzing, optimizing, and securing MySQL and MariaDB databases. Covers InnoDB storage engine, composite index left-prefix rule, locking & deadlocks, transactions, connection pooling, and utf8mb4 collation.
+- **DO NOT activate when:** The task falls outside the `backend-mysql` 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. **Engine Verification**: Confirm all tables use InnoDB engine (`ENGINE=InnoDB`); reject MyISAM.
+2. **Charset & Collation**: Enforce `utf8mb4` and `utf8mb4_0900_ai_ci` (or `utf8mb4_unicode_ci` for older versions); reject 3-byte `utf8`.
+3. **Transaction Isolation**: Identify active isolation level (`REPEATABLE READ` is MySQL default; watch for Next-Key locking gaps).
+4. **Foreign Key Integrity**: Check cascade definitions and verify indexes exist on all child FK columns.
+5. **Slow Query Verification**: Inspect query plans with `EXPLAIN FORMAT=JSON` to check `type`, `possible_keys`, `key_len`, and `rows`.
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+### 1. Left-Prefix Index Rule & Optimization
+```sql
+-- For query: WHERE tenant_id = 12 AND created_at >= '2026-01-01' ORDER BY status
+-- ❌ Ineffective Index:
+CREATE INDEX idx_bad ON orders(created_at, tenant_id, status);
+
+-- ✅ Optimal Index: Equality first, then range/sort
+CREATE INDEX idx_optimal ON orders(tenant_id, created_at, status);
+```
+
+### 2. Deadlock Prevention Pattern
+```sql
+-- Always acquire locks on multiple rows in deterministic primary key order
+-- Transaction A & B both update accounts #101 and #202:
+BEGIN;
+-- Sort IDs in application code before querying: [101, 202]
+SELECT id, balance FROM accounts WHERE id IN (101, 202) ORDER BY id FOR UPDATE;
+
+UPDATE accounts SET balance = balance - 50 WHERE id = 101;
+UPDATE accounts SET balance = balance + 50 WHERE id = 202;
+COMMIT;
+```
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **Large Offset Pagination** | `LIMIT 500000, 20` scans 500,020 rows causing severe IO latency | Use keyset (cursor) pagination: `WHERE id > :last_seen_id ORDER BY id ASC LIMIT 20` |
+| **Implicit Type Conversion** | Comparing VARCHAR column to numeric literal causes full table scan | Match data types strictly in query bindings (`WHERE phone = '12345'`) |
+| **Deadlock on Next-Key Lock** | `REPEATABLE READ` locks gap between rows, causing deadlocks on concurrent inserts | Switch to `READ COMMITTED` with row-based replication (`binlog_format=ROW`) |
+
+## 🤖 LLM-Specific Traps Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **Old `utf8` Charset** | Specifying `CHARACTER SET utf8` which only supports 3-byte characters | Always specify `CHARACTER SET utf8mb4` to support emojis and 4-byte Unicode |
+| **Unindexed `UPDATE/DELETE`** | Running `UPDATE ... WHERE status = 'X'` without index | Without an index, InnoDB locks every record in the table, blocking the entire database |
+
+## 🏛️ Tribunal Verification & Guardrails
+- **Active Reviewers:** `database-architect`, `sql-pro`, `security-auditor`
+- **Evidence Standard:** Maintain strict separation of `[OBSERVED]` code, `[INFERRED]` execution plans, and `[UNVERIFIED]` performance metrics.

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]`.