tribunal-kit 9.2.3 → 9.2.4

package/README.md

@@ -6,38 +6,28 @@
   </a>
 
   <h1 style="font-size: 1.35em; color: #ffffff; font-weight: 600; margin: 10px 0 8px 0;">
-    Tribunal Kit: AI Coding Agent Governance Layer
+    Tribunal Kit
   </h1>
   <p style="font-size: 1.0em; color: #88888b; font-weight: 400; letter-spacing: 0.5px; margin: 0 0 25px 0;">
-    Your AI writes code that doesn't exist. Tribunal Kit stops it. The zero-dependency AI governance layer for preventing hallucinations and ghost packages — 52 specialists, 28 reviewers, compiled Rust core.
+    The minimal-dependency governance layer for AI coding agents. Real-time hallucination prevention, parallel AST review, and cross-session memory via a compiled Rust core.
   </p>
 
   <!-- BADGES -->
   <div style="margin-bottom: 25px;">
-    <a href="https://www.npmjs.com/package/tribunal-kit">
-      <img src="https://img.shields.io/npm/v/tribunal-kit?style=for-the-badge&logo=npm&logoColor=white&color=ff1637" alt="NPM Version" />
-    </a>
-    <a href="https://github.com/Harmitx7/tribunal-kit">
-      <img src="https://img.shields.io/github/stars/Harmitx7/tribunal-kit?style=for-the-badge&logo=github&logoColor=white&color=111111&label=Stars" alt="GitHub Stars" />
+    <a href="https://github.com/Harmitx7/tribunal-kit/releases">
+      <img src="https://img.shields.io/badge/Release-v9.2.4-blue?style=for-the-badge" alt="Release" />
     </a>
     <a href="https://www.npmjs.com/package/tribunal-kit">
-      <img src="https://img.shields.io/npm/dw/tribunal-kit?style=for-the-badge&logo=npm&logoColor=white&color=1a1a1f&label=Downloads" alt="NPM Downloads" />
+      <img src="https://img.shields.io/npm/v/tribunal-kit?style=for-the-badge&logo=npm&logoColor=white&color=ff1637" alt="NPM Version" />
     </a>
     <a href="https://github.com/Harmitx7/tribunal-kit/actions/workflows/ci.yml">
       <img src="https://img.shields.io/github/actions/workflow/status/Harmitx7/tribunal-kit/ci.yml?style=for-the-badge&logo=githubactions&logoColor=white&label=CI" alt="CI Status" />
     </a>
-    <br>
     <a href="LICENSE">
       <img src="https://img.shields.io/badge/License-MIT-1a1a1f?style=for-the-badge&color=2d2d30" alt="License" />
     </a>
-    <a href="CHANGELOG.md">
-      <img src="https://img.shields.io/badge/Release-v9.2.3-ff3300?style=for-the-badge&color=111111&logo=github&logoColor=ff3300" alt="Release Version" />
-    </a>
     <a href="package.json">
-      <img src="https://img.shields.io/badge/Dependencies-0-ff3300?style=for-the-badge&color=111111&logoColor=ff3300" alt="Zero Dependencies" />
-    </a>
-    <a href="DESIGN.md">
-      <img src="https://img.shields.io/badge/Design_System-Classical_Neo--Brutalist-ff3300?style=for-the-badge&color=111111" alt="Design System" />
+      <img src="https://img.shields.io/badge/Dependencies-Minimal-ff3300?style=for-the-badge&color=111111&logoColor=ff3300" alt="Minimal Dependencies" />
     </a>
     <a href="crates/core">
       <img src="https://img.shields.io/badge/Core-Rust_10ms-DEA584?style=for-the-badge&logo=rust&logoColor=white" alt="Rust Core" />
@@ -45,9 +35,6 @@
     <a href="mcp_config.json">
       <img src="https://img.shields.io/badge/MCP-Ready-00c2ff?style=for-the-badge&logo=openai&logoColor=111" alt="MCP Server" />
     </a>
-    <a href="SECURITY.md">
-      <img src="https://img.shields.io/badge/Security-Strict_Sandbox-ff1637?style=for-the-badge" alt="Security Policy" />
-    </a>
   </div>
 
   <p>
@@ -58,485 +45,198 @@
 
 <br>
 
-<!-- THE PROBLEM -->
-<div style="background: linear-gradient(145deg, #180a0c, #11141c); border: 1px solid #4a1820; border-radius: 12px; padding: 24px; margin-bottom: 20px;">
-  <div style="display: flex; align-items: center; margin-bottom: 12px;">
-    <span style="background-color: #ff2200; color: white; padding: 4px 8px; border-radius: 4px; font-size: 0.75em; font-weight: 800; text-transform: uppercase; letter-spacing: 1.5px; margin-right: 10px;">The Problem</span>
-    <strong style="color: #ffffff; font-size: 1.15em;">AI coding agents hallucinate. Constantly.</strong>
-  </div>
-  <p style="color: #c9c9d1; font-size: 0.95em; line-height: 1.6; margin: 0;">
-    They import phantom packages that don't exist on npm. They invent deprecated framework hooks. They hallucinate database columns not in your schema. They bloat system prompts with static rules models ignore, and repeat the exact syntax bug you fixed 20 minutes ago.
-    <br><br>
-    <strong>No linter catches this. No typechecker catches this.</strong> Linters only run <em>after</em> code is written and cannot understand semantic intent. Until now, nothing governed your AI in real time.
-  </p>
-</div>
+## 🛡️ Value Proposition
 
-<!-- THE SOLUTION -->
-<div style="background: linear-gradient(145deg, #121622, #0c0f17); border: 1px solid #ff3300; border-radius: 12px; padding: 24px; margin-bottom: 35px;">
-  <div style="display: flex; align-items: center; margin-bottom: 12px;">
-    <span style="background-color: #ff3300; color: #ffffff; padding: 4px 8px; border-radius: 4px; font-size: 0.75em; font-weight: 800; text-transform: uppercase; letter-spacing: 1.5px; margin-right: 10px;">The Solution</span>
-    <h2 style="color: #ffffff; font-size: 1.15em; margin: 0; font-weight: bold; display: inline;">One command. Your AI stops hallucinating ghost packages.</h2>
-  </div>
-  <p style="color: #c9c9d1; font-size: 0.95em; line-height: 1.6; margin: 0;">
-    Tribunal Kit wraps your coding agents in an active <strong>neurosymbolic verification envelope</strong> — 52 specialist agents, 28 parallel reviewers, 185 skills, and a native compiled Rust core. It intercepts AI output in <strong>&lt; 10ms</strong>, validates it against your live repository AST, and blocks hallucinated code before it ever touches disk.
-  </p>
-</div>
+AI coding assistants frequently hallucinate dependencies, deprecated framework hooks, and incorrect database columns. Linters and typecheckers catch these errors only *after* the code is written, failing to understand semantic intent during generation.
 
-<!-- VISUAL DEMONSTRATION -->
-<div align="center" style="margin: 28px 0;">
-  <img src="docs/assets/realtime-difference.svg" alt="The Real-Time Difference: Without vs With Tribunal Kit" width="100%" style="max-width: 1100px; border-radius: 14px;" />
-</div>
+Tribunal Kit acts as a **neurosymbolic verification envelope**. It intercepts AI output locally in **&lt; 10ms**, validates it against your live repository AST, and prevents hallucinated code and phantom packages from ever touching your disk. 
 
 ---
 
-<!-- QUICKSTART -->
+## ⚡ Core Capabilities
 
-## ⚡ 30-Second Quickstart
+- **Parallel Review Pipeline:** 29 domain-specific reviewers analyze generated code simultaneously before the write operation.
+- **Compiled Rust Core:** Sub-10ms AST parsing, semantic graph extraction, and file synchronization using SHA-256 diffs.
+- **Phantom Package Guardrails:** Blocks "slopsquatting" and non-existent npm package imports during generation.
+- **Cross-Session Memory:** "Supreme Court Case Law" (`tk case`) records past AI mistakes so they are never repeated across sessions.
+- **Subagent-Driven Development (SDD):** Orchestrates multi-agent fan-out and synthesis, strictly isolating context windows to prevent token bloat.
+- **Minimal Dependencies:** The Node.js CLI runtime requires almost zero production dependencies, protecting your supply chain.
+- **Native MCP Server:** Exposes real-time repository AST and team contract rules to Model Context Protocol compatible clients.
 
-Install the governance layer in any repository with one command:
-
-```bash
-npx tribunal-kit init    # Scaffolds .agent/ and auto-detects Cursor, Windsurf, VS Code
-npx tribunal-kit sync    # Synchronizes active governance rules across all IDEs
-npx tribunal-kit status  # Verifies repository health and rule integrity
-```
-
-### 🔌 Universal CLI Agent Adapter (Claude Code, Aider, Cline)
+---
 
-Tribunal Kit includes native plugins and adapter hooks for terminal agents:
+## 🏗️ Architecture Overview
 
-```bash
-npx tribunal-kit tk-adapt           # Auto-detect and install for all active CLI agents
-npx tribunal-kit tk-adapt claude    # Install directly for Claude Code
-npx tribunal-kit tk-adapt aider     # Install directly for Aider
-npx tribunal-kit tk-adapt --global  # Install globally to ~/.tribunal-kit/
-```
+Tribunal Kit operates as a fast, intercepting middleware layer between the AI generation event and the local filesystem.
 
-### 🛡️ Pre-Push Supply Chain Protection
-
-Catch hallucinated imports and ghost packages before code ever reaches your remote:
+```mermaid
+graph LR
+    A[User Request] --> B[Context Broker]
+    B --> C[Compiled Rust Core<br/>AST / Graph extraction]
+    C --> D[29 Parallel Reviewers]
+    D -->|Violation| E[Inner-Loop Auto-Correct]
+    E -.-> B
+    D -->|Passed| F[Human Gate]
+    F --> G[Safe Commit to Disk]
 
-```bash
-npx tribunal-kit hook       # Installs automated Git pre-push governance hook
-npx tribunal-kit guardrail  # Manually scans changes for phantom packages & // VERIFY tags
+    style C fill:#ff3300,stroke:#fff,stroke-width:1px,color:#fff
+    style D fill:#111,stroke:#444,stroke-width:1px,color:#fff
 ```
 
-<br>
-<hr style="height: 1px; border: none; background: linear-gradient(to right, transparent, #33333f, transparent); margin: 40px 0;" />
-
-<!-- NATIVE PLUGINS ECOSYSTEM -->
-
-## 🔌 First-Class Native Plugins & Ecosystem Integrations
-
-Tribunal Kit ships with pre-configured native plugins and extensions across the AI engineering landscape:
-
-<div style="overflow-x: auto; margin-top: 20px; border-radius: 8px; border: 1px solid #222225;">
-  <table style="width: 100%; border-collapse: collapse; text-align: left; background-color: #111115;">
-    <thead>
-      <tr style="border-bottom: 2px solid #22222f; background-color: #16161d; color: #ffffff;">
-        <th style="padding: 12px 16px; font-weight: 600;">Environment / Agent</th>
-        <th style="padding: 12px 16px; font-weight: 600;">Integration Type</th>
-        <th style="padding: 12px 16px; font-weight: 600;">One-Line Activation</th>
-      </tr>
-    </thead>
-    <tbody>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px; font-weight: 600; color: #ffffff;">Anthropic Claude Code</td>
-        <td style="padding: 12px 16px; color: #ff4d1a; font-weight: 600;">Native Marketplace Plugin (<code>.claude-plugin/</code>)</td>
-        <td style="padding: 12px 16px;"><code>/plugin marketplace add Harmitx7/tribunal-kit</code> or <code>tk-adapt claude</code></td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px; font-weight: 600; color: #ffffff;">OpenCode.ai</td>
-        <td style="padding: 12px 16px; color: #ff4d1a; font-weight: 600;">Native Plugin Config (<code>.opencode/</code>)</td>
-        <td style="padding: 12px 16px;">Add <code>"plugin": ["tribunal-kit@latest"]</code> in <code>opencode.json</code></td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px; font-weight: 600; color: #ffffff;">Cursor IDE</td>
-        <td style="padding: 12px 16px; color: #ff4d1a; font-weight: 600;">Plugin &amp; Rule Bridge (<code>.cursor-plugin/</code>)</td>
-        <td style="padding: 12px 16px;"><code>npx tribunal-kit sync</code></td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px; font-weight: 600; color: #ffffff;">Cognition Devin</td>
-        <td style="padding: 12px 16px; color: #ff4d1a; font-weight: 600;">Devin Native Plugin (<code>.devin-plugin/</code>)</td>
-        <td style="padding: 12px 16px;">Auto-detected via <code>.devin-plugin/plugin.json</code></td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px; font-weight: 600; color: #ffffff;">Google Gemini CLI</td>
-        <td style="padding: 12px 16px; color: #ff4d1a; font-weight: 600;">Extension Manifest (<code>gemini-extension.json</code>)</td>
-        <td style="padding: 12px 16px;">Auto-registered via <code>gemini-extension.json</code></td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px; font-weight: 600; color: #ffffff;">Moonshot Kimi &amp; Hermes</td>
-        <td style="padding: 12px 16px; color: #ff4d1a; font-weight: 600;">Native Plugin Bundles (<code>.kimi-plugin</code>, <code>.hermes-plugin</code>)</td>
-        <td style="padding: 12px 16px;">Packaged out-of-the-box with manifest bindings</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px; font-weight: 600; color: #ffffff;">Aider CLI &amp; Codex</td>
-        <td style="padding: 12px 16px; color: #ff4d1a; font-weight: 600;">Conventions &amp; Agents Bridge</td>
-        <td style="padding: 12px 16px;"><code>npx tribunal-kit tk-adapt aider</code></td>
-      </tr>
-    </tbody>
-  </table>
-</div>
-
-<br>
-<hr style="height: 1px; border: none; background: linear-gradient(to right, transparent, #33333f, transparent); margin: 40px 0;" />
-
-<!-- WHAT YOU GET -->
-
-### 📦 What's Inside
+### Data Flow
 
-| Layer                        | Count | What It Does                                                                                   |
-| :--------------------------- | :---- | :--------------------------------------------------------------------------------------------- |
-| **Specialist Agents**        | 52    | Domain-specific reasoning (Frontend, Backend, Security, Database, Mobile, DevOps)              |
-| **Tribunal Reviewers**       | 28    | Parallel review pipeline that intercepts logic and security defects before disk write          |
-| **Reusable Skills**          | 184   | Deep knowledge packs (React 19, Next.js 15, Rust, Python, Vue, Animations, A11y)               |
-| **Slash Workflows**          | 41    | One-command operations (`/generate`, `/debug`, `/audit`, `/deploy`, `/refactor`)               |
-| **Native Plugins**           | 9+    | First-class plugins for Claude Code, Cursor, OpenCode, Devin, Kimi, Hermes, Pi, and Gemini CLI |
-| **Compiled Rust Core**       | 1     | Native binary for AOT Semantic Graph extraction, AST parsing, hashing, and deduping            |
-| **MCP Server**               | 1     | Model Context Protocol integration with `query_semantic_graph` capabilities                    |
-| **Supreme Court Precedents** | ∞     | Permanent repository memory that records AI mistakes so they are never repeated                |
-
-<br>
-<hr style="height: 1px; border: none; background: linear-gradient(to right, transparent, #33333f, transparent); margin: 40px 0;" />
-
-<!-- COMPARATIVE ANALYSIS -->
-
-## 📈 Comparative Analysis: Tribunal Kit vs. Alternatives
-
-AI engineering requires active verification, not passive prompt text:
-
-<div style="overflow-x: auto; margin-top: 20px; border-radius: 8px; border: 1px solid #222225;">
-  <table style="width: 100%; border-collapse: collapse; text-align: left; background-color: #111115;">
-    <thead>
-      <tr style="border-bottom: 2px solid #22222f; background-color: #16161d;">
-        <th style="padding: 14px 18px; color: #ffffff; font-weight: 600;">Dimension / Capability</th>
-        <th style="padding: 14px 18px; color: #ff4d1a; font-weight: 700;">Tribunal Kit 🛡️</th>
-        <th style="padding: 14px 18px; color: #a0a0a5; font-weight: 600;">Static <code>.cursorrules</code></th>
-        <th style="padding: 14px 18px; color: #a0a0a5; font-weight: 600;">AST Linters (ESLint)</th>
-        <th style="padding: 14px 18px; color: #a0a0a5; font-weight: 600;">Manual System Prompts</th>
-      </tr>
-    </thead>
-    <tbody>
-      <tr style="border-bottom: 1px solid #222228;">
-        <td style="padding: 14px 18px; font-weight: 600; color: #ffffff;">Hallucination Interception</td>
-        <td style="padding: 14px 18px; color: #ff4d1a; font-weight: 700; background-color: #1c100c;">Active check gates (<code>tk guardrail</code>)</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">None (passive text only)</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">None (misses semantic intent)</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">None (models drift)</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222228;">
-        <td style="padding: 14px 18px; font-weight: 600; color: #ffffff;">Context Window Overhead</td>
-        <td style="padding: 14px 18px; color: #ff4d1a; font-weight: 700; background-color: #1c100c;">Budget-gated recall &amp; MCP tools</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">Severe (bloats with entire files)</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">N/A (runs post-edit)</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">High (burns context budget)</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222228;">
-        <td style="padding: 14px 18px; font-weight: 600; color: #ffffff;">Cross-Session Memory</td>
-        <td style="padding: 14px 18px; color: #ff4d1a; font-weight: 700; background-color: #1c100c;">Supreme Court Case Law (<code>tk case</code>)</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">None (forgets every prompt)</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">None</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">None</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222228;">
-        <td style="padding: 14px 18px; font-weight: 600; color: #ffffff;">Self-Evolution</td>
-        <td style="padding: 14px 18px; color: #ff4d1a; font-weight: 700; background-color: #1c100c;">Git diff learning &amp; SkillOpt</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">Manual editing</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">Manual config edits</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">Manual prompt tuning</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222228;">
-        <td style="padding: 14px 18px; font-weight: 600; color: #ffffff;">IDE &amp; CLI Universal Support</td>
-        <td style="padding: 14px 18px; color: #ff4d1a; font-weight: 700; background-color: #1c100c;">Cursor, Windsurf, VSCode, Claude, Aider</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">Cursor/Windsurf only</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">Independent</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">Hand-copied</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222228;">
-        <td style="padding: 14px 18px; font-weight: 600; color: #ffffff;">Execution Performance</td>
-        <td style="padding: 14px 18px; color: #ff4d1a; font-weight: 700; background-color: #1c100c;">Compiled Rust Core (<code>tribunal-core</code>)</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">N/A (static)</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">Slow Node processes</td>
-        <td style="padding: 14px 18px; color: #c9c9d1;">Slow API calls</td>
-      </tr>
-    </tbody>
-  </table>
-</div>
-
-<br>
-<hr style="height: 1px; border: none; background: linear-gradient(to right, transparent, #33333f, transparent); margin: 40px 0;" />
+1. **Input:** An LLM agent generates a code change proposal (or triggers a workflow like `/generate`).
+2. **Processing:** The Rust Core extracts the current AST and validates the semantic bounds. The proposal is dispatched to parallel Reviewers (e.g., `logic-reviewer`, `security-auditor`).
+3. **Output:** If valid, it passes to the Human Gate or writes directly to disk. If invalid, the process is halted, and feedback is fed back into the agent's context loop.
 
-<!-- SECTION: 4 SUPERPOWERS -->
-
-## 🏛️ The 4 Core Superpowers
-
-<div align="center" style="margin: 25px 0 35px 0;">
-  <img src="docs/assets/superpowers-grid.svg" alt="The 4 Core Superpowers of Tribunal Kit" width="100%" style="max-width: 1200px; border-radius: 14px;" />
-</div>
+---
 
-### 1. ⚖️ Supreme Court Case Law & Memory (`tk case`)
+## 🚀 Installation & Quick Start
 
-**Your AI will never make the same mistake twice.** Whenever your coding assistant introduces an antipattern or bug, record it as a legal precedent:
+Install Tribunal Kit in your project directory. Node.js >= 18.0.0 is required.
 
 ```bash
-# Add an AI mistake precedent
-tk case add
-
-# Search case law database
-tk case search "postgres deadlock"
-```
-
-The `precedence-reviewer` actively checks this database during generation. If the agent attempts the same antipattern, Tribunal Kit rules it unconstitutional and blocks the write.
+# 1. Initialize Tribunal Kit in your repository
+npx tribunal-kit init
 
-### 2. 🛡️ Phantom Package & Schema Guardrails (`tk guardrail`)
+# 2. Sync rules with your local IDE (Cursor, Windsurf, VS Code)
+npx tribunal-kit sync
 
-AI models frequently hallucinate libraries that sound plausible but do not exist, exposing developers to **AI Package Hallucination Exploits (Slopsquatting)**:
-
-```bash
-# Scan workspace changes for unverified dependencies and // VERIFY tags
-npx tribunal-kit guardrail
+# 3. Verify repository health and active rules
+npx tribunal-kit status
 ```
 
-### 3. 🧬 SkillOpt: Autonomous Self-Evolution Engine
-
-Stop manually re-prompting. SkillOpt mutates, token-checks, and benchmarks instruction skills directly against real test harnesses:
-
+**Using a CLI Agent?**
+Install the native adapter for Claude Code or Aider:
 ```bash
-# Optimize a skill against a test harness
-tk optimize-skill --target ./skills/auth-security.md "npm run test:auth" --epochs 5 --candidates 3
+npx tribunal-kit tk-adapt claude
+# or
+npx tribunal-kit tk-adapt aider
 ```
 
-- **Proposal Generation**: The LLM suggests micro-patches for instruction files.
-- **Rust Deduplication**: Normalized Levenshtein similarity (default `0.85`) filters redundant proposals.
-- **Genetic Promotion**: Passing harness tests promote winning candidates as the new baseline.
+---
 
-### 4. ⚡ Compiled Rust Core (`tribunal-core`)
+## 💻 Usage Guide & CLI Reference
 
-Heavy computation is delegated to a native Rust binary:
+Tribunal Kit CLI operations are routed through the compiled Rust binary when supported, falling back to the JavaScript engine gracefully.
 
-- **Zero-Latency Hash Manifests**: File synchronization uses SHA-256 incremental hash diffs, speeding up CLI sync by **95%**.
-- **Semaphore-Bounded Parallelism**: Fully concurrent thread pools (64 in Rust, 32 in Node.js) eliminate resource starvation in massive monorepos.
+| Command | Arguments | Description |
+| :--- | :--- | :--- |
+| `init` | `[--force]` | Initializes the `.agent/` configuration payload. |
+| `sync` | — | Syncs rules with IDEs (.cursorrules, .windsurfrules). |
+| `status` | — | Evaluates workspace rules and checks for violations. |
+| `guardrail` | `[--file <path>]` | Scans changes for phantom packages and `// VERIFY` tags. |
+| `tk-adapt` | `[claude\|aider\|--global]` | Installs universal CLI agent adapters. |
+| `hook` | — | Installs the automated Git pre-push governance hook. |
+| `memory` | `store \| recall \| gc` | Manages persistent cross-session AI memory. |
+| `case` | `add \| search <q>` | Records or searches for AI mistake precedents. |
 
-<br>
-<hr style="height: 1px; border: none; background: linear-gradient(to right, transparent, #33333f, transparent); margin: 40px 0;" />
+*(For workflow execution, Tribunal Kit monitors for slash commands like `/orchestrate`, `/audit`, or `/deploy` inside your AI context).*
 
-<!-- PIPELINE MERMAID -->
-
-## ⚖️ The Tribunal Pipeline — Mitigating AI Code Hallucinations
+---
 
-Code generation is solved. **Code correctness is the frontier.**
+## ⚙️ Configuration Reference
 
-The Tribunal Pipeline intercepts raw agent generation and routes it through a parallel suite of **28 domain-specific reviewers** before presenting changes to the developer:
+Tribunal Kit is largely zero-config, driven by the `.agent/` directory, but exposes settings via `mcp_config.json` and `package.json`.
 
-<div align="center" style="margin: 25px 0 35px 0;">
-  <img src="docs/assets/tribunal-pipeline.svg" alt="The Tribunal Architecture Pipeline" width="100%" style="max-width: 1200px; border-radius: 14px;" />
-</div>
+**Example MCP Configuration (`mcp_config.json`)**
+```json
+{
+  "mcpServers": {
+    "tribunal-kit": {
+      "command": "node",
+      "args": [".agent/scripts/mcp_server.js"],
+      "env": { "NODE_ENV": "production" }
+    }
+  }
+}
+```
 
-<details>
-<summary><b>View Raw Pipeline Specification (Mermaid Graph)</b></summary>
-<br>
+---
 
-```mermaid
-graph LR
-    A[User Request] --> B[Context Broker]
-    B --> C[Compiled Rust Core]
-    C --> D[28 Parallel Reviewers]
-    D -->|Violation| E[Inner-Loop Auto-Correct]
-    E -.-> B
-    D -->|Passed| F[Human Gate]
-    F --> G[Safe Commit to Disk]
+## 📂 Project Structure
+
+```text
+tribunal-kit/
+├── .agent/              # Active AI governance rules and workflows
+│   ├── agents/          # Specialist agent definitions
+│   ├── scripts/         # Verification and build scripts
+│   ├── skills/          # Reusable AI knowledge packs
+│   └── workflows/       # Slash command executions (e.g., /orchestrate)
+├── bin/                 # CLI entry points (wrapper.js)
+├── crates/core/         # Compiled Rust semantic engine
+├── dist/                # JS Fallback CLI runtime
+├── docs/                # Project documentation and assets
+└── AGENTS.md            # Master Fabel protocol and rule registry
 ```
 
-</details>
+---
 
-### Reviewer Swarms Include:
+## 🔗 Integrations
 
-- **`logic-reviewer`** · Semantic soundness & impossible logic checks.
-- **`security-auditor`** · Payload boundaries, injection & OWASP scanning.
-- **`resilience-reviewer`** · Async error boundaries and retry logic.
-- **`ui-ux-auditor`** · Structural accessibility (WCAG 2.2 AA) & premium animations.
-- **`schema-reviewer`** · Type narrowing, Prisma/Drizzle integrity checks.
+| Environment / Tool | Integration Type | Status |
+| :--- | :--- | :--- |
+| **Cursor IDE** | Plugin & `.cursorrules` bridge | Supported |
+| **Anthropic Claude Code** | Native Marketplace Plugin (`.claude-plugin/`) | Supported |
+| **Windsurf** | Native `.windsurfrules` sync | Supported |
+| **Cognition Devin** | Native Plugin (`.devin-plugin/`) | Supported |
+| **Aider CLI** | Conventions Bridge (`tk-adapt`) | Supported |
+| **Google Gemini CLI** | Extension Manifest (`gemini-extension.json`) | Supported |
 
-<br>
-<hr style="height: 1px; border: none; background: linear-gradient(to right, transparent, #33333f, transparent); margin: 40px 0;" />
+---
+
+## 🔒 Security and Reliability
 
-<!-- SOVEREIGN CONTRACTS -->
+- **Strict Sandboxing:** Tribunal Kit executes entirely locally. It does not phone home, exfiltrate data, or execute arbitrary remote binaries.
+- **Zero Dependencies:** The production NPM distribution is meticulously engineered to have zero external dependencies, entirely neutralizing downstream supply-chain attacks.
+- **Memory Boundaries:** Context provided to agents is strictly bounded by the `context_broker`, preventing context overflow and reducing token hallucination vectors.
 
-## 📜 Sovereign Covenant Protocol — Behavioral Contract Testing (`tk contract`)
+---
 
-Declare repo invariants in declarative YAML rules stored in `.tribunal/contracts/`:
+## 🧪 Testing and Quality
 
-```yaml
-name: 'No console.log in production code'
-scope: 'src/**/*.ts, src/**/*.tsx'
-severity: block
-must_not:
-  - pattern: 'console.log'
-    message: 'Use structured logger instead of console.log'
-```
+Tribunal Kit employs rigorous continuous integration.
 
 ```bash
-# Scaffold starter contracts
-npx tribunal-kit contract init
-
-# Verify contract invariants against modified files
-npx tribunal-kit contract verify
+# Run payload validation and the Jest test suite
+npm run test:all
 
-# Replay failure trace snapshot
-npx tribunal-kit contract replay <trace_id>
+# Run the Rust core test suite
+npm run test:rust
 ```
 
-<br>
-<hr style="height: 1px; border: none; background: linear-gradient(to right, transparent, #33333f, transparent); margin: 40px 0;" />
-
-<!-- MCP SERVER -->
-
-## 🔌 Model Context Protocol (MCP) Server Integration
-
-Tribunal Kit hosts an out-of-the-box **MCP server** via stdio. Connect it to Cursor, VSCode, Windsurf, or Claude Desktop to allow coding agents to query tools dynamically.
+The validation pipeline enforces `validate-payload.js` checks to ensure every specialist agent, workflow, and skill definition conforms to the strict schema before compilation.
 
-### Config Snippet (`mcp_config.json` / Claude Desktop)
-
-```json
-{
-  "mcpServers": {
-    "tribunal-kit": {
-      "command": "npx",
-      "args": ["-y", "tribunal-kit", "mcp"]
-    }
-  }
-}
-```
+---
 
-### Exposed MCP Tools:
+## ⚡ Performance
 
-- `query_semantic_graph` — Queries active project AST and dependency edges.
-- `verify_contracts` — Verifies proposed code against team contract rules before writing to disk.
-- `get_tribunal_skill` — Dynamically injects skills without overloading system prompts.
+By offloading AST evaluation and file hashing to the `tribunal-core` Rust binary, Tribunal Kit achieves:
+- **Sub-10ms** execution overhead for the `guardrail` and `sync` commands.
+- Up to **95% faster** context validation compared to standard Node.js implementations traversing large monorepos.
 
-<br>
-<hr style="height: 1px; border: none; background: linear-gradient(to right, transparent, #33333f, transparent); margin: 40px 0;" />
-
-<!-- COMMAND REFERENCE -->
-
-## 💻 Complete CLI Command Reference
-
-Below is the structured list of all core commands available via `npx tribunal-kit <command>` (or `tk <command>`):
-
-<div style="overflow-x: auto; margin-top: 20px; border-radius: 8px; border: 1px solid #222225;">
-  <table style="width: 100%; border-collapse: collapse; text-align: left; background-color: #111115;">
-    <thead>
-      <tr style="border-bottom: 2px solid #22222f; background-color: #16161d; color: #ffffff;">
-        <th style="padding: 12px 16px; font-weight: 600;">Command</th>
-        <th style="padding: 12px 16px; font-weight: 600;">Action / Arguments</th>
-        <th style="padding: 12px 16px; font-weight: 600;">Description</th>
-      </tr>
-    </thead>
-    <tbody>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px;"><kbd style="background: #1c1c24; border: 1px solid #333; padding: 2px 6px; border-radius: 4px; color: #ffffff;">init</kbd></td>
-        <td style="padding: 12px 16px; color: #c9c9d1;"><code>[--force] [--path &lt;dir&gt;]</code></td>
-        <td style="padding: 12px 16px; color: #a0a0a5;">Initializes the <code>.agent/</code> configuration payload.</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px;"><kbd style="background: #1c1c24; border: 1px solid #333; padding: 2px 6px; border-radius: 4px; color: #ffffff;">sync</kbd></td>
-        <td style="padding: 12px 16px; color: #c9c9d1;">—</td>
-        <td style="padding: 12px 16px; color: #a0a0a5;">Syncs <code>.agent</code> rules with Cursor, Windsurf, and VSCode configs.</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px;"><kbd style="background: #1c1c24; border: 1px solid #333; padding: 2px 6px; border-radius: 4px; color: #ffffff;">status</kbd></td>
-        <td style="padding: 12px 16px; color: #c9c9d1;">—</td>
-        <td style="padding: 12px 16px; color: #a0a0a5;">Evaluates workspace rules and manifest counts for violations.</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px;"><kbd style="background: #1c1c24; border: 1px solid #333; padding: 2px 6px; border-radius: 4px; color: #ffffff;">guardrail</kbd></td>
-        <td style="padding: 12px 16px; color: #c9c9d1;"><code>[--file &lt;path&gt;]</code></td>
-        <td style="padding: 12px 16px; color: #a0a0a5;">Scans workspace changes for phantom packages and <code>// VERIFY</code> tags.</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px;"><kbd style="background: #1c1c24; border: 1px solid #333; padding: 2px 6px; border-radius: 4px; color: #ffffff;">tk-adapt</kbd></td>
-        <td style="padding: 12px 16px; color: #c9c9d1;"><code>[claude|aider|--global]</code></td>
-        <td style="padding: 12px 16px; color: #a0a0a5;">Universal CLI agent adapter installer for Claude Code & Aider.</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px;"><kbd style="background: #1c1c24; border: 1px solid #333; padding: 2px 6px; border-radius: 4px; color: #ffffff;">hook</kbd></td>
-        <td style="padding: 12px 16px; color: #c9c9d1;">—</td>
-        <td style="padding: 12px 16px; color: #a0a0a5;">Installs an automated Git pre-push governance check hook.</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px;"><kbd style="background: #1c1c24; border: 1px solid #333; padding: 2px 6px; border-radius: 4px; color: #ffffff;">optimize-skill</kbd></td>
-        <td style="padding: 12px 16px; color: #c9c9d1;"><code>--target &lt;file&gt; "&lt;cmd&gt;"</code></td>
-        <td style="padding: 12px 16px; color: #a0a0a5;">Launches a self-evolving prompt optimization sequence.</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px;"><kbd style="background: #1c1c24; border: 1px solid #333; padding: 2px 6px; border-radius: 4px; color: #ffffff;">align</kbd></td>
-        <td style="padding: 12px 16px; color: #c9c9d1;"><code>[--file &lt;path&gt;]</code></td>
-        <td style="padding: 12px 16px; color: #a0a0a5;">Align outputs, strip intro/conclusion slop, enforce framework bounds.</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px;"><kbd style="background: #1c1c24; border: 1px solid #333; padding: 2px 6px; border-radius: 4px; color: #ffffff;">learn</kbd></td>
-        <td style="padding: 12px 16px; color: #c9c9d1;"><code>[--dry-run]</code></td>
-        <td style="padding: 12px 16px; color: #a0a0a5;">Analyzes Git diff logs to automatically distill project idioms.</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px;"><kbd style="background: #1c1c24; border: 1px solid #333; padding: 2px 6px; border-radius: 4px; color: #ffffff;">case</kbd></td>
-        <td style="padding: 12px 16px; color: #c9c9d1;"><code>add | search &lt;q&gt; | export</code></td>
-        <td style="padding: 12px 16px; color: #a0a0a5;">Records, searches, or compiles AI mistake precedents.</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px;"><kbd style="background: #1c1c24; border: 1px solid #333; padding: 2px 6px; border-radius: 4px; color: #ffffff;">memory</kbd></td>
-        <td style="padding: 12px 16px; color: #c9c9d1;"><code>store | recall | gc</code></td>
-        <td style="padding: 12px 16px; color: #a0a0a5;">Manages 4-type persistent memory with budget-gated recall.</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px;"><kbd style="background: #1c1c24; border: 1px solid #333; padding: 2px 6px; border-radius: 4px; color: #ffffff;">marathon</kbd></td>
-        <td style="padding: 12px 16px; color: #c9c9d1;"><code>init | status | next</code></td>
-        <td style="padding: 12px 16px; color: #a0a0a5;">Sets up and executes long-running autonomous development.</td>
-      </tr>
-      <tr style="border-bottom: 1px solid #222225;">
-        <td style="padding: 12px 16px;"><kbd style="background: #1c1c24; border: 1px solid #333; padding: 2px 6px; border-radius: 4px; color: #ffffff;">contract</kbd></td>
-        <td style="padding: 12px 16px; color: #c9c9d1;"><code>init | verify | list | trace | replay</code></td>
-        <td style="padding: 12px 16px; color: #a0a0a5;">AI Agent Behavioral Contract Testing and failure context trace replay.</td>
-      </tr>
-    </tbody>
-  </table>
-</div>
+*(Benchmarks available via `npm run benchmark:rust` locally)*.
 
-<br>
-<hr style="height: 1px; border: none; background: linear-gradient(to right, transparent, #33333f, transparent); margin: 40px 0;" />
+---
 
-<!-- VIRAL BADGE SECTION -->
+## 🤝 Contributing
 
-## 🌐 Spread the Shield (Add to Your Repository)
+We welcome community-authored agents, skills, and Rust core optimizations.
 
-Help protect the open-source ecosystem from AI hallucinations. Embed this badge in your repository's `README.md`:
+1. Ensure Node.js 18+ and Rust/Cargo are installed.
+2. Build the Rust core: `npm run build:rust`
+3. Run tests: `npm run test:all`
+4. Review [CONTRIBUTING.md](CONTRIBUTING.md) and [DESIGN.md](DESIGN.md) before submitting pull requests.
 
-```markdown
-[![Protected by Tribunal Kit](https://img.shields.io/badge/Protected%20by-Tribunal%20Kit-ff3300?style=for-the-badge&logo=shield&logoColor=white)](https://github.com/Harmitx7/tribunal-kit)
-```
+---
 
-**Renders as:**  
-[![Protected by Tribunal Kit](https://img.shields.io/badge/Protected%20by-Tribunal%20Kit-ff3300?style=for-the-badge&logo=shield&logoColor=white)](https://github.com/Harmitx7/tribunal-kit)
+## 📄 License
 
-<div align="center" style="margin: 25px 0;">
-  <img src="docs/assets/shield-badge-banner.svg" alt="Protected by Tribunal Kit Supply Chain Seal" width="100%" style="max-width: 800px; border-radius: 12px;" />
-</div>
+This project is open-source and licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.
 
 <br>
-<hr style="height: 1px; border: none; background: linear-gradient(to right, transparent, #33333f, transparent); margin: 40px 0;" />
-
-<!-- FOOTER -->
-
-## 🤝 Contributing & Security
-
-- **Design System**: Built under the Classical Neo-Brutalist & Kinetic Governance specification. See [DESIGN.md](DESIGN.md).
-- **Security Policy**: Zero network runtime dependencies, zero dynamic `eval`, and sandboxed file paths. Review [SECURITY.md](SECURITY.md).
-- **Contributing Guide**: We welcome community-authored agents, skills, and Rust core optimizations. See [CONTRIBUTING.md](CONTRIBUTING.md).
-
-<div align="center" style="background: #0e1118; border: 1px solid #242938; border-radius: 8px; padding: 25px; margin-top: 50px;">
+<div align="center">
   <img src="https://img.shields.io/badge/Status-Active_&_Secured-ff3300?style=for-the-badge&logoColor=white" alt="Status" />
   <br><br>
-  <span style="font-style: italic; color: #f5f2eb; font-size: 0.95em;">"Never guess database schemas. Verify every async boundary. Welcome to the Tribunal."</span><br><br>
-  <sub style="color: #8a92a3;"><b>MIT Licensed</b> • Engineered for ultimate AI code governance • Classical Neo-Brutalist Edition.</sub>
+  <span style="font-style: italic; color: #8a92a3; font-size: 0.95em;">Engineered for ultimate AI code governance.</span>
 </div>