tribunal-kit 4.4.3 → 4.4.5

package/.agent/scripts/marathon_harness.js

@@ -39,7 +39,7 @@ const ARCHIVE_DIR = path.join(MARATHON_DIR, 'archive');
 
 const VALID_COMMANDS = new Set([
     'init', 'status', 'next', 'mark', 'log',
-    'session-start', 'session-end', 'reset', 'add-feature'
+    'session-start', 'session-end', 'reset', 'add-feature', 'distill'
 ]);
 
 // ── Schema Defaults ──────────────────────────────────────────────────────────
@@ -153,25 +153,50 @@ function getGitBranch() {
 // ── Progress Helpers ─────────────────────────────────────────────────────────
 
 /**
- * Count passing features.
+ * Count passing features and blocked features.
  * @param {object} featureList
- * @returns {{ total: number, passing: number, failing: number }}
+ * @returns {{ total: number, passing: number, failing: number, blocked: number }}
  */
 function countFeatures(featureList) {
     const features = featureList.features || [];
     const total = features.length;
     const passing = features.filter(f => f.passes === true).length;
-    return { total, passing, failing: total - passing };
+    let blocked = 0;
+    
+    features.forEach(f => {
+        if (!f.passes && f.dependencies && f.dependencies.length > 0) {
+            const allPassed = f.dependencies.every(depId => {
+                const dep = features.find(d => d.id === depId);
+                return dep && dep.passes === true;
+            });
+            if (!allPassed) blocked++;
+        }
+    });
+    
+    return { total, passing, failing: total - passing, blocked };
 }
 
 /**
- * Get the next unfinished feature.
+ * Get the next unfinished, unblocked feature.
  * @param {object} featureList
  * @returns {object|null}
  */
 function getNextFeature(featureList) {
     const features = featureList.features || [];
-    return features.find(f => f.passes !== true) || null;
+    return features.find(f => {
+        if (f.passes === true) return false;
+        
+        // Check dependencies (DAG)
+        if (f.dependencies && f.dependencies.length > 0) {
+            const allPassed = f.dependencies.every(depId => {
+                const dep = features.find(d => d.id === depId);
+                return dep && dep.passes === true;
+            });
+            if (!allPassed) return false; // Feature is blocked
+        }
+        
+        return true;
+    }) || null;
 }
 
 /**
@@ -240,8 +265,9 @@ function cmdInit(spec) {
  * @param {string} category
  * @param {string} description
  * @param {string[]} steps
+ * @param {number[]} deps
  */
-function cmdAddFeature(category, description, steps) {
+function cmdAddFeature(category, description, steps, deps = []) {
     if (!isActive()) {
         console.error(`${RED}❌ No active marathon. Run ${CYAN}init${RED} first.${RESET}`);
         process.exit(1);
@@ -264,6 +290,9 @@ function cmdAddFeature(category, description, steps) {
         category: category.toLowerCase(),
         description,
         steps: steps.length > 0 ? steps : ['Implement and verify'],
+        dependencies: deps,
+        attempts: 0,
+        failureReasons: [],
         passes: false,
         sessionCompleted: null
     };
@@ -289,7 +318,7 @@ function cmdStatus() {
     const progress = readJSON(PROGRESS_FILE);
     if (!featureList || !progress) return;
 
-    const { total, passing, failing } = countFeatures(featureList);
+    const { total, passing, failing, blocked } = countFeatures(featureList);
     const nextFeature = getNextFeature(featureList);
     const sessions = progress.sessions || [];
     const lastSession = sessions[sessions.length - 1] || null;
@@ -303,7 +332,8 @@ function cmdStatus() {
     console.log();
 
     // ── Progress Bar ──
-    console.log(`  ${BOLD}Progress:${RESET} ${progressBar(passing, total)}  ${GREEN}${passing}${RESET}/${total} features`);
+    const blockedInfo = blocked > 0 ? ` (${YELLOW}${blocked} blocked${RESET})` : '';
+    console.log(`  ${BOLD}Progress:${RESET} ${progressBar(passing, total)}  ${GREEN}${passing}${RESET}/${total} features${blockedInfo}`);
     console.log();
 
     // ── Category Breakdown ──
@@ -382,7 +412,12 @@ function cmdNext() {
     const nextFeature = getNextFeature(featureList);
 
     if (!nextFeature) {
-        console.log(`${GREEN}${BOLD}🎉 All ${total} features are passing! Marathon complete.${RESET}`);
+        if (passing === total) {
+            console.log(`${GREEN}${BOLD}🎉 All ${total} features are passing! Marathon complete.${RESET}`);
+        } else {
+            console.log(`${RED}${BOLD}⚠️ Deadlock detected: ${total - passing} features remain, but all are blocked by failing dependencies.${RESET}`);
+            console.log(`   ${DIM}Check 'status' and use 'mark <id> pass' to resolve dependencies.${RESET}`);
+        }
         return;
     }
 
@@ -400,6 +435,14 @@ function cmdNext() {
         console.log();
     }
 
+    if (nextFeature.failureReasons && nextFeature.failureReasons.length > 0) {
+        console.log(`  ${RED}${BOLD}Previous Failures (${nextFeature.attempts} attempts):${RESET}`);
+        for (const reason of nextFeature.failureReasons) {
+            console.log(`    ${DIM}* ${reason}${RESET}`);
+        }
+        console.log();
+    }
+
     console.log(`  ${DIM}When done: marathon_harness.js mark ${nextFeature.id} pass${RESET}`);
     console.log();
 }
@@ -408,8 +451,9 @@ function cmdNext() {
  * Mark a feature as passing or failing.
  * @param {number} id
  * @param {string} verdict - 'pass' or 'fail'
+ * @param {string} [reason] - Reason for failure
  */
-function cmdMark(id, verdict) {
+function cmdMark(id, verdict, reason) {
     if (!isActive()) {
         console.error(`${RED}❌ No active marathon.${RESET}`);
         process.exit(1);
@@ -437,6 +481,14 @@ function cmdMark(id, verdict) {
     feature.passes = newPasses;
     feature.sessionCompleted = newPasses ? new Date().toISOString() : null;
 
+    if (!newPasses) {
+        feature.attempts = (feature.attempts || 0) + 1;
+        if (reason) {
+            if (!feature.failureReasons) feature.failureReasons = [];
+            feature.failureReasons.push(`Attempt ${feature.attempts}: ${reason}`);
+        }
+    }
+
     writeJSON(FEATURE_LIST_FILE, featureList);
 
     const { total, passing } = countFeatures(featureList);
@@ -482,6 +534,30 @@ function cmdLog(message) {
     ok(`Logged: ${message}`);
 }
 
+/**
+ * Distill a lesson learned into memory context.
+ * @param {string} lesson
+ */
+function cmdDistill(lesson) {
+    if (!isActive()) {
+        console.error(`${RED}❌ No active marathon.${RESET}`);
+        process.exit(1);
+    }
+
+    if (!lesson) {
+        console.error(`${RED}❌ Lesson required. Usage: distill "Your architectural lesson"${RESET}`);
+        process.exit(1);
+    }
+
+    ensureDir();
+    const DISTILL_FILE = path.join(MARATHON_DIR, 'distilled_context.md');
+    const timestamp = new Date().toISOString().slice(0, 16);
+    const entry = `- [${timestamp}] ${lesson}\n`;
+
+    fs.appendFileSync(DISTILL_FILE, entry, 'utf8');
+    ok(`Distilled memory saved: ${lesson}`);
+}
+
 /**
  * Start a new session — reads state, shows bearings.
  */
@@ -567,7 +643,11 @@ function cmdSessionStart() {
             }
         }
     } else {
-        console.log(`  ${GREEN}${BOLD}🎉 All features passing! Nothing to implement.${RESET}`);
+        if (passing === total) {
+            console.log(`  ${GREEN}${BOLD}🎉 All features passing! Nothing to implement.${RESET}`);
+        } else {
+            console.log(`  ${RED}${BOLD}⚠️ Deadlock: ${total - passing} features are blocked by failing dependencies.${RESET}`);
+        }
     }
     console.log();
 
@@ -717,11 +797,12 @@ function showHelp() {
     cmd('status', 'Show progress dashboard');
     cmd('next', 'Show the next unfinished feature');
     cmd('mark <id> pass', 'Mark a feature as passing');
-    cmd('mark <id> fail', 'Mark a feature as failing');
+    cmd('mark <id> fail', 'Mark a feature as failing (optional: "reason")');
     cmd('log "note"', 'Add a timestamped progress note');
+    cmd('distill "rule"', 'Save an architectural rule or lesson to memory');
     cmd('session-start', 'Begin a new work session (reads state, shows bearings)');
     cmd('session-end', 'End session with optional summary');
-    cmd('add-feature', 'Add a feature: add-feature "category" "description" "step1" ...');
+    cmd('add-feature', 'Add a feature (supports --deps=1,2,3 for DAG dependencies)');
     cmd('reset', 'Archive current marathon and start fresh');
     console.log();
 }
@@ -759,11 +840,12 @@ function main() {
         case 'mark': {
             const id = parseInt(args[1], 10);
             const verdict = (args[2] || '').toLowerCase();
+            const reason = args.slice(3).join(' ').trim();
             if (isNaN(id)) {
-                console.error(`${RED}❌ Feature ID required. Usage: mark <id> pass|fail${RESET}`);
+                console.error(`${RED}❌ Feature ID required. Usage: mark <id> pass|fail "reason"${RESET}`);
                 process.exit(1);
             }
-            cmdMark(id, verdict);
+            cmdMark(id, verdict, reason);
             break;
         }
         case 'log': {
@@ -782,8 +864,23 @@ function main() {
         case 'add-feature': {
             const category = args[1] || '';
             const description = args[2] || '';
-            const steps = args.slice(3);
-            cmdAddFeature(category, description, steps);
+            let steps = args.slice(3);
+            let deps = [];
+            
+            steps = steps.filter(step => {
+                if (step.startsWith('--deps=')) {
+                    deps = step.replace('--deps=', '').split(',').map(Number).filter(n => !isNaN(n));
+                    return false;
+                }
+                return true;
+            });
+            
+            cmdAddFeature(category, description, steps, deps);
+            break;
+        }
+        case 'distill': {
+            const lesson = args.slice(1).join(' ').trim();
+            cmdDistill(lesson);
             break;
         }
         case 'reset':

package/.agent/scripts/prompt_compiler.js

@@ -8,30 +8,13 @@ if (!rawInput) {
   process.exit(1);
 }
 
-// 1. Strip conversational fluff (lowers token count)
-let cleanInput = rawInput
-  .replace(/hey,? /gi, '')
-  .replace(/can you /gi, '')
-  .replace(/could you /gi, '')
-  .replace(/please /gi, '')
-  .replace(/i want to /gi, '')
-  .replace(/i need you to /gi, '')
-  .replace(/for me/gi, '')
-  .replace(/would it be possible to /gi, '')
-  .trim();
+// 1. Keep original input, only optionally strip leading "please" for action matching
+const cleanInput = rawInput.trim();
 
 // 2. Extract Action (Intent mapping)
-const actionMatch = cleanInput.match(/^(build|create|fix|debug|refactor|update|write|design|audit)\b/i);
+const actionMatch = cleanInput.match(/^(?:(?:hey,?\s*|please\s+|can you\s+|could you\s+|would you\s+|i need you to\s+|i want to\s+)*)(build|create|fix|debug|refactor|update|write|design|audit)\b/i);
 const action = actionMatch ? actionMatch[1].toLowerCase() : 'execute';
 
-// Remove the action from the target string
-if (actionMatch) {
-  cleanInput = cleanInput.substring(actionMatch[0].length).trim();
-}
-
-// Strip leading articles
-cleanInput = cleanInput.replace(/^(a|an|some)\s+/i, '');
-
 // 3. Extract Technology Stack
 const techKeywords = [
   'react', 'tailwind', 'next.js', 'sql', 'postgres', 'express', 
@@ -41,16 +24,64 @@ const techKeywords = [
 
 const stack = [];
 techKeywords.forEach(tech => {
-  // Use word boundaries to prevent partial matches
   const regex = new RegExp(`\\b${tech.replace('.', '\\.')}\\b`, 'i');
   if (regex.test(cleanInput)) {
     stack.push(tech.toLowerCase());
   }
 });
 
-// 4. Output highly compressed YAML
+// 4. Intelligent Pre-Routing
+const routerMap = {
+  'react': ['react-specialist', 'frontend-design'],
+  'tailwind': ['tailwind-patterns'],
+  'next.js': ['nextjs-react-expert', 'react-specialist'],
+  'sql': ['sql-pro', 'database-design'],
+  'postgres': ['database-design'],
+  'express': ['nodejs-best-practices'],
+  'python': ['python-pro'],
+  'node': ['nodejs-best-practices'],
+  'vue': ['vue-expert'],
+  'svelte': ['frontend-design'],
+  'typescript': ['typescript-advanced'],
+  'js': ['clean-code'],
+  'css': ['tailwind-patterns'],
+  'html': ['frontend-design'],
+  'prisma': ['database-design'],
+  'drizzle': ['database-design']
+};
+
+const actionRouter = {
+  'build': ['architecture'],
+  'create': ['architecture'],
+  'fix': ['systematic-debugging'],
+  'debug': ['systematic-debugging'],
+  'refactor': ['clean-code'],
+  'update': ['clean-code'],
+  'write': ['clean-code'],
+  'design': ['frontend-design'],
+  'audit': ['vulnerability-scanner', 'lint-and-validate']
+};
+
+const recommendedSkills = new Set();
+
+if (actionRouter[action]) {
+  actionRouter[action].forEach(s => recommendedSkills.add(s));
+}
+
+stack.forEach(tech => {
+  if (routerMap[tech]) {
+    routerMap[tech].forEach(s => recommendedSkills.add(s));
+  }
+});
+
+const finalSkills = Array.from(recommendedSkills).slice(0, 3);
+
+// 5. Output highly compressed YAML
 console.log('---');
 console.log(`action: ${action}`);
-console.log(`target: ${cleanInput}`);
+console.log(`target: |`);
+const indentedTarget = cleanInput.split('\n').map(line => '  ' + line).join('\n');
+console.log(indentedTarget);
 console.log(`stack: [${stack.join(', ')}]`);
+console.log(`recommended_skills: [${finalSkills.join(', ')}]`);
 console.log('---');

package/.agent/skills/advanced-rag-pipelines/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: advanced-rag-pipelines
+description: Production-grade Retrieval-Augmented Generation (RAG) mastery. Semantic chunking, Hybrid Search (Dense + Sparse/BM25), Cross-Encoder Reranking, and architecture-agnostic vector database management.
+---
+
+# Advanced RAG Pipelines (Production AI Data)
+
+You are an expert in building production-grade Retrieval-Augmented Generation (RAG) data pipelines. You understand that naive RAG (fixed chunking + Cosine similarity) fails in production. You architect systems that retrieve context with high precision using hybrid search, reranking, and semantic strategies.
+
+## 1. Core Principles
+- **Garbage In, Garbage Out:** Vector embeddings are only as good as the chunking strategy. Never use arbitrary character counts for chunking code or complex documents.
+- **Hybrid Search is Mandatory:** Dense vectors (embeddings) are terrible at exact keyword matches (e.g., finding "ID-4912" or "v4.4.4"). Always combine Dense Search with Sparse Search (BM25) to catch both semantic intent and exact matches.
+- **Retrieve Many, Rerank to Few:** It is cheaper and more accurate to retrieve 50 candidate chunks from a Vector DB and use a Cross-Encoder to rerank them down to the top 5 for the LLM.
+
+## 2. Advanced Architectural Patterns
+
+### A. Semantic Chunking
+Instead of splitting text every 1000 characters, split by structural bounds:
+- **Code:** Split by Abstract Syntax Tree (AST) nodes (functions, classes).
+- **Markdown:** Split by Header levels (`##`).
+- **Prose:** Use LLM-assisted proposition extraction (extracting atomic facts from sentences).
+
+### B. Two-Stage Retrieval (Reranking)
+```text
+1. User Query -> Embed -> Vector DB (Pinecone/Milvus/Pgvector)
+2. Retrieve Top K = 50 (Fast, low precision)
+3. Pass (Query + 50 Chunks) to Cross-Encoder (e.g., Cohere Rerank, BGE-Reranker)
+4. Reranker outputs Top N = 5 (Slow, high precision)
+5. Pass Top 5 to LLM Context
+```
+
+### C. Query Transformation
+Never embed the user's raw query directly. Users write poor queries.
+- **HyDE (Hypothetical Document Embeddings):** Have the LLM write a fake answer to the query, then embed that fake answer to search the Vector DB.
+- **Query Routing:** Route "summarize" queries to a Graph database, and "how do I" queries to the Vector DB.
+
+## 3. LLM Traps & Pre-Flight Checks
+- **TRAP:** Sending 20 chunks to the LLM. This dilutes the context (Lost in the Middle phenomenon) and increases cost.
+- **FIX:** Always rerank and aggressively filter down to 3-5 highly relevant chunks before the generation step.
+- **TRAP:** Not attaching metadata to chunks.
+- **FIX:** Always attach `{ source_file, line_numbers, date, author }` to the vector payload. This allows the Vector DB to pre-filter before calculating cosine similarity.
+
+## Verification Protocol
+Before submitting code, ensure:
+1. Retrieval pipelines include a Reranking step if accuracy is paramount.
+2. BM25 / Sparse search is considered alongside standard dense embeddings.
+3. Chunks are injected into the final LLM prompt with explicit `<context>` XML boundaries to prevent prompt injection.

package/.agent/skills/browser-native-ai/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: browser-native-ai
+description: Browser-native AI mastery. Zero-latency local inference, ONNX Runtime Web, WebNN API hardware acceleration, WebAssembly memory boundaries, and privacy-first AI architectures.
+---
+
+# Browser-Native AI (Local SLMs)
+
+You are an expert at running AI models directly on the client's device, inside the web browser. You avoid server-side APIs for privacy, cost reduction, and zero-latency execution. Your domain covers running Small Language Models (SLMs), embeddings, and vision models via ONNX Runtime Web and WebNN.
+
+## 1. Core Principles
+- **Privacy by Default:** Data never leaves the browser. This is critical for HIPAA compliance, banking, and private notes apps.
+- **Zero-Latency:** Because the model runs in memory, token generation and text embeddings happen instantly.
+- **Hardware Acceleration First:** Always attempt to use WebGPU (`executionProviders: ['webgpu']`) or WebNN before falling back to WebAssembly (Wasm).
+
+## 2. ONNX Runtime Web Integration
+Use `@huggingface/transformers` (Transformers.js) or `onnxruntime-web` for execution.
+
+```typescript
+import { pipeline, env } from '@huggingface/transformers';
+
+// Use WebGPU backend for acceleration
+env.backends.onnx.wasm.numThreads = 1;
+env.allowLocalModels = false;
+
+// Instantiate an SLM or Embedding model
+const extractor = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', {
+  device: 'webgpu', // Fallback to 'wasm' if needed
+});
+
+// Run inference entirely offline
+const output = await extractor('Hello world', { pooling: 'mean', normalize: true });
+console.log(output.data); // Float32Array embedding
+```
+
+## 3. Memory & Asset Management
+- **Quantization:** Only load `q4` (4-bit quantized) models into the browser to prevent crashing mobile devices. A 7B parameter model is ~4GB quantized, which is too large. Target 0.5B to 1.5B parameter models (e.g., Llama-3.2-1B, Phi-3-mini).
+- **Caching:** Cache model weights using the Origin Private File System (OPFS) or Cache API so the user only downloads the 500MB payload once.
+- **Web Workers:** AI inference blocks the main thread in Wasm mode. **Always** run inference inside a Web Worker so the UI stays 60fps.
+
+## 4. LLM Traps & Pre-Flight Checks
+- **TRAP:** Running inference on the React main thread.
+- **FIX:** Move pipeline instantiation and execution to a `worker.js` and communicate via `postMessage`.
+- **TRAP:** Failing to handle model download progress.
+- **FIX:** Pass a `progress_callback` to the pipeline to show a loading bar (e.g., "Downloading weights 45%").
+- **TRAP:** Loading float16 or float32 models.
+- **FIX:** Only request ONNX models that are specifically quantized (`_q4f16`) for web.
+
+## Verification Protocol
+Before submitting code, ensure:
+1. `postMessage` architecture is used for non-blocking inference.
+2. WebGPU is requested as the primary execution provider.
+3. Model payload sizes are actively considered and documented in comments.

package/.agent/skills/generative-ui-expert/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: generative-ui-expert
+description: Generative UI mastery. Vercel AI SDK 3.0+, React Server Components (RSC) + LLMs, streaming UI elements, structured tool calling (Zod schemas), and managing client-side AI state via useChat/useObject.
+---
+
+# Generative UI Expert (Vercel AI SDK)
+
+You are the definitive expert in Generative UI using the Vercel AI SDK and React Server Components (RSC). Your goal is to move AI from spitting out "markdown walls of text" into rendering interactive, stateful, and dynamic UI components natively inside the chat or application stream.
+
+## 1. Core Principles
+- **No Markdown Slop:** Avoid dumping raw markdown when structured UI can be used. If the user asks for a weather report, stream a `<WeatherCard />`, not text.
+- **Server-Driven UI:** Leverage React Server Components (`ai/rsc`) to stream actual React components over the wire as the LLM yields function calls.
+- **Structured Data First:** Use strict Zod schemas (`useObject`, `streamObject`) whenever you need the LLM to output parsable data.
+- **Progressive Disclosure:** Use `streamUI` to yield intermediate loading states (e.g., `<SkeletonLoader />`) while waiting for external APIs.
+
+## 2. Vercel AI SDK Patterns
+
+### A. Streaming React Components (`ai/rsc`)
+When setting up `ai/rsc`, define explicit tool boundaries:
+```typescript
+import { createAI, getMutableAIState, streamUI } from "ai/rsc";
+import { z } from "zod";
+
+export const AI = createAI({
+  actions: {
+    submitMessage: async (message: string) => {
+      "use server";
+      return streamUI({
+        model: openai("gpt-4-turbo"),
+        system: "You are a helpful assistant.",
+        prompt: message,
+        tools: {
+          getWeather: {
+            description: "Get the weather for a location",
+            parameters: z.object({ city: z.string() }),
+            generate: async ({ city }) => {
+              yield <WeatherSkeleton city={city} />;
+              const temp = await fetchWeatherAPI(city);
+              return <WeatherCard city={city} temp={temp} />;
+            }
+          }
+        }
+      });
+    }
+  }
+});
+```
+
+### B. Structured Output (`streamObject`)
+Use this when you need strict JSON streams for charts, tables, or complex states.
+```typescript
+const result = await streamObject({
+  model: openai("gpt-4-turbo"),
+  schema: z.object({
+    points: z.array(z.object({ x: z.number(), y: z.number() }))
+  }),
+  prompt: "Generate a sales forecast chart data",
+});
+// Client consumes via useObject
+```
+
+## 3. Client-Side State Management
+- Use `useChat` for standard text+tool workflows.
+- Use `useUIState` and `useAIState` to manage the UI payload array and the underlying LLM message history separately.
+- Always include `id` and `role` in message schemas to prevent key-rendering bugs in React.
+
+## 4. LLM Traps & Pre-Flight Checks
+- **TRAP:** Sending client components directly over the wire from `generate:`.
+- **FIX:** Server actions can only return Server Components. If returning an interactive widget, wrap it in a client component but yield it from the server.
+- **TRAP:** Forgetting to yield intermediate states in slow tools.
+- **FIX:** Always `yield <Loading />` before awaiting slow API calls inside a tool's `generate` function.
+
+## Verification Protocol
+Before submitting code, ensure:
+1. `zod` is used for all tool parameters.
+2. Server Actions are properly annotated with `"use server"`.
+3. The model supports tool calling (e.g., `gpt-4o`, `claude-3-5-sonnet`).

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

@@ -0,0 +1,67 @@
+---
+name: webgpu-performance
+description: 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.
+---
+
+# WebGPU Performance Mastery
+
+You are an expert in writing low-level, high-performance browser graphics and compute pipelines using WebGPU and WGSL (WebGPU Shading Language). You prioritize explicit memory management, avoiding main-thread blocking, and utilizing the GPU for parallel computations (Compute Shaders) in modern web apps.
+
+## 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.