ESTD. 2026 // ARTICLE IV § 12 // ZERO-DEPENDENCY GOVERNANCE ENGINE

Tribunal Kit

The zero-dependency governance layer and neurosymbolic verification envelope for AI coding agents. Intercepts AI hallucinations, phantom packages, and architectural regressions locally before code reaches disk.

[ ⚡ Overview ]  •  [ 🚀 Quick Start ]  •  [ 💻 CLI Reference ]  •  [ 🛡 31 Reviewers ]  •  [ 🏗 Architecture ]  •  [ 🔒 Security ]  •  [ 🔌 MCP Server ]

📑 Structured Directory & Index

01 // Architecture & Core Invariants

What is Tribunal Kit?

AI coding assistants hallucinate. They invent packages that do not exist on public package registries ("slopsquatting"), invoke deprecated framework APIs, emit unparameterized SQL queries, invent non-existent database columns, and repeat identical blunders across development sessions.

Compilers and linters catch these errors only after the code is already written to disk—completely blind to multi-file semantic intent or agent task planning during generation.

Tribunal Kit acts as a neurosymbolic verification envelope. It intercepts AI agent outputs locally before disk writes, validates proposals against your repository's live AST and schema models, and evaluates them with a deterministic 31-reviewer swarm running across 3 partitioned waves.

Problem vs. Solution Matrix

Core Superpower Breakdown

Dual-Engine Pipeline Execution

Tribunal Kit employs a dual-engine execution architecture. Commands are first routed through the compiled native Rust binary (tribunal-core). If the binary is unavailable, uncompiled, or if the environment forces JavaScript (TRIBUNAL_FORCE_JS=1), execution seamlessly falls back to the modular JavaScript engine (src/cli.js).

flowchart TD
    User([User or AI Coding Agent]) --> Wrapper[bin/wrapper.js CLI Router]

    Wrapper --> EngineCheck{Native Rust Core<br/>Available & Supported?}
    EngineCheck -->|Yes: sub-10ms| RustCore["tribunal-core (crates/core)<br/>Tokio • Serde • OXC Parser"]
    EngineCheck -->|Fallback / Forced| JSEngine["src/cli.js (Node.js)<br/>Modular Lazy-Loaded Commands"]

    RustCore --> Router{Command Surface}
    JSEngine --> Router

    Router -->|Lifecycle| C1["init • sync • status • guardrail"]
    Router -->|Governance| C2["arch • validate • contract • impact-tier"]
    Router -->|Memory| C3["case • memory • rsi • learn"]
    Router -->|Agentic| C4["sdd • marathon • skill-intel • context"]

    C2 --> Swarm["31 Parallel Reviewers Swarm"]

    subgraph Waves [Stage-Partitioned Review Waves]
        W1["Wave 1: Core Integrity & Precedences"]
        W2["Wave 2: Security, Types & Code Quality"]
        W3["Wave 3: Domain, UI & Performance"]
        W1 --> W2 --> W3
    end

    Swarm --> Waves
    Waves --> VerdictCheck{Global Verdict}

    VerdictCheck -->|❌ Rejected| AutoCorrect["Inner-Loop Auto-Correct<br/>Structured Feedback Loop"]
    AutoCorrect -.-> User
    VerdictCheck -->|✅ Approved| ControlledWrite["ControlledWriteService<br/>Atomic Transaction & SHA-256 Commit"]
    ControlledWrite --> SafeDisk([Safe Verified Disk Write])

    style RustCore fill:#d97706,stroke:#fff,stroke-width:1px,color:#fff
    style JSEngine fill:#0e1117,stroke:#8a92a3,stroke-width:1px,color:#fff
    style Swarm fill:#060709,stroke:#ff3300,stroke-width:1.5px,color:#fff
    style ControlledWrite fill:#059669,stroke:#fff,stroke-width:1.5px,color:#fff

02 // Quick Start & Installation

Prerequisites

• Node.js: >= 18.0.0 (LTS recommended)
• Rust Toolchain: (Optional) Precompiled binaries for Linux (x64, arm64), macOS (Apple Silicon, Intel), and Windows (x64, arm64) are distributed via optional dependencies. Cargo is only required if compiling from source.

Hardened Installation (Zero-Lifecycle Scripts)

Tribunal Kit enforces a zero install-time lifecycle script policy (no preinstall, install, or postinstall scripts in package.json). For high-security environments, you can safely invoke or install Tribunal Kit with npm script execution explicitly disabled:

# Execute directly via npx with script execution disabled
npx -y --ignore-scripts tribunal-kit@9.3.0 init

# Or install globally with script isolation
npm install -g --ignore-scripts tribunal-kit@9.3.0

Step-by-Step Initialization

Step 01: Scaffold the Governance Payload

Run init from the root of your target application repository:

# Initialize .agent/ governance payload and IDE rule bridges
npx tribunal-kit init

[!NOTE] Self-Install Safeguard: Tribunal Kit prevents running init inside the tribunal-kit repository itself. Run init from external target project directories.

Step 02: Verify Repository Health Cockpit

Inspect active bridges, memory counters, and reviewer readiness:

npx tribunal-kit status

Step 03: Synchronize Editor Rule Bridges

Generate and update IDE bridge configuration files:

npx tribunal-kit sync

CLI Agent Adapters (tk-adapt / tk adapt)

For developers using terminal-based AI coding agents, install native bridges with a single command:

# Auto-detect all installed CLI agents and configure them
npx tk-adapt
# Or via main CLI
npx tribunal-kit adapt

# Or configure for a specific CLI agent
npx tk-adapt claude     # Claude Code CLI (.claude/CLAUDE.md + MCP)
npx tk-adapt aider      # Aider CLI (.aider.conf.yml + CONVENTIONS.md)
npx tk-adapt codex      # OpenAI Codex CLI (AGENTS.md)
npx tk-adapt gemini-cli # Google Gemini CLI (.gemini/rules/GEMINI.md)

Minimal Installation Mode (--minimal)

For resource-constrained setups or microservices, install the streamlined core payload (~21 core specialists, ~19 core skills):

npx tribunal-kit init --minimal

03 // Command Cockpit & CLI Surface

Both binary identifiers are registered: tribunal-kit and tk.

tk <command> [subcommand] [flags]

Complete Command Reference

Global Execution Flags

--path <dir>         Target a specific project directory (defaults to cwd)
--file <path>        Specify input file for validation, context, or guardrail scanning
--force              Force overwrite existing configuration files during initialization
--minimal            Install core agents & skills only (~21 specialists)
--dry-run            Preview actions without writing disk changes
--json               Emit machine-readable JSON output for CI pipelines
--quiet              Suppress all non-essential banners and output
--verbose            Show detailed debug logging and internal execution traces
--version, -v        Print installed package and native core version (9.3.0)

04 // The 31-Reviewer Verification Swarm

When code is checked via tk validate, /tribunal-full, or git pre-push hooks, Tribunal Kit invokes 31 specialized domain reviewers. To eliminate context window dilution, reviewers execute in three stage-partitioned waves.

3-Wave Execution Stage Partitioning

graph TD
    subgraph Wave1 ["Wave 1: Core Integrity & Precedences"]
        R01[precedence-reviewer]
        R02[logic-reviewer]
        R03[schema-reviewer]
        R04[resilience-reviewer]
    end

    subgraph Wave2 ["Wave 2: Security, Types & Code Quality"]
        R05[security-auditor]
        R06[dependency-reviewer]
        R07[type-safety-reviewer]
        R08[complexity-reviewer]
        R09[sql-reviewer]
    end

    subgraph Wave3 ["Wave 3: Domain, UI & Performance"]
        R10[frontend-reviewer]
        R11[performance-reviewer]
        R12[mobile-reviewer]
        R13[ai-code-reviewer]
        R14[test-coverage-reviewer]
        R15[accessibility-reviewer]
        R16[ui-ux-auditor]
        R17[review-animations]
        R18[vitals-reviewer]
        R19[db-latency-auditor]
        R20[throughput-optimizer]
        R21[memory-leak-auditor]
        R22[pipeline-checker]
        R23[cognitive-boundary]
        R24[auth-boundary-gate]
        R25[jwt-algorithm-guard]
        R26[sanitization-auditor]
        R27[secrets-leak-guard]
        R28[vbc-evidence-auditor]
    end

    Wave1 -->|Pass| Wave2
    Wave2 -->|Pass| Wave3
    Wave3 -->|Pass| FinalApproval([Approved for Human Gate])

    Wave1 -.->|Fail| Halt([Halt & Feedback Loop])
    Wave2 -.->|Fail| Halt
    Wave3 -.->|Fail| Halt

    style Wave1 fill:#0e1117,stroke:#ff3300,stroke-width:1px,color:#fff
    style Wave2 fill:#0e1117,stroke:#d97706,stroke-width:1px,color:#fff
    style Wave3 fill:#0e1117,stroke:#0284c7,stroke-width:1px,color:#fff
    style FinalApproval fill:#059669,stroke:#fff,stroke-width:1.5px,color:#fff
    style Halt fill:#b91c1c,stroke:#fff,stroke-width:1.5px,color:#fff

Domain Activation Matrix

Reviewers automatically adapt to the code under review. Unrelated reviewers auto-pass with N/A, maximizing pipeline throughput:

05 // Ecosystem, IDE Bridges & MCP Server

IDE Bridge Architecture

When tk init or tk sync runs, Tribunal Kit generates bridge files that hook directly into the system prompts of major AI coding environments:

Your Project Root
├── .cursorrules                         ← Cursor IDE bridge
├── .windsurfrules                       ← Windsurf IDE bridge
├── .claude/CLAUDE.md                    ← Claude Code directory bridge
├── CLAUDE.md                            ← Claude Code root bridge
├── AGENTS.md                            ← OpenAI Codex & multi-agent system bridge
├── .github/copilot-instructions.md      ← GitHub Copilot workspace instructions
└── .gemini/
    ├── settings.json                    ← Antigravity / Gemini tool & skill configuration
    └── GEMINI.md                        ← Master Gemini rules bridge

Model Context Protocol (MCP) Server

Tribunal Kit provides a production-grade MCP server (bin/mcp-server.js) communicating over JSON-RPC 2.0 stdio:

Client Configuration (mcp_config.json)

{
  "mcpServers": {
    "tribunal-kit": {
      "command": "node",
      "args": ["bin/mcp-server.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Key MCP Tools

• tribunal_request_write: Requests a controlled repository mutation, returning a preview diff and cryptographic authorization token.
• tribunal_commit_write: Atomically commits an approved write transaction to disk with SHA-256 rollback protection.
• search_case_law: Queries historical code rejections and legal precedents.
• recall_memory: Recalls budget-constrained memories ranked by relevance, recency, and priority.
• store_memory: Persists a validated memory entry across sessions (semantic, procedural, episodic, working).
• run_tribunal_audit: Executes workspace-wide anti-hallucination audits.

Environment Variables & Overrides

06 // Skills Corpus & Technical References

Tribunal Kit includes a curated, schema-validated corpus of 235 modular engineering skills located in .agent/skills/.

18-Section Governance Standard

All 235 skills adhere to a strict 18-section governance architecture designed to eliminate LLM ambiguity:

1. Frontmatter: Strict YAML metadata (name, description, version, domain, triggers).
2. Mental Sandbox: Epistemic confidence levels (L1–L5) and anti-hallucination guardrails.
3. Pre-Flight Checklist: Mandatory files and packages to inspect before generating code.
4. VBC Protocol: Non-negotiable Verification-Before-Completion test execution commands.
5. Tri-State Evidence Classification: All findings and claims must be explicitly tagged:
   • [OBSERVED]: Confirmed directly by terminal command output, AST query, or file inspection.
   • [INFERRED]: Reasoned logically from active code structures with stated assumptions.
   • [UNVERIFIED]: Speculative hypothesis requiring explicit verification before commitment.

Hybrid Domain Reference Specifications (Model C)

To prevent LLM context saturation, deep technical domain standards are partitioned into 23 compact, zero-hallucination reference specifications (<1,500 tokens each) under .agent/references/:

07 // Security Architecture & Trust Boundaries

1. Centralized Containment (src/security/boundary.js)

All file interactions are mediated through assertWithinRoot. This function enforces:

• Lexical Containment: Rejects any path resolving outside the project root via path.relative.
• Symlink Escape Protection: Resolves realpaths via fs.realpathSync.native to ensure symlinks cannot point to sensitive host directories (/etc, C:\Windows).
• Null-Byte Injection Neutralization: Rejects any string containing \0.

2. SSRF & Cloud Metadata Defense

The browser and web intelligence engine enforces strict outbound network policies via validateBrowserUrl:

• Cloud Metadata Protection: Unconditionally blocks access to link-local and cloud metadata IPs (169.254.169.254, fd00:ec2::254).
• Private Subnet Isolation: Blocks loopback (127.0.0.0/8, ::1), RFC 1918 private subnets (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), and Carrier-Grade NAT.
• Scheme & Port Restrictions: Permits only http: and https:. Rejects sensitive administrative ports (22, 25, 2375, 6379, 27017).

3. Supply-Chain Purity & Minimal Dependencies

• Minimal Production Dependencies: Exactly 1 vetted production runtime dependency (zod: "^4.6.7" for deterministic schema validation and boundary guarantees). Zero extraneous dependencies or deep dependency trees.
• Zero Install Lifecycle Scripts: package.json contains no preinstall, install, or postinstall scripts, preventing arbitrary code execution during installation.
• Verifiable SLSA Provenance: All releases are built via pinned GitHub Actions workflows and signed with Sigstore provenance (npm publish --provenance).
• Runtime Network Neutrality: The CLI operates 100% offline by default. It performs zero telemetry, zero analytics, and zero phone-home calls. The only network request is an optional npm version check during init, which is completely skippable via --skip-update-check or TK_SKIP_UPDATE_CHECK=1.

4. Permissions & Blast-Radius Transparency

Tribunal Kit maintains an evidence-backed capability inventory to ensure complete transparency regarding host interactions:

Complete line-by-line capability mappings are audited and maintained in docs/security/CAPABILITY_INVENTORY.md.

5. Containment Trust Boundaries

[!WARNING] Operational Boundary Clarification: Tribunal Kit is an application-level governance layer and neurosymbolic verification envelope. It is not an operating system container, virtual machine, or Linux seccomp sandbox. While it blocks unauthorized writes and validates code structure, it should be paired with standard container isolation (e.g. Docker, Dev Containers) when executing arbitrary untrusted code.

08 // Local Compilation & Test Suites

Development Setup

# Clone the repository
git clone https://github.com/Harmitx7/tribunal-kit.git
cd tribunal-kit

# Install devDependencies (Jest, TypeScript, ESLint, Prettier)
npm install

Test Commands & Validation Suites

# Run unit tests with Jest
npm run test:unit

# Run native Rust core test suite (89 tests)
npm run test:rust

# Validate .agent/ payload integrity and reference links
npm run validate-payload

# Run full test suite across JavaScript and Rust
npm run test:all

Rust Core Compilation & Benchmarking

# Compile tribunal-core in release mode (LTO + stripped)
cargo build --release --manifest-path crates/core/Cargo.toml

# Run performance benchmarks comparing Rust core vs JavaScript fallback
npm run benchmark:rust

09 // Repository Architecture

tribunal-kit/
├── bin/                             # Executable entry points
│   ├── wrapper.js                   # Primary CLI wrapper (Rust dispatch + JS fallback)
│   ├── adapter-install.js           # Universal CLI agent adapter installer (tk-adapt)
│   ├── mcp-server.js                # Model Context Protocol stdio server
│   └── tk-proxy.js                  # Interception proxy for coding agents
├── crates/core/                     # High-performance native Rust core
│   ├── Cargo.toml                   # Rust package manifest (Tokio, Clap, Serde, OXC)
│   └── src/
│       ├── main.rs                  # CLI parser, command routing & Serde schemas
│       ├── commands/                # 20 native command implementations
│       └── tui/                     # Native terminal UI formatting
├── src/                             # Modular JavaScript CLI runtime (lazy-loaded)
│   ├── cli.js                       # CLI argument router and command registry
│   ├── commands/                    # 35 individual command implementations
│   ├── security/                    # Centralized containment & SSRF boundary service
│   ├── execution/                   # Controlled write service & transaction engines
│   ├── browser/                     # Chrome DevTools Protocol & IDPI defense
│   ├── system1/                     # Optional local ONNX neural assessment provider
│   └── tui/                         # Progress bars, reviewer grid matrix, banner
├── .agent/                          # Intelligence & Governance Payload
│   ├── agents/                      # 60 specialist agents (31 reviewers)
│   ├── skills/                      # 235 schema-validated engineering skills
│   ├── references/                  # 23 zero-hallucination domain specifications
│   ├── workflows/                   # 51 audited slash-command workflows
│   ├── rules/                       # Master governance rules (GEMINI.md, kernel.md)
│   └── scripts/                     # 106 automated verification & audit scripts
├── docs/                            # Visual assets, architecture diagrams & documentation
├── test/                            # Comprehensive Jest test suites
│   ├── unit/                        # Unit tests for CLI, memory, security, and skills
│   └── integration/                 # End-to-end wrapper and execution tests
├── AGENTS.md                        # Master Codex / multi-agent governance rules
├── CLAUDE.md                        # Canonical Claude Code bridge rules
├── package.json                     # NPM package configuration (zero runtime deps)
└── Cargo.toml                       # Cargo workspace manifest

10 // Diagnostic & Troubleshooting Manual

11 // Community & Responsible Disclosure

Contributing Guidelines

We welcome community contributions, including new specialist agents, skills, and Rust core optimizations.

1. Fork & Branch: Create a feature branch from main.
2. Coding Standards: Follow existing code style. ESLint and Prettier are configured:

   npm run lint
   npm run typecheck
   

3. Run Validation: Ensure all tests and payload integrity checks pass:

   npm run test:all
   

4. Conventional Commits: Write structured commit messages (e.g. feat: add AST support for Vue SFC, fix: correct SSRF subnet boundary).
5. Review Guidelines: Consult CONTRIBUTING.md and SECURITY.md before submitting pull requests.

Security Vulnerability Reporting

If you discover a potential security vulnerability in Tribunal Kit, please do not open a public issue. Follow our Responsible Disclosure Policy and submit a private report via GitHub Security Advisories.

License

Tribunal Kit is open-source software licensed under the MIT License.