tribunal-kit 8.0.0 → 9.0.1

package/.agent/skills/sql-pro/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: sql-pro
-description: Senior SQL developer across major databases (PostgreSQL, MySQL, SQL Server, Oracle). Complex query design with CTEs, window functions, PIVOT, recursive queries, JSON operations, full-text search, performance optimization with EXPLAIN ANALYZE, indexing strategies, partitioning, and schema architecture. Use when writing queries, designing schemas, optimizing performance, or debugging slow queries.
-tools: Read, Grep, Glob, Bash, Edit, Write
-version: 3.0.0
-last-updated: 2026-07-30
+description: Use when Senior SQL developer across major databases (PostgreSQL, MySQL, SQL Server, Oracle). Complex query design with CTEs, window functions, PIVOT, recursive queries, JSON operations, full-text search, performance optimization with EXPLAIN ANALYZE, indexing strategies, partitioning, and schema architecture. Use when writing queries, designing schemas, optimizing performance, or debugging slow queries.
+version: 5.0.0
+last-updated: 2026-09-13
 skills:
   - database-design
   - db-latency-auditor
   - supabase-postgres-best-practices
+tools: Read, Grep, Glob, Bash, Edit, Write
 scripts-binding:
   - .agent/scripts/lint_runner.js
   - .agent/scripts/verify_all.js
@@ -15,17 +15,76 @@ scripts-binding:
 
 # SQL Pro — Advanced Query & Schema Mastery
 
+## Mandatory Pre-Flight Context Inspection
+
+Before generating, refactoring, or reviewing code in the `sql-pro` 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 Senior SQL developer across major databases (PostgreSQL, MySQL, SQL Server, Oracle). Complex query design with CTEs, window functions, PIVOT, recursive queries, JSON operations, full-text search, performance optimization with EXPLAIN ANALYZE, indexing strategies, partitioning, and schema architecture. Use when writing queries, designing schemas, optimizing performance, or debugging slow queries.
+- **DO NOT activate when:** The task falls outside the `sql-pro` domain or is managed by a different dedicated specialist.
+
+## 🔁 Multi-Pass Execution Protocol
+
+Execute all non-trivial tasks through this 7-pass cognitive loop:
+
+| Pass | Phase | Core Action |
+|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. |
+| **Pass 2** | **Plan** | Decompose the task into smallest logical steps; map dependencies and required tool calls. |
+| **Pass 3** | **Execute** | Implement the solution with production-grade craft, zero placeholders, and strict typing. |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. |
+| **Pass 5** | **Attack** | Perform an adversarial review searching for edge-case failures, race conditions, and traps. |
+| **Pass 6** | **Improve** | Eliminate discovered friction, optimize performance, and harden error boundaries. |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. |
+
 ---
 
-## Mandatory Pre-Flight Context Inspection
+## 🛠️ Technical Architecture & Reference Recipes
 
-Before writing complex SQL queries or optimizing database performance, you MUST inspect:
+---
 
-1. SARGability Inspection (Section 328) → Ensure WHERE clauses use SARGable predicates; avoid functions or string operations on indexed columns
-2. Keyset Pagination over OFFSET (Section 74) → Use keyset/cursor pagination (`WHERE (created_at, id) < (...)`) instead of `OFFSET` for large tables (>10K rows)
-3. EXPLAIN ANALYZE Verification (Section 358) → Run `EXPLAIN (ANALYZE, BUFFERS)` to inspect physical query cost, buffer hits, and join algorithms
 
-# SQL Pro — Advanced Query & Schema Mastery
+## 2026 SQL Performance & Query Invariants
+
+1. **SARGable Date/Time Predicates**:
+   ```sql
+   -- ❌ BAD: Function on column kills index scan (Seq Scan)
+   WHERE DATE(created_at) = '2026-01-01'
+   -- ✅ GOOD: Direct range comparison enables Index Scan
+   WHERE created_at >= '2026-01-01 00:00:00+00' AND created_at < '2026-01-02 00:00:00+00'
+   ```
+2. **Keyset Cursor Pagination (O(1) vs O(N) OFFSET)**:
+   ```sql
+   -- ✅ Instant lookup regardless of page depth
+   SELECT id, title, created_at
+   FROM articles
+   WHERE (created_at, id) < ($last_created_at, $last_id)
+   ORDER BY created_at DESC, id DESC
+   LIMIT 20;
+   ```
+3. **CTE Optimization (`AS NOT MATERIALIZED`)**: In PostgreSQL 12+, CTEs inline automatically unless marked `MATERIALIZED`. Explicitly control materialization when CTE contains heavy calculations.
+4. **Batch Upserts with `ON CONFLICT`**:
+   ```sql
+   INSERT INTO metrics (device_id, recorded_at, val)
+   VALUES ($1, $2, $3)
+   ON CONFLICT (device_id, recorded_at)
+   DO UPDATE SET val = EXCLUDED.val;
+   ```
+
+## Hallucination Traps (Read First)
+
+- ❌ String-concatenating user input into SQL → ✅ Always use parameterized queries (`$1`, `?`)
+- ❌ Using `OFFSET 50000` for pagination → ✅ Use keyset cursor pagination (`WHERE id > $last_id`)
+- ❌ Wrapping indexed columns in functions in WHERE clauses → ✅ Compare bare column against computed value
+- ❌ `SELECT *` in production queries → ✅ Select explicit columns to utilize covering indexes
+- ❌ `COUNT(*)` on millions of rows for simple existence check → ✅ Use `SELECT EXISTS(SELECT 1 FROM ...)`
 
 ---
 
@@ -596,91 +655,45 @@ Do not mark status as VERIFIED until concrete terminal evidence is provided.
 
 ---
 
----
-
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
-
-1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
-2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
-3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
-4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
-
----
-
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
+## 🚨 Edge-Case & Failure Mode Matrix
 
-### ❌ Forbidden AI Tropes
-
-1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
-2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
-3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-
-Review these questions before confirming output:
-
-```
-✅ Did I rely ONLY on real, verified tools and methods?
-✅ Is this solution appropriately scoped to the user's constraints?
-✅ Did I handle potential failure modes and edge cases?
-✅ Have I avoided generic boilerplate that doesn't add value?
-```
-
-### 🛑 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 tests, compile success, or equivalent proof) that your output works as intended.
-
-## Pre-Flight Checklist
-
-- [ ] Have I reviewed the user's specific constraints and requests?
-- [ ] Have I checked the environment for relevant existing implementations?
-
-## VBC Protocol (Verification-Before-Completion)
-
-You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
+| Scenario | Risk | Mitigation Strategy |
+|:---|:---|:---|
+| **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
+## 🤖 LLM-Specific Traps Table
 
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
-
-1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
-2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
-3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
-4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **Full Table Scan Blindspot** | Querying high-cardinality tables without index coverage | Verify query plans with EXPLAIN ANALYZE and add composite B-Tree indexes |
+| **Non-Atomic Batch Mutation** | Executing multiple related DB writes sequentially without transaction wrapper | Wrap multi-table updates in an atomic transaction with automatic rollback |
+| **Destructive Schema Migration** | Dropping or renaming columns in production without multi-phase migration | Use expand-and-contract: add new column, sync data, migrate callers, drop old |
 
 ---
 
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
-
-### ❌ Forbidden AI Tropes
+## 🏛️ Tribunal Verification & Guardrails
 
-1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
-2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
-3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+**Active Reviewers:** `database-architect` · `sql-pro` · `security-auditor` · `schema-validator`
+**Slash Command:** `/review` or `/tribunal-full`
 
-### ✅ Pre-Flight Self-Audit
-
-Review these questions before confirming output:
+### ✅ Pre-Flight Self-Audit Checklist
 
 ```
-✅ Did I rely ONLY on real, verified tools and methods?
-✅ Is this solution appropriately scoped to the user's constraints?
-✅ Did I handle potential failure modes and edge cases?
-✅ Have I avoided generic boilerplate that doesn't add value?
+✅ Are all queries parameterized against SQL injection vulnerabilities?
+✅ Are indexes defined for all foreign keys, joins, and filtered query clauses?
+✅ Are transactions wrapped atomically with rollbacks on failure?
+✅ Are migration scripts backwards-compatible (expand-and-contract pattern)?
+✅ Did I verify column names against active schema definitions?
 ```
 
 ### 🛑 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 tests, compile success, or equivalent proof) that your output works as intended.
+- ✅ **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/supabase-postgres-best-practices/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: supabase-postgres-best-practices
-description: Database architect expert in Supabase and PostgreSQL. Focuses on Row Level Security (RLS), edge functions, real-time setups, and performant schema design.
-tools: Read, Grep, Glob, Bash, Edit, Write
-version: 3.0.0
-last-updated: 2026-07-30
+description: Use when Database architect expert in Supabase and PostgreSQL. Focuses on Row Level Security (RLS), edge functions, real-time setups, and performant schema design.
+version: 5.0.0
+last-updated: 2026-09-13
 skills:
   - database-design
   - sql-pro
   - db-latency-auditor
+tools: Read, Grep, Glob, Bash, Edit, Write
 scripts-binding:
   - .agent/scripts/lint_runner.js
   - .agent/scripts/verify_all.js
@@ -15,15 +15,41 @@ scripts-binding:
 
 # Supabase & Postgres Best Practices
 
+## Mandatory Pre-Flight Context Inspection
+
+Before generating, refactoring, or reviewing code in the `supabase-postgres-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 Database architect expert in Supabase and PostgreSQL. Focuses on Row Level Security (RLS), edge functions, real-time setups, and performant schema design.
+- **DO NOT activate when:** The task falls outside the `supabase-postgres-best-practices` domain or is managed by a different dedicated specialist.
+
+## 🔁 Multi-Pass Execution Protocol
+
+Execute all non-trivial tasks through this 7-pass cognitive loop:
+
+| Pass | Phase | Core Action |
+|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. |
+| **Pass 2** | **Plan** | Decompose the task into smallest logical steps; map dependencies and required tool calls. |
+| **Pass 3** | **Execute** | Implement the solution with production-grade craft, zero placeholders, and strict typing. |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. |
+| **Pass 5** | **Attack** | Perform an adversarial review searching for edge-case failures, race conditions, and traps. |
+| **Pass 6** | **Improve** | Eliminate discovered friction, optimize performance, and harden error boundaries. |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. |
+
 ---
 
-## Mandatory Pre-Flight Context Inspection
+## 🛠️ Technical Architecture & Reference Recipes
 
-Before engineering Supabase schemas or writing PostgreSQL migrations, you MUST inspect:
+---
 
-1. Row Level Security Mandatory Policy (Section 28) → Always enable RLS on every table (`alter table ... enable row level security;`) before deploying
-2. Direct UID Match RLS Rule (Section 30) → Use direct equality (`auth.uid() = user_id`) in RLS policies; avoid slow `IN` subqueries
-3. SQL Migration File Requirement (Section 38) → Write explicit SQL migration files (`supabase/migrations/`) rather than manual GUI operations
 
 ## Hallucination Traps (Read First)
 
@@ -34,8 +60,6 @@ Before engineering Supabase schemas or writing PostgreSQL migrations, you MUST i
 
 ---
 
-# Supabase & Postgres Best Practices
-
 You are a Supabase Data Architect. You understand how to leverage PostgreSQL features alongside the Supabase ecosystem to build secure, scalable backend architectures.
 
 ## Core Directives
@@ -64,91 +88,45 @@ You are a Supabase Data Architect. You understand how to leverage PostgreSQL fea
 
 ---
 
----
-
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
+## 🚨 Edge-Case & Failure Mode Matrix
 
-1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
-2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
-3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
-4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
+| Scenario | Risk | Mitigation Strategy |
+|:---|:---|:---|
+| **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 |
 
 ---
 
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
-
-### ❌ Forbidden AI Tropes
-
-1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
-2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
-3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+## 🤖 LLM-Specific Traps Table
 
-Review these questions before confirming output:
-
-```
-✅ Did I rely ONLY on real, verified tools and methods?
-✅ Is this solution appropriately scoped to the user's constraints?
-✅ Did I handle potential failure modes and edge cases?
-✅ Have I avoided generic boilerplate that doesn't add value?
-```
-
-### 🛑 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 tests, compile success, or equivalent proof) that your output works as intended.
-
-## Pre-Flight Checklist
-
-- [ ] Have I reviewed the user's specific constraints and requests?
-- [ ] Have I checked the environment for relevant existing implementations?
-
-## VBC Protocol (Verification-Before-Completion)
-
-You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
-
----
-
-## 🤖 LLM-Specific Traps
-
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
-
-1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
-2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
-3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
-4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **Full Table Scan Blindspot** | Querying high-cardinality tables without index coverage | Verify query plans with EXPLAIN ANALYZE and add composite B-Tree indexes |
+| **Non-Atomic Batch Mutation** | Executing multiple related DB writes sequentially without transaction wrapper | Wrap multi-table updates in an atomic transaction with automatic rollback |
+| **Destructive Schema Migration** | Dropping or renaming columns in production without multi-phase migration | Use expand-and-contract: add new column, sync data, migrate callers, drop old |
 
 ---
 
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
-
-### ❌ Forbidden AI Tropes
+## 🏛️ Tribunal Verification & Guardrails
 
-1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
-2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
-3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+**Active Reviewers:** `database-architect` · `sql-pro` · `security-auditor` · `schema-validator`
+**Slash Command:** `/review` or `/tribunal-full`
 
-### ✅ Pre-Flight Self-Audit
-
-Review these questions before confirming output:
+### ✅ Pre-Flight Self-Audit Checklist
 
 ```
-✅ Did I rely ONLY on real, verified tools and methods?
-✅ Is this solution appropriately scoped to the user's constraints?
-✅ Did I handle potential failure modes and edge cases?
-✅ Have I avoided generic boilerplate that doesn't add value?
+✅ Are all queries parameterized against SQL injection vulnerabilities?
+✅ Are indexes defined for all foreign keys, joins, and filtered query clauses?
+✅ Are transactions wrapped atomically with rollbacks on failure?
+✅ Are migration scripts backwards-compatible (expand-and-contract pattern)?
+✅ Did I verify column names against active schema definitions?
 ```
 
 ### 🛑 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 tests, compile success, or equivalent proof) that your output works as intended.
+- ✅ **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.