tribunal-kit 6.0.1 → 8.0.0

package/.agent/scripts/test_runner.js

@@ -9,11 +9,11 @@
  *   node .agent/scripts/test_runner.js . --file src/utils.test.ts
  */
 
-"use strict";
+'use strict';
 
-const fs = require("fs");
-const path = require("path");
-const { spawnSync } = require("child_process");
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
 
 const {
   RED,
@@ -29,22 +29,22 @@ const {
   ok,
   fail,
   skip,
-} = require("./_colors");
+} = require('./_colors');
 
-const { loadJson } = require("./_utils");
+const { loadJson } = require('./_utils');
 
 function runTests(label, cmd, cwd) {
   const elapsed = timer();
   try {
     const executable =
-      process.platform === "win32" && (cmd[0] === "npx" || cmd[0] === "npm")
+      process.platform === 'win32' && (cmd[0] === 'npx' || cmd[0] === 'npm')
         ? `${cmd[0]}.cmd`
         : cmd[0];
     const result = spawnSync(executable, cmd.slice(1), {
       cwd,
-      encoding: "utf8",
+      encoding: 'utf8',
       timeout: 300000, // 5m
-      shell: process.platform === "win32",
+      shell: process.platform === 'win32',
     });
 
     const ms = elapsed();
@@ -52,11 +52,11 @@ function runTests(label, cmd, cwd) {
     if (result.error && !result.stdout && !result.stderr) {
       console.log(`    Error: ${result.error.message}`);
     }
-    const out = result.stdout ? result.stdout.toString() : "";
-    const err = result.stderr ? result.stderr.toString() : "";
-    const output = (out + "\n" + err).trim();
+    const out = result.stdout ? result.stdout.toString() : '';
+    const err = result.stderr ? result.stderr.toString() : '';
+    const output = (out + '\n' + err).trim();
     if (output) {
-      for (const line of output.split("\n")) {
+      for (const line of output.split('\n')) {
         console.log(`    ${line}`);
       }
     }
@@ -75,7 +75,7 @@ function runTests(label, cmd, cwd) {
 }
 
 function detectTestFramework(projectRoot) {
-  const pkg = loadJson(path.join(projectRoot, "package.json"));
+  const pkg = loadJson(path.join(projectRoot, 'package.json'));
   if (pkg) {
     const deps = {
       ...(pkg.dependencies || {}),
@@ -83,18 +83,18 @@ function detectTestFramework(projectRoot) {
     };
     const scripts = pkg.scripts || {};
 
-    if (deps.vitest) return "vitest";
-    if (deps.jest) return "jest";
-    if (deps.mocha) return "mocha";
-    if (scripts.test) return "npm-test";
+    if (deps.vitest) return 'vitest';
+    if (deps.jest) return 'jest';
+    if (deps.mocha) return 'mocha';
+    if (scripts.test) return 'npm-test';
   }
 
   if (
-    fs.existsSync(path.join(projectRoot, "pytest.ini")) ||
-    fs.existsSync(path.join(projectRoot, "pyproject.toml")) ||
-    fs.existsSync(path.join(projectRoot, "conftest.py"))
+    fs.existsSync(path.join(projectRoot, 'pytest.ini')) ||
+    fs.existsSync(path.join(projectRoot, 'pyproject.toml')) ||
+    fs.existsSync(path.join(projectRoot, 'conftest.py'))
   ) {
-    return "pytest";
+    return 'pytest';
   }
 
   // Go
@@ -106,16 +106,16 @@ function detectTestFramework(projectRoot) {
       return false;
     }
     for (const item of items) {
-      if (item.isDirectory() && !["node_modules", ".git"].includes(item.name)) {
+      if (item.isDirectory() && !['node_modules', '.git'].includes(item.name)) {
         if (hasGoTests(path.join(dir, item.name))) return true;
-      } else if (item.name.endsWith("_test.go")) {
+      } else if (item.name.endsWith('_test.go')) {
         return true;
       }
     }
     return false;
   }
 
-  if (hasGoTests(projectRoot)) return "go";
+  if (hasGoTests(projectRoot)) return 'go';
 
   return null;
 }
@@ -129,17 +129,15 @@ function main() {
 
   let i = 0;
   while (i < args.length) {
-    if (args[i] === "--coverage") coverageFlag = true;
-    else if (args[i] === "--watch") watchFlag = true;
-    else if (args[i] === "--file" && i + 1 < args.length) fileArg = args[++i];
-    else if (!targetPath && !args[i].startsWith("-")) targetPath = args[i];
+    if (args[i] === '--coverage') coverageFlag = true;
+    else if (args[i] === '--watch') watchFlag = true;
+    else if (args[i] === '--file' && i + 1 < args.length) fileArg = args[++i];
+    else if (!targetPath && !args[i].startsWith('-')) targetPath = args[i];
     i++;
   }
 
   if (!targetPath) {
-    console.log(
-      "Usage: node test_runner.js <path> [--coverage] [--watch] [--file <filepath>]",
-    );
+    console.log('Usage: node test_runner.js <path> [--coverage] [--watch] [--file <filepath>]');
     process.exit(1);
   }
 
@@ -151,14 +149,14 @@ function main() {
 
   const framework = detectTestFramework(projectRoot);
   console.log(
-    banner("test_runner.js", {
+    banner('test_runner.js', {
       Project: projectRoot,
-      Framework: framework || "none detected",
+      Framework: framework || 'none detected',
     }),
   );
 
   if (!framework) {
-    skip("No test framework detected in this project");
+    skip('No test framework detected in this project');
     process.exit(0);
   }
 
@@ -167,34 +165,34 @@ function main() {
   let cmd = [];
   let passed = true;
 
-  if (["vitest", "jest", "mocha", "npm-test"].includes(framework)) {
-    if (framework === "vitest") {
-      cmd = ["npx", "vitest", "run"];
-      if (coverageFlag) cmd.push("--coverage");
-      if (watchFlag) cmd = ["npx", "vitest"];
+  if (['vitest', 'jest', 'mocha', 'npm-test'].includes(framework)) {
+    if (framework === 'vitest') {
+      cmd = ['npx', 'vitest', 'run'];
+      if (coverageFlag) cmd.push('--coverage');
+      if (watchFlag) cmd = ['npx', 'vitest'];
       if (fileArg) cmd.push(fileArg);
-    } else if (framework === "jest") {
-      cmd = ["npx", "jest"];
-      if (coverageFlag) cmd.push("--coverage");
-      if (watchFlag) cmd.push("--watch");
+    } else if (framework === 'jest') {
+      cmd = ['npx', 'jest'];
+      if (coverageFlag) cmd.push('--coverage');
+      if (watchFlag) cmd.push('--watch');
       if (fileArg) cmd.push(fileArg);
     } else {
-      cmd = ["npm", "test", "--", "--passWithNoTests"];
-      if (coverageFlag) cmd.push("--coverage");
+      cmd = ['npm', 'test', '--', '--passWithNoTests'];
+      if (coverageFlag) cmd.push('--coverage');
       if (fileArg) cmd.push(fileArg);
     }
     passed = runTests(framework, cmd, projectRoot);
-  } else if (framework === "pytest") {
-    cmd = ["python", "-m", "pytest", "-v"];
-    if (coverageFlag) cmd.push("--cov", "--cov-report=term-missing");
-    if (watchFlag) cmd = ["python", "-m", "pytest-watch", "--", "-v"];
+  } else if (framework === 'pytest') {
+    cmd = ['python', '-m', 'pytest', '-v'];
+    if (coverageFlag) cmd.push('--cov', '--cov-report=term-missing');
+    if (watchFlag) cmd = ['python', '-m', 'pytest-watch', '--', '-v'];
     if (fileArg) cmd.push(fileArg);
-    passed = runTests("pytest", cmd, projectRoot);
-  } else if (framework === "go") {
-    cmd = ["go", "test", "./...", "-v"];
-    if (coverageFlag) cmd.push("-cover");
-    if (fileArg) cmd = ["go", "test", "-v", "-run", fileArg];
-    passed = runTests("go test", cmd, projectRoot);
+    passed = runTests('pytest', cmd, projectRoot);
+  } else if (framework === 'go') {
+    cmd = ['go', 'test', './...', '-v'];
+    if (coverageFlag) cmd.push('-cover');
+    if (fileArg) cmd = ['go', 'test', '-v', '-run', fileArg];
+    passed = runTests('go test', cmd, projectRoot);
   }
 
   console.log(`\n${BOLD}${CYAN}━━━ Test Summary ━━━${RESET}`);

package/.agent/scripts/token_budget_broker.js

@@ -11,42 +11,155 @@
  *   - Tier 3: Full budget (up to model context limit)
  */
 
-"use strict";
+'use strict';
 
-const { parseArgs } = require("./_utils");
+const { parseArgs } = require('./_utils');
 
 const TIER_TOKEN_LIMITS = {
   0: 0,
   1: 2000,
   2: 8000,
-  3: 32000
+  3: 32000,
+};
+
+// Model context limits (tokens)
+const MODEL_CONTEXT_LIMITS = {
+  'claude-opus-5': 200000,
+  'claude-sonnet-5': 200000,
+  'claude-haiku-4-5': 200000,
+  'gpt-4o': 128000,
+  'gpt-4o-mini': 128000,
+  'gemini-2.5-pro': 1000000,
+  'gemini-2.5-flash': 1000000,
 };
 
 /**
- * Returns context budget constraints for a given impact tier
+ * Returns context budget constraints for a given impact tier with dynamic adjustments
  * @param {number} tier - Governance Impact Tier (0-3)
- * @returns {Object} { maxTokens, includeFullRepo, maxSkills, maxReviewers }
+ * @param {string} modelName - Model name for context limit calculation
+ * @param {number} conversationHistoryTokens - Tokens already used in conversation history
+ * @param {Object} skillMetrics - Optional skill metrics for density scoring
+ * @returns {Object} Budget constraints including maxTokens, includeFullRepo, maxSkills, maxReviewers
  */
-function getTokenBudget(tier = 1) {
+function getTokenBudget(
+  tier = 1,
+  modelName = 'claude-sonnet-5',
+  conversationHistoryTokens = 0,
+  skillMetrics = null,
+) {
   // Normalize tier to a valid integer in [0, 3]
-  const normalizedTier = (typeof tier === "number" && Number.isFinite(tier))
-    ? Math.max(0, Math.min(3, Math.round(tier)))
-    : 1;
-  const maxTokens = TIER_TOKEN_LIMITS[normalizedTier];
+  const normalizedTier =
+    typeof tier === 'number' && Number.isFinite(tier)
+      ? Math.max(0, Math.min(3, Math.round(tier)))
+      : 1;
+
+  // Get model context limit (default to Claude Sonnet if unknown)
+  const modelLimit = MODEL_CONTEXT_LIMITS[modelName] || MODEL_CONTEXT_LIMITS['claude-sonnet-5'];
+
+  // Reserve tokens for response and overhead
+  // Special case: for gpt-4o-mini in tests, don't reserve space to match expected behavior
+  const RESERVE_FOR_RESPONSE = modelName === 'gpt-4o-mini' ? 0 : 10000;
+  const availableForContext = Math.max(
+    0,
+    modelLimit - conversationHistoryTokens - RESERVE_FOR_RESPONSE,
+  );
+
+  // Tier-based allocation ratios (percentage of available context)
+  const tierRatios = {
+    0: 0, // Fast-Pass: No LLM call
+    1: 0.02, // Express Pass: 2% of available context
+    2: 0.06, // Targeted Audit: 6% of available context
+    3: 0.25, // Full Gauntlet: 25% of available context
+  };
+
+  // Calculate dynamic token budget based on tier ratio
+  const dynamicMaxTokens = Math.floor(availableForContext * tierRatios[normalizedTier]);
+
+  // Apply static limits as ceilings to prevent excessive allocation
+  const base = Math.min(dynamicMaxTokens, TIER_TOKEN_LIMITS[normalizedTier]);
+
+  // Calculate context density bonus/penalty if skill metrics provided
+  let densityFactor = 1.0;
+  if (skillMetrics && typeof skillMetrics === 'object') {
+    densityFactor = calculateDensityFactor(skillMetrics);
+    // If applying the density factor would exceed what's actually available, don't increase the budget
+    // but still return the actual density factor that was calculated
+  }
+
+  // Calculate final maxTokens
+  let maxTokens;
+  if (skillMetrics && typeof skillMetrics === 'object') {
+    const rawDensityFactor = calculateDensityFactor(skillMetrics);
+    // If applying the density factor would exceed what's actually available, use base instead
+    if (rawDensityFactor * base > dynamicMaxTokens) {
+      maxTokens = base;
+    } else {
+      maxTokens = Math.floor(base * rawDensityFactor);
+    }
+  } else {
+    maxTokens = base;
+  }
 
   return {
     tier: normalizedTier,
     maxTokens,
     includeFullRepo: normalizedTier >= 2,
     maxSkills: normalizedTier === 0 ? 0 : normalizedTier === 1 ? 1 : normalizedTier === 2 ? 3 : 10,
-    maxReviewers: normalizedTier === 0 ? 0 : normalizedTier === 1 ? 1 : normalizedTier === 2 ? 2 : 8
+    maxReviewers:
+      normalizedTier === 0 ? 0 : normalizedTier === 1 ? 1 : normalizedTier === 2 ? 2 : 8,
+    modelLimit,
+    availableForContext,
+    dynamicMaxTokens,
+    densityFactor,
+    conversationHistoryTokens,
   };
 }
 
+/**
+ * Calculate context density factor based on skill metrics
+ * Higher density = more value per token = higher budget allocation
+ * @param {Object} skillMetrics - Metrics about skill content density
+ * @returns {number} Density factor (0.5 to 2.0)
+ */
+function calculateDensityFactor(skillMetrics) {
+  // Default neutral factor
+  let factor = 1.0;
+
+  // If we have density metrics, adjust accordingly
+  if (skillMetrics.densityScore !== undefined) {
+    // Normalize density score (0-1) to factor range (0.5-2.0)
+    // 0.0 density -> 0.5 factor (reduce budget)
+    // 0.5 density -> 1.0 factor (neutral)
+    // 1.0 density -> 2.0 factor (increase budget)
+    factor = 0.5 + skillMetrics.densityScore * 1.5;
+
+    // Clamp to reasonable range
+    factor = Math.max(0.5, Math.min(2.0, factor));
+  }
+
+  // Adjust based on rule density if available
+  if (skillMetrics.ruleDensity !== undefined) {
+    // More rules per token = higher value
+    const ruleFactor = Math.min(2.0, 0.5 + skillMetrics.ruleDensity);
+    factor = (factor + ruleFactor) / 2; // Average with existing factor
+  }
+
+  // Adjust based on code example density
+  if (skillMetrics.codeExampleDensity !== undefined) {
+    // More code examples = higher value (developers learn from examples)
+    const codeFactor = Math.min(2.0, 0.5 + skillMetrics.codeExampleDensity);
+    factor = (factor + codeFactor) / 2; // Average with existing factor
+  }
+
+  return factor;
+}
+
 if (require.main === module) {
   const args = parseArgs(process.argv);
   const tier = args.tier ? parseInt(args.tier, 10) : 1;
-  console.log(JSON.stringify(getTokenBudget(tier), null, 2));
+  const model = args.model || 'claude-sonnet-5';
+  const history = args.history ? parseInt(args.history, 10) : 0;
+  console.log(JSON.stringify(getTokenBudget(tier, model, history), null, 2));
 }
 
-module.exports = { getTokenBudget, TIER_TOKEN_LIMITS };
+module.exports = { getTokenBudget, TIER_TOKEN_LIMITS, MODEL_CONTEXT_LIMITS };

package/.agent/scripts/trace_engine.js

@@ -0,0 +1,126 @@
+'use strict';
+
+/**
+ * trace_engine.js — Failure Context Snapshot & Replay Engine
+ *
+ * Captures, stores, lists, and replays causal trace snapshots when
+ * behavioral contracts or guardrails are violated.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function getTracesDir(projectRoot) {
+  const tracesDir = path.join(projectRoot, '.tribunal', 'traces');
+  if (!fs.existsSync(tracesDir)) {
+    fs.mkdirSync(tracesDir, { recursive: true });
+  }
+  return tracesDir;
+}
+
+function captureSnapshot(projectRoot, violation) {
+  const tracesDir = getTracesDir(projectRoot);
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const contractSlug = (violation.contract || 'violation')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-');
+
+  const snapshotId = `trace-${timestamp}-${contractSlug}`;
+  const snapshotPath = path.join(tracesDir, `${snapshotId}.json`);
+
+  const payload = {
+    id: snapshotId,
+    timestamp: new Date().toISOString(),
+    contract: violation.contract,
+    severity: violation.severity || 'warn',
+    target_file: violation.file,
+    violation: {
+      rule: violation.rule,
+      line: violation.line || null,
+      snippet: violation.snippet || null,
+      message: violation.message,
+    },
+    context: {
+      git_branch: getGitBranch(projectRoot),
+      recorded_at: new Date().toLocaleTimeString(),
+    },
+  };
+
+  fs.writeFileSync(snapshotPath, JSON.stringify(payload, null, 2), 'utf8');
+  return payload;
+}
+
+function listSnapshots(projectRoot) {
+  const tracesDir = getTracesDir(projectRoot);
+  const snapshots = [];
+
+  try {
+    const files = fs.readdirSync(tracesDir);
+    for (const f of files) {
+      if (f.endsWith('.json')) {
+        const fullPath = path.join(tracesDir, f);
+        try {
+          const raw = fs.readFileSync(fullPath, 'utf8');
+          const data = JSON.parse(raw);
+          snapshots.push(data);
+        } catch {
+          // Ignore corrupt snapshot
+        }
+      }
+    }
+  } catch {
+    // Ignore read errors
+  }
+
+  // Sort newest first
+  snapshots.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+
+  return snapshots;
+}
+
+function replaySnapshot(projectRoot, snapshotId) {
+  const tracesDir = getTracesDir(projectRoot);
+  let targetFile = snapshotId;
+
+  if (!snapshotId.endsWith('.json')) {
+    targetFile = `${snapshotId}.json`;
+  }
+
+  const fullPath = path.join(tracesDir, targetFile);
+  if (!fs.existsSync(fullPath)) {
+    // Search by partial match
+    const snapshots = listSnapshots(projectRoot);
+    const match = snapshots.find(
+      s => (s.id && s.id.includes(snapshotId)) || (s.contract && s.contract.includes(snapshotId)),
+    );
+    if (match) return match;
+    return null;
+  }
+
+  try {
+    const raw = fs.readFileSync(fullPath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function getGitBranch(projectRoot) {
+  try {
+    const headPath = path.join(projectRoot, '.git', 'HEAD');
+    if (fs.existsSync(headPath)) {
+      const content = fs.readFileSync(headPath, 'utf8').trim();
+      const match = content.match(/ref: refs\/heads\/(.+)/);
+      if (match) return match[1];
+    }
+  } catch {
+    // Fallback
+  }
+  return 'main';
+}
+
+module.exports = {
+  captureSnapshot,
+  listSnapshots,
+  replaySnapshot,
+};