tribunal-kit 4.4.4 → 4.4.5

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.

package/bin/wrapper.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * Tribunal-Kit Core Wrapper
+ * 
+ * This script routes commands to the ultra-fast Rust binary if available and supported.
+ * For legacy commands (or if the binary isn't available/compiled yet), it gracefully
+ * falls back to the original JavaScript implementation.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const os = require('os');
+
+// Commands that have been fully ported to Rust so far
+const RUST_COMMANDS = new Set(['init', 'validate', 'status']);
+
+// Determine the path to the compiled Rust binary
+// In a full production release, this checks optionalDependencies in node_modules
+// For development, it checks the local target/release folder
+function getBinaryPath() {
+    const isWindows = os.platform() === 'win32';
+    const ext = isWindows ? '.exe' : '';
+    
+    // First, check bin/ directory (postinstall downloaded binary)
+    const binPath = path.resolve(__dirname, `tribunal-core${ext}`);
+    if (fs.existsSync(binPath)) {
+        return binPath;
+    }
+
+    // Second, try to find the binary compiled from crates/core/Cargo.toml
+    const devPath = path.resolve(__dirname, '..', 'target', 'release', `tribunal-core${ext}`);
+    if (fs.existsSync(devPath)) {
+        return devPath;
+    }
+
+    // Third, try target/debug (if they ran `cargo build` instead of `--release`)
+    const debugPath = path.resolve(__dirname, '..', 'target', 'debug', `tribunal-core${ext}`);
+    if (fs.existsSync(debugPath)) {
+        return debugPath;
+    }
+
+    // Production resolution (from optionalDependencies) would go here
+    return null;
+}
+
+function runRustBinary(binPath, args) {
+    const result = spawnSync(binPath, args, {
+        stdio: 'inherit',
+        env: process.env
+    });
+
+    if (result.error) {
+        console.error(`\x1b[91m✖ Failed to execute Rust engine:\x1b[0m ${result.error.message}`);
+        process.exit(1);
+    }
+
+    process.exit(result.status || 0);
+}
+
+function runLegacyFallback() {
+    // Graceful fallback to the original JS implementation
+    // We do this by modifying process.argv so it appears normal to the legacy script
+    require('./tribunal-kit.js');
+}
+
+function main() {
+    // Skip 'node' and 'wrapper.js'
+    const args = process.argv.slice(2);
+    
+    // Extract the command (the first non-flag argument)
+    const command = args.find(a => !a.startsWith('-'));
+
+    if (command && RUST_COMMANDS.has(command)) {
+        const binPath = getBinaryPath();
+        
+        if (binPath) {
+            // For the init command, Rust needs to know where the .agent template folder is.
+            if (command === 'init') {
+                const sourceDir = path.resolve(__dirname, '..', '.agent');
+                args.push('--source-dir', sourceDir);
+            }
+
+            // Route to Rust engine
+            // console.log('\x1b[90m⚡ Executing via Rust Core Engine\x1b[0m');
+            runRustBinary(binPath, args);
+            return;
+        } else {
+            // Warn if Rust command was requested but binary is missing
+            console.warn('\x1b[93m⚠ Rust binary not found in target/. Falling back to JS engine.\x1b[0m');
+        }
+    }
+
+    // Fall back to JS logic for un-ported commands (e.g. `learn`, `case`, `marathon`)
+    runLegacyFallback();
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tribunal-kit",
-    "version": "4.4.4",
+    "version": "4.4.5",
     "description": "Anti-Hallucination AI Agent Kit — 40 specialist agents, 32 slash commands, 16 parallel Tribunal reviewers, Performance Swarm engine, Supreme Court case law pipeline, and long-running agent harness.",
     "keywords": [
         "ai",
@@ -42,8 +42,8 @@
     },
     "license": "MIT",
     "bin": {
-        "tribunal-kit": "bin/tribunal-kit.js",
-        "tk": "bin/tribunal-kit.js"
+        "tribunal-kit": "bin/wrapper.js",
+        "tk": "bin/wrapper.js"
     },
     "files": [
         "bin/",
@@ -65,6 +65,7 @@
         "changelog:preview": "node scripts/changelog.js --preview",
         "sync": "node scripts/sync-version.js",
         "validate-payload": "node scripts/validate-payload.js",
+        "postinstall": "node scripts/postinstall.js",
         "build": "echo 'No build step required for this project'"
     },
     "devDependencies": {

package/scripts/postinstall.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * postinstall.js — Binary Download Script
+ * 
+ * After `npm install`, this script downloads the pre-compiled Rust binary
+ * for the user's platform from the latest GitHub Release.
+ * 
+ * If the download fails (offline, unsupported platform, etc.), it's a soft failure.
+ * The wrapper.js will detect the missing binary and fall back to the JS engine.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const os = require('os');
+const crypto = require('crypto');
+
+const PKG = require(path.resolve(__dirname, '..', 'package.json'));
+const VERSION = PKG.version;
+
+const BINARY_DIR = path.resolve(__dirname, '..', 'bin');
+const REPO = 'Harmitx7/tribunal-kit';
+
+function getPlatformBinary() {
+    const platform = os.platform();
+    const arch = os.arch();
+
+    const map = {
+        'win32-x64':    'tribunal-core-win-x64.exe',
+        'win32-arm64':  'tribunal-core-win-arm64.exe',
+        'darwin-x64':   'tribunal-core-darwin-x64',
+        'darwin-arm64': 'tribunal-core-darwin-arm64',
+        'linux-x64':    'tribunal-core-linux-x64',
+        'linux-arm64':  'tribunal-core-linux-arm64',
+    };
+
+    const key = `${platform}-${arch}`;
+    return map[key] || null;
+}
+
+function getLocalBinaryPath() {
+    const isWindows = os.platform() === 'win32';
+    return path.join(BINARY_DIR, `tribunal-core${isWindows ? '.exe' : ''}`);
+}
+
+function download(url) {
+    return new Promise((resolve, reject) => {
+        const request = https.get(url, { headers: { 'User-Agent': `tribunal-kit/${VERSION}` } }, (res) => {
+            // Handle redirects (GitHub sends 302 to the actual download URL)
+            if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+                download(res.headers.location).then(resolve).catch(reject);
+                return;
+            }
+
+            if (res.statusCode !== 200) {
+                reject(new Error(`HTTP ${res.statusCode}`));
+                return;
+            }
+
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => resolve(Buffer.concat(chunks)));
+            res.on('error', reject);
+        });
+
+        request.on('error', reject);
+        request.setTimeout(30000, () => { request.destroy(); reject(new Error('Timeout')); });
+    });
+}
+
+async function main() {
+    const binaryName = getPlatformBinary();
+
+    if (!binaryName) {
+        console.log(`[tribunal-kit] No pre-built binary for ${os.platform()}-${os.arch()}. Using JS fallback.`);
+        return;
+    }
+
+    const localPath = getLocalBinaryPath();
+
+    // Skip if binary already exists (e.g. dev environment with cargo build)
+    if (fs.existsSync(localPath)) {
+        return;
+    }
+
+    const url = `https://github.com/${REPO}/releases/download/v${VERSION}/${binaryName}`;
+    const checksumsUrl = `https://github.com/${REPO}/releases/download/v${VERSION}/checksums.txt`;
+    
+    console.log(`[tribunal-kit] Downloading native binary for ${os.platform()}-${os.arch()}...`);
+
+    try {
+        // 1. Download checksums file
+        const checksumsData = await download(checksumsUrl);
+        const checksumsText = checksumsData.toString('utf-8');
+        
+        // 2. Extract expected hash
+        const hashMatch = checksumsText.split('\n').find(line => line.includes(binaryName));
+        if (!hashMatch) {
+            throw new Error(`Checksum for ${binaryName} not found in checksums.txt`);
+        }
+        const expectedHash = hashMatch.split(' ')[0].trim();
+
+        // 3. Download binary
+        const data = await download(url);
+
+        // 4. Verify checksum
+        const actualHash = crypto.createHash('sha256').update(data).digest('hex');
+        if (actualHash !== expectedHash) {
+            throw new Error(`Checksum mismatch! Expected ${expectedHash}, got ${actualHash}. Potential tamper detected.`);
+        }
+
+        // 5. Write to disk
+        fs.writeFileSync(localPath, data);
+
+        // Make executable on Unix
+        if (os.platform() !== 'win32') {
+            fs.chmodSync(localPath, 0o755);
+        }
+
+        console.log(`[tribunal-kit] Native binary installed and verified successfully.`);
+    } catch (e) {
+        // Soft failure — wrapper.js will use the JS engine
+        console.log(`[tribunal-kit] Binary download skipped (${e.message}). Using JS fallback.`);
+    }
+}
+
+main();