tribunal-kit 9.2.5 → 9.2.7

package/.agent/skills/backend-alembic/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: backend-alembic
+description: "Use when creating, reviewing, validating, and debugging Alembic database migrations. Covers migration DAGs, zero-downtime expand-and-contract migrations, branch heads, autogenerate limitations, and SQLite batch mode."
+version: 6.0.0
+last-updated: 2026-09-29
+skills:
+  - backend-sqlalchemy
+  - database-design
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Alembic Migration Engineering & Zero-Downtime Governance
+
+## Activation Boundaries
+- **Activate when:** Use when creating, reviewing, validating, and debugging Alembic database migrations. Covers migration DAGs, zero-downtime expand-and-contract migrations, branch heads, autogenerate limitations, and SQLite batch mode.
+- **DO NOT activate when:** The task falls outside the `backend-alembic` 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. **Migration Head Status**: Run `alembic heads` to verify there is only a single active head; detect split branches.
+2. **Autogenerate Limitations**: Inspect generated revision for unhandled types (custom enum alterations, check constraints, table renames).
+3. **Locking Risk**: Identify migrations that lock high-volume tables (adding NOT NULL without default, altering column types).
+4. **Downgrade Symmetry**: Ensure the `downgrade()` function precisely reverses the `upgrade()` function without data loss.
+5. **Target Dialect Compatibility**: Ensure SQLite migrations use `batch_alter_table` when modifying existing columns.
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+### 1. Expand-and-Contract Migration Protocol (Zero-Downtime)
+```python
+"""Rename column 'phone' to 'phone_number' without breaking running application instances"""
+
+# Phase 1 (Migration 1): Expand - Add new nullable column
+def upgrade():
+    op.add_column('users', sa.Column('phone_number', sa.String(20), nullable=True))
+    # Code syncs writes to both phone and phone_number
+
+# Phase 2 (Migration 2): Backfill existing records in small batches
+
+# Phase 3 (Migration 3): Contract - Drop old column after all application pods are updated
+def upgrade():
+    op.drop_column('users', 'phone')
+```
+
+### 2. SQLite Batch Alter Mode
+```python
+from alembic import op
+import sqlalchemy as sa
+
+def upgrade():
+    # SQLite does not support ALTER COLUMN directly; requires table copy
+    with op.batch_alter_table('users', schema=None) as batch_op:
+        batch_op.alter_column('status',
+                              existing_type=sa.VARCHAR(10),
+                              type_=sa.String(25),
+                              existing_nullable=False)
+```
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **Multiple Heads Divergence** | Two developers merge migrations with the same parent, causing deploy collision | Run `alembic merge heads -m "merge branches"` before pushing |
+| **Exclusive Table Lock on Heavy Table** | `ALTER TABLE ADD COLUMN NOT NULL DEFAULT 'val'` on PG < 11 locks table | Add column as NULL, backfill rows in batches, then set NOT NULL |
+| **Enum Type Alteration Failure** | Modifying Postgres native ENUM via autogenerate is not supported | Use explicit raw SQL `op.execute("ALTER TYPE user_status ADD VALUE 'SUSPENDED'")` |
+
+## 🤖 LLM-Specific Traps Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **Empty or `pass` Downgrades** | Leaving `def downgrade(): pass` in production migrations | Always implement functional, symmetric `downgrade()` logic |
+| **Direct Schema Inspection Assumption** | Assuming `autogenerate` catches everything | Always manually verify detected changes; autogenerate misses table renames, index partials, and check constraints |
+
+## 🏛️ Tribunal Verification & Guardrails
+- **Active Reviewers:** `database-architect`, `sql-pro`, `devops-engineer`
+- **Evidence Standard:** Mark findings as `[OBSERVED]`, `[INFERRED]`, or `[UNVERIFIED]`.

package/.agent/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/.agent/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/.agent/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/.agent/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/.agent/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.