tribunal-kit 9.2.4 → 9.2.6

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

@@ -1,8 +1,8 @@
 ---
 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
+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
@@ -15,143 +15,213 @@ scripts-binding:
 
 # 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).
 
-## 🛠️ Technical Architecture & Reference Recipes
 
----
+## 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.
 
----
 
-## Passwords & Hashing
+## 🔁 Multi-Pass Execution Protocol
 
-```typescript
-// ❌ BAD: md5, sha1, sha256 (too fast, vulnerable to brute force/rainbow tables)
-const hash = crypto.createHash('sha256').update(password).digest('hex');
+| 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 |
 
-// ✅ GOOD: Argon2 (memory-hard, ASIC resistant) or bcrypt
-import * as argon2 from 'argon2';
 
-async function hashPassword(password: string): Promise<string> {
-  // Argon2 hashes include the salt inherently in the resulting string
-  return await argon2.hash(password, {
-    type: argon2.argon2id, // recommended variant
-    memoryCost: 2 ** 16, // 64 MB
-    timeCost: 3, // iterations
-    parallelism: 1, // threads
-  });
-}
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
 
-async function verifyPassword(hash: string, password: string): Promise<boolean> {
-  return await argon2.verify(hash, password);
-}
+---
+
+## Passwords & Hashing
+
+```typescript
+// ❌ BAD: md5, sha1, sha256 (too fast, vulnerable to brute force/rainbow tables)
+const hash = crypto.createHash('sha256').update(password).digest('hex');
+
+// ✅ GOOD: Argon2 (memory-hard, ASIC resistant) or bcrypt
+import * as argon2 from 'argon2';
+
+async function hashPassword(password: string): Promise<string> {
+  // Argon2 hashes include the salt inherently in the resulting string
+  return await argon2.hash(password, {
+    type: argon2.argon2id, // recommended variant
+    memoryCost: 2 ** 16, // 64 MB
+    timeCost: 3, // iterations
+    parallelism: 1, // threads
+  });
+}
+
+async function verifyPassword(hash: string, password: string): Promise<boolean> {
+  return await argon2.verify(hash, password);
+}
+```
+
+### Password Policies
+
+- **Length over complexity**: Require minimum 12 characters. Stop requiring arbitrary symbols (e.g., `!@#`).
+- **Check against breaches**: Use HaveIBeenPwned API or similar to reject compromised passwords during signup.
+- **Never expire passwords arbitrarily**: Only force resets if there is evidence of a breach.
+
+---
+
+## Session Management vs. JWT
+
+### 1. Stateful Sessions (Cookies)
+
+**Best for**: Monolithic web apps, SSR apps (Next.js, Remix).
+
+- Server stores session ID mapped to user data in Redis/DB.
+- Client stores session ID in an `HttpOnly`, `Secure`, `SameSite=Lax/Strict` cookie.
+- **Pros**: Immediate revocation, server-side truth, invisible to XSS.
+- **Cons**: Requires DB lookup per request.
+
+### 2. Stateless JWT (JSON Web Tokens)
+
+**Best for**: Distributed APIs, Microservices, Native mobile apps.
+
+- Server signs a token containing user claims.
+- Client passes it in `Authorization: Bearer <token>` header.
+- **Pros**: No DB lookup needed, easy cross-origin sharing.
+- **Cons**: Cannot be easily revoked before expiration.
+
+### The JWT "Refresh Token" Pattern
+
+```typescript
+// Scenario: API authentication
+// 1. Access Token (Short-lived: 15 mins)
+const accessToken = jwt.sign({ userId: user.id }, JWT_SECRET, {
+  expiresIn: '15m',
+  algorithm: 'HS256', // ALWAYS explicitly specify
+});
+// 2. Refresh Token (Long-lived: 7 days, opaque string in DB)
+const refreshToken = crypto.randomBytes(40).toString('hex');
+await db.refreshTokens.create({ token: refreshToken, userId: user.id, expires: addDays(7) });
+
+// Client flow:
+// - Access token kept in memory (JS variable) to prevent XSS theft.
+// - Refresh token kept in HttpOnly cookie.
+// - When Access Token expires, endpoint reads cookie, validates DB, issues new Access Token.
+```
+
+---
+
+## OAuth2 & OIDC (OpenID Connect)
+
+```
+Roles:
+1. Resource Owner (User)
+2. Client (Your App)
+3. Authorization Server (Google/GitHub/Auth0)
+4. Resource Server (API)
+
+Flow (Authorization Code + PKCE):
+1. User clicks "Login with Google".
+2. App generates `code_verifier` and `code_challenge`.
+3. App redirects user to Google with `code_challenge`.
+4. User logs in, Google redirects back to App with an authorization `code`.
+5. App sends `code` + `code_verifier` to Google backend.
+6. Google returns `id_token` (OIDC identity) and `access_token` (OAuth permissions).
+
+// ❌ HALLUCINATION TRAP: Implicit Flow is deprecated.
+// Never use Implicit Flow (response_type=token) where the token is returned in the URL hash.
+// Always use Authorization Code Flow with PKCE, even for Single Page Apps (SPAs).
+```
+
+---
+
+## Multi-Factor Authentication (MFA)
+
+- **SMS**: Deprecated by NIST due to SIM swapping vulnerabilities. (Better than nothing, but avoid as primary MFA).
+- **TOTP (Authenticator Apps)**: Standard implementations use HMAC-SHA1. Keep the secret key heavily encrypted at rest.
+- **WebAuthn / Passkeys**: The modern gold standard. Replaces passwords entirely using hardware enclaves (FaceID, TouchID, YubiKey).
+
+---
+
+## Authorization Models
+
+### RBAC (Role-Based Access Control)
+
+- Users have Roles (`admin`, `editor`, `viewer`).
+- Roles have Permissions (`create:post`, `delete:user`).
+
+```typescript
+// ✅ Check permissions, not roles directly (more flexible)
+if (!user.permissions.includes('delete:user')) {
+  throw new ForbiddenError();
+}
+```
+
+### ABAC (Attribute-Based Access Control)
+
+- Access based on context (e.g., "User can edit Document if Document.department == User.department").
+
+```typescript
+// Example Policy
+function canEditPost(user: User, post: Post): boolean {
+  if (user.role === 'admin') return true;
+  if (post.authorId === user.id) return true;
+  if (post.status === 'draft' && user.department === 'content') return true;
+  return false;
+}
 ```
 
-### Password Policies
-
-- **Length over complexity**: Require minimum 12 characters. Stop requiring arbitrary symbols (e.g., `!@#`).
-- **Check against breaches**: Use HaveIBeenPwned API or similar to reject compromised passwords during signup.
-- **Never expire passwords arbitrarily**: Only force resets if there is evidence of a breach.
-
----
-
-## Session Management vs. JWT
-
-### 1. Stateful Sessions (Cookies)
-
-**Best for**: Monolithic web apps, SSR apps (Next.js, Remix).
+## 🚨 Edge-Case & Failure Mode Matrix
 
-- Server stores session ID mapped to user data in Redis/DB.
-- Client stores session ID in an `HttpOnly`, `Secure`, `SameSite=Lax/Strict` cookie.
-- **Pros**: Immediate revocation, server-side truth, invisible to XSS.
-- **Cons**: Requires DB lookup per request.
+| 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 |
 
-### 2. Stateless JWT (JSON Web Tokens)
 
-**Best for**: Distributed APIs, Microservices, Native mobile apps.
+## 🤖 LLM-Specific Traps Table
 
-- Server signs a token containing user claims.
-- Client passes it in `Authorization: Bearer <token>` header.
-- **Pros**: No DB lookup needed, easy cross-origin sharing.
-- **Cons**: Cannot be easily revoked before expiration.
+| 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 |
 
-### The JWT "Refresh Token" Pattern
 
-```typescript
-// Scenario: API authentication
-// 1. Access Token (Short-lived: 15 mins)
-const accessToken = jwt.sign({ userId: user.id }, JWT_SECRET, {
-  expiresIn: '15m',
-  algorithm: 'HS256', // ALWAYS explicitly specify
-});
-// 2. Refresh Token (Long-lived: 7 days, opaque string in DB)
-const refreshToken = crypto.randomBytes(40).toString('hex');
-await db.refreshTokens.create({ token: refreshToken, userId: user.id, expires: addDays(7) });
+## 🏛️ Tribunal Verification & Guardrails
 
-// Client flow:
-// - Access token kept in memory (JS variable) to prevent XSS theft.
-// - Refresh token kept in HttpOnly cookie.
-// - When Access Token expires, endpoint reads cookie, validates DB, issues new Access Token.
-```
-
----
+**Active Reviewers:** `security-auditor` · `penetration-tester` · `backend-security-expert`
+**Slash Command:** `/review` or `/tribunal-full`
 
-## OAuth2 & OIDC (OpenID Connect)
+### 🔬 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
 ```
-Roles:
-1. Resource Owner (User)
-2. Client (Your App)
-3. Authorization Server (Google/GitHub/Auth0)
-4. Resource Server (API)
-
-Flow (Authorization Code + PKCE):
-1. User clicks "Login with Google".
-2. App generates `code_verifier` and `code_challenge`.
-3. App redirects user to Google with `code_challenge`.
-4. User logs in, Google redirects back to App with an authorization `code`.
-5. App sends `code` + `code_verifier` to Google backend.
-6. Google returns `id_token` (OIDC identity) and `access_token` (OAuth permissions).
-
-// ❌ HALLUCINATION TRAP: Implicit Flow is deprecated.
-// Never use Implicit Flow (response_type=token) where the token is returned in the URL hash.
-// Always use Authorization Code Flow with PKCE, even for Single Page Apps (SPAs).
+✅ 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?
 ```
 
----
-
-## Multi-Factor Authentication (MFA)
-
-- **SMS**: Deprecated by NIST due to SIM swapping vulnerabilities. (Better than nothing, but avoid as primary MFA).
-- **TOTP (Authenticator Apps)**: Standard implementations use HMAC-SHA1. Keep the secret key heavily encrypted at rest.
-- **WebAuthn / Passkeys**: The modern gold standard. Replaces passwords entirely using hardware enclaves (FaceID, TouchID, YubiKey).
-
----
-
-## Authorization Models
-
-### RBAC (Role-Based Access Control)
-
-- Users have Roles (`admin`, `editor`, `viewer`).
-- Roles have Permissions (`create:post`, `delete:user`).
-
-```typescript
-// ✅ Check permissions, not roles directly (more flexible)
-if (!user.permissions.includes('delete:user')) {
-  throw new ForbiddenError();
-}
-```
-
-### ABAC (Attribute-Based Access Control)
-
-- Access based on context (e.g., "User can edit Document if Document.department == User.department").
-
-```typescript
-// Example Policy
-function canEditPost(user: User, post: Post): boolean {
-  if (user.role === 'admin') return true;
-  if (post.authorId === user.id) return true;
-  if (post.status === 'draft' && user.department === 'content') return true;
-  return false;
-}
-```
+### 🛑 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/.agent/skills/autonomous-execution/SKILL.md

@@ -0,0 +1,154 @@
+---
+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
+
+---
+
+## 1. Scratchpad Memory Rule
+
+You MUST initialize and maintain your state in `task-<N>-scratchpad.md`.
+Do not try to remember complex API signatures in your context window. Write them down in the scratchpad.
+
+### Scratchpad Structure:
+
+```markdown
+# Scratchpad - Task <N>
+
+## 1. Goal
+
+[Briefly state the goal derived from the task brief]
+
+## 2. Execution Plan
+
+- [ ] Step 1
+- [ ] Step 2
+
+## 3. Current Context
+
+- `some_file.js`: Exports `functionA(a, b)`
+- API: Requires `Bearer` token
+
+## 4. Attempt Log
+
+- Attempt 1: Failed test `x is undefined`. Fix: Update `y`.
+```
+
+Whenever you discover something new or fail a test, UPDATE the scratchpad before taking your next action.
+
+## 2. Dynamic Discovery (No Guessing)
+
+Do NOT assume file structures or API endpoints.
+
+- Use `list_dir` or `grep_search` to find the files you need to modify.
+- Use `view_file` to read the exact lines of code you are changing.
+- Verify every import against `package.json`.
+
+## 3. The ReAct Loop (Thought -> Action -> Observation)
+
+You are in a continuous loop. Do not stop until the task is complete.
+
+1. **Thought:** "I need to find the SDD controller."
+2. **Action:** Call `grep_search` for "SDD controller".
+3. **Observation:** See results.
+4. **Thought:** "I found it in `sdd.js`. I will read it."
+5. **Action:** Call `view_file` on `sdd.js`.
+
+## 4. TDD Self-Correction
+
+1. Write tests.
+2. Run tests via `run_command` (e.g., `npm run test` or `cargo test`).
+3. If they fail, READ the error output.
+4. Document the failure in your scratchpad.
+5. Fix the code.
+6. Loop until tests pass (GREEN).
+
+## 5. Circuit Breaker
+
+If you fail the same test 3 times, or if you reach 10 total iterations, STOP and report the failure in your final output. Do NOT loop infinitely.
+
+## 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`.
+
+## 🚨 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/.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]`.