tribunal-kit 2.4.6 → 3.1.0

package/.agent/workflows/tribunal-frontend.md

@@ -1,115 +1,95 @@
 ---
-description: Frontend + React specific Tribunal. Runs Logic + Security + Frontend + Types. Use for React components, hooks, and UI code.
+description: Frontend and React specific Tribunal. Runs Logic + Security + Frontend + Type Safety reviewers. Use for React components, hooks, UI code, Next.js pages, Server Components, and Client Components.
 ---
 
-# /tribunal-frontend — UI & React Audit
+# /tribunal-frontend — Frontend Code Audit
 
 $ARGUMENTS
 
 ---
 
-Focused audit for React, Next.js, Vue, and frontend code. Four reviewers analyze it simultaneously for framework-specific issues that generic reviews miss.
+## When to Use /tribunal-frontend
 
----
+|Use `/tribunal-frontend` when...|Use something else when...|
+|:---|:---|
+|React components (Server or Client)|Backend routes → `/tribunal-backend`|
+|Custom hooks|Database queries → `/tribunal-database`|
+|Next.js pages and layouts|Mobile (React Native) → `/tribunal-mobile`|
+|UI state management|Maximum coverage → `/tribunal-full`|
+|Form handling with Server Actions||
 
-## When to Use This vs Other Tribunals
+---
 
-| Code type | Right tribunal |
-|---|---|
-| React components, hooks, JSX | `/tribunal-frontend` ← you are here |
-| API routes, auth, middleware | `/tribunal-backend` |
-| SQL queries, ORM | `/tribunal-database` |
-| React Native / mobile UI | `/tribunal-mobile` |
-| Unknown domain or cross-domain | `/tribunal-full` |
+## 4 Active Reviewers (All Run Simultaneously)
+
+### logic-reviewer
+- Hallucinated React 19 hooks (non-existent hook names)
+- useFormState called instead of useActionState (React 19 rename)
+- useEffect missing dependencies (stale closure)
+- Multiple setStates that should be batched (React 19 auto-batches in most cases)
+
+### security-auditor
+- `dangerouslySetInnerHTML` with user-controlled content (XSS)
+- eval/Function() calls in component code
+- Exposing sensitive data in client-rendered output
+
+### frontend-reviewer
+- useState/useReducer in Server Components (no client runtime!)
+- 'use client' directive missing on components using hooks
+- Missing 'use server' on Server Actions
+- cookies()/headers()/params not awaited in Next.js 15
+- useEffect not cleaned up (subscription leaks)
+- Keys not unique in list rendering (using index as key)
+- Direct DOM mutations (document.querySelector inside React)
+
+### type-safety-reviewer  
+- Props typed as `any`
+- Event handlers typed as `any` (use `React.MouseEvent<HTMLButtonElement>`)
+- Server Component async props typed without Promise<> (Next.js 15 params)
+- No explicit return type on custom hooks
 
 ---
 
-## Active Reviewers
+## Verdict System
 
 ```
-logic-reviewer          → Non-existent React APIs, impossible render conditions,
-                          stale closure patterns, state set during unmounted component
-security-auditor        → XSS via dangerouslySetInnerHTML, exposed tokens or secrets
-                          in component state, unsanitized URL params
-frontend-reviewer       → Hooks violations (rules of hooks), missing dep arrays,
-                          direct state mutation, infinite render loops
-type-safety-reviewer    → Untyped props, any in hooks, unsafe DOM ref usage,
-                          missing generic type parameters
+If ANY reviewer → ❌ REJECTED: fix before Human Gate
+If any reviewer → ⚠️ WARNING:  proceed with flagged items
+If all reviewers → ✅ APPROVED: Human Gate
 ```
 
 ---
 
-## What Gets Flagged — Real Examples
-
-| Reviewer | Example Finding |
-|---|---|
-| logic | `useState.useAsync()` — not a real React API |
-| logic | Setting state during render without a guard → infinite loop |
-| security | `dangerouslySetInnerHTML={{ __html: userInput }}` — XSS |
-| security | `localStorage.setItem('token', jwt)` — accessible to XSS |
-| frontend | `useEffect(() => {...}, [])` with a prop used inside — stale closure |
-| frontend | `setCount(count + 1)` inside a stale closure — use functional updater |
-| frontend | Hook called inside a conditional `if (loggedIn) { useData() }` |
-| type-safety | `function Card(props: any)` — no defined prop interface |
-| type-safety | `ref.current.focus()` without null check |
-
 ---
 
-## Report Format
-
-```
-━━━ Frontend Audit ━━━━━━━━━━━━━━━━━━━━━━
-
-  logic-reviewer:     ✅ APPROVED
-  security-auditor:   ✅ APPROVED
-  frontend-reviewer:  ❌ REJECTED
-  type-safety:        ⚠️  WARNING
-
-━━━ Issues ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## Frontend-Specific Hallucination Traps (Common LLM Mistakes)
 
-frontend-reviewer:
-  ❌ HIGH — Line 18
-     Missing dep: userId used inside useEffect but not in dep array
-     Code: useEffect(() => fetchUser(userId), [])
-     Fix:  useEffect(() => fetchUser(userId), [userId])
+```typescript
+// ❌ React 19: useFormState renamed to useActionState
+import { useFormState } from 'react';      // useFormState no longer exists in React 19
+import { useActionState } from 'react';    // Correct React 19 name
 
-  ❌ HIGH — Line 34
-     Hook called conditionally: if (isAuth) { useDashboardData() }
-     Fix: Move hook to top level, use enabled flag inside hook
+// ❌ Next.js 15: params and searchParams must be awaited
+const { id } = params;                    // WRONG — params is a Promise in Next.js 15
+const { id } = await params;             // CORRECT
 
-type-safety-reviewer:
-  ⚠️ MEDIUM — Line 3
-     props: any — define a typed interface for this component
-     Fix: interface CardProps { title: string; content: React.ReactNode }
+// ❌ Hook not valid in Server Component
+export default async function Page() {
+  const [count, setCount] = useState(0); // Server Components cannot use hooks
+}
 
-━━━ Verdict: REJECTED — fix before merging ━━━━━━
+// ❌ Server Action missing 'use server'
+async function saveData(formData: FormData) {  // Without 'use server' — not a Server Action
+  'use server';                                // Must be FIRST line
 ```
 
 ---
 
-## Hallucination Guard
-
-- Only real React/Vue/Next.js APIs are accepted — invented hooks get REJECTED
-- Hook violation findings cite the **specific hooks rule being broken**
-- XSS findings include the **specific input path** that creates the injection
-
----
-
-## Cross-Workflow Navigation
-
-| Finding type | Next step |
-|---|---|
-| XSS finding | Contact security team + `/audit` for project-wide XSS scan |
-| Hooks violations everywhere | `/refactor` to extract to properly structured custom hooks |
-| All approved | Human Gate to write code to disk |
-
----
-
-## Usage
+## Usage Examples
 
 ```
-/tribunal-frontend [paste component code]
-/tribunal-frontend [paste custom hook]
-/tribunal-frontend src/components/UserCard.tsx
-/tribunal-frontend the usePagination hook
+/tribunal-frontend the ProductCard component with server-fetched data
+/tribunal-frontend the useAuth custom hook implementation
+/tribunal-frontend the checkout page with Server Action form
+/tribunal-frontend the DashboardLayout with Suspense and loading states
 ```

package/.agent/workflows/tribunal-full.md

@@ -1,136 +1,92 @@
 ---
-description: Run ALL 11 Tribunal reviewer agents simultaneously. Maximum hallucination coverage. Use before merging any AI-generated code.
+description: Run ALL 11 Tribunal reviewer agents simultaneously. Maximum hallucination coverage. Use before merging any AI-generated code, before production deployments, or when maximum confidence is required.
 ---
 
-# /tribunal-full — Full Panel Review
+# /tribunal-full — Complete 11-Reviewer Audit
 
 $ARGUMENTS
 
 ---
 
-Paste code. All 11 reviewers analyze it simultaneously. Maximum coverage, no domain gaps.
+## When to Use /tribunal-full
 
-Use this **before merging any AI-generated code**, or when you're not sure which domain a piece of code sits in.
+|Use `/tribunal-full` when...|Use targeted tribunal when...|
+|:---|:---|
+|Before merging any AI-generated code|Backend only → `/tribunal-backend`|
+|Before production deployment|Frontend only → `/tribunal-frontend`|
+|Security-critical feature review|DB only → `/tribunal-database`|
+|Code affects auth, payments, or PII||
+|Maximum confidence required||
 
 ---
 
-## When to Use /tribunal-full vs Targeted Tribunals
-
-| Use `/tribunal-full` when... | Use a targeted tribunal when... |
-|---|---|
-| Not sure which domain applies | You know it's backend-only → `/tribunal-backend` |
-| Cross-domain code (API + DB + UI) | Pure frontend → `/tribunal-frontend` |
-| AI-generated code, pre-merge | Pure database queries → `/tribunal-database` |
-| Security-critical code path | Mobile-specific → `/tribunal-mobile` |
-| "Final check" before shipping | Performance concern only → `/tribunal-performance` |
-
----
-
-## Who Runs
+## 11 Reviewers — All Active Simultaneously
 
 ```
-logic-reviewer          → Hallucinated methods, impossible logic, undefined refs
-security-auditor        → OWASP Top 10, injection, secrets, auth bypass
-dependency-reviewer     → Imports not found in package.json
-type-safety-reviewer    → any, unsafe casts, unguarded access
-sql-reviewer            → Injection via interpolation, N+1, invented schema
-frontend-reviewer       → Hooks violations, missing dep arrays, state mutation
-performance-reviewer    → O(n²), blocking I/O, memory allocation anti-patterns
-test-coverage-reviewer  → Tautology tests, no-assertion specs, over-mocking
-mobile-reviewer         → Touch targets, safe areas, keyboard avoidance, image memory
-ai-code-reviewer        → Hallucinated model names, fake params, prompt injection, rate limits
-accessibility-reviewer  → WCAG violations, missing ARIA, contrast, keyboard navigation
+Tier 1: Always active (universal concerns)
+├── logic-reviewer         → Hallucinated methods, impossible logic, undefined refs
+└── security-auditor       → OWASP 2025, injection, JWT, SSRF, IDOR
+
+Tier 2: Code quality
+├── dependency-reviewer    → Fabricated packages, supply chain, version compatibility
+├── type-safety-reviewer   → 'any' epidemic, Zod parse vs cast, unguarded access
+└── sql-reviewer           → Injection, N+1, missing indexes, unscoped mutations
+
+Tier 3: Domain-specific
+├── frontend-reviewer      → React 19 APIs, RSC violations, hook rules, hydration
+├── performance-reviewer   → 2026 CWV targets, re-render cascades, memory leaks
+├── mobile-reviewer        → Reanimated thread safety, FlashList, safe area insets
+├── ai-code-reviewer       → Model name hallucinations, prompt injection, cost explosion
+├── test-coverage-reviewer → Happy path only, brittle selectors, missing edge cases
+└── accessibility-reviewer → WCAG 2.2 AA, ARIA misuse, focus management, live regions
 ```
 
-All 11 run in parallel. You wait for all verdicts before seeing the result.
-
 ---
 
-## Severity Levels
+## Active Reviewers by Code Type
 
-| Symbol | Severity | Meaning |
-|---|---|---|
-| `❌ CRITICAL` | Blocking | Must be fixed before code reaches the codebase |
-| `❌ HIGH` | Blocking | Likely to cause bugs or security issues in production |
-| `⚠️ MEDIUM` | Non-blocking | Should be addressed; review before approving |
-| `💬 LOW` | Advisory | Consider fixing; does not block merge |
+Not all 11 reviewers produce meaningful findings on all code types. Active reviewers detect their first finding immediately — inactive reviewers auto-pass with "N/A for this code type."
 
-**Policy:** Any `CRITICAL` or `HIGH` finding means the verdict is `REJECTED`. Code must be revised.
+|Code Under Review|Critical Reviewers|
+|:---|:---|
+|REST API route|logic, security, dependency, type-safety, sql|
+|React component|logic, frontend, accessibility, type-safety|
+|Database query|logic, security, sql|
+|AI LLM integration|logic, security, ai-code, dependency|
+|Test file|test-coverage, logic|
+|React Native / Expo|mobile, logic, security, performance|
+|Next.js page|logic, frontend, performance, accessibility|
+|Auth/JWT code|security, logic, type-safety|
 
 ---
 
-## Report Format
+## Verdict Aggregation
 
 ```
-━━━ Full Tribunal Audit ━━━━━━━━━━━━━━━━━━━━━
-
-  logic-reviewer:          ✅ APPROVED
-  security-auditor:        ❌ REJECTED
-  dependency-reviewer:     ✅ APPROVED
-  type-safety-reviewer:    ⚠️  WARNING
-  sql-reviewer:            ✅ APPROVED
-  frontend-reviewer:       ✅ APPROVED
-  performance-reviewer:    ✅ APPROVED
-  test-coverage-reviewer:  ❌ REJECTED
-  mobile-reviewer:         ✅ APPROVED (N/A — no mobile code)
-  ai-code-reviewer:        ✅ APPROVED (N/A — no LLM calls)
-  accessibility-reviewer:  ✅ APPROVED
-
-━━━ Issues ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-security-auditor:
-  ❌ CRITICAL — Line 12
-     SQL injection: db.query(`WHERE id = ${id}`)
-     Fix: db.query('WHERE id = $1', [id])
-
-test-coverage-reviewer:
-  ❌ HIGH — Line 45-60
-     Tautology test: expect(fn(x)).toBe(fn(x)) — always passes regardless of fn's behavior
-
-type-safety-reviewer:
-  ⚠️ MEDIUM — Line 7
-     Implicit any in parameter: function (data) — add explicit type annotation
-
-━━━ Verdict ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  2 REJECTED. Fix all CRITICAL and HIGH issues before this code reaches your codebase.
-  1 WARNING — review before approving.
-  8 APPROVED.
+All 11 verdicts are collected. Aggregated result:
+
+If ANY reviewer = ❌ REJECTED → Global verdict: ❌ REJECTED (must fix before Human Gate)
+If any reviewer = ⚠️ WARNING  → Global verdict: ⚠️ WARNINGS (proceed with attention)
+If all reviewers = ✅ APPROVED → Global verdict: ✅ APPROVED (proceed to Human Gate)
 ```
 
 ---
 
+---
+
 ## Retry Protocol
 
-If code is rejected:
+When code is rejected:
 
 ```
-Attempt 1 → Fix issues from verdicts and resubmit
-Attempt 2 → Stricter constraints + specific reviewer feedback
-Attempt 3 → Maximum constraints + full context dump
-Attempt 4 → HALT. Escalate to human with full failure history.
+Attempt 1: Maker revises with reviewer feedback
+Attempt 2: Maker revises with stricter constraints + full reviewer context
+Attempt 3: Maker revises with maximum constraints + full context dump
+
+After 3 failed attempts:
+  → HALT
+  → Report to human with full failure history
+  → DO NOT retry silently
 ```
 
-Hard limit: **3 revisions**. After 3 rejections, the agent stops and reports.
-
 ---
-
-## Cross-Workflow Navigation
-
-| After seeing findings... | Go to |
-|---|---|
-| Security findings need a targeted scan | `/audit` for full project-wide security sweep |
-| Performance issues found | `/tribunal-performance` for deeper profiling |
-| SQL injection pattern found | Check with `/tribunal-database` across all queries |
-| Stale or phantom deps found | `/audit` → dependency scan |
-
----
-
-## Usage
-
-```
-/tribunal-full [paste any code]
-/tribunal-full before merging
-/tribunal-full when you're unsure which domain applies
-/tribunal-full the entire auth service
-```

package/.agent/workflows/tribunal-mobile.md

@@ -1,123 +1,94 @@
 ---
-description: Mobile-specific Tribunal. Runs Logic + Security + Mobile reviewers. Use for React Native, Flutter, and responsive web code.
+description: Mobile-specific Tribunal. Runs Logic + Security + Mobile reviewers. Use for React Native, Expo, gesture handlers, animations, navigation, and any iOS/Android-targeted code.
 ---
 
-# /tribunal-mobile — Mobile Code Tribunal
+# /tribunal-mobile — Mobile Code Audit
 
 $ARGUMENTS
 
 ---
 
-This command activates the **Mobile Tribunal** — a focused panel of reviewers covering the specific failure modes of mobile and responsive application code.
+## When to Use /tribunal-mobile
 
-Use this instead of `/tribunal-full` when your code is specifically mobile-domain. It gives faster, more precise feedback than running all 11 reviewers.
+|Use `/tribunal-mobile` when...|Use something else when...|
+|:---|:---|
+|React Native components|Web-only components → `/tribunal-frontend`|
+|Expo Router navigation|API routes → `/tribunal-backend`|
+|Reanimated animations/gestures|Full audit → `/tribunal-full`|
+|FlashList / FlatList code||
+|Platform-specific (ios/android) code||
 
 ---
 
-## When to Use This vs Other Tribunals
-
-| Code type | Right tribunal |
-|---|---|
-| React Native, Flutter, mobile UI | `/tribunal-mobile` ← you are here |
-| Pure React (web) components | `/tribunal-frontend` |
-| API routes, auth, middleware | `/tribunal-backend` |
-| Cross-domain or pre-merge audit | `/tribunal-full` |
+## 3 Active Reviewers (All Run Simultaneously)
+
+### logic-reviewer
+- `runOnJS` called inside `onUpdate` instead of `onEnd` (runs every frame)
+- Missing `'worklet'` directive on functions called inside Reanimated
+- FlatList inside ScrollView (disables virtualization)
+- `useSharedValue` vs `useState` confusion (SharedValue on wrong thread)
+
+### security-auditor
+- AsyncStorage storing sensitive data (tokens, PII) unencrypted
+- API keys in source code (should be in EAS Secrets)
+- cleartext HTTP traffic (should be HTTPS on all platforms)
+- Deep link not validated before processing URL scheme
+
+### mobile-reviewer
+- `setState` inside Reanimated `onUpdate` (JS bridge crossing = jank)
+- Missing `'worklet'` on custom functions used in Reanimated
+- FlatList for large lists (use FlashList with `estimatedItemSize`)
+- Hardcoded pixel insets instead of `useSafeAreaInsets()`
+- `Platform.OS === 'ios'` inside StyleSheet.create (not evaluated correctly)
+- Missing `AppState` subscription cleanup (`subscription.remove()`)
+- `react-native Image` used instead of `expo-image` (poor caching)
 
 ---
 
-## Active Reviewers
-
-| Reviewer | What It Catches |
-|---|---|
-| `logic-reviewer` | Hallucinated RN/Flutter APIs, impossible logic, undefined refs |
-| `security-auditor` | Hardcoded secrets, insecure storage, OWASP Mobile Top 10 |
-| `mobile-reviewer` | Touch targets, safe areas, keyboard avoidance, gesture handling, image optimization |
-
----
-
-## What Gets Flagged — Real Examples
-
-| Reviewer | Example Finding | Severity |
-|---|---|---|
-| logic | Calling a non-existent `Animated.stagger()` method | ❌ HIGH |
-| security | `AsyncStorage.setItem('token', jwt)` — use `expo-secure-store` instead | ⚠️ MEDIUM |
-| security | Deeplink handler with no validation of `url` param | ❌ HIGH |
-| security | Missing certificate pinning on sensitive API endpoints | ⚠️ MEDIUM |
-| mobile | Button `height: 20` — minimum touch target is 44pt (iOS) / 48dp (Android) | ❌ HIGH |
-| mobile | Missing `<SafeAreaView>` on root screen component | ❌ HIGH |
-| mobile | No `KeyboardAvoidingView` on screen with text inputs | ❌ HIGH |
-| mobile | `<Image source={uri}>` with no width/height bounds — memory risk | ⚠️ MEDIUM |
-| mobile | No `Platform.OS` guard on platform-specific code | ⚠️ MEDIUM |
-
----
-
-## Mobile-Specific Anti-Hallucination Rules
+## Verdict System
 
 ```
-❌ Never reference RN APIs not listed in the installed react-native version
-❌ Never assume iOS and Android behave identically — always check Platform.OS when needed
-❌ Never use AsyncStorage for sensitive data (tokens, passwords, biometrics)
-❌ Never skip keyboard avoidance on screens with text inputs
-❌ Never use hardcoded pixel values — use pt (iOS) or dp (Android) logical units
-❌ Never claim an animation approach is "performant" without mentioning native driver usage
+If ANY reviewer → ❌ REJECTED: fix before Human Gate
+If any reviewer → ⚠️ WARNING:  proceed with flagged items
+If all reviewers → ✅ APPROVED: Human Gate
 ```
 
 ---
 
-## Output Format
-
-```
-━━━ Tribunal: Mobile ━━━━━━━━━━━━━━━━━━━━━
-
-Active reviewers: logic · security · mobile
-
-[Your code under review]
-
-━━━ Verdicts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-logic-reviewer:    ✅ APPROVED
-security-auditor:  ⚠️  WARNING
-mobile-reviewer:   ❌ REJECTED
-
-━━━ Issues ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-security-auditor:
-  ⚠️ MEDIUM — Line 8
-     AsyncStorage used for auth token storage
-     Fix: Use expo-secure-store or react-native-keychain for sensitive data
-
-mobile-reviewer:
-  ❌ HIGH — Line 12
-     Touch target: Button height is 20pt. Minimum is 44pt (iOS) / 48dp (Android)
-     Fix: style={{ minHeight: 44 }}
-
-  ❌ HIGH — Line 34
-     Missing SafeAreaView wrapping the root view
-     Fix: Wrap with <SafeAreaView style={{ flex: 1 }}>
-
-━━━ Verdict: REJECTED ━━━━━━━━━━━━━━━━━━━━
-
-Address rejections?  Y = fix and re-review | N = accept risk | R = revise manually
-```
-
 ---
 
-## Cross-Workflow Navigation
-
-| Finding type | Next step |
-|---|---|
-| Insecure storage CRITICAL | Replace storage library via `/enhance` |
-| All touch target issues | `/enhance` to normalize touch targets in shared components |
-| Cross-platform behavior gap | `/refactor` to extract Platform.OS guards into a utility |
-| All approved | Human Gate to write to disk |
+## Mobile-Specific Hallucination Traps (Common LLM Mistakes)
+
+```tsx
+// ❌ Missing 'worklet' — animation function crashes silently
+const clamp = (val: number, min: number, max: number) => Math.min(Math.max(val, min), max);
+// ✅ Must have worklet directive
+const clamp = (val: number, min: number, max: number): number => {
+  'worklet';
+  return Math.min(Math.max(val, min), max);
+};
+
+// ❌ Expo Router: navigate() was refactored in v4 — old API
+import { navigate } from 'expo-router';   // Named export doesn't exist
+// ✅ Current Expo Router v4
+import { router } from 'expo-router';
+router.push('/products/123');
+
+// ❌ React Native: StyleSheet.create doesn't eval functions
+const styles = StyleSheet.create({
+  box: { paddingTop: Platform.OS === 'ios' ? 20 : 0 } // Doesn't work in all contexts
+});
+// ✅ Use Platform.select or dynamic style object
+const boxStyle = Platform.select({ ios: { paddingTop: 20 }, android: { paddingTop: 0 } });
+```
 
 ---
 
-## Usage
+## Usage Examples
 
 ```
-/tribunal-mobile my React Native login screen component
-/tribunal-mobile the Flutter payment form widget
-/tribunal-mobile the responsive mobile nav component with touch gestures
-/tribunal-mobile the biometric authentication flow
+/tribunal-mobile the SwipeToDelete gesture implementation with Reanimated 3
+/tribunal-mobile the ProductList component using FlashList
+/tribunal-mobile the auth token storage and retrieval functions
+/tribunal-mobile the ProfileScreen with safe area insets
 ```