tribunal-kit 9.2.6 → 9.2.8

package/src/intelligence/governance_simulator.js

@@ -0,0 +1,115 @@
+'use strict';
+
+/**
+ * governance_simulator.js — Tribunal Intelligence: Simulator
+ * ============================================================================
+ * Phase 7P / 7Q / 7R implementation.
+ *
+ * Runs candidate policies against the historical dataset to verify they do not
+ * reduce safety parameters, generating structural PolicyProposals.
+ */
+
+const { CaseIndexer } = require('./case_indexer');
+const { CaseMemory } = require('./case_memory');
+
+class GovernanceSimulator {
+  constructor(options = {}) {
+    this.indexer = options.indexer || new CaseIndexer(options);
+    this.memory = options.memory || new CaseMemory(options);
+  }
+
+  /**
+   * Simulates a candidate policy against historical data.
+   *
+   * @param {Object} candidatePolicy Contains rule overrides (e.g., maxReviewers: 2)
+   * @returns {Object} Simulation metrics comparing baseline vs candidate
+   */
+  simulatePolicy(candidatePolicy) {
+    const allCases = Object.keys(this.indexer.index.cases || {}).map(id => this.memory.getCase(id));
+    if (allCases.length === 0) {
+      throw new Error('No historical cases available for simulation.');
+    }
+
+    const baseline = {
+      tokenCost: 0,
+      rejections: 0,
+      approvals: 0,
+    };
+
+    const candidate = {
+      tokenCost: 0,
+      rejections: 0, // In a full implementation, we'd replay the exact conditions
+      approvals: 0,
+      safetyDegradation: false,
+    };
+
+    for (const c of allCases) {
+      if (!c) continue;
+
+      // Baseline
+      if (c.finalVerdict === 'RESOLVED') baseline.approvals++;
+      else if (c.finalVerdict === 'REJECTED') baseline.rejections++;
+      const trCost = (c.tokenUsage || {}).input + (c.tokenUsage || {}).output || 0;
+      baseline.tokenCost += trCost;
+
+      // Simulation proxy logic - e.g. capping reviewers
+      let candidateCaseCost = trCost;
+      if (candidatePolicy.maxReviewers) {
+        const actualRCount = (c.selectedReviewers || []).length;
+        if (actualRCount > candidatePolicy.maxReviewers) {
+          candidateCaseCost = Math.floor(trCost * (candidatePolicy.maxReviewers / actualRCount));
+
+          // Did pruning this reviewer prune someone who found a critical issue?
+          const rejectedByPruned = (c.reviewResults || []).some((res, idx) => {
+            return idx >= candidatePolicy.maxReviewers && res.status === 'REJECTED';
+          });
+
+          if (rejectedByPruned && c.finalVerdict === 'REJECTED') {
+            // Optimization would have caused a false approval!
+            candidate.safetyDegradation = true;
+            candidate.approvals++;
+          } else if (c.finalVerdict === 'REJECTED') {
+            candidate.rejections++;
+          } else {
+            candidate.approvals++;
+          }
+        } else {
+          if (c.finalVerdict === 'RESOLVED') candidate.approvals++;
+          else if (c.finalVerdict === 'REJECTED') candidate.rejections++;
+        }
+      }
+
+      candidate.tokenCost += candidateCaseCost;
+    }
+
+    return {
+      casesSimulated: allCases.length,
+      baseline,
+      candidate,
+    };
+  }
+
+  /**
+   * Generates a structural policy proposal based on a successful simulation
+   */
+  proposePolicy(policyObj, simulationResult) {
+    if (simulationResult.candidate.safetyDegradation) {
+      throw new Error(
+        'Will not generate proposal: Simulation indicates safety degradation (e.g. false approvals).',
+      );
+    }
+
+    const tokensSaved = simulationResult.baseline.tokenCost - simulationResult.candidate.tokenCost;
+
+    return {
+      proposalId: `PROP-${Date.now()}`,
+      policy: policyObj,
+      evidence: `Simulated across ${simulationResult.casesSimulated} cases.`,
+      projectedSavings: `${tokensSaved} tokens`,
+      safetyRisk: 'No mandatory safety reduction detected in historical replay.',
+      status: 'PENDING_HUMAN_APPROVAL',
+    };
+  }
+}
+
+module.exports = { GovernanceSimulator };

package/src/intelligence/human_intelligence.js

@@ -0,0 +1,46 @@
+'use strict';
+
+/**
+ * human_intelligence.js — Tribunal Intelligence: Human-in-the-Loop
+ * ============================================================================
+ * Phase 7N implementation.
+ *
+ * Tracks human overrides of Tribunal decisions. Ensures that human override
+ * DOES NOT equate to an automatic policy rewrite.
+ */
+
+const { CaseMemory } = require('./case_memory');
+
+class HumanIntelligence {
+  constructor(options = {}) {
+    this.memory = options.memory || new CaseMemory(options);
+    this.overrides = [];
+  }
+
+  /**
+   * Records a human overriding a deterministic tribunal decision.
+   */
+  recordOverride(caseId, originalVerdict, finalVerdict, reason) {
+    if (!caseId || !originalVerdict || !finalVerdict || !reason) {
+      throw new Error('Missing require params for human override.');
+    }
+
+    const overrideRecord = {
+      overrideId: `OVR-${Date.now()}`,
+      timestamp: new Date().toISOString(),
+      caseId,
+      originalTribunalVerdict: originalVerdict,
+      humanDecision: finalVerdict,
+      reason,
+      status: 'PENDING_POLICY_ANALYSIS',
+    };
+
+    this.overrides.push(overrideRecord);
+
+    // In a real system, this would write to `.agent/intelligence/overrides/`
+    // For this step, we'll keep it simple or hook into a write function.
+    return overrideRecord;
+  }
+}
+
+module.exports = { HumanIntelligence };

package/src/intelligence/mcp_tools.js

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * mcp_tools.js — Tribunal Intelligence: MCP Layer
+ * ============================================================================
+ * Phase 7T implementation.
+ */
+
+const { CaseMemory } = require('./case_memory');
+const { CaseIndexer } = require('./case_indexer');
+const { CaseBasedReasoningEngine } = require('./cbr_engine');
+
+const TOOLS = [
+  {
+    name: 'tribunal_search_cases',
+    description: 'Search historical cases by tier, files, or categories.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        files: { type: 'array', items: { type: 'string' } },
+        impactTier: { type: 'number' },
+      },
+    },
+  },
+  {
+    name: 'tribunal_get_case',
+    description: 'Retrieve full case structured data.',
+    inputSchema: {
+      type: 'object',
+      properties: { caseId: { type: 'string' } },
+      required: ['caseId'],
+    },
+  },
+  {
+    name: 'tribunal_generate_review_plan',
+    description: 'Generate an intelligence-driven review plan.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        files: { type: 'array', items: { type: 'string' } },
+        impactTier: { type: 'number' },
+      },
+    },
+  },
+];
+
+class IntelligenceMCPHandler {
+  constructor() {
+    this.cbr = new CaseBasedReasoningEngine();
+    this.mem = new CaseMemory();
+    this.idx = new CaseIndexer();
+  }
+
+  getToolDefinitions() {
+    return TOOLS;
+  }
+
+  async callTool(name, args) {
+    switch (name) {
+      case 'tribunal_search_cases': {
+        return {
+          content: [
+            { type: 'text', text: JSON.stringify(this.cbr.similarity.findSimilar(args), null, 2) },
+          ],
+        };
+      }
+      case 'tribunal_get_case': {
+        const caseRecord = this.mem.getCase(args.caseId);
+        return {
+          content: [
+            { type: 'text', text: JSON.stringify(caseRecord || { error: 'Not found' }, null, 2) },
+          ],
+        };
+      }
+      case 'tribunal_generate_review_plan': {
+        const plan = this.cbr.generateReviewPlan(args);
+        return {
+          content: [{ type: 'text', text: JSON.stringify(plan, null, 2) }],
+        };
+      }
+      default:
+        throw new Error(`Unknown intelligence tool: ${name}`);
+    }
+  }
+}
+
+module.exports = { IntelligenceMCPHandler, TOOLS };

package/src/intelligence/reviewer_performance.js

@@ -0,0 +1,94 @@
+'use strict';
+
+/**
+ * reviewer_performance.js — Tribunal Intelligence: Reviewer Performance Model
+ * ============================================================================
+ * Phase 7G implementation.
+ *
+ * Tracks reviewer effectiveness dynamically without reducing it to simple
+ * approval rates. Evaluates usefulness against independently verified outcomes
+ * and regressions.
+ */
+
+const { CaseIndexer } = require('./case_indexer');
+const { CaseMemory } = require('./case_memory');
+
+class ReviewerPerformance {
+  constructor(options = {}) {
+    this.indexer = options.indexer || new CaseIndexer(options);
+    this.memory = options.memory || new CaseMemory(options);
+  }
+
+  /**
+   * Calculates comprehensive reviewer performance statistics.
+   *
+   * Metrics:
+   * - Participation count
+   * - Final agreement (did their verdict match the finalized case outcome)
+   * - False Acceptances (they approved, but a regression occurred later)
+   * - False Rejections (they blocked excessively on cases that ultimately required no structure changes)
+   *
+   * @param {string} reviewerName
+   * @returns {Object} Structured metrics
+   */
+  getReviewerStats(reviewerName) {
+    const caseIds = this.indexer.index.byReviewer[reviewerName];
+    if (!caseIds || caseIds.size === 0) {
+      return {
+        reviewer: reviewerName,
+        participationCount: 0,
+        reliabilityScore: null,
+        falseAcceptances: 0,
+        regressionsMissed: 0,
+      };
+    }
+
+    let participationCount = 0;
+    let agreementCount = 0;
+    let regressionsMissed = 0;
+
+    for (const caseId of caseIds) {
+      const caseRecord = this.memory.getCase(caseId);
+      if (!caseRecord) continue;
+
+      participationCount++;
+
+      // Find this reviewer's verdict in the case
+      const revResult = (caseRecord.reviewResults || []).find(r => r.reviewer === reviewerName);
+      if (revResult) {
+        const reviewerApproved = revResult.status === 'APPROVED';
+        const finalApproved = caseRecord.finalVerdict === 'RESOLVED';
+
+        if (reviewerApproved === finalApproved) {
+          agreementCount++;
+        }
+
+        // Did they approve, but it resulted in a regression case logging against this file?
+        const hasRegressions = caseRecord.regressions && caseRecord.regressions.length > 0;
+        if (reviewerApproved && hasRegressions) {
+          regressionsMissed++;
+        }
+      }
+    }
+
+    const agreementRate = participationCount > 0 ? agreementCount / participationCount : 0;
+
+    // Reliability penalizes missed regressions heavily.
+    // Base agreement is good, but letting a bug slip through is the primary failure mode.
+    const missPenalty = participationCount > 0 ? (regressionsMissed / participationCount) * 1.5 : 0;
+    let reliabilityScore = Math.max(0, agreementRate - missPenalty);
+
+    // Cap max
+    reliabilityScore = Math.min(1.0, reliabilityScore);
+
+    return {
+      reviewer: reviewerName,
+      participationCount,
+      agreementRate,
+      regressionsMissed,
+      reliabilityScore,
+    };
+  }
+}
+
+module.exports = { ReviewerPerformance };

package/src/intelligence/risk_prediction_engine.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * risk_prediction_engine.js — Tribunal Intelligence: Predictive Risk
+ * ============================================================================
+ * Phase 7J implementation.
+ *
+ * Models probability of rejection, regression, and correction failure.
+ * Predictions are explicitly ADVISORY.
+ */
+
+const { CaseIndexer } = require('./case_indexer');
+const { CaseMemory } = require('./case_memory');
+
+class RiskPredictionEngine {
+  constructor(options = {}) {
+    this.indexer = options.indexer || new CaseIndexer(options);
+    this.memory = options.memory || new CaseMemory(options);
+  }
+
+  /**
+   * Generates a structural risk prediction report based on similar cases.
+   *
+   * @param {Array} similarCases Output from CaseSimilarity.findSimilar
+   * @returns {Object} Prediction report containing probabilities and historical basis
+   */
+  predictRisk(similarCases) {
+    if (!similarCases || similarCases.length === 0) {
+      return {
+        probabilityOfRejection: 'UNKNOWN',
+        probabilityOfRegression: 'UNKNOWN',
+        probabilityOfCorrectionFailure: 'UNKNOWN',
+        expectedVerificationCost: 'UNKNOWN',
+        advisoryMessage: 'Insufficient historical data to generate predictions.',
+        basis: { similarCaseCount: 0 },
+      };
+    }
+
+    let rejectionCount = 0;
+    let regressionCount = 0;
+    let correctionFailureCount = 0;
+    let totalTokens = 0;
+
+    const analyzedCount = similarCases.length;
+
+    for (const simCase of similarCases) {
+      const caseRecord = this.memory.getCase(simCase.caseId);
+      if (!caseRecord) continue;
+
+      if (caseRecord.finalVerdict === 'REJECTED') rejectionCount++;
+      if (caseRecord.regressions && caseRecord.regressions.length > 0) regressionCount++;
+
+      const corrections = caseRecord.correctionAttempts || [];
+      if (corrections.length > 0) {
+        const lastCorrection = corrections[corrections.length - 1];
+        if (lastCorrection.status === 'FAILED') {
+          correctionFailureCount++;
+        }
+      }
+
+      const input = (caseRecord.tokenUsage || {}).input || 0;
+      const output = (caseRecord.tokenUsage || {}).output || 0;
+      totalTokens += input + output;
+    }
+
+    const rejectionProb = analyzedCount > 0 ? rejectionCount / analyzedCount : 0;
+    const regressionProb = analyzedCount > 0 ? regressionCount / analyzedCount : 0;
+    const correctionFailureProb = analyzedCount > 0 ? correctionFailureCount / analyzedCount : 0;
+    const avgCost = analyzedCount > 0 ? Math.round(totalTokens / analyzedCount) : 0;
+
+    return {
+      probabilityOfRejection: (rejectionProb * 100).toFixed(1) + '%',
+      probabilityOfRegression: (regressionProb * 100).toFixed(1) + '%',
+      probabilityOfCorrectionFailure: (correctionFailureProb * 100).toFixed(1) + '%',
+      expectedVerificationCost: avgCost > 0 ? `${avgCost} tokens` : 'UNKNOWN',
+      prediction: {
+        correctionDifficulty:
+          correctionFailureProb > 0.4 ? 'HIGH' : correctionFailureProb > 0.1 ? 'MEDIUM' : 'LOW',
+        regressionRisk: regressionProb > 0.3 ? 'HIGH' : regressionProb > 0.1 ? 'MEDIUM' : 'LOW',
+      },
+      advisoryMessage: `Based on ${analyzedCount} historical cases. This prediction must never directly approve a transaction.`,
+      basis: {
+        similarCaseCount: analyzedCount,
+        rejections: rejectionCount,
+        regressions: regressionCount,
+        correctionFailures: correctionFailureCount,
+      },
+    };
+  }
+}
+
+module.exports = { RiskPredictionEngine };

package/src/intelligence/token_intelligence.js

@@ -0,0 +1,73 @@
+'use strict';
+
+/**
+ * token_intelligence.js — Tribunal Intelligence: Token Economics
+ * ============================================================================
+ * Phase 7I implementation.
+ *
+ * Tracks input/output tokens, cost per verified resolution, and identifies
+ * where context can be compressed safely.
+ */
+
+const { CaseMemory } = require('./case_memory');
+
+class TokenIntelligence {
+  constructor(options = {}) {
+    this.memory = options.memory || new CaseMemory(options);
+  }
+
+  /**
+   * Generates economics metadata for a completed case to be indexed.
+   */
+  calculateCaseEconomics(caseRecord) {
+    if (!caseRecord || !caseRecord.tokenUsage) return null;
+
+    const input = caseRecord.tokenUsage.input || 0;
+    const output = caseRecord.tokenUsage.output || 0;
+    const total = input + output;
+
+    const reviewerCount = (caseRecord.selectedReviewers || []).length;
+    const avgTokensPerReviewer = reviewerCount > 0 ? total / reviewerCount : 0;
+    const findingsCount = (caseRecord.reviewResults || []).reduce(
+      (acc, r) => acc + (r.findings ? r.findings.length : 0),
+      0,
+    );
+
+    const tokensPerFinding = findingsCount > 0 ? total / findingsCount : total;
+
+    return {
+      totalTokens: total,
+      avgTokensPerReviewer: Math.round(avgTokensPerReviewer),
+      tokensPerFinding: Math.round(tokensPerFinding),
+      correctionCount: (caseRecord.correctionAttempts || []).length,
+      efficiencyRating: total < 10000 ? 'EXCELLENT' : total < 30000 ? 'GOOD' : 'HEAVY',
+    };
+  }
+
+  /**
+   * Proposes a token budget given historical performance.
+   * "Optimization objective is: MINIMIZE TOKEN COST SUBJECT TO SAFETY >= CURRENT BASELINE"
+   */
+  proposeContextLimits(impactTier, reviewerCount, similarityConfidence) {
+    let maxTokens = 4000;
+
+    // High tier needs more context
+    if (impactTier === 3) maxTokens = 15000;
+    else if (impactTier === 2) maxTokens = 8000;
+
+    // If we are highly confident in our similarity match, we know exactly what evidence matters.
+    // We can compress the context boundary aggressively.
+    if (similarityConfidence === 'HIGH') {
+      maxTokens = Math.floor(maxTokens * 0.6); // 40% reduction
+    } else if (similarityConfidence === 'MEDIUM') {
+      maxTokens = Math.floor(maxTokens * 0.85); // 15% reduction
+    }
+
+    return {
+      recommendedTokenLimit: maxTokens,
+      projectedCostSavings: 4000 - maxTokens > 0 ? 4000 - maxTokens : 0,
+    };
+  }
+}
+
+module.exports = { TokenIntelligence };