tribunal-kit 9.2.5 → 9.2.7

package/.agents/skills/authentication-best-practices/SKILL.md

@@ -1,26 +1,51 @@
----
-name: authentication-best-practices
-description: "Use when Authentication and Authorization mastery. Best practices for OAuth2, OpenID Connect, JWT (JSON Web Tokens), session management, password hashing, MFA (Multi-Factor Authentication), RBAC/ABAC, SSO, and secure credential storage. Use when auditing or implementing login flows, identity systems, or access control."
-version: 5.0.0
-last-updated: 2026-09-13
-skills:
-  - backend-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
----
-
-# Authentication & Authorization — Identity Mastery
-
----
-
-## 🛠️ Technical Architecture & Reference Recipes
-
+---
+name: authentication-best-practices
+description: "Use when auditing, pen-testing, hardening, and verifying code against authentication best practices vulnerabilities, injection vectors, and auth flaws."
+version: 6.0.0
+last-updated: 2026-09-29
+skills:
+  - backend-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
+---
+
+# Authentication & Authorization — Identity Mastery
+
+## Mandatory Pre-Flight Context Inspection
+Before reading, generating, or refactoring code in the `authentication-best-practices` 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 auditing, pen-testing, hardening, and verifying code against authentication best practices vulnerabilities, injection vectors, and auth flaws.
+- **DO NOT activate when:** The task falls outside the `authentication-best-practices` 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
+
 ---
 
 ## Passwords & Hashing
@@ -154,4 +179,49 @@ function canEditPost(user: User, post: Post): boolean {
   if (post.status === 'draft' && user.department === 'content') return true;
   return false;
 }
-```
+```
+
+## 🚨 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 |
+
+
+## 🤖 LLM-Specific Traps Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **Hardcoded Secret Pattern** | Committing API keys, tokens, or private salts into source code | Load credentials strictly via runtime environment variables and secret stores |
+| **Prompt Injection Surface** | Directly concatenating untrusted user input into LLM system prompts | Wrap user content in isolated delimiters and strip injection control sequences |
+| **Missing Authorization Check** | Relying only on authentication token presence without checking tenant/object RBAC | Verify user permissions against the specific target record ID before mutation |
+
+
+## 🏛️ Tribunal Verification & Guardrails
+
+**Active Reviewers:** `security-auditor` · `penetration-tester` · `backend-security-expert`
+**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 user inputs sanitized and treated as untrusted data at system boundaries?
+✅ Are secrets loaded strictly via environment variables with zero hardcoding?
+✅ Is least-privilege enforcement active on APIs, tokens, and storage buckets?
+✅ Are prompt-injection delimiters and sanitizers wrapped around LLM inputs?
+✅ Did I verify encryption in transit and at rest for sensitive data?
+```
+
+### 🛑 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/.agents/skills/autonomous-execution/SKILL.md

@@ -1,10 +1,43 @@
----
-description: Use when executing subagent tasks autonomously. Defines the scratchpad structure and ReAct loops.
-version: 3.0.0
----
-
-# Autonomous Execution (Bounded Jev-style Loop)
-
+---
+name: autonomous-execution
+description: "Use when executing, coordinating, planning, or reviewing autonomous execution agent workflows, cognitive loops, and architecture standards."
+version: 6.0.0
+last-updated: 2026-09-29
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Autonomous Execution (Bounded Jev-style Loop)
+
+## Mandatory Pre-Flight Context Inspection
+Before reading, generating, or refactoring code in the `autonomous-execution` 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 executing, coordinating, planning, or reviewing autonomous execution agent workflows, cognitive loops, and architecture standards.
+- **DO NOT activate when:** The task falls outside the `autonomous-execution` 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 |
+
+
 $ARGUMENTS
 
 ---
@@ -73,4 +106,49 @@ If you fail the same test 3 times, or if you reach 10 total iterations, STOP and
 
 ## 6. Zero Commits
 
-You are an implementer. You only modify files. The SDD Controller will generate the `.diff` and commit the files after the Tribunal Wave approves your work. DO NOT run `git commit`.
+You are an implementer. You only modify files. The SDD Controller will generate the `.diff` and commit the files after the Tribunal Wave approves your work. DO NOT run `git commit`.
+
+## 🚨 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 |
+
+
+## 🤖 LLM-Specific Traps Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **Hallucinated Tool Capabilities** | Assuming an external library or CLI command exists without verification | Run a verification check or verify package.json before referencing tools |
+| **Premature Completion Claim** | Declaring a task finished because code was generated without verification | Execute tests, linters, or terminal commands to provide concrete proof |
+| **Context Bloat Dumping** | Pasting entire multi-thousand-line files into prompt context | Extract targeted excerpts, symbols, and signatures to preserve tokens |
+
+
+## 🏛️ Tribunal Verification & Guardrails
+
+**Active Reviewers:** `orchestrator` · `agent-organizer` · `logic-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
+```
+✅ Did I deconstruct the root objective before proposing architecture?
+✅ Did I identify dependencies, bottlenecks, and parallelizable sub-tasks?
+✅ Did I avoid over-engineering and select the simplest effective pattern?
+✅ Did I verify assumptions with concrete file reads instead of speculation?
+✅ Did I establish measurable verification criteria before completion?
+```
+
+### 🛑 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/.agents/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/.agents/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/.agents/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/.agents/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.