tribunal-kit 9.0.0 → 9.0.2

package/.agents/skills/ui-ux-pro-max/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: ui-ux-pro-max
+description: Use when The Picasso Protocol — Elite UI/UX design mastery. Integrates the 16-step UI Reasoning Engine, Category-Specific Heuristics, and Anti-Pattern controls to generate portfolio-grade interfaces.
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - ui-reasoning-engine
+  - product-aware-heuristics
+  - frontend-design
+  - web-design-guidelines
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# UI/UX Pro Max v3.0 — The Picasso Protocol
+
+## Mandatory Pre-Flight Context Inspection
+
+Before generating, refactoring, or reviewing code in the `ui-ux-pro-max` 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 The Picasso Protocol — Elite UI/UX design mastery. Integrates the 16-step UI Reasoning Engine, Category-Specific Heuristics, and Anti-Pattern controls to generate portfolio-grade interfaces.
+- **DO NOT activate when:** The task falls outside the `ui-ux-pro-max` 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. |
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+---
+
+
+## 2026 Picasso Protocol Design Invariants
+
+1. **Anti-Cliché Palette Discipline**:
+   Never use purple (#7c3aed / #8b5cf6) as primary brand color. Curate characterful palettes: Obsidian + Signal Orange, Slate + Electric Cyan, or Bone White + Deep Emerald.
+2. **Intentional Typography Pairing**:
+   Pair an expressive display font (e.g., Clash Display, Syne, Cabinet Grotesk, Newsreader) with an ultra-readable neutral body font (e.g., Geist Sans, Plus Jakarta Sans, General Sans).
+3. **Fluid Layout Bounds & Asymmetry**:
+   Break repetitive bento grids. Use asymmetric column spans (e.g. 7:5 or 8:4), overlapping cards, and ambient grain overlays.
+
+---
+
+## 🚨 Design Governance Guardrails (REJECTION Rules)
+
+- ❌ **Primary Purple Accents:** Banned. Use electric blue, signal orange, coral, warm slate, or natural sage.
+- ❌ **Inter/Roboto Defaults:** Banned. Display titles must use characterful display fonts; body text uses readable body options.
+- ❌ **Left Text/Right Image Hero:** Banned. Use full-bleed, asymmetric overlap, or typographical layouts.
+- ❌ **Radial Mesh Backgrounds:** Banned. Use ambient grain overlay, solid high-contrast depth, or radial tinting.
+- ❌ **Bento Box Grid Overuse:** Banned. Break the grid intentionally for visual interest.
+- ❌ **Flat Glassmorphic Panels:** Banned. Translucency should only be used as a rare overlay, not for main containers.
+- ❌ **No States Feedback:** Banned. Every control must have styled states (Hover, Focus-visible, Active, Disabled).
+
+---
+
+## 1. Color Gamuts & Display-P3 Color Science
+
+Use dynamic OKLCH variables to access the wider Display-P3 color spectrum for stunning vibrancy. Perceptually uniform lightness ensures stable contrast:
+
+```css
+:root {
+  /* oklch(Lightness Chroma Hue / Alpha) */
+  --color-primary: oklch(65% 0.22 250); /* Brand electric blue */
+  --color-primary-hover: oklch(58% 0.22 250); /* Darker active state */
+  --bg-base: oklch(0.08 0.005 250); /* OLED base background */
+  --bg-surface: oklch(0.12 0.008 250); /* Stepped card surface */
+  --border-subtle: oklch(22% 0.01 250 / 0.4); /* Hairline separator */
+}
+```
+
+### Color Gamut Guidelines
+
+- **Display-P3 Saturated Accents:** When targeting high-end modern screens, use chroma values between `0.20` and `0.28`.
+- **Stepped Neutral Contrast:** Stepped neutral surfaces must increase by `0.04` Lightness increments (e.g., base `0.08` → surface `0.12` → raised `0.16` → overlay `0.20`) to create physical depth without color tint deviations.
+
+---
+
+## 2. Typographical Tracking & scaling
+
+Headings must use `clamp()` for fluid sizing and tight negative letter spacing (tracking) to prevent loose display layouts:
+
+| Token         | Clamp Value                  | Weight | Line Height | Tracking           |
+| :------------ | :--------------------------- | :----- | :---------- | :----------------- |
+| `--text-hero` | `clamp(2.5rem, 6vw, 4.5rem)` | 800    | 0.95        | `-0.04em` (Tight)  |
+| `--text-h1`   | `clamp(2.0rem, 4vw, 3.0rem)` | 700    | 1.05        | `-0.03em`          |
+| `--text-h2`   | `clamp(1.5rem, 3vw, 2.0rem)` | 600    | 1.15        | `-0.02em`          |
+| `--text-body` | `1rem`                       | 400    | 1.60        | `0` (Normal)       |
+| `--text-sm`   | `0.875rem`                   | 400    | 1.50        | `+0.005em` (Loose) |
+
+- **BALANCED Headings:** Always declare `text-wrap: balance` on all dynamic title elements to prevent visual orphans.
+- **Reading Measures:** Paragraph widths must be clamped to `65ch` max width (`max-width: 65ch`) to reduce cognitive scan overhead.
+
+---
+
+## 3. Depth Shadows & Layering Math
+
+Flat shadows look cheap. Premium interfaces use physics-based multi-layered shadows to simulate light occlusion:
+
+```css
+/* Stepped ambient + key shadow coefficients */
+.elevation-md {
+  box-shadow:
+    0 1px 2px oklch(0% 0 0 / 0.05),
+    /* Ambient shadow */ 0 4px 12px oklch(0% 0 0 / 0.08),
+    /* Key shadow */ 0 0 1px oklch(100% 0 0 / 0.12); /* Hairline luminous stroke */
+}
+```
+
+- In dark themes, shadows should drop in opacity and be accompanied by luminous hairlines (`border: 1px solid oklch(100% 0 0 / 0.08)`) instead of thick black shadows.
+
+---
+
+## 4. Interaction States & Transitions
+
+All buttons and active controls must define styled properties for:
+
+- `hover`, `focus-visible`, `active`/`pressed`, and `disabled` states.
+- Use spring easing curves: `cubic-bezier(0.34, 1.56, 0.64, 1)`.
+
+---
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| 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 Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **Uncontrolled Re-render Loop** | Mutating state inside render bodies or omitting hook dependencies | Wrap effects with explicit deps and isolate reactive derivations in useMemo |
+| **Accessibility Neglect** | Interactive <div> without role="button", tabIndex, or onKeyDown | Use semantic <button> or provide ARIA role, keyboard handlers, and focus ring |
+| **Layout Shift Flash** | Images/dynamic content without aspect-ratio or explicit dimensions | Enforce aspect-ratio or skeleton placeholders to guarantee zero CLS |
+
+---
+
+## 🏛️ Tribunal Verification & Guardrails
+
+**Active Reviewers:** `frontend-reviewer` · `type-safety` · `ui-ux-auditor` · `complexity-reviewer`
+**Slash Command:** `/review` or `/tribunal-full`
+
+### ✅ 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 focus, contrast) 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/.agents/skills/ui-ux-researcher/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: ui-ux-researcher
+description: Use when Expert auditor for accessibility, cognitive load, and premium design heuristics.
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - web-design-guidelines
+  - frontend-design
+  - trend-researcher
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# UI/UX Researcher Skill
+
+## Mandatory Pre-Flight Context Inspection
+
+Before generating, refactoring, or reviewing code in the `ui-ux-researcher` 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 Expert auditor for accessibility, cognitive load, and premium design heuristics.
+- **DO NOT activate when:** The task falls outside the `ui-ux-researcher` 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. |
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+---
+
+
+## When to Activate
+
+- When asked to "review my UI", "check accessibility", "audit design", or "review UX".
+- After any `/create` or `/enhance` that generates UI code.
+- When paired with `trend-researcher` for a full "Design Intelligence" pass.
+- During the VERIFICATION phase of any frontend build.
+
+## Audit Framework
+
+### Tier System
+
+Every UI element is evaluated across 3 tiers. Each tier has hard requirements that must pass before moving to the next:
+
+```
+┌─────────────────────────────────────┐
+│  P0: SAFETY & ACCESS               │  ← Must pass. Blocks ship.
+│  Accessibility, error handling,     │
+│  keyboard nav, screen readers       │
+├─────────────────────────────────────┤
+│  P1: CLARITY & FLOW                 │  ← Should pass. Flags issues.
+│  Information hierarchy, feedback,   │
+│  task completion, error recovery    │
+├─────────────────────────────────────┤
+│  P2: POLISH & PREMIUM              │  ← Nice to have. Elevates quality.
+│  Micro-interactions, whitespace,    │
+│  consistency, delight moments       │
+└─────────────────────────────────────┘
+```
+
+### P0: Safety & Accessibility (BLOCKS SHIP)
+
+| #    | Check                                           | Standard                                                    | How to Verify                                         |
+| ---- | ----------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------- |
+| 0.1  | Color contrast (normal text)                    | ≥ 4.5:1 (WCAG AA)                                           | Calculate `(L1 + 0.05) / (L2 + 0.05)`                 |
+| 0.2  | Color contrast (large text ≥18px bold or ≥24px) | ≥ 3:1                                                       | Same formula                                          |
+| 0.3  | Touch targets                                   | ≥ 44×44px (WCAG 2.5.8)                                      | Check CSS `min-width`/`min-height` or padding         |
+| 0.4  | Keyboard navigation                             | All interactive elements focusable, visible focus ring      | Check for `tabindex`, `:focus-visible` styles         |
+| 0.5  | Screen reader labels                            | All images have `alt`, all inputs have `label`/`aria-label` | Grep for `<img` without `alt`, `<input` without label |
+| 0.6  | Semantic HTML                                   | Single `<h1>`, proper heading hierarchy, landmark regions   | Parse DOM structure                                   |
+| 0.7  | Error prevention                                | Destructive actions require confirmation                    | Check delete/submit flows                             |
+| 0.8  | Escape hatches                                  | Every modal/overlay has close, every flow has "Back"        | Check for close buttons, back navigation              |
+| 0.9  | Reduced motion                                  | `prefers-reduced-motion` media query present                | Grep for the media query                              |
+| 0.10 | Color-only indicators                           | Information is not conveyed by color alone                  | Check error states, status badges                     |
+
+### P1: Clarity & Flow (SHOULD FIX)
+
+| #   | Check                  | Heuristic                              | What to Look For                                   |
+| --- | ---------------------- | -------------------------------------- | -------------------------------------------------- |
+| 1.1 | Single primary action  | One dominant CTA per view              | Multiple same-weight buttons competing             |
+| 1.2 | Visual feedback        | Every interaction has visible response | Missing hover/active/disabled states               |
+| 1.3 | Loading states         | Async operations show progress         | Missing spinners, skeletons, or progress bars      |
+| 1.4 | Empty states           | Zero-data views have guidance          | Blank screens with no "Get Started"                |
+| 1.5 | Error messaging        | Errors are specific and actionable     | Generic "Something went wrong" without context     |
+| 1.6 | Information scent      | Users can predict what happens next    | Ambiguous labels like "Submit" vs "Create Account" |
+| 1.7 | Consistency            | Similar elements behave similarly      | Mixed button styles, inconsistent spacing          |
+| 1.8 | Progressive disclosure | Complex forms use steps or sections    | 20+ fields on one page                             |
+| 1.9 | Alignment & grid       | Elements follow a consistent grid      | Misaligned elements, inconsistent gutters          |
+
+### P2: Polish & Premium (ELEVATES QUALITY)
+
+| #   | Check                 | Quality Signal                                              | Implementation                                   |
+| --- | --------------------- | ----------------------------------------------------------- | ------------------------------------------------ |
+| 2.1 | Whitespace balance    | Content has room to breathe                                 | Audit `padding`/`margin` — minimum 16px sections |
+| 2.2 | Corner radius harmony | Outer radius > inner radius, consistent across components   | Check `border-radius` values                     |
+| 2.3 | Shadow depth system   | Consistent shadow levels (sm → md → lg → xl)                | Verify `box-shadow` consistency                  |
+| 2.4 | Typography rhythm     | Consistent line-height, letter-spacing across hierarchy     | Check for modular type scale                     |
+| 2.5 | Micro-interactions    | Entrances, hovers, and feedback feel intentional            | Cross-reference with `whimsy-injector`           |
+| 2.6 | Icon consistency      | Same style family (outline vs filled, same weight)          | Mixed icon sets = visual noise                   |
+| 2.7 | Color temperature     | Warm palette stays warm, cool stays cool                    | Check for temperature clashes                    |
+| 2.8 | Content density       | Not too sparse (wasted space), not too dense (overwhelming) | Subjective — use Goldilocks principle            |
+
+## Scoring Protocol
+
+### UX Score (1-10)
+
+```
+Score = (P0_pass_rate × 0.5) + (P1_pass_rate × 0.3) + (P2_pass_rate × 0.2)
+
+8-10: Ship-ready. Minor polish opportunities.
+6-7:  Good foundation. Fix P0 violations, address key P1 issues.
+4-5:  Needs work. Multiple accessibility or flow problems.
+1-3:  Significant rework needed. Fundamental usability barriers.
+```
+
+### Severity Labels
+
+| Label         | Meaning                                      | Action               |
+| ------------- | -------------------------------------------- | -------------------- |
+| 🔴 BLOCKER    | P0 violation, breaks accessibility or safety | Must fix before ship |
+| 🟡 WARNING    | P1 issue, impacts clarity or flow            | Should fix           |
+| 🔵 SUGGESTION | P2 opportunity, improves polish              | Nice to fix          |
+
+## Report Format
+
+```
+━━━ UX Audit Report ━━━━━━━━━━━━━━━━━━━━━
+
+Target:  [component/page name]
+Score:   [X] / 10
+Grade:   [A/B/C/D/F]
+
+━━━ P0: Safety & Access ━━━━━━━━━━━━━━━━━
+
+🔴 0.1 FAIL — Contrast ratio 2.8:1 on `.card-subtitle` (needs 4.5:1)
+   File: components/Card.tsx:24
+   Fix:  Change color from hsl(0,0%,70%) to hsl(0,0%,40%)
+
+🔴 0.4 FAIL — No focus ring on `.nav-link`
+   File: components/Nav.tsx:12
+   Fix:  Add `:focus-visible { outline: 2px solid var(--primary); outline-offset: 2px }`
+
+✅ 0.2, 0.3, 0.5, 0.6, 0.7, 0.8, 0.9, 0.10 — PASS
+
+━━━ P1: Clarity & Flow ━━━━━━━━━━━━━━━━━━
+
+🟡 1.3 — No loading state on data fetch
+   File: pages/Dashboard.tsx:45
+   Fix:  Add skeleton placeholder while `isLoading` is true
+
+🟡 1.4 — Empty state shows blank div
+   File: pages/Users.tsx:28
+   Fix:  Add "No users yet. Invite your team →" with CTA
+
+✅ 1.1, 1.2, 1.5, 1.6, 1.7, 1.8, 1.9 — PASS
+
+━━━ P2: Polish & Premium ━━━━━━━━━━━━━━━━
+
+🔵 2.2 — Buttons use 8px radius, cards use 16px, but nested card buttons should use 12px
+   Fix:  Apply harmonized radius: outer 16px → inner 12px
+
+🔵 2.5 — No entrance animations on page load
+   Fix:  Partner with whimsy-injector for staggered fade-in
+
+✅ 2.1, 2.3, 2.4, 2.6, 2.7, 2.8 — PASS
+
+━━━ Fix Priority ━━━━━━━━━━━━━━━━━━━━━━━━
+1. Fix contrast on .card-subtitle (P0, 2 min)
+2. Add focus ring to .nav-link (P0, 1 min)
+3. Add loading skeletons (P1, 15 min)
+4. Add empty state messaging (P1, 10 min)
+```
+
+## Nielsen's 10 Heuristics Quick Reference
+
+Used as the theoretical backbone for P1 checks:
+
+| #   | Heuristic                           | What to Check                              |
+| --- | ----------------------------------- | ------------------------------------------ |
+| H1  | Visibility of system status         | Loading indicators, progress bars          |
+| H2  | Match between system and real world | Natural language labels, familiar icons    |
+| H3  | User control and freedom            | Undo, Back, Cancel always available        |
+| H4  | Consistency and standards           | Same patterns across the app               |
+| H5  | Error prevention                    | Confirmation dialogs, input validation     |
+| H6  | Recognition over recall             | Labels over icons-only, visible navigation |
+| H7  | Flexibility and efficiency          | Keyboard shortcuts, bulk actions           |
+| H8  | Aesthetic and minimalist design     | No extraneous information                  |
+| H9  | Help users recognize errors         | Specific error messages with recovery      |
+| H10 | Help and documentation              | Tooltips, onboarding, contextual help      |
+
+## Cross-Skill Integration
+
+| Paired Skill             | Integration Point                                            |
+| ------------------------ | ------------------------------------------------------------ |
+| `trend-researcher`       | Validate that applied trends pass P0 contrast and P1 clarity |
+| `whimsy-injector`        | P2.5 — delegate micro-interaction implementation             |
+| `web-design-guidelines`  | Reference for component-level design standards               |
+| `frontend-design`        | Token-level validation (spacing, radius, shadows)            |
+| `accessibility-reviewer` | Deep-dive partner for complex ARIA patterns                  |
+
+## Anti-Hallucination Guard
+
+- **Never claim a design is "accessible"** without verifying specific contrast ratios and ARIA attributes.
+- **Never fabricate UX scores** — always calculate from the checklist pass rate.
+- **Only suggest ARIA attributes** that are verified in the current codebase context.
+- **Ground all UX claims** in Nielsen's heuristics or WCAG 2.2 standards — cite the specific rule.
+- **Do not invent file paths or line numbers** — only reference code that has been read.
+
+---
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| 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 Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **Uncontrolled Re-render Loop** | Mutating state inside render bodies or omitting hook dependencies | Wrap effects with explicit deps and isolate reactive derivations in useMemo |
+| **Accessibility Neglect** | Interactive <div> without role="button", tabIndex, or onKeyDown | Use semantic <button> or provide ARIA role, keyboard handlers, and focus ring |
+| **Layout Shift Flash** | Images/dynamic content without aspect-ratio or explicit dimensions | Enforce aspect-ratio or skeleton placeholders to guarantee zero CLS |
+
+---
+
+## 🏛️ Tribunal Verification & Guardrails
+
+**Active Reviewers:** `frontend-reviewer` · `type-safety` · `ui-ux-auditor` · `complexity-reviewer`
+**Slash Command:** `/review` or `/tribunal-full`
+
+### ✅ 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 focus, contrast) 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/.agents/skills/vector-search-pgvector/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: vector-search-pgvector
+description: Use when Production vector database search using pgvector 0.8.0+, halfvec, sparsevec, Pinecone, Weaviate, hybrid sparse-dense retrieval, and iterative HNSW scanning.
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - database-architect
+  - sql-pro
+  - advanced-rag-pipelines
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/schema_validator.js
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Vector Search & pgvector 0.8.0+ — 2026 Database Standards
+
+## Mandatory Pre-Flight Context Inspection
+
+Before generating, refactoring, or reviewing code in the `vector-search-pgvector` 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 Production vector database search using pgvector 0.8.0+, halfvec, sparsevec, Pinecone, Weaviate, hybrid sparse-dense retrieval, and iterative HNSW scanning.
+- **DO NOT activate when:** The task falls outside the `vector-search-pgvector` 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. |
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+## High-Performance pgvector 0.8.0+ Schema (`halfvec` + HNSW)
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+
+CREATE TABLE document_chunks (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    document_id UUID NOT NULL,
+    chunk_index INT NOT NULL,
+    content TEXT NOT NULL,
+    fts_vector tsvector GENERATED ALWAYS AS (to_tsvector('english', content)) STORED,
+    embedding halfvec(1536) NOT NULL  -- 50% memory reduction vs float4 vector
+);
+
+-- HNSW index using halfvec with iterative scanning support (pgvector 0.8.0+)
+CREATE INDEX idx_chunks_embedding_hnsw
+ON document_chunks USING hnsw (embedding halfvec_cosine_ops)
+WITH (m = 16, ef_construction = 64);
+
+-- Full text search GIN index
+CREATE INDEX idx_chunks_fts ON document_chunks USING gin (fts_vector);
+```
+
+## Hybrid Search Query (pgvector 0.8.0+ Iterative Scan + RRF)
+
+```sql
+-- pgvector 0.8.0+ automatically performs iterative prober scans when filtering
+WITH vector_search AS (
+    SELECT id, content, ROW_NUMBER() OVER (ORDER BY embedding <=> $1::halfvec) as rank
+    FROM document_chunks
+    WHERE document_id = $3  -- Iterative scan prevents overfiltering
+    LIMIT 20
+),
+fts_search AS (
+    SELECT id, content, ROW_NUMBER() OVER (ORDER BY ts_rank(fts_vector, websearch_to_tsquery($2)) DESC) as rank
+    FROM document_chunks
+    WHERE fts_vector @@ websearch_to_tsquery($2) AND document_id = $3
+    LIMIT 20
+)
+SELECT
+    COALESCE(v.id, f.id) as id,
+    COALESCE(v.content, f.content) as content,
+    COALESCE(1.0 / (60 + v.rank), 0.0) + COALESCE(1.0 / (60 + f.rank), 0.0) as rrf_score
+FROM vector_search v
+FULL OUTER JOIN fts_search f ON v.id = f.id
+ORDER BY rrf_score DESC
+LIMIT 10;
+```
+
+---
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| 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 Table
+
+| 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 Verification & Guardrails
+
+**Active Reviewers:** `database-architect` · `sql-pro` · `security-auditor` · `schema-validator`
+**Slash Command:** `/review` or `/tribunal-full`
+
+### ✅ Pre-Flight Self-Audit Checklist
+
+```
+✅ 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 test suites, compiler success, or equivalent operational proof) that your output works as intended.