tribunal-kit 4.0.1 → 4.3.0

package/.agent/agents/vitals-reviewer.md

@@ -0,0 +1,223 @@
+---
+name: vitals-reviewer
+description: Frontend Core Web Vitals specialist. Audits React/Next.js/CSS code for INP violations, LCP blockers, CLS triggers, paint jank from View Transitions API misuse, Suspense waterfall patterns, render-blocking fonts, non-passive event listeners, and missing content-visibility optimizations. Token-scoped to UI files only (.tsx/.jsx/.css). Activates on /tribunal-speed and /tribunal-full.
+version: 1.0.0
+last-updated: 2026-04-13
+---
+
+# Vitals Reviewer — Frontend Performance Specialist
+
+---
+
+## Core Mandate
+
+You audit **frontend files only** — `.tsx`, `.jsx`, `.css`, `.module.css`. You never read server-side files, SQL, or ORM code. Your single goal: ensure every UI file meets 2026 Core Web Vitals targets. Every finding maps to a specific CWV metric.
+
+---
+
+## Token Scope (MANDATORY)
+
+```
+✅ Activate on: **/*.tsx, **/*.jsx, **/*.css, **/*.module.css
+❌ Skip entirely: **/*.sql, **/api/**, **/server/**, schema.prisma, *.test.*
+```
+
+This scope is non-negotiable. If a file doesn't match, return `N/A — outside vitals-reviewer scope`.
+
+---
+
+## 2026 CWV Targets
+
+|Metric|Good|Needs Work|Poor (❌ REJECTED)|
+|:---|:---|:---|:---|
+|**INP** Interaction to Next Paint|< 200ms|200–500ms|> 500ms|
+|**LCP** Largest Contentful Paint|< 2.5s|2.5–4.0s|> 4.0s|
+|**CLS** Cumulative Layout Shift|< 0.1|0.1–0.25|> 0.25|
+
+---
+
+## Section 1: LCP Audit Patterns
+
+```tsx
+// ❌ LCP DAMAGE: Hero image without priority — browser discovers it late
+<img src="/hero.jpg" />
+
+// ❌ LCP DAMAGE: Raw @font-face without font-display — invisible text flash
+@font-face {
+  font-family: 'Brand';
+  src: url('/brand.woff2');
+  /* Missing: font-display: swap; */
+}
+
+// ✅ APPROVED: next/image with priority on above-fold content
+<Image src="/hero.jpg" priority={true} sizes="100vw" width={1920} height={1080} alt="Hero" />
+
+// ✅ APPROVED: next/font eliminates render-blocking entirely
+import { Inter } from 'next/font/google';
+const inter = Inter({ subsets: ['latin'], display: 'swap' });
+
+// ❌ LCP DAMAGE: Large SVG inlined in JSX (forces full parse before paint)
+// Flag SVGs > 5KB inlined in component render — suggest external .svg file
+```
+
+---
+
+## Section 2: INP Audit Patterns
+
+```tsx
+// ❌ INP DAMAGE: Synchronous heavy computation on click
+function handleSearch(query: string) {
+  const results = filterAllRecords(data, query); // Blocks main thread
+  setResults(results);
+}
+
+// ✅ APPROVED: useTransition defers expensive state update
+const [isPending, startTransition] = useTransition();
+function handleSearch(query: string) {
+  startTransition(() => setResults(filterAllRecords(data, query)));
+}
+
+// ❌ INP DAMAGE: Non-passive scroll listener (blocks scroll painting)
+element.addEventListener('scroll', handler); // Missing { passive: true }
+
+// ✅ APPROVED: Passive listener — browser paints immediately
+element.addEventListener('scroll', handler, { passive: true });
+
+// ❌ INP DAMAGE: Complex computation on mousemove (fires 60+/sec)
+document.addEventListener('mousemove', (e) => {
+  renderComplexGradient(e.clientX, e.clientY);
+});
+```
+
+---
+
+## Section 3: CLS Audit Patterns
+
+```tsx
+// ❌ CLS DAMAGE: Image without dimensions — shifts when loaded
+<img src="/photo.jpg" /> // No width/height or aspect-ratio
+
+// ❌ CLS DAMAGE: Dynamic content injected above fold
+container.prepend(banner); // Pushes existing content down
+
+// ✅ APPROVED: Reserved space with aspect-ratio
+<div style={{ aspectRatio: '16/9', width: '100%' }}>
+  <Image src="/photo.jpg" fill alt="Photo" />
+</div>
+
+// ❌ CLS DAMAGE: Async font swap without size-adjust
+// Fallback font metrics differ from web font → text reflows on swap
+```
+
+---
+
+## Section 4: React 19 + Next.js 15 Patterns
+
+```tsx
+// ❌ WATERFALL: Sequential use() calls creating fetch cascades
+function Dashboard() {
+  const user = use(fetchUser());       // Waits for user
+  const posts = use(fetchPosts(user)); // THEN waits for posts — serial
+}
+
+// ✅ APPROVED: Parallel Suspense boundaries
+function Dashboard() {
+  return (
+    <>
+      <Suspense fallback={<UserSkeleton />}><UserCard /></Suspense>
+      <Suspense fallback={<PostsSkeleton />}><PostsList /></Suspense>
+    </>
+  );
+}
+
+// ❌ PAINT JANK: View Transition API started without checking support
+document.startViewTransition(() => updateDOM());
+
+// ✅ APPROVED: Feature-detect before using
+if (document.startViewTransition) {
+  document.startViewTransition(() => updateDOM());
+} else {
+  updateDOM();
+}
+
+// ❌ SUSPENSE TOO HIGH: Single Suspense wrapping entire page
+<Suspense fallback={<FullPageSpinner />}>
+  <Header /><Sidebar /><Content /><Footer />
+</Suspense>
+// All components wait for the slowest one — defeats Suspense purpose
+
+// ✅ APPROVED: Granular Suspense per async boundary
+<Header />
+<Suspense fallback={<SidebarSkeleton />}><Sidebar /></Suspense>
+<Suspense fallback={<ContentSkeleton />}><Content /></Suspense>
+<Footer />
+```
+
+---
+
+## Section 5: CSS Performance Opportunities
+
+```css
+/* ❌ MISSED OPTIMIZATION: Long scrollable list without content-visibility */
+.feed-item {
+  /* Browser renders ALL items even off-screen */
+}
+
+/* ✅ APPROVED: content-visibility skips rendering off-screen items */
+.feed-item {
+  content-visibility: auto;
+  contain-intrinsic-size: auto 200px;
+}
+
+/* ❌ MISSED OPTIMIZATION: No CSS containment on isolated widgets */
+.dashboard-card {
+  /* Recalculates layout for entire page when card content changes */
+}
+
+/* ✅ APPROVED: contain: layout limits recalc scope */
+.dashboard-card {
+  contain: layout;
+}
+```
+
+---
+
+## Section 6: Animation Frame Leaks
+
+```tsx
+// ❌ FRAME LEAK: useGSAP without cleanup (gsap timelines persist)
+useEffect(() => {
+  gsap.to('.box', { x: 100 }); // No cleanup — leaks on unmount
+}, []);
+
+// ✅ APPROVED: useGSAP from @gsap/react handles cleanup automatically
+import { useGSAP } from '@gsap/react';
+useGSAP(() => {
+  gsap.to('.box', { x: 100 });
+}, { scope: containerRef });
+
+// ❌ FRAME LEAK: Framer Motion AnimatePresence without mode
+<AnimatePresence>
+  {items.map(item => <motion.div key={item.id} />)}
+</AnimatePresence>
+// Exit + enter animations overlap — causes layout thrash
+
+// ✅ APPROVED: mode="wait" prevents overlap
+<AnimatePresence mode="wait">
+  {items.map(item => <motion.div key={item.id} exit={{ opacity: 0 }} />)}
+</AnimatePresence>
+```
+
+---
+
+## Verdict Format
+
+```
+[SEVERITY] vitals-reviewer | file.tsx:LINE
+Metric:  INP | LCP | CLS
+Issue:   [Specific pattern found]
+Fix:     [Exact code change]
+Impact:  [Estimated metric improvement]
+```
+
+---

package/.agent/history/case-law/cases/case-0001.json

@@ -0,0 +1,33 @@
+{
+  "id": 1,
+  "fingerprint": "54a75a8b",
+  "timestamp": "2026-04-12T00:58:14",
+  "domain": "security",
+  "verdict": "REJECTED",
+  "reason": "User input was concatenated directly into the system prompt, creating a critical prompt injection vulnerability.",
+  "pr_ref": "PR-1",
+  "reviewer": "security-auditor",
+  "tags": [
+    "systemprompt",
+    "you",
+    "helpful",
+    "assistant",
+    "context",
+    "userinput",
+    "response",
+    "generate",
+    "user",
+    "input",
+    "concatenated",
+    "directly",
+    "into",
+    "system",
+    "prompt",
+    "creating",
+    "critical",
+    "injection",
+    "vulnerability"
+  ],
+  "diff_raw": "const systemPrompt = `You are a helpful assistant. Context: ${userInput}`;\nconst response = await ai.generate(systemPrompt);",
+  "diff_delta": "const systemPrompt = `You are a helpful assistant. Context: ${userInput}`;\nconst response = await ai.generate(systemPrompt);"
+}

package/.agent/history/case-law/index.json

@@ -0,0 +1,35 @@
+{
+  "version": "1.0",
+  "cases": [
+    {
+      "id": 1,
+      "fingerprint": "54a75a8b",
+      "domain": "security",
+      "verdict": "REJECTED",
+      "tags": [
+        "systemprompt",
+        "you",
+        "helpful",
+        "assistant",
+        "context",
+        "userinput",
+        "response",
+        "generate",
+        "user",
+        "input",
+        "concatenated",
+        "directly",
+        "into",
+        "system",
+        "prompt",
+        "creating",
+        "critical",
+        "injection",
+        "vulnerability"
+      ],
+      "timestamp": "2026-04-12T00:58:14",
+      "reason_summary": "User input was concatenated directly into the system prompt, creating a critical prompt injection vulnerability."
+    }
+  ],
+  "next_id": 2
+}

package/.agent/rules/GEMINI.md

@@ -33,6 +33,7 @@ Every code or design request activates an agent. This is not optional.
 |Domain|Primary Agent / Skill|
 |---|---|
 |API / server / backend|`backend-specialist`|
+|API contract design / REST / GraphQL|`api-architect`|
 |C# / .NET / Blazor|`dotnet-core-expert`|
 |Python / FastAPI / Django|`python-pro`|
 |Database / schema / SQL|`database-architect`|
@@ -43,6 +44,8 @@ Every code or design request activates an agent. This is not optional.
 |Mobile (RN / Flutter)|`mobile-developer`|
 |Debugging / errors|`debugger`|
 |Security / vulnerabilities|`security-auditor`|
+|Fault tolerance / retries / error boundaries|`resilience-reviewer`|
+|Input validation / Zod / Pydantic schemas|`schema-reviewer`|
 |Performance / optimization|`performance-optimizer`|
 |DevOps / CI-CD / Docker|`devops-engineer`|
 |Production incidents|`devops-incident-responder`|
@@ -50,6 +53,20 @@ Every code or design request activates an agent. This is not optional.
 |Multi-agent architecture|`agent-organizer`|
 |Multi-domain (2+ areas)|`orchestrator`|
 |Unknown codebase|`explorer-agent`|
+|Legacy code / codebase archaeology|`code-archaeologist`|
+|Game development / Unity / Godot|`game-developer`|
+|Documentation / README / API docs|`documentation-writer`|
+|Test generation / test strategy|`test-engineer`|
+|QA automation / E2E testing|`qa-automation-engineer`|
+|Project planning / roadmaps|`project-planner`|
+|Product strategy / feature prioritization|`product-manager`|
+|User stories / backlog management|`product-owner`|
+|SEO / search optimization|`seo-specialist`|
+|Throughput / latency / load optimization|`throughput-optimizer`|
+|Core Web Vitals / LCP / CLS / INP|`vitals-reviewer`|
+|Pen testing / red team / attack surface|`penetration-tester`|
+|Database performance / slow queries|`db-latency-auditor`|
+|AI/LLM integration code / prompts|`ai-code-reviewer`|
 
 **When activated, announce the agent:**
 
@@ -138,12 +155,12 @@ The Human Gate is never skipped. No code is written to a file without explicit u
 
 |Code type|Reviewers|
 |---|---|
-|Backend/API|logic + security + dependency + type-safety|
+|Backend/API|logic + security + dependency + type-safety + resilience + schema|
 |Frontend/React|logic + security + frontend + type-safety|
-|Database/SQL|logic + security + sql|
+|Database/SQL|logic + security + sql + schema|
 |Mobile/Cross-platform|logic + security + mobile-reviewer + type-safety|
 |Any domain|+ performance (if optimization)|
-|Before merge|/tribunal-full (all 9)|
+|Before merge|/tribunal-full (all 16)|
 
 ---
 
@@ -205,7 +222,7 @@ These scripts live in `.agent/scripts/`. Agents and skills can invoke them:
 |`checklist.py`|Priority audit: Security→Lint→Schema→Tests→UX→SEO|Before/after any major change|
 |`verify_all.py`|Full pre-deploy validation suite|Pre-deploy|
 |`auto_preview.py`|Start/stop/restart local dev server|After /create or /enhance|
-|`session_manager.py`|Track session state between conversations|Multi-session work|
+|`session_manager.js`|Track session state between conversations|Multi-session work|
 |`lint_runner.py`|Standalone lint runner (ESLint, Prettier, Ruff)|Every code change|
 |`test_runner.py`|Standalone test runner (Jest, Vitest, pytest, Go)|After logic changes|
 |`security_scan.py`|Deep OWASP-aware source code security scan|Always on deploy, /audit|
@@ -213,22 +230,22 @@ These scripts live in `.agent/scripts/`. Agents and skills can invoke them:
 |`schema_validator.py`|Database schema validation (Prisma, SQL)|After DB changes|
 |`bundle_analyzer.py`|JS/TS bundle size analysis|Before deploy|
 |`skill_integrator.py`|Maps active skills to their executable scripts|Automatically when skills are invoked|
-|`swarm_dispatcher.py`|Validate Orchestrator micro-worker JSON payloads|After /orchestrate, before dispatching agents|
-|`test_swarm_dispatcher.py`|Unit tests for swarm_dispatcher|After modifying swarm_dispatcher.py|
+|`swarm_dispatcher.js`|Validate Orchestrator micro-worker JSON payloads|After /orchestrate, before dispatching agents|
+|`test_swarm_dispatcher.js`|Unit tests for swarm_dispatcher|After modifying swarm_dispatcher.js|
 
 **Run pattern:**
 ```
-python .agent/scripts/checklist.py .
-python .agent/scripts/verify_all.py
-python .agent/scripts/security_scan.py .
+node .agent/scripts/checklist.js .
+node .agent/scripts/verify_all.js
+node .agent/scripts/security_scan.js .
 python .agent/scripts/lint_runner.py . --fix
 python .agent/scripts/test_runner.py . --coverage
 python .agent/scripts/dependency_analyzer.py . --audit
 python .agent/scripts/schema_validator.py .
 python .agent/scripts/bundle_analyzer.py . --build
 python .agent/scripts/skill_integrator.py
-python .agent/scripts/swarm_dispatcher.py --file payload.json
-python .agent/scripts/test_swarm_dispatcher.py
+node .agent/scripts/swarm_dispatcher.js --file payload.json
+npx jest test/integration/swarm_dispatcher.test.js
 ```
 
 ---

package/.agent/scripts/_colors.js

@@ -0,0 +1,18 @@
+/**
+ * Shared ANSI color constants for Tribunal Kit scripts.
+ * Import this module instead of duplicating color codes.
+ */
+
+'use strict';
+
+const GREEN   = '\x1b[92m';
+const YELLOW  = '\x1b[93m';
+const CYAN    = '\x1b[96m';
+const RED     = '\x1b[91m';
+const BLUE    = '\x1b[94m';
+const MAGENTA = '\x1b[95m';
+const BOLD    = '\x1b[1m';
+const DIM     = '\x1b[2m';
+const RESET   = '\x1b[0m';
+
+module.exports = { GREEN, YELLOW, CYAN, RED, BLUE, MAGENTA, BOLD, DIM, RESET };

package/.agent/scripts/_utils.js

@@ -0,0 +1,42 @@
+/**
+ * Shared utilities for Tribunal Kit scripts.
+ * Import this module instead of duplicating helper functions.
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { RED, RESET } = require('./_colors');
+
+/**
+ * Walk up the directory tree to find the nearest .agent/ folder.
+ * @param {string} [startDir] - Directory to start searching from (defaults to cwd).
+ * @returns {string} Absolute path to the .agent directory.
+ */
+function findAgentDir(startDir) {
+    let current = path.resolve(startDir || process.cwd());
+    const root = path.parse(current).root;
+
+    while (current !== root) {
+        const candidate = path.join(current, '.agent');
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+            return candidate;
+        }
+        current = path.dirname(current);
+    }
+
+    console.error(`${RED}✖ Error: '.agent' directory not found. Please run 'npx tribunal-kit init' first.${RESET}`);
+    process.exit(1);
+}
+
+/**
+ * Check if a package.json exists in the given directory.
+ * @param {string} dir - Directory to check.
+ * @returns {boolean}
+ */
+function hasNpm(dir) {
+    return fs.existsSync(path.join(dir, 'package.json'));
+}
+
+module.exports = { findAgentDir, hasNpm };

package/.agent/scripts/auto_preview.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * auto_preview.js — Start, stop, or check a local development server.
+ *
+ * Usage:
+ *   node .agent/scripts/auto_preview.js start
+ *   node .agent/scripts/auto_preview.js stop
+ *   node .agent/scripts/auto_preview.js status
+ *   node .agent/scripts/auto_preview.js restart
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawn, execSync } = require('child_process');
+const net = require('net');
+
+const PID_FILE = ".preview.pid";
+const DEFAULT_PORT = 3000;
+const TIMEOUT_SECONDS = 30;
+
+const { GREEN, RED, YELLOW, BOLD, RESET } = require('./colors.js');
+
+function findStartCommand() {
+    const pkgPath = path.resolve("package.json");
+    if (!fs.existsSync(pkgPath)) return { cmd: [], found: false };
+
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        const scripts = pkg.scripts || {};
+        if (scripts.dev) return { cmd: ["npm", "run", "dev"], found: true };
+        if (scripts.start) return { cmd: ["npm", "run", "start"], found: true };
+    } catch {
+        // Ignore
+    }
+    return { cmd: [], found: false };
+}
+
+function getPortFromEnv() {
+    const envPath = path.resolve(".env");
+    if (fs.existsSync(envPath)) {
+        try {
+            const data = fs.readFileSync(envPath, 'utf8');
+            for (const line of data.split('\n')) {
+                if (line.trim().startsWith("PORT=")) {
+                    return parseInt(line.split("=")[1].trim(), 10);
+                }
+            }
+        } catch {}
+    }
+    return DEFAULT_PORT;
+}
+
+function isPortOpen(port) {
+    return new Promise(resolve => {
+        const client = new net.Socket();
+        client.setTimeout(1000);
+        client.once('connect', () => {
+            client.destroy();
+            resolve(true);
+        }).once('timeout', () => {
+            client.destroy();
+            resolve(false);
+        }).once('error', () => {
+            resolve(false);
+        }).connect(port, 'localhost');
+    });
+}
+
+function readPid() {
+    if (fs.existsSync(PID_FILE)) {
+        try {
+            return parseInt(fs.readFileSync(PID_FILE, 'utf8').trim(), 10);
+        } catch {}
+    }
+    return null;
+}
+
+function writePid(pid) {
+    fs.writeFileSync(PID_FILE, String(pid), 'utf8');
+}
+
+function clearPid() {
+    if (fs.existsSync(PID_FILE)) {
+        fs.unlinkSync(PID_FILE);
+    }
+}
+
+async function startServer() {
+    const port = getPortFromEnv();
+
+    if (await isPortOpen(port)) {
+        console.log(`${YELLOW}⚠️  Port ${port} is already in use.${RESET}`);
+        const pid = readPid();
+        if (pid) console.log(`   Known PID: ${pid}`);
+        return;
+    }
+
+    const { cmd, found } = findStartCommand();
+    if (!found) {
+        console.log(`${RED}❌ No dev/start script found.${RESET}`);
+        console.log(`   This project has no package.json, or its package.json has no 'dev' or 'start' script.`);
+        console.log(`   Add a script to package.json, or start your server manually.`);
+        return;
+    }
+
+    console.log(`${BOLD}Starting: ${cmd.join(' ')}${RESET}`);
+    // Adjust command for windows (npm.cmd instead of npm)
+    const executable = process.platform === 'win32' ? `${cmd[0]}.cmd` : cmd[0];
+    
+    const proc = spawn(executable, cmd.slice(1), {
+        stdio: 'pipe',
+        detached: true
+    });
+    
+    // Ignore children stdout inside detached mode to let node exit
+    proc.stdout.unref();
+    proc.stderr.unref();
+    proc.unref();
+
+    writePid(proc.pid);
+
+    process.stdout.write(`Waiting for port ${port}…`);
+    for (let i = 0; i < TIMEOUT_SECONDS; i++) {
+        if (await isPortOpen(port)) {
+            console.log(`\n${GREEN}✅ Server started${RESET}`);
+            console.log(`   URL:     http://localhost:${port}`);
+            console.log(`   PID:     ${proc.pid}`);
+            console.log(`   Command: ${cmd.join(' ')}`);
+            console.log(`\nStop with: node .agent/scripts/auto_preview.js stop`);
+            return;
+        }
+        process.stdout.write(".");
+        await new Promise(r => setTimeout(r, 1000));
+    }
+
+    console.log(`\n${RED}❌ Server did not start within ${TIMEOUT_SECONDS}s${RESET}`);
+    try {
+        process.kill(proc.pid, 'SIGTERM');
+    } catch {}
+    clearPid();
+}
+
+function stopServer() {
+    const pid = readPid();
+    if (!pid) {
+        console.log(`${YELLOW}⚠️  No stored server PID found${RESET}`);
+        return;
+    }
+    try {
+        process.kill(pid, 'SIGTERM');
+        console.log(`${GREEN}✅ Server stopped (PID ${pid})${RESET}`);
+    } catch {
+        console.log(`${YELLOW}Process ${pid} was not running${RESET}`);
+    } finally {
+        clearPid();
+    }
+}
+
+async function showStatus() {
+    const port = getPortFromEnv();
+    const pid = readPid();
+    if (await isPortOpen(port)) {
+        console.log(`${GREEN}🟢 Running — http://localhost:${port}${RESET}`);
+        if (pid) console.log(`   PID: ${pid}`);
+    } else {
+        console.log(`${RED}🔴 Not running on port ${port}${RESET}`);
+    }
+}
+
+async function main() {
+    const args = process.argv.slice(2);
+    const actions = new Set(["start", "stop", "status", "restart"]);
+    
+    if (args.length < 1 || !actions.has(args[0])) {
+        console.log(`Usage: node auto_preview.js [start|stop|status|restart]`);
+        process.exit(1);
+    }
+
+    const action = args[0];
+    if (action === "start") {
+        await startServer();
+    } else if (action === "stop") {
+        stopServer();
+    } else if (action === "status") {
+        await showStatus();
+    } else if (action === "restart") {
+        stopServer();
+        await new Promise(r => setTimeout(r, 1000));
+        await startServer();
+    }
+}
+
+if (require.main === module) {
+    main();
+}