tribunal-kit 9.2.6 → 9.2.8

package/src/intelligence/case_memory.js

@@ -0,0 +1,149 @@
+'use strict';
+
+/**
+ * case_memory.js — Tribunal Intelligence: Case Memory System
+ * ============================================================================
+ * Phase 7B implementation of persistent, local-first case intelligence.
+ *
+ * Every completed governance event is stored here as an immutable case.
+ * Cases are NEVER mutated after finalization; corrections create linked
+ * cases to maintain untampered historical truth.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+class CaseMemory {
+  constructor(options = {}) {
+    this.workspace = options.workspace || process.cwd();
+    this.agentDir = options.agentDir || path.join(this.workspace, '.agent');
+    this.intelligenceDir = path.join(this.agentDir, 'intelligence');
+    this.casesDir = path.join(this.intelligenceDir, 'cases');
+
+    // Ensure directories exist
+    this._ensureDirectories();
+  }
+
+  _ensureDirectories() {
+    if (!fs.existsSync(this.agentDir)) fs.mkdirSync(this.agentDir, { recursive: true });
+    if (!fs.existsSync(this.intelligenceDir))
+      fs.mkdirSync(this.intelligenceDir, { recursive: true });
+    if (!fs.existsSync(this.casesDir)) fs.mkdirSync(this.casesDir, { recursive: true });
+  }
+
+  /**
+   * Generates a deterministic hash for repository states based on current context.
+   */
+  _generateFingerprint(data) {
+    return crypto
+      .createHash('sha256')
+      .update(typeof data === 'string' ? data : JSON.stringify(data))
+      .digest('hex');
+  }
+
+  _getCasePath(caseId) {
+    return path.join(this.casesDir, `${caseId}.json`);
+  }
+
+  /**
+   * Finalizes and stores an immutable governance case.
+   *
+   * @param {Object} caseData The raw case outcome structure
+   * @throws {Error} If the caseId already exists to enforce immutability
+   * @returns {Object} The finalized, frozen case record
+   */
+  storeCase(caseData) {
+    if (!caseData || !caseData.caseId) {
+      throw new Error('Cannot store case: caseId is missing.');
+    }
+
+    const { caseId } = caseData;
+    const casePath = this._getCasePath(caseId);
+
+    if (fs.existsSync(casePath)) {
+      throw new Error(
+        `Immutability violation: Case ${caseId} already exists and cannot be overwritten.`,
+      );
+    }
+
+    const finalizedCase = {
+      caseId,
+      timestamp: caseData.timestamp || new Date().toISOString(),
+      repositoryFingerprint: caseData.repositoryFingerprint || 'UNKNOWN',
+      changeFingerprint: caseData.changeFingerprint || null,
+      findingFingerprint: caseData.findingFingerprint || null,
+      impactTier: caseData.impactTier || 'UNKNOWN',
+      policyDecision: caseData.policyDecision || {},
+      selectedReviewers: caseData.selectedReviewers || [],
+      reviewResults: caseData.reviewResults || [],
+      correctionAttempts: caseData.correctionAttempts || [],
+      validationResults: caseData.validationResults || [],
+      evidence: caseData.evidence || {},
+      finalVerdict: caseData.finalVerdict || 'UNRESOLVED',
+      resolutionCertificate: caseData.resolutionCertificate || null,
+      tokenUsage: caseData.tokenUsage || { input: 0, output: 0 },
+      latency: caseData.latency || 0,
+      failureModes: caseData.failureModes || [],
+      regressions: caseData.regressions || [],
+      linkedParentCase: caseData.linkedParentCase || null, // For correction chains
+
+      // Compute cryptographic hash of the entire record bounds for immutability check
+      _recordHash: '',
+    };
+
+    // Seal the record with its own hash
+    finalizedCase._recordHash = this._generateFingerprint({ ...finalizedCase, _recordHash: '' });
+
+    fs.writeFileSync(casePath, JSON.stringify(finalizedCase, null, 2), 'utf8');
+
+    return finalizedCase;
+  }
+
+  /**
+   * Retrieves an immutable case.
+   *
+   * @param {string} caseId
+   * @returns {Object|null} The case record, or null if missing.
+   */
+  getCase(caseId) {
+    const casePath = this._getCasePath(caseId);
+    if (!fs.existsSync(casePath)) return null;
+
+    try {
+      const data = fs.readFileSync(casePath, 'utf8');
+      const caseRecord = JSON.parse(data);
+
+      // Immutability Integrity Check
+      const storedHash = caseRecord._recordHash;
+      const computedHash = this._generateFingerprint({ ...caseRecord, _recordHash: '' });
+
+      if (storedHash !== computedHash) {
+        console.warn(
+          `[Tribunal Case Memory] CORRUPTION WARNING: Case ${caseId} fails internal integrity hash.`,
+        );
+      }
+
+      return Object.freeze(caseRecord); // Prevent accidental in-memory mutation
+    } catch (e) {
+      console.error(`[Tribunal Case Memory] Failed to read case ${caseId}:`, e);
+      return null;
+    }
+  }
+
+  /**
+   * Scans all stored cases without loading full objects immediately.
+   * Useful for indexing.
+   */
+  *listCaseIds() {
+    if (!fs.existsSync(this.casesDir)) return;
+    const files = fs.readdirSync(this.casesDir);
+    for (const file of files) {
+      if (file.endsWith('.json')) {
+        yield file.replace('.json', '');
+      }
+    }
+  }
+}
+
+module.exports = { CaseMemory };

package/src/intelligence/case_similarity.js

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * case_similarity.js — Tribunal Intelligence: Similarity Engine
+ * ============================================================================
+ * Phase 7D implementation.
+ *
+ * Compares incoming/ongoing cases against historical index data using
+ * deterministic signals first (files, categories, impact).
+ * Embeddings could be plugged here later, but are NOT the sole governance mechanism.
+ */
+
+const { CaseIndexer } = require('./case_indexer');
+const { CaseMemory } = require('./case_memory');
+
+class CaseSimilarity {
+  constructor(options = {}) {
+    this.indexer = options.indexer || new CaseIndexer(options);
+    this.memory = options.memory || new CaseMemory(options);
+  }
+
+  /**
+   * Find historical cases similar to a proposed change.
+   *
+   * @param {Object} query Signal query (e.g., impactTier, files array, categories)
+   * @returns {Array} List of { caseId, similarityScore, matchedSignals, confidence }
+   */
+  findSimilar(query) {
+    if (!query) return [];
+
+    const hitScores = new Map(); // caseId -> score tracking object
+    const { impactTier, files = [], categories = [] } = query;
+
+    const trackHit = (caseId, signalName, weight) => {
+      if (!hitScores.has(caseId)) {
+        hitScores.set(caseId, { score: 0, matchedSignals: [] });
+      }
+      const data = hitScores.get(caseId);
+      data.score += weight;
+      if (!data.matchedSignals.includes(signalName)) {
+        data.matchedSignals.push(signalName);
+      }
+    };
+
+    // 1. Same Files (High Signal)
+    for (const file of files) {
+      const cases = this.indexer.getCasesByFile(file);
+      for (const caseId of cases) {
+        trackHit(caseId, `FILE_MATCH:${file}`, 0.4); // 40% weight per matched file
+      }
+    }
+
+    // 2. Same Impact Tier (Medium Signal)
+    if (impactTier) {
+      const cases = this.indexer.getCasesByImpactTier(impactTier);
+      for (const caseId of cases) {
+        trackHit(caseId, `TIER_MATCH:${impactTier}`, 0.2); // 20% weight per tier match
+      }
+    }
+
+    // Prepare Results
+    const results = [];
+    for (const [caseId, data] of hitScores.entries()) {
+      // Cap score at 1.0 logically, though raw scoring might exceed 1
+      const normalizedScore = Math.min(data.score, 1.0);
+      let confidence = 'LOW';
+      if (normalizedScore > 0.7) confidence = 'HIGH';
+      else if (normalizedScore >= 0.4) confidence = 'MEDIUM';
+
+      results.push({
+        caseId,
+        similarityScore: normalizedScore,
+        rawScore: data.score,
+        matchedSignals: data.matchedSignals,
+        confidence,
+      });
+    }
+
+    // Sort descending by score
+    results.sort((a, b) => b.similarityScore - a.similarityScore);
+
+    return results;
+  }
+}
+
+module.exports = { CaseSimilarity };

package/src/intelligence/cbr_engine.js

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * cbr_engine.js — Tribunal Intelligence: Case-Based Reasoning Engine
+ * ============================================================================
+ * Phase 7L implementation.
+ *
+ * Orchestrates the full lifecycle before a review begins:
+ * Current Change -> Similarity -> Failures -> Reviewers -> Evidence -> Plan.
+ * Limits historical context length to avoid overwhelming the reviewer prompt.
+ */
+
+const { CaseSimilarity } = require('./case_similarity');
+const { FailureIntelligence } = require('./failure_intelligence');
+const { AdaptiveReviewerOrchestrator } = require('./adaptive_reviewer_orchestrator');
+const { EvidenceOptimization } = require('./evidence_optimization');
+const { RiskPredictionEngine } = require('./risk_prediction_engine');
+
+class CaseBasedReasoningEngine {
+  constructor(options = {}) {
+    this.similarity = new CaseSimilarity(options);
+    this.failureIntel = new FailureIntelligence(options);
+    this.adaptiveOrchestrator = new AdaptiveReviewerOrchestrator(options);
+    this.evidenceOptimizer = new EvidenceOptimization(options);
+    this.riskEngine = new RiskPredictionEngine(options);
+  }
+
+  /**
+   * Generates a structural Review Plan by flowing through intelligence layers.
+   *
+   * @param {Object} changeContext { diff, files, task, previousFindings }
+   */
+  generateReviewPlan(changeContext) {
+    // 1. Initial baseline deterministic signals (mocked classification proxy for the pipeline)
+    // In the real flow, resolveMonotonicImpactTier would have given us the tier. Let's assume passed in for now.
+    const query = {
+      files: changeContext.files || [],
+      impactTier: changeContext.impactTier || 1,
+      categories: (changeContext.previousFindings || []).map(f => f.category),
+    };
+
+    // 2. Historical Case Retrieval
+    const similarCases = this.similarity.findSimilar(query);
+
+    // 3. Known Failure Patterns
+    const failures = [];
+    for (const file of query.files) {
+      const pattern = this.failureIntel.detectFailurePattern('FILE', file);
+      if (pattern) failures.push(pattern);
+    }
+
+    // 4. Relevant Reviewers
+    // Pass baseline options through the adaptive wrapper
+    const reviewerPayload = this.adaptiveOrchestrator.adaptReviewers(changeContext, {
+      ...query,
+      similarCases,
+    });
+
+    // 5. Relevant Evidence
+    const evidencePlan = this.evidenceOptimizer.generateEvidencePlan(changeContext, {
+      ...query,
+      similarCases,
+    });
+
+    // 6. Risk Prediction
+    const predictedRisk = this.riskEngine.predictRisk(similarCases);
+
+    // 7. Context Compression
+    // The reviewer context should contain ONLY useful historical info.
+    // Do NOT dump the entire database into the prompt.
+    const topHistoricalContext = similarCases.slice(0, 2).map(sc => {
+      return {
+        caseId: sc.caseId,
+        reasonForRetrieval: `Matched ${sc.matchedSignals.length} signals including ${sc.matchedSignals.join(', ')}`,
+        similarityScore: sc.similarityScore,
+      };
+    });
+
+    return {
+      timestamp: new Date().toISOString(),
+      predictedRisk,
+      reviewerOrchestration: reviewerPayload,
+      evidencePlan,
+      knownFailurePatterns: failures,
+      historicalContext: topHistoricalContext,
+    };
+  }
+}
+
+module.exports = { CaseBasedReasoningEngine };

package/src/intelligence/evidence_optimization.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * evidence_optimization.js — Tribunal Intelligence: Evidence System Upgrade
+ * ============================================================================
+ * Phase 7H implementation.
+ *
+ * Upgrades the static Evidence Engine to determine which evidence is actually
+ * useful for a given change type based on historical success, creating an
+ * optimized EvidencePlan.
+ */
+
+const { collectAndRankEvidence } = require('../system1/evidence_engine');
+const { ReviewerPerformance } = require('./reviewer_performance');
+
+class EvidenceOptimization {
+  constructor(options = {}) {
+    this.performance = options.performanceStore || new ReviewerPerformance(options);
+  }
+
+  /**
+   * Generates an optimized Execution Plan for a review, dictating what
+   * evidence must be fetched and what can be skipped.
+   *
+   * @param {Object} options Options passed to collectAndRankEvidence
+   * @param {Object} query Intelligence query containing similarity metadata
+   * @returns {Object} EvidencePlan payload
+   */
+  generateEvidencePlan(options, query = {}) {
+    // 1. Fetch baseline deterministic evidence
+    // We do NOT weaken mandatory checks.
+    const baseline = collectAndRankEvidence({
+      ...options,
+      maxItems: 50, // Temporarily expand to see everything
+      maxTokens: 10000,
+    });
+
+    const plan = {
+      required: [],
+      optional: [],
+      avoid: [],
+      tokenEstimate: 0,
+    };
+
+    // 2. Classify costs and historical value
+    const cheapTypes = new Set(['changed_symbol', 'previous_finding']);
+    const expensiveTypes = new Set(['configuration', 'historical_memory', 'relevant_test']);
+
+    // 3. Scan the raw items and re-classify based on intelligence
+    for (const item of baseline.evidence) {
+      // Is it statically mandatory? It MUST be required.
+      if (item.is_mandatory) {
+        plan.required.push(item);
+        plan.tokenEstimate += item.estimated_tokens;
+        continue;
+      }
+
+      // Intelligence overlay: Has this evidence type actually caught things for this category?
+      // (Simplified heuristic for the architectural scaffolding: usually tests and symbols matter most for logic)
+      let historicallyUseful = false;
+      if (query.categories && query.categories.includes('logic') && item.type === 'relevant_test') {
+        historicallyUseful = true;
+      }
+      if (
+        query.categories &&
+        query.categories.includes('dependency') &&
+        item.type === 'configuration'
+      ) {
+        historicallyUseful = true;
+      }
+
+      if (historicallyUseful) {
+        // Upgrade to required
+        plan.required.push({ ...item, is_mandatory: true, _intelligence_upgraded: true });
+        plan.tokenEstimate += item.estimated_tokens;
+        continue;
+      }
+
+      // If expensive and not historically useful for this specific type of change, skip it to save tokens
+      if (expensiveTypes.has(item.type) && plan.tokenEstimate > 4000) {
+        plan.avoid.push({
+          id: item.id,
+          reason: `Expensive evidence type (${item.type}) not historically critical for this scope. Token optimization active.`,
+        });
+        continue;
+      }
+
+      // Default to optional
+      plan.optional.push(item);
+    }
+
+    // Sort to keep deterministic execution order
+    plan.required.sort((a, b) => b.score - a.score);
+    plan.optional.sort((a, b) => b.score - a.score);
+
+    return {
+      evidencePlanId: `EP-${Date.now()}`,
+      timestamp: new Date().toISOString(),
+      mandatoryCount: plan.required.length,
+      optimizedTokenEstimate: plan.tokenEstimate,
+      plan,
+    };
+  }
+}
+
+module.exports = { EvidenceOptimization };

package/src/intelligence/failure_intelligence.js

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * failure_intelligence.js — Tribunal Intelligence: Failure Patterns
+ * ============================================================================
+ * Phase 7E implementation.
+ *
+ * Scans case history and generates structural FailurePatterns.
+ * Ensures weak observations are marked as THIN.
+ */
+
+const { CaseIndexer } = require('./case_indexer');
+const { CaseMemory } = require('./case_memory');
+const crypto = require('crypto');
+
+class FailureIntelligence {
+  constructor(options = {}) {
+    this.indexer = options.indexer || new CaseIndexer(options);
+    this.memory = options.memory || new CaseMemory(options);
+  }
+
+  _generatePatternId(category, context) {
+    return crypto
+      .createHash('sha256')
+      .update(`${category}:${context}`)
+      .digest('hex')
+      .substring(0, 16);
+  }
+
+  /**
+   * Analyzes history to detect repeated failures on a specific file, reviewer, etc.
+   *
+   * @param {string} entityType 'FILE', 'REVIEWER', 'STRATEGY'
+   * @param {string} entityValue The file path or reviewer name
+   * @returns {Object|null} A structured FailurePattern or null if none detected.
+   */
+  detectFailurePattern(entityType, entityValue) {
+    let caseIds = [];
+    if (entityType === 'FILE') {
+      caseIds = this.indexer.getCasesByFile(entityValue);
+    } else if (entityType === 'REVIEWER') {
+      caseIds = this.indexer.getCasesByReviewer(entityValue) || [];
+    }
+
+    if (!caseIds || caseIds.length === 0) return null;
+
+    let failureCount = 0;
+    let regressionCount = 0;
+    const affectedCases = [];
+    let firstSeen = null;
+    let lastSeen = null;
+
+    for (const caseId of caseIds) {
+      const caseRecord = this.memory.getCase(caseId);
+      if (!caseRecord) continue;
+
+      const time = new Date(caseRecord.timestamp).getTime();
+      if (!firstSeen || time < firstSeen) firstSeen = time;
+      if (!lastSeen || time > lastSeen) lastSeen = time;
+
+      const hasFailures =
+        (caseRecord.failureModes && caseRecord.failureModes.length > 0) ||
+        caseRecord.finalVerdict === 'REJECTED';
+      const hasRegressions = caseRecord.regressions && caseRecord.regressions.length > 0;
+
+      if (hasFailures || hasRegressions) {
+        failureCount++;
+        affectedCases.push(caseId);
+        if (hasRegressions) regressionCount++;
+      }
+    }
+
+    if (failureCount === 0) return null;
+
+    // Pattern strength logic
+    let confidence = 'ROBUST';
+    if (failureCount < 3) confidence = 'THIN';
+    else if (failureCount < 5) confidence = 'MODERATE';
+
+    return {
+      patternId: this._generatePatternId(entityType, entityValue),
+      category: `${entityType}_FAILURE`,
+      frequency: failureCount,
+      totalObservations: caseIds.length,
+      regressionCount,
+      affectedCases,
+      firstSeen: firstSeen ? new Date(firstSeen).toISOString() : null,
+      lastSeen: lastSeen ? new Date(lastSeen).toISOString() : null,
+      evidence: `Observed ${failureCount} failures out of ${caseIds.length} historical executions.`,
+      confidence,
+    };
+  }
+}
+
+module.exports = { FailureIntelligence };

package/src/intelligence/governance_drift_detector.js

@@ -0,0 +1,75 @@
+'use strict';
+
+/**
+ * governance_drift_detector.js — Tribunal Intelligence: Governance Drift
+ * ============================================================================
+ * Phase 7O implementation.
+ *
+ * Scans historical metadata to detect statistically meaningful deviation
+ * from baseline governance policies.
+ */
+
+const { CaseIndexer } = require('./case_indexer');
+const { CaseMemory } = require('./case_memory');
+
+class GovernanceDriftDetector {
+  constructor(options = {}) {
+    this.indexer = options.indexer || new CaseIndexer(options);
+    this.memory = options.memory || new CaseMemory(options);
+  }
+
+  /**
+   * Scans the index for drift across defined windows.
+   */
+  detectDrift() {
+    const allCases = Object.values(this.indexer.index.cases || {});
+    if (allCases.length < 20) {
+      return { status: 'INSUFFICIENT_DATA', message: 'Need at least 20 cases to detect drift.' };
+    }
+
+    // Sort chronological
+    allCases.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+
+    // Split into older half (baseline) and newer half (current)
+    const halfway = Math.floor(allCases.length / 2);
+    const baselineWindow = allCases.slice(0, halfway);
+    const currentWindow = allCases.slice(halfway);
+
+    // Metrics calculation helper
+    const calcMetrics = win => {
+      let approved = 0;
+      let rejected = 0;
+      for (const c of win) {
+        if (c.finalVerdict === 'RESOLVED') approved++;
+        else if (c.finalVerdict === 'REJECTED') rejected++;
+      }
+      return {
+        approvalRate: win.length > 0 ? approved / win.length : 0,
+        rejectionRate: win.length > 0 ? rejected / win.length : 0,
+      };
+    };
+
+    const baseMetrics = calcMetrics(baselineWindow);
+    const currMetrics = calcMetrics(currentWindow);
+
+    const signals = [];
+
+    // Detect approval rate explosions
+    if (currMetrics.approvalRate - baseMetrics.approvalRate > 0.3) {
+      signals.push('DRIFT_DETECTED: Approval rate suddenly increased > 30%');
+    }
+
+    if (currMetrics.rejectionRate - baseMetrics.rejectionRate > 0.3) {
+      signals.push('DRIFT_DETECTED: Rejection rate suddenly increased > 30%');
+    }
+
+    return {
+      status: signals.length > 0 ? 'DRIFT_DETECTED' : 'STABLE',
+      signals,
+      baselines: baseMetrics,
+      current: currMetrics,
+    };
+  }
+}
+
+module.exports = { GovernanceDriftDetector };