tribunal-kit 5.8.0 → 5.8.2

package/.agent/scripts/skill_evolution.js

@@ -487,50 +487,209 @@ async function callLlmApi(prompt, provider, apiKey) {
   return null;
 }
 
+// ── Commands ──────────────────────────────────────────────────────────────────
+// ── Strategy Filtering ────────────────────────────────────────────────────────
+function applyStrategyFilter(signals, strategy) {
+  if (strategy === "repair-only") {
+    return signals.filter((s) => s.type === "log_error");
+  }
+  return signals;
+}
+
+// ── Log Reflection Prompt ─────────────────────────────────────────────────────
+function generateLogReflectionPrompt(delta) {
+  return `You are analyzing runtime log signals (errors, tracebacks, and warnings) from an AI agent's execution.
+Your job is to identify systemic coding issues and extract evolution assets:
+1. **Idioms (Genes)**: Coding rules/conventions to prevent the AI from generating this mistake again.
+2. **Cases (Capsules)**: Rejection precedents (offending code pattern and why it failed) to block reviewers from approving it.
+
+Rules:
+- Return ONLY a YAML structure containing 'idioms:' and 'cases:'. No markdown boxes, no conversational prose.
+- Maximum 3 idioms and 3 cases.
+- If an asset category is not applicable, leave it empty (e.g., 'idioms: []').
+
+Log Signals:
+\`\`\`
+${delta.slice(0, 1800)}
+\`\`\`
+
+Output format (YAML only):
+idioms:
+  - pattern: "<code convention or rule to avoid this error>"
+    reason: "<why it is needed based on the error>"
+    domain: "<backend|frontend|database|security|performance|general>"
+cases:
+  - pattern: "<offending code snippet or error-triggering pattern>"
+    reason: "<specific runtime error / traceback reason>"
+    domain: "<backend|frontend|database|security|performance|general>"
+    verdict: "REJECTED"
+`;
+}
+
+// ── Combined YAML Parser ──────────────────────────────────────────────────────
+function parseEvolutionYaml(response) {
+  const idioms = [];
+  const cases = [];
+  let currentSection = null; // 'idioms' | 'cases'
+  let current = null;
+
+  const lines = response.split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === "idioms:") {
+      if (current) {
+        if (currentSection === "idioms") idioms.push(current);
+        if (currentSection === "cases") cases.push(current);
+      }
+      currentSection = "idioms";
+      current = null;
+      continue;
+    }
+    if (trimmed === "cases:") {
+      if (current) {
+        if (currentSection === "idioms") idioms.push(current);
+        if (currentSection === "cases") cases.push(current);
+      }
+      currentSection = "cases";
+      current = null;
+      continue;
+    }
+
+    if (trimmed.startsWith("- pattern:") || (trimmed.startsWith("- ") && trimmed.includes("pattern:"))) {
+      if (current) {
+        if (currentSection === "idioms") idioms.push(current);
+        if (currentSection === "cases") cases.push(current);
+      }
+      let pat = "";
+      if (trimmed.startsWith("- pattern:")) {
+        pat = trimmed.substring("- pattern:".length).trim();
+      } else {
+        pat = trimmed.split("pattern:", 2)[1].trim();
+      }
+      current = { pattern: pat.replace(/^['"]|['"]$/g, "") };
+    } else if (trimmed.startsWith("reason:") && current) {
+      current.reason = trimmed.substring("reason:".length).trim().replace(/^['"]|['"]$/g, "");
+    } else if (trimmed.startsWith("domain:") && current) {
+      current.domain = trimmed.substring("domain:".length).trim().replace(/^['"]|['"]$/g, "");
+    } else if (trimmed.startsWith("verdict:") && current) {
+      current.verdict = trimmed.substring("verdict:".length).trim().replace(/^['"]|['"]$/g, "");
+    }
+  }
+
+  if (current) {
+    if (currentSection === "idioms") idioms.push(current);
+    if (currentSection === "cases") cases.push(current);
+  }
+
+  return { idioms, cases };
+}
+
 // ── Commands ──────────────────────────────────────────────────────────────────
 async function cmdDigest(args) {
   const dryRun = args.includes("--dry-run");
   const diffMode = args.includes("--head") ? "head" : "staged";
 
+  const logArg = args.find((a) => a.startsWith("--log="));
+  const logFile = logArg ? logArg.split("=").slice(1).join("=") : null;
+
+  const strategyArg = args.find((a) => a.startsWith("--strategy="));
+  const strategy = strategyArg ? strategyArg.split("=").slice(1).join("=") : "balanced";
+
   console.log(
     `\n${BOLD}${CYAN}━━━ Skill Evolution — Digest Cycle ━━━━━━━━━━━━━━━━${RESET}`,
   );
   if (dryRun)
     console.log(`  ${YELLOW}DRY RUN — no files will be written${RESET}\n`);
 
-  console.log(`  ${DIM}[1/5] Fetching git diff (${diffMode})...${RESET}`);
-  const rawDiff = getGitDiff(diffMode);
-  if (!rawDiff.trim()) {
+  let rawDiff = "";
+  let delta = "";
+  let rawTokens = 0;
+  let deltaTokens = 0;
+  let logSignals = [];
+  const isLogMode = !!logFile;
+
+  if (isLogMode) {
+    console.log(`  ${DIM}[1/5] Reading log file: ${logFile}...${RESET}`);
+    if (!fs.existsSync(logFile)) {
+      console.log(`  ${RED}✖ Log file not found: ${logFile}${RESET}\n`);
+      return;
+    }
+    const logText = fs.readFileSync(logFile, "utf8");
+    rawTokens = countTokensEstimate(logText);
+
     console.log(
-      `  ${YELLOW}⚠ No diff found. Commit or stage changes first.${RESET}`,
+      `  ${DIM}[2/5] Extracting signals from log (Signal Detector)...${RESET}`,
     );
+    const { detectSignals } = require("./signal_detector");
+    const signals = detectSignals(logText);
+
+    if (signals.length === 0) {
+      console.log(
+        `  ${GREEN}✔ No errors or performance signals found in logs.${RESET}`,
+      );
+      console.log(`  ${DIM}  No self-evolution reflection needed.${RESET}\n`);
+      return;
+    }
+
+    logSignals = applyStrategyFilter(signals, strategy);
+    if (logSignals.length === 0) {
+      console.log(
+        `  ${YELLOW}⚠ Strategy filter [${strategy}] filtered out all signals.${RESET}\n`,
+      );
+      return;
+    }
+
     console.log(
-      `  ${DIM}Tip: Use --head to diff against the last commit.${RESET}\n`,
+      `  ${GREEN}✔ Filtered to ${logSignals.length} signal(s) using [${strategy}] strategy.${RESET}`,
     );
-    return;
-  }
 
-  const rawTokens = countTokensEstimate(rawDiff);
-  console.log(
-    `  ${DIM}   Raw diff: ~${rawTokens} tokens (${rawDiff.length} chars)${RESET}`,
-  );
+    delta = logSignals
+      .map((s) => {
+        let chunk = `--- SIGNAL: ${s.type} ---\n`;
+        if (s.file) chunk += `File: ${s.file}${s.line ? `:${s.line}` : ""}\n`;
+        chunk += `Message: ${s.message}\n`;
+        chunk += `Context:\n${s.context}\n`;
+        return chunk;
+      })
+      .join("\n\n");
+
+    deltaTokens = countTokensEstimate(delta);
+  } else {
+    console.log(`  ${DIM}[1/5] Fetching git diff (${diffMode})...${RESET}`);
+    rawDiff = getGitDiff(diffMode);
+    if (!rawDiff.trim()) {
+      console.log(
+        `  ${YELLOW}⚠ No diff found. Commit or stage changes first.${RESET}`,
+      );
+      console.log(
+        `  ${DIM}Tip: Use --head to diff against the last commit.${RESET}\n`,
+      );
+      return;
+    }
 
-  console.log(
-    `  ${DIM}[2/5] Extracting architectural delta (Semantic Filter)...${RESET}`,
-  );
-  const delta = semanticDelta(rawDiff, 2);
-  if (!delta.trim()) {
+    rawTokens = countTokensEstimate(rawDiff);
     console.log(
-      `  ${GREEN}✔ Delta is 100% trivial (whitespace/comments/imports only).${RESET}`,
+      `  ${DIM}   Raw diff: ~${rawTokens} tokens (${rawDiff.length} chars)${RESET}`,
     );
+
     console.log(
-      `  ${DIM}  No LLM call needed. Zero tokens consumed.${RESET}\n`,
+      `  ${DIM}[2/5] Extracting architectural delta (Semantic Filter)...${RESET}`,
     );
-    return;
+    delta = semanticDelta(rawDiff, 2);
+    if (!delta.trim()) {
+      console.log(
+        `  ${GREEN}✔ Delta is 100% trivial (whitespace/comments/imports only).${RESET}`,
+      );
+      console.log(
+        `  ${DIM}  No LLM call needed. Zero tokens consumed.${RESET}\n`,
+      );
+      return;
+    }
+
+    deltaTokens = countTokensEstimate(delta);
   }
 
-  const deltaTokens = countTokensEstimate(delta);
-  const savedTokens = rawTokens - deltaTokens;
+  const savedTokens = Math.max(0, rawTokens - deltaTokens);
   const savedPct = Math.floor((savedTokens / Math.max(rawTokens, 1)) * 100);
   console.log(
     `  ${GREEN}✔ Filtered to ~${deltaTokens} tokens  (${savedPct}% reduction, saved ~${savedTokens} tokens)${RESET}`,
@@ -546,7 +705,7 @@ async function cmdDigest(args) {
   }
   if (delta.split("\n").length > 20)
     console.log(
-      `    ${DIM}... (${delta.split("\n").length - 20} more lines)${RESET}`,
+      `    ... (${delta.split("\n").length - 20} more lines)`,
     );
 
   if (dryRun) {
@@ -559,8 +718,10 @@ async function cmdDigest(args) {
     return;
   }
 
-  // GENERATE: Auto-LLM call. Tries API first, falls back to manual paste if no key.
-  const reflectionPrompt = generateReflectionPrompt(delta);
+  // GENERATE: Auto-LLM call.
+  const reflectionPrompt = isLogMode
+    ? generateLogReflectionPrompt(delta)
+    : generateReflectionPrompt(delta);
   let llmResponse = "";
 
   let llmCreds = detectLlmProvider();
@@ -582,12 +743,12 @@ async function cmdDigest(args) {
       console.log(
         `  ${YELLOW}⚠ API call failed — falling back to manual mode${RESET}`,
       );
-      llmCreds = null; // triggers manual fallback below
+      llmCreds = null;
     }
   }
 
   if (!llmCreds || !llmResponse) {
-    // Manual fallback: copy-paste mode (no API key configured)
+    // Manual fallback: copy-paste mode
     console.log(
       `\n  ${DIM}[3/5] LLM Reflection — copy the prompt below and paste the response${RESET}`,
     );
@@ -619,21 +780,42 @@ async function cmdDigest(args) {
     llmResponse = responseLines.join("\n");
   }
 
-  console.log(`\n  ${DIM}[4/5] Parsing idioms...${RESET}`);
-  const newIdioms = parseLlmYamlResponse(llmResponse);
-  if (!newIdioms.length) {
-    console.log(`  ${YELLOW}⚠ No idioms extracted from LLM response.${RESET}`);
+  console.log(`\n  ${DIM}[4/5] Parsing idioms/cases...${RESET}`);
+  let newIdioms = [];
+  let newCases = [];
+
+  if (isLogMode) {
+    const parsed = parseEvolutionYaml(llmResponse);
+    newIdioms = parsed.idioms;
+    newCases = parsed.cases;
+  } else {
+    newIdioms = parseLlmYamlResponse(llmResponse);
+  }
+
+  if (!newIdioms.length && !newCases.length) {
     console.log(
-      `  ${DIM}  The LLM may have returned idioms: [] — no architectural pattern detected.${RESET}\n`,
+      `  ${YELLOW}⚠ No idioms or cases extracted from LLM response.${RESET}`,
     );
+    console.log(`\n`);
     return;
   }
 
-  console.log(`  ${GREEN}✔ Extracted ${newIdioms.length} idiom(s)${RESET}`);
-  for (const idiom of newIdioms) {
-    console.log(
-      `    ${CYAN}• ${idiom.pattern || "?"}${RESET}  — ${idiom.reason || ""}`,
-    );
+  if (newIdioms.length > 0) {
+    console.log(`  ${GREEN}✔ Extracted ${newIdioms.length} idiom(s)${RESET}`);
+    for (const idiom of newIdioms) {
+      console.log(
+        `    ${CYAN}• ${idiom.pattern || "?"}${RESET}  — ${idiom.reason || ""}`,
+      );
+    }
+  }
+
+  if (newCases.length > 0) {
+    console.log(`  ${GREEN}✔ Extracted ${newCases.length} case precedent(s)${RESET}`);
+    for (const c of newCases) {
+      console.log(
+        `    ${RED}• ${c.pattern || "?"}${RESET}  — ${c.reason || ""}`,
+      );
+    }
   }
 
   console.log(
@@ -647,10 +829,8 @@ async function cmdDigest(args) {
   let added = 0;
 
   for (const idiom of newIdioms) {
-    // FIX: Use Levenshtein normalised similarity (threshold 0.80) instead of
-    // substring .includes() which was over-aggressive and blocked valid idioms.
     if (isDuplicateIdiom(idiom.pattern || "", existing)) {
-      console.log(`  ${DIM}  Skipped near-duplicate: ${idiom.pattern}${RESET}`);
+      console.log(`  ${DIM}  Skipped near-duplicate idiom: ${idiom.pattern}${RESET}`);
       continue;
     }
     merged.push({
@@ -664,17 +844,86 @@ async function cmdDigest(args) {
     added++;
   }
 
-  if (added === 0) {
-    console.log(
-      `  ${YELLOW}⚠ All extracted idioms were duplicates. SKILL.md unchanged.${RESET}\n`,
-    );
-    return;
+  if (added > 0) {
+    log.total_idioms = merged.length;
+    const skillMd = renderSkillMd(merged, (log.cycles || []).length + 1);
+    fs.mkdirSync(SKILL_DIR, { recursive: true });
+    fs.writeFileSync(SKILL_FILE, skillMd, "utf8");
+    console.log(`  ${GREEN}✔ ${added} new idiom(s) added to SKILL.md${RESET}`);
+  } else {
+    console.log(`  ${DIM}  No new unique idioms added to SKILL.md.${RESET}`);
   }
 
-  log.total_idioms = merged.length;
-  const skillMd = renderSkillMd(merged, (log.cycles || []).length + 1);
-  fs.mkdirSync(SKILL_DIR, { recursive: true });
-  fs.writeFileSync(SKILL_FILE, skillMd, "utf8");
+  // Record Case Precedents if present
+  if (newCases && newCases.length > 0) {
+    console.log(`\n  ${DIM}Merging into Case Law precedents...${RESET}`);
+    const caseLawManager = require("./case_law_manager");
+    const clIndex = caseLawManager.loadIndex();
+    let clNextId = clIndex.next_id;
+    let clAdded = 0;
+
+    for (const c of newCases) {
+      const diffText = c.pattern || "";
+      const reason = c.reason || "";
+      const domain = c.domain || "general";
+      const verdict = c.verdict || "REJECTED";
+      const fingerprint = caseLawManager.contentHash(diffText);
+
+      let isDup = false;
+      for (const existing of clIndex.cases) {
+        if (existing.fingerprint === fingerprint) {
+          isDup = true;
+          break;
+        }
+      }
+      if (isDup) {
+        console.log(
+          `  ${DIM}  Skipped duplicate case: ${reason.slice(0, 50)}...${RESET}`,
+        );
+        continue;
+      }
+
+      const deltaCase = caseLawManager.semanticDelta(diffText);
+      const tags = caseLawManager.extractTags(diffText + " " + reason);
+      const caseRecord = {
+        id: clNextId,
+        fingerprint,
+        timestamp: new Date().toISOString().slice(0, 19),
+        domain,
+        verdict,
+        reason: reason.trim(),
+        pr_ref: "auto-evolution",
+        reviewer: "skill-evolution",
+        tags,
+        stack_version: null,
+        diff_raw: diffText.trim(),
+        diff_delta: deltaCase,
+        auto_recorded: true,
+      };
+
+      caseLawManager.saveCase(caseRecord);
+      clIndex.cases.push({
+        id: clNextId,
+        fingerprint,
+        domain,
+        verdict,
+        tags,
+        timestamp: caseRecord.timestamp,
+        reason_summary: reason.trim().slice(0, 120),
+        stack_version: null,
+      });
+      clNextId++;
+      clAdded++;
+    }
+
+    if (clAdded > 0) {
+      clIndex.next_id = clNextId;
+      caseLawManager.saveIndex(clIndex);
+      console.log(`  ${GREEN}✔ ${clAdded} new Case Law precedent(s) recorded.${RESET}`);
+    } else {
+      console.log(`  ${DIM}  No new unique Case Law precedents recorded.${RESET}`);
+    }
+  }
 
   log.cycles = log.cycles || [];
   log.cycles.push({
@@ -687,15 +936,11 @@ async function cmdDigest(args) {
   log.total_tokens_saved = (log.total_tokens_saved || 0) + savedTokens;
   saveLog(log);
 
-  console.log(`\n  ${GREEN}✔ ${added} new idiom(s) added to SKILL.md${RESET}`);
-  console.log(`  ${DIM}   File: ${SKILL_FILE}${RESET}`);
+  console.log(`\n  ${GREEN}✔ Learn cycle complete.${RESET}`);
   console.log(`  ${DIM}   Total idioms: ${merged.length}${RESET}`);
   console.log(
     `  ${DIM}   Lifetime tokens saved: ${log.total_tokens_saved}${RESET}\n`,
   );
-  console.log(
-    `  ${CYAN}Commit SKILL.md to share your Engineering Culture with the team.${RESET}\n`,
-  );
 }
 
 function cmdShow() {

package/.agent/skills/fabel-protocol/SKILL.md

@@ -32,6 +32,15 @@ CONFIDENCE CHECK:
     → Standard library (Node, Python, Rust) → Low risk. Proceed with confidence.
 ```
 
+### Epistemic Confidence Levels (L1-L5)
+
+Rate the certainty of your implementation decisions using this hierarchy:
+- **L1: Absolute Certainty (Verified Truth)**: Code is fully checked against active files in the workspace or verified in up-to-date documentation.
+- **L2: High Confidence (Standard API)**: Using standard library or stable, unchanged language features (e.g. standard Node `fs` methods, basic Python functions).
+- **L3: Moderate Confidence (Likely but Unverified)**: Custom utilities or package features that are likely correct but not actively verified. Must add `// VERIFY: [reason]` tags.
+- **L4: Low Confidence (Speculative)**: Unstable APIs, recently modified dependencies, or legacy components. Search or audit first.
+- **L5: Pure Speculation (Guessed / Blind)**: Complete guesswork. Strictly prohibited from code generation. Must stop and research or ask.
+
 ### Uncertainty Markers
 
 When uncertain, never silently guess. Use explicit markers:
@@ -193,7 +202,25 @@ ALWAYS:
 
 ---
 
-## 6. Anti-Hallucination Quick Reference
+## 6. Fabel-5 Cognitive Boundaries (Wellbeing, Evenhandedness, Memory)
+
+### User Wellbeing & Safety
+* **No Psychoanalysis / Diagnosis**: Reflect what is said without diagnosing or assigning psychological narratives (e.g. "you restrict because of trauma"). Suggest professional help without clinical labels.
+* **Self-Harm Interruptions**: Never suggest physical substitutes (holding ice, snapping rubber bands, drawing lines) or mimic self-harm. They reinforce the self-harm loop.
+* **No Over-reliance**: Do not thank the user for reaching out, encourage them to stay, or reiterate willingness to continue. Avoid conversational dependencies.
+* **Positive Paths**: Acknowledge distress without reflective listening that amplifies negative spirals. Keep paths to external help open.
+
+### Moral & Political Evenhandedness
+* **Nuance Over Brevity**: Reject requests for simple yes/no or one-word answers on contested political, ethical, or policy issues. Give a fair, balanced overview of existing positions.
+* **Opposing Perspectives**: Conclude arguments for positions by presenting opposing viewpoints or empirical disputes even if the user/AI agrees with the primary view.
+
+### Memory & Preference Boundaries
+* **Invisible Integration**: Integrate remembered user context silently without attribution or observation verbs ("I notice in your profile...", "Based on your memory...").
+* **Expertise Tuning**: Match language and technical depth to the user's stated background without lecturing.
+
+---
+
+## 7. Anti-Hallucination Quick Reference
 
 High-risk hallucination zones (verify before using):
 
@@ -211,6 +238,15 @@ When in doubt: **search the official docs**. Never trust training data for API s
 
 ---
 
+## ⚡ Hallucination Heatmap (High-Risk Zones)
+
+- **Next.js 15+ Route Handlers**: Dynamic functions (`headers()`, `cookies()`, `params`) are now async and must be awaited. Unawaited calls throw runtime errors.
+- **React 19 Hooks**: `useFormState` was renamed to `useActionState`. Direct context creation using `React.createServerContext()` was removed.
+- **Drizzle ORM Queries**: `db.select().from().filter()` does not exist; Drizzle uses `.where()` for filtering.
+- **OpenAI / Anthropic SDKs**: Model strings (e.g., trying to use `gpt-5` or `claude-4-opus` which do not exist or are incorrect).
+
+---
+
 ## LLM Traps — Self-Audit
 
 ```

package/.agent/workflows/generate.md

@@ -109,6 +109,7 @@ When unsure: write `// VERIFY: [specific reason]` instead of hallucinating.
 precedence-reviewer→ Enforces repository Case Law and past rejections (Runs First)
 logic-reviewer     → Hallucinated methods, undefined refs, impossible logic
 security-auditor   → OWASP vulnerabilities, hardcoded secrets, injection
+complexity-reviewer→ Enforces the Dependency Ladder to prevent over-engineering
 ```
 
 **Auto-activated by keywords:**

package/.agent/workflows/tribunal-full.md

@@ -1,9 +1,9 @@
 ---
-description: Run ALL 19 Tribunal reviewer agents simultaneously. Maximum hallucination coverage. Use before merging any AI-generated code, before production deployments, or when maximum confidence is required.
+description: Run ALL 20 Tribunal reviewer agents simultaneously. Maximum hallucination coverage. Use before merging any AI-generated code, before production deployments, or when maximum confidence is required.
 required-skills: all domain skills auto-loaded
 ---
 
-# /tribunal-full — Complete 19-Reviewer Audit
+# /tribunal-full — Complete 20-Reviewer Audit
 
 $ARGUMENTS
 
@@ -32,7 +32,7 @@ Read BEFORE full review:
 
 ---
 
-## 19 Reviewers — All Active Simultaneously
+## 20 Reviewers — All Active Simultaneously
 
 ```
 Tier 1: Always active (universal concerns)
@@ -44,6 +44,7 @@ Tier 1: Always active (universal concerns)
 Tier 2: Code quality
 ├── dependency-reviewer    → Fabricated packages, supply chain, version compatibility
 ├── type-safety-reviewer   → 'any' epidemic, Zod parse vs cast, unguarded access
+├── complexity-reviewer    → Enforces the Dependency Ladder to prevent over-engineering
 ├── schema-reviewer        → Missing input validation, loose schemas, raw req.body
 └── sql-reviewer           → Injection, N+1, missing indexes, unscoped mutations
 

package/CONTRIBUTING.md

@@ -0,0 +1,134 @@
+# Contributing to Tribunal Kit
+
+Thank you for your interest in contributing to Tribunal Kit! This guide will help you get started.
+
+## Quick Start
+
+```bash
+# Clone the repository
+git clone https://github.com/Harmitx7/tribunal-kit.git
+cd tribunal-kit
+
+# Install dependencies
+npm install
+
+# Run tests
+npm run test:unit
+
+# Run the CLI locally
+node bin/wrapper.js --help
+```
+
+## Development Setup
+
+### Prerequisites
+
+- **Node.js** >= 18.0.0 (LTS recommended)
+- **npm** >= 9
+- **Rust** (optional) — Only needed if modifying the Rust core engine in `crates/`
+
+### Project Structure
+
+```
+tribunal-kit/
+├── bin/                    # CLI entry points (JS monolith + MCP server)
+│   ├── wrapper.js          # Main entry: routes to Rust binary or JS fallback
+│   ├── tribunal-kit.js     # Legacy JS CLI (1,500+ lines)
+│   └── mcp-server.js       # MCP server over JSON-RPC 2.0 / stdio
+├── dist/                   # Modular CLI (lazy-loaded commands)
+│   ├── cli.js              # CLI core with command routing
+│   ├── commands/           # Individual command modules
+│   ├── utils/              # Logger, helpers, version checker, hasher
+│   └── index.d.ts          # TypeScript declarations
+├── crates/core/            # Rust core engine (Tokio-based)
+├── .agent/                 # The intelligence payload (agents, skills, workflows)
+│   ├── agents/             # 43 specialist agent definitions
+│   ├── skills/             # Reusable skill packs
+│   ├── workflows/          # 34 workflow definitions
+│   └── scripts/            # Automation scripts
+├── test/
+│   ├── unit/               # Unit tests (Jest)
+│   └── integration/        # Integration tests
+└── scripts/                # Build & release scripts
+```
+
+### Running Tests
+
+```bash
+# Unit tests with coverage
+npm run test:unit
+
+# All tests
+npm test
+
+# Run a specific test file
+npx jest test/unit/memory.test.js
+```
+
+### Building the Rust Core (Optional)
+
+```bash
+# Build in release mode
+cargo build --release
+
+# Run benchmarks comparing Rust vs JS
+npm run benchmark:rust
+```
+
+## How to Contribute
+
+### Reporting Bugs
+
+1. Check [existing issues](https://github.com/Harmitx7/tribunal-kit/issues) first
+2. Use the bug report template
+3. Include: Node.js version, OS, steps to reproduce, expected vs actual behavior
+
+### Suggesting Features
+
+1. Open a [GitHub Discussion](https://github.com/Harmitx7/tribunal-kit/discussions) first
+2. Describe the use case, not just the solution
+3. Be specific about which command or workflow this affects
+
+### Submitting Pull Requests
+
+1. **Fork** the repository and create a branch from `main`
+2. **Write tests** for any new functionality
+3. **Run the test suite** — all tests must pass: `npm run test:unit`
+4. **Follow existing code style** — the project uses ESLint
+5. **Write clear commit messages** following [Conventional Commits](https://www.conventionalcommits.org/):
+   ```
+   feat: add --json flag to status command
+   fix: handle symlinks in init --force
+   docs: update CLI reference for memory command
+   test: add coverage for marathon harness
+   ```
+6. **Open a PR** with a clear description of what changed and why
+
+### Contributing Agents or Skills
+
+Tribunal Kit's value comes from its agent and skill library. To contribute:
+
+1. **Agents** go in `.agent/agents/` as markdown files
+2. **Skills** go in `.agent/skills/<skill-name>/SKILL.md`
+3. Follow the existing format — check any existing agent/skill for the structure
+4. Include the YAML frontmatter (`name`, `description`)
+5. Add practical, non-obvious guidance — not generic advice
+
+### Code Style
+
+- **JavaScript**: CommonJS (`require`/`module.exports`), no transpilation needed
+- **Naming**: `camelCase` for functions/variables, `UPPER_SNAKE` for constants
+- **Error handling**: Always handle errors in async functions
+- **Comments**: Explain *why*, not *what*
+- **No new dependencies**: Zero production dependencies is a feature, not a limitation
+
+## Review Process
+
+1. All PRs are reviewed by a maintainer
+2. CI must pass (tests + lint)
+3. Changes to `.agent/` content are reviewed for accuracy and usefulness
+4. Breaking changes require a discussion before implementation
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).