tribunal-kit 9.2.5 → 9.2.6

package/skills/expo-router-v4/SKILL.md

@@ -1,20 +1,47 @@
----
-name: expo-router-v4
-description: "Use when React Native 0.76+ New Architecture (Fabric/TurboModules), Expo Router v4 typed file-based navigation, native haptics, and biometrics."
-version: 5.0.0
-last-updated: 2026-09-13
-skills:
-  - mobile-developer
-  - mobile-design
-  - react-specialist
-tools: Read, Grep, Glob, Bash, Edit, Write
-scripts-binding:
-  - .agent/scripts/lint_runner.js
-  - .agent/scripts/verify_all.js
----
-
-# Expo Router v4 & React Native New Architecture
-
+---
+name: expo-router-v4
+description: "Use when building, optimizing, and securing expo router v4 mobile interfaces, native bridges, touch gestures, and offline states."
+version: 6.0.0
+last-updated: 2026-09-29
+skills:
+  - mobile-developer
+  - mobile-design
+  - react-specialist
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Expo Router v4 & React Native New Architecture
+
+## Mandatory Pre-Flight Context Inspection
+Before reading, generating, or refactoring code in the `expo-router-v4` 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 building, optimizing, and securing expo router v4 mobile interfaces, native bridges, touch gestures, and offline states.
+- **DO NOT activate when:** The task falls outside the `expo-router-v4` 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
@@ -69,4 +96,49 @@ export function TouchButton({ label, onPress, ...props }: TouchButtonProps) {
     </Pressable>
   );
 }
-```
+```
+
+## 🚨 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 |
+|:---|:---|:---|
+| **JS Thread Animation Lag** | Driving gestures and scrolling physics on the React Native JS thread | Use React Native Reanimated worklets running directly on the UI thread |
+| **Missing Keyboard Offset** | Forms hidden behind native software keyboard on iOS/Android | Wrap form views in KeyboardAvoidingView with platform-calibrated behavior |
+| **Uncached Image Flooding** | Rendering raw image URLs in list items without memory caching | Use FastImage or Expo Image with disk cache policies and thumbnail previews |
+
+
+## 🏛️ Tribunal Verification & Guardrails
+
+**Active Reviewers:** `mobile-reviewer` · `frontend-reviewer` · `type-safety`
+**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
+```
+✅ Do touch targets satisfy the 44x44px minimum touch boundary standard?
+✅ Are gesture handlers and native animations offloaded via Reanimated worklets on the UI thread?
+✅ Are keyboard avoiding views, safe areas, and notch offsets handled?
+✅ Is offline storage and state hydration handled with optimistic sync?
+✅ Did I verify compatibility across iOS, Android, and varying screen densities?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing test suites, compiler success, or equivalent operational proof) that your output works as intended.

package/skills/extract-design-system/SKILL.md

@@ -1,36 +1,58 @@
----
-name: extract-design-system
-description: "Use when Design system extraction and tokenization mastery. Identifying repeated HTML/CSS patterns, extracting CSS variables, generating design tokens (colors, spacing, typography), building reusable component schemas, and standardizing ad-hoc styles into cohesive global systems. Use when refactoring messy CSS into a unified design system."
-version: 5.0.0
-last-updated: 2026-09-13
-skills:
-  - create-design-md
-  - tailwind-patterns
-  - baseline-ui
-tools: Read, Grep, Glob, Bash, Edit, Write
-scripts-binding:
-  - .agent/scripts/lint_runner.js
-  - .agent/scripts/verify_all.js
----
-
-# Extract Design System — Tokenization Mastery
-
----
-
-## 🛠️ Technical Architecture & Reference Recipes
-
+---
+name: extract-design-system
+description: "Use when building, styling, optimizing, and auditing extract design system components, responsive layouts, design systems, and frontend state."
+version: 6.0.0
+last-updated: 2026-09-29
+skills:
+  - create-design-md
+  - tailwind-patterns
+  - baseline-ui
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Extract Design System — Tokenization Mastery
+
+## Mandatory Pre-Flight Context Inspection
+Before reading, generating, or refactoring code in the `extract-design-system` 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 building, styling, optimizing, and auditing extract design system components, responsive layouts, design systems, and frontend state.
+- **DO NOT activate when:** The task falls outside the `extract-design-system` 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
+
 ## Hallucination Traps (Read First)
 
 - ❌ Creating CSS variables for every possible value -> ✅ Only tokenize values that appear 3+ times across components
 - ❌ Extracting a design system before the UI is stable -> ✅ Wait until patterns are proven by real usage before standardizing
 - ❌ Naming tokens by appearance (`--blue-500`) instead of purpose (`--color-primary`) -> ✅ Semantic names survive theme changes
 
----
-
----
-
+---
 ## 1. The Token Extraction Protocol
 
 When reviewing a messy, legacy UI file (`<div style="background: #e23e2a; border-radius: 6px; padding: 12px">`), the agent must extract these hardcoded values into Global Tokens.
@@ -117,4 +139,40 @@ const buttonStyles = cva(
 A Design System must mandate accessibility at the token level, preventing developers from manually breaking contrast ratios later.
 
 1. Extracted primary text colors must hit a **4.5:1 contrast ratio** against the extracted background surfaces.
-2. Focus rings must be decoupled and standardized globally (`ring-2 ring-primary ring-offset-2`).
+2. Focus rings must be decoupled and standardized globally (`ring-2 ring-primary ring-offset-2`).
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
+| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
+| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
+| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
+| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
+
+
+## 🏛️ Tribunal Verification & Guardrails
+
+**Active Reviewers:** `frontend-reviewer` · `type-safety` · `ui-ux-auditor` · `complexity-reviewer`
+**Slash Command:** `/review` or `/tribunal-full`
+
+### 🔬 Evidence Standard (Tri-State Verification)
+Every finding, audit statement, or completion claim must classify its factual certainty:
+- **`[OBSERVED]`**: Directly confirmed in the codebase or verified via executed terminal command.
+- **`[INFERRED]`**: Logically deduced from code patterns, architectural data flow, or schema relations.
+- **`[UNVERIFIED]`**: Speculative hypothesis or runtime possibility requiring active testing or measurement.
+
+### ✅ Pre-Flight Self-Audit Checklist
+```
+✅ Are all component props strictly typed with zero implicit "any"?
+✅ Are responsive breakpoints, fluid typography, and optical balance verified?
+✅ Is accessibility (ARIA labels, keyboard navigation, contrast ratio >= 4.5:1) validated?
+✅ Are re-renders minimized and state lifecycles cleanly separated?
+✅ Did I verify all imported UI components and icon sets actually exist?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing test suites, compiler success, or equivalent operational proof) that your output works as intended.

package/skills/fabel-protocol/SKILL.md

@@ -1,27 +1,52 @@
----
-name: fabel-protocol
-description: "Use when Distilled Fabel-5 cognitive intelligence protocol. Injects epistemic reasoning, coding discipline, design evaluation cascades, and orchestration patterns into any AI model. Load this skill to make any model think, reason, code, and design like Fabel-5. Activates for complex builds, code generation, design tasks, and multi-agent orchestration."
-version: 5.0.0
-last-updated: 2026-09-13
-skills:
-  - agentic-patterns
-  - thinking-protocol
-  - knowledge-graph
-tools: Read, Grep, Glob, Bash, Edit, Write
-scripts-binding:
-  - .agent/scripts/checklist.js
-  - .agent/scripts/verify_all.js
-  - .agent/scripts/lint_runner.js
----
-
-# Fabel Protocol — Cognitive Intelligence Engine
-
----
-
-## 🛠️ Technical Architecture & Reference Recipes
-
+---
+name: fabel-protocol
+description: "Use when executing, coordinating, planning, or reviewing fabel protocol agent workflows, cognitive loops, and architecture standards."
+version: 6.0.0
+last-updated: 2026-09-29
+skills:
+  - agentic-patterns
+  - thinking-protocol
+  - knowledge-graph
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/checklist.js
+  - .agent/scripts/verify_all.js
+  - .agent/scripts/lint_runner.js
+---
+
+# Fabel Protocol — Cognitive Intelligence Engine
+
+## Mandatory Pre-Flight Context Inspection
+Before reading, generating, or refactoring code in the `fabel-protocol` 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 fabel protocol agent workflows, cognitive loops, and architecture standards.
+- **DO NOT activate when:** The task falls outside the `fabel-protocol` 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
+
 ---
 
 ## 1. Epistemic Reasoning Protocol
@@ -279,4 +304,49 @@ Before finalizing any response, ask yourself:
 
 ## 8. Brain vs Hands Decoupling Boundary
 
-Agents are explicitly forbidden from attempting to read environment variables, OS tokens, or secrets directly from the shell. The "Brain" (LLM) plans, but the "Hands" (harness manager) executes securely via the Agent Syscall Registry. Do not attempt to bypass this sandbox.
+Agents are explicitly forbidden from attempting to read environment variables, OS tokens, or secrets directly from the shell. The "Brain" (LLM) plans, but the "Hands" (harness manager) executes securely via the Agent Syscall Registry. Do not attempt to bypass this sandbox.
+
+## 🚨 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/skills/failure-mode-analysis/SKILL.md

@@ -1,14 +1,45 @@
----
-name: failure-mode-analysis
-description: 'Evaluates the blast radius and cascading failure potential of architectural changes.'
-version: 1.1.0
-last-updated: 2026-09-26
-skills:
-  - fabel-protocol
----
-
-# Failure Mode Analysis Skill
-
+---
+name: failure-mode-analysis
+description: "Use when executing, coordinating, planning, or reviewing failure mode analysis agent workflows, cognitive loops, and architecture standards."
+version: 6.0.0
+last-updated: 2026-09-29
+skills:
+  - fabel-protocol
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Failure Mode Analysis Skill
+
+## Mandatory Pre-Flight Context Inspection
+Before reading, generating, or refactoring code in the `failure-mode-analysis` 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 failure mode analysis agent workflows, cognitive loops, and architecture standards.
+- **DO NOT activate when:** The task falls outside the `failure-mode-analysis` 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 |
+
+
 Use this skill when evaluating an architecture or an implementation for reliability.
 
 ## 🔴 Hallucination Traps
@@ -45,4 +76,49 @@ failure: '[Scenario]'
 detection_time: '[e.g. 30s timeout]'
 blast_radius: '[Scope of failure]'
 mitigation: '[e.g. Circuit Breaker, Fallback]'
-```
+```
+
+## 🚨 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/skills/fastapi-pro/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: fastapi-pro
+description: "Use when designing, building, auditing, and securing FastAPI applications. Covers Pydantic v2 schemas, async def vs def threadpool mechanics, dependency injection security (Depends), BOLA/IDOR prevention, middleware, and OpenAPI documentation."
+version: 6.0.0
+last-updated: 2026-09-29
+skills:
+  - python-pro
+  - api-security-auditor
+  - backend-security-expert
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# FastAPI & Pydantic v2 Production Architecture Mastery
+
+## Activation Boundaries
+- **Activate when:** Use when designing, building, auditing, and securing FastAPI applications. Covers Pydantic v2 schemas, async def vs def threadpool mechanics, dependency injection security (Depends), BOLA/IDOR prevention, middleware, and OpenAPI documentation.
+- **DO NOT activate when:** The task falls outside the `fastapi-pro` 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. **Async vs Sync Function Signature**: Verify whether route handlers do blocking IO; `async def` with blocking calls freezes event loop.
+2. **Pydantic Version**: Confirm Pydantic v2 syntax (`model_dump()`, `model_validate()`, `field_validator`); reject v1 (`dict()`, `parse_obj()`).
+3. **Dependency Scopes**: Inspect `Depends()` hierarchies; verify authorization and database session boundaries are encapsulated cleanly.
+4. **Data Exposure in Responses**: Verify every endpoint declares an explicit `response_model` to filter private internal fields.
+5. **CORS & Middleware Order**: Ensure security and exception handling middleware are initialized in correct order.
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+### 1. Correct Async vs Sync Handler Architecture
+```python
+from fastapi import FastAPI, Depends, HTTPException, status
+import time
+import asyncio
+
+app = FastAPI()
+
+# ❌ BAD: Blocking IO inside async def blocks the entire single-threaded event loop!
+@app.get("/bad-async")
+async def bad_async():
+    time.sleep(2)  # FREEZES all incoming requests on server
+    return {"status": "blocked"}
+
+# ✅ CORRECT: Use regular def for synchronous/blocking libraries (FastAPI runs in external threadpool)
+@app.get("/good-sync")
+def good_sync():
+    time.sleep(2)  # Executed safely inside anyio worker threadpool
+    return {"status": "threaded"}
+
+# ✅ CORRECT: Use async def ONLY with non-blocking awaitable calls
+@app.get("/good-async")
+async def good_async():
+    await asyncio.sleep(2)  # Releases event loop to handle concurrent requests
+    return {"status": "concurrent"}
+```
+
+### 2. Secure Dependency Injection & Object-Level Authorization (BOLA/IDOR)
+```python
+from pydantic import BaseModel, ConfigDict
+from typing import Annotated
+
+class UserRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: int
+    email: str
+
+async def get_current_user(token: Annotated[str, Depends(oauth2_scheme)]) -> User:
+    user = await verify_jwt_and_fetch_user(token)
+    if not user:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")
+    return user
+
+async def get_project_for_user(
+    project_id: int,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)]
+) -> Project:
+    project = await db.get(Project, project_id)
+    if not project:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
+    # Tenancy / Ownership validation
+    if project.owner_id != current_user.id and current_user.role != "admin":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Access denied")
+    return project
+
+@app.get("/projects/{project_id}", response_model=ProjectRead)
+async def read_project(project: Annotated[Project, Depends(get_project_for_user)]):
+    return project
+```
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Production Mitigation |
+|:---|:---|:---|
+| **Missing response_model** | Accidental return of ORM model exposes password hashes, salts, and internal keys | Always define explicit output schema on route decorator `@app.get(..., response_model=UserPublic)` |
+| **Wildcard CORS with Credentials** | `allow_origins=["*"]` with `allow_credentials=True` triggers browser security rejection | Explicitly declare exact trusted origins array from environment configuration |
+| **Payload Size Bomb** | Unbounded body uploads cause memory exhaustion | Enforce maximum content-length validation in custom middleware |
+
+## 🤖 LLM-Specific Traps Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **Pydantic v1 Syntax** | Using `.dict()`, `.json()`, `validator` | Use Pydantic v2: `.model_dump()`, `.model_dump_json()`, `@field_validator` |
+| **Direct Request Body Extraction** | Manually parsing `await request.json()` | Use type-annotated Pydantic models in endpoint parameters |
+
+## 🏛️ Tribunal Verification & Guardrails
+- **Active Reviewers:** `backend-specialist`, `security-auditor`, `api-architect`
+- **Evidence Standard:** Mark all findings as `[OBSERVED]`, `[INFERRED]`, or `[UNVERIFIED]`.