tribunal-kit 9.2.6 → 9.2.8

package/src/execution/verdict_aggregator.js

@@ -0,0 +1,181 @@
+'use strict';
+
+/**
+ * verdict_aggregator.js — Deterministic Governance Verdict Aggregator
+ * ====================================================================
+ * Phase 1I: Deterministic Verdict Aggregator & Monotonic Safety Invariants
+ *
+ * Core Directives:
+ * 1. LLMs provide evidence and individual opinions; this deterministic engine decides the final state.
+ * 2. Monotonic Safety: Uncertainty or errors can maintain or increase scrutiny, never silently decrease it.
+ * 3. Fail-Closed: Unknown states or failures never become APPROVED.
+ * 4. Deterministic checks always overrule conflicting LLM claims.
+ */
+
+class VerdictAggregator {
+  /**
+   * Aggregates multiple ReviewerResult objects and optional deterministic checks
+   * into an authoritative governance verdict.
+   *
+   * @param {Object} params
+   * @param {Array<Object>} params.results - ReviewerResult[] from ReviewExecutor
+   * @param {Array<Object>} [params.checks] - ImplementationCheck[] (deterministic facts)
+   * @param {number} [params.tier=1] - Impact tier (0..3)
+   * @param {Object} [params.decision] - DecisionPayload
+   * @param {string} [params.reviewRunId] - Provenance ID
+   * @returns {Object} AggregatedVerdictPayload
+   */
+  static aggregate(params = {}) {
+    const results = Array.isArray(params.results) ? params.results : [];
+    const checks = Array.isArray(params.checks) ? params.checks : [];
+    const tier = typeof params.tier === 'number' ? params.tier : 1;
+    const reviewRunId = params.reviewRunId || `agg_${Date.now()}`;
+    const decision = params.decision || {};
+
+    const allFindings = [];
+    const conflicts = [];
+    const reviewersExecuted = [];
+    let hasCritical = false;
+    let hasHigh = false;
+    let hasMedium = false;
+    let hasLow = false;
+    let hasError = false;
+    let hasRejected = false;
+    let hasWarning = false;
+    let hasApproved = false;
+
+    // 1. Ingest all reviewer results
+    for (const r of results) {
+      if (!r || typeof r !== 'object') continue;
+      const revId = r.reviewerId || 'unknown';
+      reviewersExecuted.push(revId);
+
+      if (r.verdict === 'ERROR') hasError = true;
+      if (r.verdict === 'REJECTED') hasRejected = true;
+      if (r.verdict === 'WARNING') hasWarning = true;
+      if (r.verdict === 'APPROVED') hasApproved = true;
+
+      if (Array.isArray(r.findings)) {
+        for (const f of r.findings) {
+          const findingWithRev = { ...f, reviewer: revId };
+          allFindings.push(findingWithRev);
+
+          if (f.severity === 'CRITICAL') hasCritical = true;
+          if (f.severity === 'HIGH') hasHigh = true;
+          if (f.severity === 'MEDIUM') hasMedium = true;
+          if (f.severity === 'LOW') hasLow = true;
+        }
+      }
+    }
+
+    // 2. Cross-check against deterministic execution facts
+    // If deterministic test/lint/security check failed, force failure
+    for (const c of checks) {
+      if (c && c.result === 'FAILED') {
+        conflicts.push({
+          type: 'DETERMINISTIC_CHECK_FAILED',
+          description: `Deterministic check "${c.check || 'check'}" FAILED. Reviewer opinions cannot overrule deterministic failure.`,
+          resolution: 'CHECK_FAILURE_ENFORCED',
+        });
+        hasCritical = true;
+      }
+    }
+
+    // 3. Detect reviewer-to-reviewer conflicts
+    if (hasApproved && (hasRejected || hasCritical || hasHigh)) {
+      conflicts.push({
+        type: 'REVIEWER_CONTRADICTION',
+        description:
+          'One or more reviewers approved the change while others flagged Critical/High severity risks or rejected it.',
+        resolution: 'RESOLVED_TOWARD_GREATER_SCRUTINY',
+      });
+    }
+
+    // 4. Determine authoritative final verdict based on strict safety rules
+    let finalVerdict = 'APPROVED';
+    let finalSeverity = 'INFO';
+    let reason = '';
+
+    if (results.length === 0) {
+      // Tier 0 Fast-Pass with 0 reviewers is approved if no deterministic check failed
+      if (tier === 0 && !hasCritical) {
+        finalVerdict = 'APPROVED';
+        finalSeverity = 'INFO';
+        reason =
+          'Fast-Pass (Tier 0) verified: Low-risk documentation/styling change with zero risk signals.';
+      } else {
+        finalVerdict = 'REJECTED';
+        finalSeverity = 'HIGH';
+        reason = 'Fail-Closed Invariant: Zero reviewers executed for a change requiring audit.';
+      }
+    } else if (hasCritical) {
+      finalVerdict = 'REJECTED';
+      finalSeverity = 'CRITICAL';
+      reason = 'Rejected due to one or more CRITICAL security or logic findings.';
+    } else if (hasHigh) {
+      finalVerdict = 'REJECTED';
+      finalSeverity = 'HIGH';
+      reason = 'Rejected due to unmitigated HIGH severity findings.';
+    } else if (hasRejected) {
+      finalVerdict = 'REJECTED';
+      finalSeverity = 'HIGH';
+      reason = 'Rejected due to explicit reviewer rejection verdict.';
+    } else if (hasError) {
+      // Any error prevents unconditional approval
+      finalVerdict = 'WARNING';
+      finalSeverity = 'MEDIUM';
+      reason =
+        'Reviewer execution encountered one or more errors or timeouts; cannot grant unconditional approval.';
+    } else if (hasMedium || hasWarning) {
+      finalVerdict = 'WARNING';
+      finalSeverity = 'MEDIUM';
+      reason = 'Approved with warnings: Medium severity findings require developer review.';
+    } else if (hasLow) {
+      finalVerdict = 'WARNING';
+      finalSeverity = 'LOW';
+      reason = 'Approved with minor suggestions: Low severity improvements recommended.';
+    } else {
+      finalVerdict = 'APPROVED';
+      finalSeverity = 'INFO';
+      reason = `All ${reviewersExecuted.length} specialist reviewer(s) approved with zero findings.`;
+    }
+
+    // 5. Epistemic Confidence Calculation
+    let confidence = 'L1';
+    if (hasError) {
+      confidence = 'L3';
+    } else if (hasCritical || hasHigh) {
+      confidence = 'L1';
+    } else if (decision.confidence) {
+      confidence = decision.confidence;
+    }
+
+    return {
+      verdict: finalVerdict,
+      severity: finalSeverity,
+      confidence,
+      reviewersExecuted,
+      findingsCount: {
+        total: allFindings.length,
+        critical: allFindings.filter(f => f.severity === 'CRITICAL').length,
+        high: allFindings.filter(f => f.severity === 'HIGH').length,
+        medium: allFindings.filter(f => f.severity === 'MEDIUM').length,
+        low: allFindings.filter(f => f.severity === 'LOW').length,
+        info: allFindings.filter(f => f.severity === 'INFO').length,
+      },
+      findings: allFindings,
+      conflicts,
+      reason,
+      provenance: {
+        reviewRunId,
+        decisionId: decision.decision_id || null,
+        tier,
+        timestamp: new Date().toISOString(),
+      },
+    };
+  }
+}
+
+module.exports = {
+  VerdictAggregator,
+};

package/src/execution/write_policy_engine.js

@@ -0,0 +1,95 @@
+'use strict';
+
+const path = require('path');
+
+const DEFAULT_SENSITIVE_PATTERNS = [
+  /\.env.*/i,
+  /credentials/i,
+  /secrets/i,
+  /\.pem$/i,
+  /\.key$/i,
+  /\.github[\\/]workflows[\\/]/i,
+  /package(?:-lock)?\.json$/i,
+  /auth/i,
+  /security/i,
+];
+
+const CRITICAL_GOVERNANCE_PATTERNS = [
+  /tribunal-kit[\\/]src[\\/]execution[\\/]/i, // core execution engine
+  /\.agent[\\/]rules[\\/]/i, // core rules
+];
+
+class WritePolicyEngine {
+  constructor(options = {}) {
+    this.sensitivePatterns = options.sensitivePatterns || DEFAULT_SENSITIVE_PATTERNS;
+    this.criticalPatterns = options.criticalPatterns || CRITICAL_GOVERNANCE_PATTERNS;
+  }
+
+  evaluate(request, decision = null) {
+    let hasSensitive = false;
+    let hasCritical = false;
+    const reasons = [];
+
+    // Identity checks
+    if (!request.agentId || request.agentId === 'UNKNOWN_AGENT') {
+      hasSensitive = true;
+      reasons.push('Unverified agent identity requires review.');
+    }
+
+    // File patterns
+    for (const file of request.files) {
+      const normalizedPath = file.path.replace(/\\/g, '/');
+
+      // Check critical
+      if (this.criticalPatterns.some(p => p.test(normalizedPath))) {
+        hasCritical = true;
+        reasons.push(`Critical governance file touched: ${file.path}`);
+      }
+
+      // Check sensitive
+      if (this.sensitivePatterns.some(p => p.test(normalizedPath))) {
+        hasSensitive = true;
+        reasons.push(`Sensitive file pattern matched: ${file.path}`);
+      }
+    }
+
+    // Determine baseline policy from files
+    let policy = 'ALLOW';
+    if (hasCritical) {
+      policy = 'DENY'; // Must be human explicitly, or heavily gated
+    } else if (hasSensitive) {
+      policy = 'REVIEW_REQUIRED';
+    }
+
+    // Override with decision engine tier
+    if (decision) {
+      if (decision.tier > 0 && policy === 'ALLOW') {
+        policy = 'REVIEW_REQUIRED';
+        reasons.push(`Impact tier ${decision.tier} requires review.`);
+      }
+      if (decision.tier >= 3) {
+        // high tier changes might also trigger human approval
+        if (policy !== 'DENY') {
+          policy = 'REVIEW_REQUIRED';
+        }
+      }
+      if (decision.escalated) {
+        policy = 'DENY'; // Or requires human approval
+        reasons.push(`Decision engine escalated: ${decision.escalation_reason}`);
+      }
+    }
+
+    // Always require human approval for DENY or high risk? The prompt says DENY means no LLM alone can ALLOW.
+    return {
+      action: policy,
+      reasons,
+      requiresHumanApproval: policy === 'DENY' || hasCritical || (decision && decision.tier >= 3),
+    };
+  }
+}
+
+module.exports = {
+  WritePolicyEngine,
+  DEFAULT_SENSITIVE_PATTERNS,
+  CRITICAL_GOVERNANCE_PATTERNS,
+};

package/src/intelligence/adaptive_correction.js

@@ -0,0 +1,72 @@
+'use strict';
+
+/**
+ * adaptive_correction.js — Tribunal Intelligence: Adaptive Correction Strategies
+ * ============================================================================
+ * Phase 7K implementation.
+ *
+ * Uses historical evidence to recommend correction approaches for blocked cases.
+ */
+
+const { CaseIndexer } = require('./case_indexer');
+const { CaseMemory } = require('./case_memory');
+
+class AdaptiveCorrection {
+  constructor(options = {}) {
+    this.indexer = options.indexer || new CaseIndexer(options);
+    this.memory = options.memory || new CaseMemory(options);
+  }
+
+  /**
+   * Recommends a correction strategy based on historical successes for similar findings.
+   *
+   * @param {Object} finding The finding object that blocked the transaction
+   * @param {Array} similarCases Historical similar cases
+   * @returns {Object|null} Recommended strategy overlay for the correction engine
+   */
+  recommendCorrection(finding, similarCases) {
+    if (!finding || !finding.category || !similarCases || similarCases.length === 0) return null;
+
+    const strategySuccesses = new Map();
+
+    for (const sim of similarCases) {
+      const caseRecord = this.memory.getCase(sim.caseId);
+      if (!caseRecord || caseRecord.finalVerdict !== 'RESOLVED') continue;
+
+      // Did they encounter a similar finding and successfully correct it?
+      const corrections = caseRecord.correctionAttempts || [];
+      for (const corr of corrections) {
+        if (
+          corr.targetFindingCategory === finding.category &&
+          corr.status === 'SUCCESS' &&
+          corr.strategyApplied
+        ) {
+          const stratId = corr.strategyApplied;
+          strategySuccesses.set(stratId, (strategySuccesses.get(stratId) || 0) + 1);
+        }
+      }
+    }
+
+    if (strategySuccesses.size === 0) return null;
+
+    // Find the most successful strategy
+    let bestStrategy = null;
+    let bestCount = 0;
+    for (const [strat, count] of strategySuccesses.entries()) {
+      if (count > bestCount) {
+        bestStrategy = strat;
+        bestCount = count;
+      }
+    }
+
+    if (!bestStrategy) return null;
+
+    return {
+      recommendedStrategy: bestStrategy,
+      historicalSuccessCount: bestCount,
+      advisory: `This is a recommendation based on ${bestCount} historical successes. The agent still proposes the actual change, and Tribunal still governs it.`,
+    };
+  }
+}
+
+module.exports = { AdaptiveCorrection };

package/src/intelligence/adaptive_reviewer_orchestrator.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * adaptive_reviewer_orchestrator.js — Tribunal Intelligence
+ * ============================================================================
+ * Phase 7F implementation.
+ *
+ * Upgrades the static ReviewerOrchestrator decision layer with historical Case Intelligence.
+ *
+ * Contract:
+ * - Adaptive selection may optimize (add/reorder) optional reviewer choice.
+ * - Adaptive selection may NOT remove mandatory safety reviewers selected by the deterministic engine.
+ */
+
+const { orchestrateReviewers } = require('../system1/reviewer_orchestrator');
+const { ReviewerPerformance } = require('./reviewer_performance');
+
+class AdaptiveReviewerOrchestrator {
+  constructor(options = {}) {
+    this.performanceStore = options.performanceStore || new ReviewerPerformance(options);
+  }
+
+  /**
+   * Orchestrates reviewers using both deterministic safety and historical intelligence.
+   *
+   * @param {Object} options Standard orchestrator options (tier, files, diff, task, evidence, previousFindings, forcedReviewers)
+   * @param {Object} query Context for historical analysis
+   * @returns {Object} Upgraded orchestration payload
+   */
+  adaptReviewers(options, query = {}) {
+    // 1. Run Baseline Deterministic Engine
+    // This establishes the absolute minimum safety floor.
+    const baseline = orchestrateReviewers(options);
+
+    // Short circuit if Tier 0 limits reviewers absolutely
+    if (baseline.total_selected === 0) {
+      return baseline;
+    }
+
+    const { selected, rejected, coverage } = baseline;
+    const { impactTier, files, categories } = query;
+
+    // 2. Fetch Performance Intelligence
+    // Retrieve historical effectiveness of selected reviewers
+    const adaptiveSelected = [];
+    const safetyRequiredNames = new Set(selected.map(r => r.reviewer));
+
+    for (const reviewer of selected) {
+      const stats = this.performanceStore.getReviewerStats(reviewer.reviewer);
+      let boostedScore = reviewer.score;
+      let reasoning = reviewer.reason;
+
+      if (stats.reliabilityScore !== null) {
+        if (stats.reliabilityScore > 0.8) {
+          boostedScore += 0.2;
+          reasoning += ` | Historical performance indicates high reliability (${(stats.reliabilityScore * 100).toFixed(0)}%).`;
+        } else if (stats.reliabilityScore < 0.4) {
+          boostedScore -= 0.2;
+          reasoning += ` | Historical performance is poor; retained due to mandatory safety policy.`;
+        }
+      }
+
+      adaptiveSelected.push({
+        ...reviewer,
+        score: parseFloat(boostedScore.toFixed(2)),
+        reason: reasoning,
+        _isMandatorySafety: true, // Tagged to ensure it can never be removed
+      });
+    }
+
+    // 3. Optional additions based on historical Similar Cases
+    // If we have similarity insights, we might pull in a rejected reviewer.
+    // E.g., a Database reviewer on an API tier change because previously similar API changes masked DB risks.
+    if (query.similarCases && query.similarCases.length > 0) {
+      // Collect reviewers that were historically present in successful similarity matches
+      const historicalUsefulSet = new Set();
+      for (const simCase of query.similarCases) {
+        if (simCase.confidence === 'HIGH' || simCase.similarityScore >= 0.7) {
+          const histRecord = this.performanceStore.memory.getCase(simCase.caseId);
+          if (histRecord && histRecord.finalVerdict === 'RESOLVED') {
+            // If they caught things in the past successfully
+            (histRecord.selectedReviewers || []).forEach(r => historicalUsefulSet.add(r));
+          }
+        }
+      }
+
+      const tierCapacityMap = { 0: 0, 1: 1, 2: 3, 3: 8 };
+      let availableCapacity = (tierCapacityMap[options.tier] || 1) - adaptiveSelected.length;
+
+      // Sort rejected by their historical usefulness
+      const adaptiveRejected = [];
+      for (const rejectedReq of rejected) {
+        if (historicalUsefulSet.has(rejectedReq.reviewer) && availableCapacity > 0) {
+          // Elevate this reviewer
+          adaptiveSelected.push({
+            reviewer: rejectedReq.reviewer,
+            reason: `${rejectedReq.reason} | ADAPTIVE OVERRIDE: Historically necessary for highly similar cases.`,
+            risk_covered: 'adaptive_historical',
+            evidence_supplied: [],
+            expected_contribution:
+              'Historical precedent indicates hidden risks in this change profile.',
+            score: 0.5,
+            _isMandatorySafety: false,
+          });
+          availableCapacity--;
+        } else {
+          adaptiveRejected.push(rejectedReq);
+        }
+      }
+      baseline.rejected = adaptiveRejected;
+    }
+
+    // 4. Re-sort by intelligence boosted scores
+    adaptiveSelected.sort((a, b) => b.score - a.score);
+
+    baseline.selected = adaptiveSelected;
+    baseline.total_selected = adaptiveSelected.length;
+
+    return baseline;
+  }
+}
+
+module.exports = { AdaptiveReviewerOrchestrator };

package/src/intelligence/case_indexer.js

@@ -0,0 +1,166 @@
+'use strict';
+
+/**
+ * case_indexer.js — Tribunal Intelligence: Case Indexing
+ * ============================================================================
+ * Phase 7C implementation of efficient local-first case indexing.
+ *
+ * Maintains a live metadata index of all finalized cases, enabling O(1) or O(N)
+ * sweeps over case metadata without incurring full filesystem reads for payload bodies.
+ *
+ * It helps answer:
+ * - Have we seen this type of change before?
+ * - Have we seen this file before?
+ * - Have we seen this finding before?
+ * - Which reviewers performed well on similar cases?
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class CaseIndexer {
+  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.indexPath = path.join(this.intelligenceDir, 'cases.index.json');
+
+    this.index = {
+      cases: {}, // caseId -> structured metadata
+      byImpactTier: {}, // tier -> Set of caseIds
+      byFailureMode: {}, // mode -> Set of caseIds
+      byFile: {}, // filePath -> Set of caseIds
+      byReviewer: {}, // reviewerId -> Set of caseIds
+    };
+    this._loadIndex();
+  }
+
+  _loadIndex() {
+    if (fs.existsSync(this.indexPath)) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(this.indexPath, 'utf8'));
+        this.index.cases = raw.cases || {};
+
+        // Deserialize sets
+        ['byImpactTier', 'byFailureMode', 'byFile', 'byReviewer'].forEach(key => {
+          this.index[key] = {};
+          if (raw[key]) {
+            for (const [k, arr] of Object.entries(raw[key])) {
+              this.index[key][k] = new Set(arr);
+            }
+          }
+        });
+      } catch (e) {
+        console.warn('[Tribunal Case Indexer] Failed to load index, starting fresh.', e);
+      }
+    }
+  }
+
+  _saveIndex() {
+    // Serialize sets
+    const serialized = {
+      cases: this.index.cases,
+      byImpactTier: {},
+      byFailureMode: {},
+      byFile: {},
+      byReviewer: {},
+    };
+
+    ['byImpactTier', 'byFailureMode', 'byFile', 'byReviewer'].forEach(key => {
+      for (const [k, set] of Object.entries(this.index[key])) {
+        serialized[key][k] = Array.from(set);
+      }
+    });
+
+    if (!fs.existsSync(this.intelligenceDir)) {
+      fs.mkdirSync(this.intelligenceDir, { recursive: true });
+    }
+
+    // Atomic write to prevent index corruption
+    const tempPath = this.indexPath + '.tmp';
+    fs.writeFileSync(tempPath, JSON.stringify(serialized, null, 2), 'utf8');
+    fs.renameSync(tempPath, this.indexPath);
+  }
+
+  _addToSet(indexMap, key, value) {
+    if (!indexMap[key]) indexMap[key] = new Set();
+    indexMap[key].add(value);
+  }
+
+  /**
+   * Adds a finalized case to the index.
+   * Called automatically by CaseMemory.storeCase in an integrated system,
+   * or lazily via batch processors.
+   *
+   * @param {Object} caseRecord The fully structured case.
+   */
+  indexCase(caseRecord) {
+    if (!caseRecord || !caseRecord.caseId) return;
+
+    const { caseId } = caseRecord;
+
+    // Build indexing metadata
+    const files = Array.isArray(caseRecord.changeFingerprint?.files)
+      ? caseRecord.changeFingerprint.files
+      : [];
+
+    const failureModes = caseRecord.failureModes || [];
+    const impactTier = caseRecord.impactTier || 'UNKNOWN';
+    const reviewers = caseRecord.selectedReviewers || [];
+
+    // Persist small fast-scan metadata
+    this.index.cases[caseId] = {
+      timestamp: caseRecord.timestamp,
+      impactTier,
+      finalVerdict: caseRecord.finalVerdict,
+      correctionCount: (caseRecord.correctionAttempts || []).length,
+      latency: caseRecord.latency,
+      tokenInput: caseRecord.tokenUsage?.input || 0,
+    };
+
+    // Update reverse-lookup sets
+    this._addToSet(this.index.byImpactTier, impactTier, caseId);
+
+    failureModes.forEach(mode => this._addToSet(this.index.byFailureMode, mode, caseId));
+    files.forEach(f => this._addToSet(this.index.byFile, f, caseId));
+    reviewers.forEach(r => this._addToSet(this.index.byReviewer, r, caseId));
+
+    this._saveIndex();
+  }
+
+  /**
+   * Fast queries over the index
+   */
+  getCasesByFile(filePath) {
+    return Array.from(this.index.byFile[filePath] || []);
+  }
+
+  getCasesByImpactTier(tier) {
+    return Array.from(this.index.byImpactTier[tier] || []);
+  }
+
+  getCasesByFailureMode(mode) {
+    return Array.from(this.index.byFailureMode[mode] || []);
+  }
+
+  getReviewerPerformanceSignals(reviewerName) {
+    const caseIds = Array.from(this.index.byReviewer[reviewerName] || []);
+    const casesAppeared = caseIds.length;
+    let regressionsAssociated = 0;
+
+    // Scan light metadata
+    for (const cid of caseIds) {
+      if (this.index.byFailureMode['REGRESSION']?.has(cid)) {
+        regressionsAssociated++;
+      }
+    }
+
+    return {
+      casesAppeared,
+      regressionsAssociated,
+      reliabilityScore: casesAppeared === 0 ? null : 1.0 - regressionsAssociated / casesAppeared,
+    };
+  }
+}
+
+module.exports = { CaseIndexer };