tribunal-kit 9.2.1 → 9.2.4

package/skills/transformers-js/references/TEXT_GENERATION.md

@@ -0,0 +1,315 @@
+# Text Generation Guide
+
+Guide to generating text with Transformers.js, including streaming and chat format.
+
+## Table of Contents
+
+1. [Basic Generation](#basic-generation)
+2. [Streaming](#streaming)
+3. [Chat Format](#chat-format)
+4. [Generation Parameters](#generation-parameters)
+5. [Model Selection](#model-selection)
+6. [Best Practices](#best-practices)
+
+## Basic Generation
+
+```javascript
+import { pipeline } from '@huggingface/transformers';
+
+const generator = await pipeline(
+  'text-generation',
+  'onnx-community/Qwen2.5-0.5B-Instruct',
+  { dtype: 'q4' }
+);
+
+const result = await generator('Once upon a time', {
+  max_new_tokens: 100,
+  temperature: 0.7,
+});
+
+console.log(result[0].generated_text);
+
+// Clean up when done
+await generator.dispose();
+```
+
+## Streaming
+
+Stream tokens as they're generated for better UX. Once you understand streaming, you can combine it with other features like chat format.
+
+### Node.js
+
+```javascript
+import { pipeline, TextStreamer } from '@huggingface/transformers';
+
+const generator = await pipeline(
+  'text-generation',
+  'onnx-community/Qwen2.5-0.5B-Instruct',
+  { dtype: 'q4' }
+);
+
+const streamer = new TextStreamer(generator.tokenizer, {
+  skip_prompt: true,
+  skip_special_tokens: true,
+  callback_function: (token) => {
+    process.stdout.write(token);
+  },
+});
+
+await generator('Tell me a story', {
+  max_new_tokens: 200,
+  temperature: 0.7,
+  streamer,
+});
+```
+
+### Browser
+
+```html
+<!DOCTYPE html>
+<html>
+<body>
+  <textarea id="prompt" placeholder="Enter prompt..."></textarea>
+  <button onclick="generate()">Generate</button>
+  <div id="output"></div>
+
+  <script type="module">
+    import { pipeline, TextStreamer } from 'https://cdn.jsdelivr.net/npm/@huggingface/transformers@4';
+    
+    const generator = await pipeline(
+      'text-generation',
+      'onnx-community/Qwen2.5-0.5B-Instruct',
+      { dtype: 'q4' }
+    );
+    
+    window.generate = async function() {
+      const prompt = document.getElementById('prompt').value;
+      const outputDiv = document.getElementById('output');
+      outputDiv.textContent = '';
+      
+      const streamer = new TextStreamer(generator.tokenizer, {
+        skip_prompt: true,
+        skip_special_tokens: true,
+        callback_function: (token) => {
+          outputDiv.textContent += token;
+        },
+      });
+      
+      await generator(prompt, {
+        max_new_tokens: 200,
+        temperature: 0.7,
+        streamer,
+      });
+    };
+  </script>
+</body>
+</html>
+```
+
+### React
+
+```jsx
+import { useState, useRef, useEffect } from 'react';
+import { pipeline, TextStreamer } from '@huggingface/transformers';
+
+function StreamingGenerator() {
+  const generatorRef = useRef(null);
+  const [output, setOutput] = useState('');
+  const [loading, setLoading] = useState(false);
+
+  const handleGenerate = async (prompt) => {
+    if (!prompt) return;
+    
+    setLoading(true);
+    setOutput('');
+    
+    // Load model on first generate
+    if (!generatorRef.current) {
+      generatorRef.current = await pipeline(
+        'text-generation',
+        'onnx-community/Qwen2.5-0.5B-Instruct',
+        { dtype: 'q4' }
+      );
+    }
+    
+    const streamer = new TextStreamer(generatorRef.current.tokenizer, {
+      skip_prompt: true,
+      skip_special_tokens: true,
+      callback_function: (token) => {
+        setOutput((prev) => prev + token);
+      },
+    });
+
+    await generatorRef.current(prompt, {
+      max_new_tokens: 200,
+      temperature: 0.7,
+      streamer,
+    });
+    
+    setLoading(false);
+  };
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (generatorRef.current) {
+        generatorRef.current.dispose();
+      }
+    };
+  }, []);
+
+  return (
+    <div>
+      <button onClick={() => handleGenerate('Tell me a story')} disabled={loading}>
+        {loading ? 'Generating...' : 'Generate'}
+      </button>
+      <div>{output}</div>
+    </div>
+  );
+}
+```
+
+## Chat Format
+
+Use structured messages for conversations. Works with both basic generation and streaming (just add `streamer` parameter).
+
+### Single Turn
+
+```javascript
+import { pipeline } from '@huggingface/transformers';
+
+const generator = await pipeline(
+  'text-generation',
+  'onnx-community/Qwen2.5-0.5B-Instruct',
+  { dtype: 'q4' }
+);
+
+const messages = [
+  { role: 'system', content: 'You are a helpful assistant.' },
+  { role: 'user', content: 'How do I create an async function?' }
+];
+
+const result = await generator(messages, {
+  max_new_tokens: 256,
+  temperature: 0.7,
+});
+
+console.log(result[0].generated_text);
+```
+
+### Multi-turn Conversation
+
+```javascript
+const conversation = [
+  { role: 'system', content: 'You are a helpful assistant.' },
+  { role: 'user', content: 'What is JavaScript?' },
+  { role: 'assistant', content: 'JavaScript is a programming language...' },
+  { role: 'user', content: 'Can you show an example?' }
+];
+
+const result = await generator(conversation, {
+  max_new_tokens: 200,
+  temperature: 0.7,
+});
+
+// To add streaming, just pass a streamer:
+// streamer: new TextStreamer(generator.tokenizer, {...})
+```
+
+## Generation Parameters
+
+### Common Parameters
+
+```javascript
+await generator(prompt, {
+  // Token limits
+  max_new_tokens: 512,        // Maximum tokens to generate
+  min_new_tokens: 0,          // Minimum tokens to generate
+  
+  // Sampling
+  temperature: 0.7,           // Randomness (0.0-2.0)
+  top_k: 50,                  // Consider top K tokens
+  top_p: 0.95,                // Nucleus sampling
+  do_sample: true,            // Use random sampling (false = always pick most likely token)
+  
+  // Repetition control
+  repetition_penalty: 1.0,    // Penalty for repeating (1.0 = no penalty)
+  no_repeat_ngram_size: 0,    // Prevent repeating n-grams
+  
+  // Streaming
+  streamer: streamer,         // TextStreamer instance
+});
+```
+
+### Parameter Effects
+
+**Temperature:**
+- Low (0.1-0.5): More focused and deterministic
+- Medium (0.6-0.9): Balanced creativity and coherence
+- High (1.0-2.0): More creative and random
+
+```javascript
+// Focused output
+await generator(prompt, { temperature: 0.3, max_new_tokens: 100 });
+
+// Creative output
+await generator(prompt, { temperature: 1.2, max_new_tokens: 100 });
+```
+
+**Sampling Methods:**
+
+```javascript
+// Greedy (deterministic)
+await generator(prompt, { 
+  do_sample: false,
+  max_new_tokens: 100 
+});
+
+// Top-k sampling
+await generator(prompt, { 
+  top_k: 50,
+  temperature: 0.7,
+  max_new_tokens: 100 
+});
+
+// Top-p (nucleus) sampling
+await generator(prompt, { 
+  top_p: 0.95,
+  temperature: 0.7,
+  max_new_tokens: 100 
+});
+```
+
+## Model Selection
+
+Browse available text generation models on Hugging Face Hub:
+
+**https://huggingface.co/models?pipeline_tag=text-generation&library=transformers.js&sort=trending**
+
+### Selection Tips
+
+- **Small models (< 1B params)**: Fast, browser-friendly, use `dtype: 'q4'`
+- **Medium models (1-3B params)**: Balanced quality/speed, use `dtype: 'q4'` or `fp16`
+- **Large models (> 3B params)**: High quality, slower, best for Node.js with `dtype: 'fp16'`
+
+Check model cards for:
+- Parameter count and model size
+- Supported languages
+- Benchmark scores
+- License restrictions
+
+## Best Practices
+
+1. **Model Size**: Use quantized models (`q4`) for browsers, larger models (`fp16`) for servers
+2. **Streaming**: Use streaming for better UX - shows progress and feels responsive
+3. **Token Limits**: Set `max_new_tokens` to prevent runaway generation
+4. **Temperature**: Tune based on use case (creative: 0.8-1.2, factual: 0.3-0.7)
+5. **Memory**: Always call `dispose()` when done
+6. **Caching**: Load model once, reuse for multiple requests
+
+## Related Documentation
+
+- [Pipeline Options](./PIPELINE_OPTIONS.md) - Configure pipeline loading
+- [Configuration Reference](./CONFIGURATION.md) - Environment settings
+- [Code Examples](./EXAMPLES.md) - More examples for different runtimes
+- [Main Skill Guide](../SKILL.md) - Getting started guide

package/skills/transitions-dev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: transitions-dev
-description: Use when Production-ready CSS transition patterns for web apps with drop-in snippets for cards, modals, dropdowns, panels, and accordions.
+description: "Use when Production-ready CSS transition patterns for web apps with drop-in snippets for cards, modals, dropdowns, panels, and accordions."
 version: 5.0.0
 last-updated: 2026-09-13
 skills:
@@ -15,35 +15,6 @@ scripts-binding:
 
 # Transitions Dev — Production CSS Transition Snippets
 
-## Mandatory Pre-Flight Context Inspection
-
-Before generating, refactoring, or reviewing code in the `transitions-dev` 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 Production-ready CSS transition patterns for web apps with drop-in snippets for cards, modals, dropdowns, panels, and accordions.
-- **DO NOT activate when:** The task falls outside the `transitions-dev` 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
@@ -117,49 +88,3 @@ Animate element height smoothly without hardcoding fixed pixel heights:
     width 200ms ease;
 }
 ```
-
----
-
-## 🚨 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                                            |
-| :----------------------- | :-------------------------------------------------------------------- | :------------------------------------------------------------------ |
-| **The Instant Pop Trap** | Conditionally unmounting elements without animated interpolation      | Use AnimatePresence or coordinate morphs with continuous geometry   |
-| **Layout Thrashing**     | Animating width, height, top, or left inside animation loops          | Animate composite-only transform (translate3d, scale) and opacity   |
-| **Sluggish Duration**    | Setting micro-interaction transitions to 600ms+ causing interface lag | Cap interactive feedback at 160ms–240ms with snappy ease-out curves |
-
----
-
-## 🏛️ Tribunal Verification & Guardrails
-
-**Active Reviewers:** `frontend-reviewer` · `motion-reviewer` · `ui-ux-auditor`
-**Slash Command:** `/review` or `/tribunal-full`
-
-### ✅ Pre-Flight Self-Audit Checklist
-
-```
-✅ Does animation maintain 60fps/120fps using transform and opacity?
-✅ Is optical mass conserved across state interpolations without volume collapse?
-✅ Is duration capped within micro-interaction budgets (160ms–280ms)?
-✅ Is prefers-reduced-motion respected with graceful instant fallbacks?
-✅ Did I prevent layout thrashing and continuous geometry mutations?
-```
-
-### 🛑 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/skills/trend-researcher/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: trend-researcher
-description: Use when Creative muse and design trend analyzer for modern web/mobile interfaces.
+description: "Use when Creative muse and design trend analyzer for modern web/mobile interfaces."
 version: 5.0.0
 last-updated: 2026-09-13
 skills:
@@ -15,35 +15,6 @@ scripts-binding:
 
 # Trend Researcher Skill
 
-## Mandatory Pre-Flight Context Inspection
-
-Before generating, refactoring, or reviewing code in the `trend-researcher` 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 Creative muse and design trend analyzer for modern web/mobile interfaces.
-- **DO NOT activate when:** The task falls outside the `trend-researcher` 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
@@ -225,49 +196,3 @@ Next action: [concrete next step for the user]
 Pre-Flight:  ✅ All checks passed
              or ❌ [blocking item that must be resolved first]
 ```
-
----
-
-## 🚨 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.

package/skills/tribunal-instincts-memory/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: tribunal-instincts-memory
+description: "Use when extracting lessons from session logs, resolving repeated failures, creating persistent context, and validating AI memory constraints."
+version: 1.0.0
+last-updated: 2026-09-25
+skills:
+  - fabel-protocol
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/memory_archivist.js
+---
+
+# Tribunal Instincts (Continuous Memory)
+
+## Overview
+Tribunal Instincts allows the agent harness to learn from its past mistakes and successful resolutions without blowing up the context window. It extracts concrete lessons from the Event Log and injects them selectively into future sessions.
+
+## Memory Lifecycle
+1. **Candidate Extraction**: The `memory-archivist` scans the durable JSONL session log for anomalies, repeated errors, or successful recoveries.
+2. **Evidence Validation**: A memory CANNOT be created without a specific Event ID or stack trace proving it happened. Subjective complaints are dropped.
+3. **Storage**: Approved lessons are saved to `instincts.json` under specific scopes (e.g., `database`, `ui`).
+4. **Context Injection**: During workflow initialization, `context_broker.js` reads only the instincts relevant to the current task.
+
+## Rules of Instinct Retrieval
+- **Token Budget**: Never inject more than 5 instincts at a time.
+- **Conflict Resolution**: If a newer instinct contradicts an older one, the older one is archived.
+- **System Rule Supremacy**: Instincts can NEVER override hardcoded system rules (e.g., `GEMINI.md`). They serve only as technical implementation hints.
+
+## Hallucination Traps
+- ❌ Trusting a memory that says "Always use library X" without checking `package.json`.
+- ❌ Creating an instinct for a typo. (Only systemic or architectural lessons deserve permanent memory).