tribunal-kit 8.0.0 → 9.0.1

package/.agents/skills/webapp-testing/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: webapp-testing
+description: Use when Comprehensive Web Application Testing strategy. Test Pyramid, Vitest/Jest for unit logic, React Testing Library for component integrity, MSW (Mock Service Worker) for API layer simulation, and visual regression. Use when setting up testing environments or defining global test strategies across a web stack.
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - testing-patterns
+  - playwright-best-practices
+  - tdd-workflow
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/test_runner.js
+  - .agent/scripts/verify_all.js
+  - .agent/scripts/lint_runner.js
+---
+
+# Webapp Testing — Full Stack Pipeline Mastery
+
+## Mandatory Pre-Flight Context Inspection
+
+Before generating, refactoring, or reviewing code in the `webapp-testing` 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 Comprehensive Web Application Testing strategy. Test Pyramid, Vitest/Jest for unit logic, React Testing Library for component integrity, MSW (Mock Service Worker) for API layer simulation, and visual regression. Use when setting up testing environments or defining global test strategies across a web stack.
+- **DO NOT activate when:** The task falls outside the `webapp-testing` 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
+
+---
+
+
+## Hallucination Traps (Read First)
+
+- ❌ Mocking everything in integration tests -> ✅ Integration tests verify real interactions; mock only external services (APIs, DBs)
+- ❌ Testing Library: using `getByTestId` as the primary selector -> ✅ Prefer `getByRole`, `getByLabelText`, `getByText` for user-centric testing
+- ❌ Writing E2E tests that depend on seed data -> ✅ Each test should create its own data in setup and clean up in teardown
+
+---
+
+---
+
+## 1. The Strategy (The Testing Trophy)
+
+The traditional "Testing Pyramid" (lots of Unit, little E2E) is outdated for rich UI applications. Use the **Testing Trophy**:
+
+1. **Static Analysis (10%)**: TypeScript, ESLint, Prettier (Catches typos and type mismatches instantly).
+2. **Unit Tests (20%)**: Vitest (Tests complex pure functions: math, formatting, data mapping).
+3. **Integration Tests (60%)**: React Testing Library + MSW (Tests components and network mock interactions together).
+4. **End-to-End Tests (10%)**: Playwright (Tests the critical path: Login, Checkout, Account Creation on a real browser).
+
+---
+
+## 2. Integration Layer (React Testing Library + MSW)
+
+Do not mock child components. Render the specific DOM tree and interact with it as a user would.
+
+To prevent network calls, utilize Mock Service Worker (MSW) which intercepts requests at the network layer natively.
+
+```typescript
+// ❌ BAD: Mocking implementation details
+jest.mock('axios');
+axios.get.mockResolvedValue({ data: { users: [] } });
+
+// ✅ GOOD: MSW (Mock Service Worker) network level interception
+// The component functions EXACTLY as it would in production
+import { http, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+
+export const handlers = [
+  http.get('/api/users', () => {
+    return HttpResponse.json([{ id: 1, name: 'John Appleseed' }]);
+  }),
+];
+const server = setupServer(...handlers);
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+### Component Testing (RTL)
+
+```typescript
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+test('Should load users and render names', async () => {
+  // userEvent closely replicates real browser physics (focusing, keystrokes)
+  const user = userEvent.setup();
+
+  render(<UserDashboard />);
+
+  // Initial State
+  expect(screen.getByText('Loading...')).toBeInTheDocument();
+
+  // Async Resolution (Auto-waits for the MSW mock to return)
+  const johnNode = await screen.findByText('John Appleseed');
+  expect(johnNode).toBeInTheDocument();
+
+  // Interaction
+  const deleteBtn = screen.getByRole('button', { name: "Delete John" });
+  await user.click(deleteBtn);
+
+  // Verification
+  expect(johnNode).not.toBeInTheDocument();
+});
+```
+
+---
+
+## 3. Pure Unit Testing (Vitest)
+
+Isolate business logic entirely from React.
+
+```typescript
+// ✅ Move complex logic OUT of the React component entirely
+export function calculateTax(subtotal: number, state: string): number {
+  if (subtotal < 0) throw new Error('Subtotal cannot be negative');
+  if (state === 'CA') return subtotal * 0.0825;
+  return 0; // Default
+}
+
+// ✅ Test with extreme precision and coverage
+import { describe, it, expect } from 'vitest';
+
+describe('calculateTax()', () => {
+  it('applies CA tax correctly', () => {
+    expect(calculateTax(100, 'CA')).toBe(8.25);
+  });
+
+  it('throws on negative input', () => {
+    expect(() => calculateTax(-50, 'CA')).toThrowError('negative');
+  });
+});
+```
+
+---
+
+## 🚨 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 |
+|:---|:---|:---|
+| **Testing Implementation Details** | Asserting on private component state or internal helper functions | Assert on observable user behaviors, DOM roles, and network outcomes |
+| **Flaky Async Assertion** | Using arbitrary setTimeout delays before asserting on asynchronous state | Use waitFor or findBy queries that poll with timeout bounds |
+| **Shared Mutable State** | Reusing database records across concurrent test runners | Isolate test databases per worker or execute in rolled-back transactions |
+
+---
+
+## 🏛️ Tribunal Verification & Guardrails
+
+**Active Reviewers:** `test-engineer` · `qa-automation-engineer` · `logic-reviewer`
+**Slash Command:** `/review` or `/tribunal-full`
+
+### ✅ Pre-Flight Self-Audit Checklist
+
+```
+✅ Do tests follow behavioral GIVEN/WHEN/THEN specifications?
+✅ Are happy path, failure paths, and boundary conditions (0, null, max) covered?
+✅ Are test mocks isolated and reset between successive suites?
+✅ Do E2E locators rely on stable ARIA attributes instead of brittle CSS selectors?
+✅ Did I verify test suite passes without flaky race conditions?
+```
+
+### 🛑 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/webapp-testing/scripts/playwright_runner.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""
+Skill: webapp-testing
+Script: playwright_runner.py
+Purpose: Run basic Playwright browser tests
+Usage: python playwright_runner.py <url> [--screenshot]
+Output: JSON with page info, health status, and optional screenshot path
+Note: Requires playwright (pip install playwright && playwright install chromium)
+Screenshots: Saved to system temp directory (auto-cleaned by OS)
+"""
+import sys
+import json
+import os
+import tempfile
+from datetime import datetime
+
+# Fix Windows console encoding for Unicode output
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except AttributeError:
+    pass  # Python < 3.7
+
+try:
+    from playwright.sync_api import sync_playwright
+    PLAYWRIGHT_AVAILABLE = True
+except ImportError:
+    PLAYWRIGHT_AVAILABLE = False
+
+
+def run_basic_test(url: str, take_screenshot: bool = False) -> dict:
+    """Run basic browser test on URL."""
+    if not PLAYWRIGHT_AVAILABLE:
+        return {
+            "error": "Playwright not installed",
+            "fix": "pip install playwright && playwright install chromium"
+        }
+    
+    result = {
+        "url": url,
+        "timestamp": datetime.now().isoformat(),
+        "status": "pending"
+    }
+    
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            context = browser.new_context(
+                viewport={"width": 1280, "height": 720},
+                user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+            )
+            page = context.new_page()
+            
+            # Navigate
+            response = page.goto(url, wait_until="networkidle", timeout=30000)
+            
+            # Basic info
+            result["page"] = {
+                "title": page.title(),
+                "url": page.url,
+                "status_code": response.status if response else None
+            }
+            
+            # Health checks
+            result["health"] = {
+                "loaded": response.ok if response else False,
+                "has_title": bool(page.title()),
+                "has_h1": page.locator("h1").count() > 0,
+                "has_links": page.locator("a").count() > 0,
+                "has_images": page.locator("img").count() > 0
+            }
+            
+            # Console errors
+            console_errors = []
+            page.on("console", lambda msg: console_errors.append(msg.text) if msg.type == "error" else None)
+            
+            # Performance metrics
+            result["performance"] = {
+                "dom_content_loaded": page.evaluate("window.performance.timing.domContentLoadedEventEnd - window.performance.timing.navigationStart"),
+                "load_complete": page.evaluate("window.performance.timing.loadEventEnd - window.performance.timing.navigationStart")
+            }
+            
+            # Screenshot - uses system temp directory (cross-platform, auto-cleaned)
+            if take_screenshot:
+                # Cross-platform: Windows=%TEMP%, Linux/macOS=/tmp
+                screenshot_dir = os.path.join(tempfile.gettempdir(), "maestro_screenshots")
+                os.makedirs(screenshot_dir, exist_ok=True)
+                screenshot_path = os.path.join(screenshot_dir, f"screenshot_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png")
+                page.screenshot(path=screenshot_path, full_page=True)
+                result["screenshot"] = screenshot_path
+                result["screenshot_note"] = "Saved to temp directory (auto-cleaned by OS)"
+            
+            # Element counts
+            result["elements"] = {
+                "links": page.locator("a").count(),
+                "buttons": page.locator("button").count(),
+                "inputs": page.locator("input").count(),
+                "images": page.locator("img").count(),
+                "forms": page.locator("form").count()
+            }
+            
+            browser.close()
+            
+            result["status"] = "success" if result["health"]["loaded"] else "failed"
+            result["summary"] = "[OK] Page loaded successfully" if result["status"] == "success" else "[X] Page failed to load"
+            
+    except Exception as e:
+        result["status"] = "error"
+        result["error"] = str(e)
+        result["summary"] = f"[X] Error: {str(e)[:100]}"
+    
+    return result
+
+
+def run_accessibility_check(url: str) -> dict:
+    """Run basic accessibility check."""
+    if not PLAYWRIGHT_AVAILABLE:
+        return {"error": "Playwright not installed"}
+    
+    result = {"url": url, "accessibility": {}}
+    
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            page = browser.new_page()
+            page.goto(url, wait_until="networkidle", timeout=30000)
+            
+            # Basic a11y checks
+            result["accessibility"] = {
+                "images_with_alt": page.locator("img[alt]").count(),
+                "images_without_alt": page.locator("img:not([alt])").count(),
+                "buttons_with_label": page.locator("button[aria-label], button:has-text('')").count(),
+                "links_with_text": page.locator("a:has-text('')").count(),
+                "form_labels": page.locator("label").count(),
+                "headings": {
+                    "h1": page.locator("h1").count(),
+                    "h2": page.locator("h2").count(),
+                    "h3": page.locator("h3").count()
+                }
+            }
+            
+            browser.close()
+            result["status"] = "success"
+            
+    except Exception as e:
+        result["status"] = "error"
+        result["error"] = str(e)
+    
+    return result
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print(json.dumps({
+            "error": "Usage: python playwright_runner.py <url> [--screenshot] [--a11y]",
+            "examples": [
+                "python playwright_runner.py https://example.com",
+                "python playwright_runner.py https://example.com --screenshot",
+                "python playwright_runner.py https://example.com --a11y"
+            ]
+        }, indent=2))
+        sys.exit(1)
+    
+    url = sys.argv[1]
+    take_screenshot = "--screenshot" in sys.argv
+    check_a11y = "--a11y" in sys.argv
+    
+    if check_a11y:
+        result = run_accessibility_check(url)
+    else:
+        result = run_basic_test(url, take_screenshot)
+    
+    print(json.dumps(result, indent=2))

package/.agents/skills/webgpu-performance/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: webgpu-performance
+description: Use when High-performance browser graphics and compute mastery. Transitioning from WebGL to WebGPU API, WGSL compute shaders, explicit GPU memory management, and browser-side tensor calculations.
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - 60fps-animation
+  - fixing-motion-performance
+  - motion-engineering
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# WebGPU Performance Mastery
+
+## Mandatory Pre-Flight Context Inspection
+
+Before generating, refactoring, or reviewing code in the `webgpu-performance` 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 High-performance browser graphics and compute mastery. Transitioning from WebGL to WebGPU API, WGSL compute shaders, explicit GPU memory management, and browser-side tensor calculations.
+- **DO NOT activate when:** The task falls outside the `webgpu-performance` 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
+
+---
+
+
+## 1. Core Principles
+
+- **Explicit > Implicit:** Unlike WebGL, WebGPU doesn't hide state. You must explicitly configure Pipelines, BindGroups, and CommandEncoders.
+- **Compute First:** Leverage Compute Shaders (`@compute @workgroup_size(X, Y)`) for heavy array manipulation, physics, or ML tensor operations, keeping the CPU entirely free.
+- **Buffer Alignment:** WGSL requires strict 4-byte or 16-byte alignment (`vec4<f32>`, `mat4x4<f32>`). Always pad structs exactly to prevent silent memory corruption.
+
+## 2. WGSL Compute Shader Pattern
+
+When performing parallel calculations (e.g., particle physics or ML matrix multiplication):
+
+```wgsl
+struct SystemData {
+    deltaTime: f32,
+    particleCount: u32,
+}
+
+@group(0) @binding(0) var<uniform> data: SystemData;
+@group(0) @binding(1) var<storage, read_write> particles: array<vec4<f32>>;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
+    let index = global_id.x;
+    if (index >= data.particleCount) { return; }
+
+    var pos = particles[index];
+    pos.y -= 9.8 * data.deltaTime; // Gravity
+    particles[index] = pos;
+}
+```
+
+## 3. WebGPU Execution Pipeline
+
+To run the above compute shader from TypeScript:
+
+1. **Initialize:** `navigator.gpu.requestAdapter()` -> `requestDevice()`.
+2. **Create Buffers:** `device.createBuffer({ size, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST })`.
+3. **Write Data:** `device.queue.writeBuffer(buffer, 0, float32Array)`.
+4. **Bind Group:** Group buffers into a `GPUBindGroup`.
+5. **Command Encoder:**
+   ```typescript
+   const encoder = device.createCommandEncoder();
+   const pass = encoder.beginComputePass();
+   pass.setPipeline(computePipeline);
+   pass.setBindGroup(0, bindGroup);
+   pass.dispatchWorkgroups(Math.ceil(count / 64));
+   pass.end();
+   device.queue.submit([encoder.finish()]);
+   ```
+
+## 4. LLM Traps & Pre-Flight Checks
+
+- **TRAP:** Assuming WebGPU works everywhere.
+- **FIX:** Always feature-detect with `if (!navigator.gpu) { fallbackToWebGL(); }`.
+- **TRAP:** Struct alignment issues in WGSL.
+- **FIX:** Never use `vec3<f32>` inside arrays without padding. It behaves as 16-bytes anyway. Use `vec4<f32>` to be perfectly aligned.
+- **TRAP:** Reading buffers back to the CPU synchronoulsy.
+- **FIX:** Use `mapAsync(GPUMapMode.READ)` and await it. Do not block the main thread.
+
+## Verification Protocol
+
+Before submitting code, ensure:
+
+1. Devices and adapters are properly null-checked.
+2. WGSL workgroup sizes align with the dispatch sizes dynamically.
+3. GPUBuffers used for compute have `GPUBufferUsage.STORAGE` flags.
+
+---
+
+## 🚨 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 |
+|:---|:---|:---|
+| **Hallucinated Tool Capabilities** | Assuming an external library or CLI command exists without verification | Run a verification check or verify package.json before referencing tools |
+| **Premature Completion Claim** | Declaring a task finished because code was generated without verification | Execute tests, linters, or terminal commands to provide concrete proof |
+| **Context Bloat Dumping** | Pasting entire multi-thousand-line files into prompt context | Extract targeted excerpts, symbols, and signatures to preserve tokens |
+
+---
+
+## 🏛️ Tribunal Verification & Guardrails
+
+**Active Reviewers:** `orchestrator` · `agent-organizer` · `logic-reviewer`
+**Slash Command:** `/review` or `/tribunal-full`
+
+### ✅ Pre-Flight Self-Audit Checklist
+
+```
+✅ Did I deconstruct the root objective before proposing architecture?
+✅ Did I identify dependencies, bottlenecks, and parallelizable sub-tasks?
+✅ Did I avoid over-engineering and select the simplest effective pattern?
+✅ Did I verify assumptions with concrete file reads instead of speculation?
+✅ Did I establish measurable verification criteria before completion?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing test suites, compiler success, or equivalent operational proof) that your output works as intended.