tribunal-kit 9.2.5 → 9.2.7

package/src/evolution/engine.js

@@ -0,0 +1,296 @@
+'use strict';
+
+/**
+ * evolution/engine.js — Controlled Self-Evolution Engine for Tribunal Kit
+ * =======================================================================
+ * System-1 Capability 4:
+ * Governs the proposal-driven evolution of reviewer routing, context weights,
+ * heuristics, skill idioms, and regression fixtures while strictly enforcing:
+ *
+ * 1. The Human Gate: No evolution can silently deploy without human approval.
+ * 2. Trust Boundaries: Protected security boundaries, execution policies, and
+ *    package integrity validation can NEVER automatically evolve.
+ * 3. Anti-Self-Poisoning: Follows strict evidence hierarchy:
+ *    VERIFIED_TEST_RESULT > DETERMINISTIC_TELEMETRY > REPRODUCIBLE_PATTERN > REVIEWER_CLAIM
+ *    Proposals based solely on unverified LLM claims are rejected.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const ALLOWED_TARGETS = new Set([
+  'reviewer-routing',
+  'context-weights',
+  'skill-instructions',
+  'reviewer-selection',
+  'deterministic-heuristics',
+  'known-failure-patterns',
+  'workflow-guidance',
+  'regression-fixtures',
+]);
+
+const FORBIDDEN_TARGETS = new Set([
+  'security-boundaries',
+  'shell-execution-policy',
+  'package-integrity',
+  'dependency-pinning',
+  'human-gate',
+  'system1-trust-boundary',
+  'production-security',
+  'arbitrary-executable-code',
+]);
+
+const EVIDENCE_HIERARCHY = {
+  VERIFIED_TEST_RESULT: 4,
+  DETERMINISTIC_TELEMETRY: 3,
+  REPRODUCIBLE_PATTERN: 2,
+  REVIEWER_CLAIM: 1,
+};
+
+/**
+ * Creates and formats a new Evolution Proposal.
+ */
+function createEvolutionProposal({
+  target,
+  currentBehavior,
+  observedEvidence,
+  proposedChange,
+  expectedEffect,
+  risk = 'MEDIUM',
+  testsRequired = [],
+  regressionRequirements = [],
+  evidenceType = 'DETERMINISTIC_TELEMETRY',
+  proposalId = null,
+}) {
+  const id = proposalId || `EVO-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+
+  const proposal = {
+    proposal_id: id,
+    target,
+    current_behavior: currentBehavior,
+    observed_evidence: observedEvidence,
+    proposed_change: proposedChange,
+    expected_effect: expectedEffect,
+    risk: ['LOW', 'MEDIUM', 'HIGH'].includes(String(risk).toUpperCase())
+      ? String(risk).toUpperCase()
+      : 'MEDIUM',
+    tests_required: Array.isArray(testsRequired) ? testsRequired : [testsRequired],
+    regression_requirements: Array.isArray(regressionRequirements)
+      ? regressionRequirements
+      : [regressionRequirements],
+    evidence_type: EVIDENCE_HIERARCHY[evidenceType] ? evidenceType : 'REVIEWER_CLAIM',
+    evidence_weight: EVIDENCE_HIERARCHY[evidenceType] || 1,
+    status: 'PROPOSED',
+    created_at: new Date().toISOString(),
+    approval: null,
+  };
+
+  return proposal;
+}
+
+/**
+ * Validates an evolution proposal against Anti-Self-Poisoning & Security Rules.
+ */
+function validateEvolutionProposal(proposal) {
+  if (!proposal || typeof proposal !== 'object') {
+    return { valid: false, reason: 'Proposal must be an object.' };
+  }
+
+  // 1. Check required fields
+  const requiredFields = [
+    'proposal_id',
+    'target',
+    'current_behavior',
+    'observed_evidence',
+    'proposed_change',
+    'expected_effect',
+    'risk',
+    'tests_required',
+    'regression_requirements',
+  ];
+
+  for (const field of requiredFields) {
+    if (!proposal[field] || (Array.isArray(proposal[field]) && proposal[field].length === 0)) {
+      return {
+        valid: false,
+        reason: `Missing required proposal field: "${field}". Every proposal must be backed by evidence.`,
+      };
+    }
+  }
+
+  // 2. Security boundary enforcement: Forbidden targets cannot evolve automatically
+  if (FORBIDDEN_TARGETS.has(proposal.target)) {
+    return {
+      valid: false,
+      reason: `Target "${proposal.target}" is a protected security boundary. Automatic evolution of security boundaries, shell policies, and package integrity is strictly forbidden.`,
+    };
+  }
+
+  // 3. Allowed target check
+  if (!ALLOWED_TARGETS.has(proposal.target)) {
+    return {
+      valid: false,
+      reason: `Target "${proposal.target}" is not an allowed evolution target. Allowed: ${Array.from(ALLOWED_TARGETS).join(', ')}`,
+    };
+  }
+
+  // 4. Anti-Self-Poisoning Rule: Reject proposals backed solely by unverified claims
+  const evidenceType = proposal.evidence_type || 'REVIEWER_CLAIM';
+  const evidenceWeight = EVIDENCE_HIERARCHY[evidenceType] || 0;
+
+  if (evidenceWeight <= EVIDENCE_HIERARCHY.REVIEWER_CLAIM) {
+    return {
+      valid: false,
+      reason: `Anti-Self-Poisoning violation: Proposal relies solely on "${evidenceType}". Proposals must be backed by reproducible execution patterns, deterministic telemetry, or verified test results.`,
+    };
+  }
+
+  // 5. Evidence content check
+  if (
+    typeof proposal.observed_evidence !== 'string' ||
+    proposal.observed_evidence.trim().length < 10
+  ) {
+    return {
+      valid: false,
+      reason:
+        'Observed evidence is too short or vacuous. Measurable, concrete evidence is required.',
+    };
+  }
+
+  return { valid: true, reason: 'Proposal meets all verification and safety criteria.' };
+}
+
+/**
+ * Storage helpers for proposal persistence.
+ */
+function getProposalsDir(agentDir = path.join(process.cwd(), '.agent')) {
+  return path.join(agentDir, 'evolution', 'proposals');
+}
+
+function findDuplicateProposal(proposal, agentDir) {
+  const existingProposals = loadEvolutionProposals(agentDir);
+  return (
+    existingProposals.find(
+      p =>
+        p.target === proposal.target &&
+        (p.proposed_change === proposal.proposed_change ||
+          JSON.stringify(p.proposed_change) === JSON.stringify(proposal.proposed_change)) &&
+        p.status !== 'REJECTED',
+    ) || null
+  );
+}
+
+function saveEvolutionProposal(proposal, agentDir, options = {}) {
+  const validation = validateEvolutionProposal(proposal);
+  if (!validation.valid) {
+    throw new Error(`Cannot save invalid evolution proposal: ${validation.reason}`);
+  }
+
+  const dir = getProposalsDir(agentDir);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  // Phase 5 Case D: Duplicate proposal detection
+  const duplicate = findDuplicateProposal(proposal, agentDir);
+  if (duplicate) {
+    if (options.throwOnDuplicate !== false) {
+      const err = new Error(
+        `Duplicate evolution proposal detected: matches existing proposal ${duplicate.proposal_id}`,
+      );
+      err.code = 'DUPLICATE_PROPOSAL';
+      err.duplicate = true;
+      err.existing_proposal_id = duplicate.proposal_id;
+      throw err;
+    }
+    return {
+      saved: false,
+      duplicate: true,
+      existing_proposal_id: duplicate.proposal_id,
+      filePath: path.join(dir, `${duplicate.proposal_id}.json`),
+      message: `Duplicate proposal detected: matches existing proposal ${duplicate.proposal_id}`,
+    };
+  }
+
+  const filePath = path.join(dir, `${proposal.proposal_id}.json`);
+  fs.writeFileSync(filePath, JSON.stringify(proposal, null, 2), 'utf8');
+  return filePath;
+}
+
+function loadEvolutionProposals(agentDir) {
+  const dir = getProposalsDir(agentDir);
+  if (!fs.existsSync(dir)) return [];
+
+  const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+  const proposals = [];
+
+  for (const f of files) {
+    try {
+      const p = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+      proposals.push(p);
+    } catch (_) {}
+  }
+
+  return proposals;
+}
+
+/**
+ * Human Gate: Explicitly approve an evolution proposal.
+ */
+function approveEvolutionProposal(proposalId, approverName, agentDir) {
+  if (!approverName || typeof approverName !== 'string') {
+    throw new Error('Human approval requires an explicit approver name/signature.');
+  }
+
+  const dir = getProposalsDir(agentDir);
+  const filePath = path.join(dir, `${proposalId}.json`);
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Evolution proposal not found: ${proposalId}`);
+  }
+
+  const proposal = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  proposal.status = 'APPROVED';
+  proposal.approval = {
+    approved_by: approverName,
+    approved_at: new Date().toISOString(),
+    human_gate_cleared: true,
+  };
+
+  fs.writeFileSync(filePath, JSON.stringify(proposal, null, 2), 'utf8');
+  return proposal;
+}
+
+/**
+ * Reject an evolution proposal.
+ */
+function rejectEvolutionProposal(proposalId, reason, agentDir) {
+  const dir = getProposalsDir(agentDir);
+  const filePath = path.join(dir, `${proposalId}.json`);
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Evolution proposal not found: ${proposalId}`);
+  }
+
+  const proposal = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  proposal.status = 'REJECTED';
+  proposal.rejection = {
+    reason: reason || 'Rejected by developer',
+    rejected_at: new Date().toISOString(),
+  };
+
+  fs.writeFileSync(filePath, JSON.stringify(proposal, null, 2), 'utf8');
+  return proposal;
+}
+
+module.exports = {
+  createEvolutionProposal,
+  validateEvolutionProposal,
+  saveEvolutionProposal,
+  findDuplicateProposal,
+  loadEvolutionProposals,
+  approveEvolutionProposal,
+  rejectEvolutionProposal,
+  ALLOWED_TARGETS,
+  FORBIDDEN_TARGETS,
+  EVIDENCE_HIERARCHY,
+};

package/src/mcp/server.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-"use strict";
+'use strict';
 
 /**
  * Compatibility entry point for the historical src/mcp/server.js path.
  * bin/mcp-server.js is the single canonical MCP implementation.
  */
-module.exports = require("../../bin/mcp-server.js");
+module.exports = require('../../bin/mcp-server.js');

package/src/synthesis/claim_check_separator.js

@@ -0,0 +1,294 @@
+'use strict';
+
+/**
+ * claim_check_separator.js — Strict Separation of Implementation Checks vs Evidence Claims
+ * =========================================================================================
+ * System-1 Capability 3:
+ * Separates what Tribunal Kit actually verified by deterministic execution from what
+ * an AI reviewer merely claimed.
+ *
+ * Directives:
+ * 1. Never represent an evidence claim as a verified implementation fact.
+ * 2. Synthesis distinguishes VERIFIED from CLAIMED.
+ * 3. Preserve provenance for every check and claim.
+ * 4. Do not fabricate confidence scores (if unavailable, mark as 'UNAVAILABLE').
+ * 5. Resolve conflicts deterministically (verified execution > AI claims).
+ */
+
+const crypto = require('crypto');
+
+/**
+ * Creates a verified implementation check record.
+ * Must be produced by deterministic executable verification.
+ */
+function createImplementationCheck({
+  check,
+  command = null,
+  result,
+  details = null,
+  timestamp = null,
+  runId = null,
+}) {
+  if (!check || typeof check !== 'string') {
+    throw new Error('Implementation check must specify a valid check name.');
+  }
+
+  const normalizedResult = String(result).toUpperCase();
+  if (!['PASSED', 'FAILED', 'ERROR'].includes(normalizedResult)) {
+    throw new Error(`Invalid check result: ${result}. Must be PASSED, FAILED, or ERROR.`);
+  }
+
+  const ts = timestamp || new Date().toISOString();
+  const id = runId || `chk_${crypto.randomBytes(6).toString('hex')}`;
+
+  return {
+    check,
+    command: command || null,
+    result: normalizedResult,
+    details: details || null,
+    timestamp: ts,
+    run_id: id,
+    provenance: {
+      type: 'IMPLEMENTATION_CHECK',
+      command: command || null,
+      timestamp: ts,
+      run_id: id,
+      verified_by: 'executable_runner',
+    },
+  };
+}
+
+/**
+ * Creates an evidence claim record.
+ * Produced by LLM or inferred from non-executable review.
+ */
+function createEvidenceClaim({
+  claimId = null,
+  reviewer,
+  source = null,
+  file = null,
+  line = null,
+  evidence = null,
+  assertion,
+  category = 'general',
+  confidence = 'UNAVAILABLE',
+}) {
+  if (!reviewer || typeof reviewer !== 'string') {
+    throw new Error('Evidence claim must specify a reviewer name.');
+  }
+  if (!assertion || typeof assertion !== 'string') {
+    throw new Error('Evidence claim must specify an assertion statement.');
+  }
+
+  const id = claimId || `clm_${crypto.randomBytes(6).toString('hex')}`;
+
+  let normConfidence = 'UNAVAILABLE';
+  if (confidence !== 'UNAVAILABLE' && confidence !== null && confidence !== undefined) {
+    if (
+      typeof confidence === 'number' &&
+      !isNaN(confidence) &&
+      confidence >= 0 &&
+      confidence <= 1
+    ) {
+      normConfidence = parseFloat(confidence.toFixed(2));
+    } else if (
+      typeof confidence === 'string' &&
+      ['L1', 'L2', 'L3', 'L4', 'L5'].includes(confidence.toUpperCase())
+    ) {
+      normConfidence = confidence.toUpperCase();
+    }
+  }
+
+  return {
+    claim_id: id,
+    reviewer,
+    source: source || reviewer,
+    assertion,
+    category,
+    status: 'CLAIMED', // Claims can never initialize as VERIFIED
+    confidence: normConfidence,
+    provenance: {
+      reviewer,
+      source: source || reviewer,
+      file: file || null,
+      line: typeof line === 'number' ? line : null,
+      evidence: evidence || null,
+    },
+  };
+}
+
+/**
+ * Correlates and synthesizes implementation checks with reviewer claims.
+ */
+function synthesizeReviewResults({ checks = [], claims = [], runId = null, timestamp = null }) {
+  const ts = timestamp || new Date().toISOString();
+  const synthesisId = runId || `syn_${crypto.randomBytes(6).toString('hex')}`;
+
+  const validChecks = checks.map(c => (c.provenance ? c : createImplementationCheck(c)));
+  const validClaims = claims.map(c => (c.provenance ? c : createEvidenceClaim(c)));
+
+  const conflicts = [];
+  const verifiedItems = [];
+  const claimedItems = [];
+
+  // Categorize checks
+  const passedChecks = validChecks.filter(c => c.result === 'PASSED');
+  const failedChecks = validChecks.filter(c => c.result === 'FAILED' || c.result === 'ERROR');
+
+  for (const check of passedChecks) {
+    verifiedItems.push({
+      item: check.check,
+      status: 'VERIFIED',
+      provenance: check.provenance,
+    });
+  }
+
+  // Detect conflicts between checks and claims
+  for (const claim of validClaims) {
+    const claimText = (claim.assertion + ' ' + (claim.provenance?.evidence || '')).toLowerCase();
+
+    // Conflict Scenario 1: Check passed but reviewer claims failure/vulnerability in that area
+    if (
+      claim.category === 'test' &&
+      claimText.includes('fail') &&
+      passedChecks.some(c => c.check === 'tests_passed')
+    ) {
+      conflicts.push({
+        type: 'CHECK_PASSED_CLAIM_FAILED',
+        description: `Reviewer ${claim.reviewer} claimed tests failed, but tests_passed check PASSED deterministically.`,
+        check: 'tests_passed',
+        claim_id: claim.claim_id,
+        resolution: 'DETERMINISTIC_CHECK_PRESERVED',
+      });
+      claim.status = 'CLAIM_OVERRULED_BY_CHECK';
+    } else if (
+      claim.category === 'lint' &&
+      claimText.includes('fail') &&
+      passedChecks.some(c => c.check === 'lint_passed')
+    ) {
+      conflicts.push({
+        type: 'CHECK_PASSED_CLAIM_FAILED',
+        description: `Reviewer ${claim.reviewer} claimed lint failed, but lint_passed check PASSED deterministically.`,
+        check: 'lint_passed',
+        claim_id: claim.claim_id,
+        resolution: 'DETERMINISTIC_CHECK_PRESERVED',
+      });
+      claim.status = 'CLAIM_OVERRULED_BY_CHECK';
+    }
+
+    // Conflict Scenario 2: Check failed but reviewer claims success or approves
+    if (
+      claimText.includes('passed') ||
+      claimText.includes('success') ||
+      claimText.includes('approved')
+    ) {
+      const relatedFailedCheck = failedChecks.find(fc => {
+        const checkBase = fc.check.replace('_passed', '').toLowerCase();
+        const checkSpace = checkBase.replace(/_/g, ' ');
+        return (
+          claimText.includes(checkBase) ||
+          claimText.includes(checkSpace) ||
+          (claim.category && claim.category.toLowerCase().includes(checkBase.split('_')[0]))
+        );
+      });
+      if (relatedFailedCheck) {
+        conflicts.push({
+          type: 'CHECK_FAILED_CLAIM_PASSED',
+          description: `Reviewer ${claim.reviewer} claimed success, but ${relatedFailedCheck.check} FAILED. Reviewer claim cannot override failing check.`,
+          check: relatedFailedCheck.check,
+          claim_id: claim.claim_id,
+          resolution: 'CHECK_FAILURE_ENFORCED',
+        });
+        claim.status = 'CLAIM_REJECTED_CHECK_FAILED';
+      }
+    }
+
+    // Add to claimedItems preserving claim status and provenance
+    claimedItems.push({
+      claim_id: claim.claim_id,
+      reviewer: claim.reviewer,
+      assertion: claim.assertion,
+      status: claim.status,
+      confidence: claim.confidence,
+      provenance: claim.provenance,
+    });
+  }
+
+  // Detect reviewer vs reviewer conflicts on same file:line
+  const claimMap = new Map();
+  for (const claim of validClaims) {
+    const loc = claim.provenance?.file
+      ? `${claim.provenance.file}:${claim.provenance.line || 0}`
+      : null;
+    if (loc) {
+      if (!claimMap.has(loc)) claimMap.set(loc, []);
+      claimMap.get(loc).push(claim);
+    }
+  }
+
+  for (const [loc, locClaims] of claimMap.entries()) {
+    if (locClaims.length >= 2) {
+      const revA = locClaims[0];
+      const revB = locClaims[1];
+      const textA = revA.assertion.toLowerCase();
+      const textB = revB.assertion.toLowerCase();
+
+      const aSaysIssue =
+        textA.includes('vulnerab') ||
+        textA.includes('insecure') ||
+        textA.includes('bug') ||
+        textA.includes('error');
+      const bSaysSafe =
+        textB.includes('safe') ||
+        textB.includes('correct') ||
+        textB.includes('approved') ||
+        textB.includes('clean');
+
+      if ((aSaysIssue && bSaysSafe) || (textA.includes('safe') && textB.includes('bug'))) {
+        conflicts.push({
+          type: 'REVIEWER_OPPOSITE_CLAIMS',
+          description: `Reviewer ${revA.reviewer} and ${revB.reviewer} make opposite claims regarding ${loc}.`,
+          location: loc,
+          claim_ids: [revA.claim_id, revB.claim_id],
+          resolution: 'UNVERIFIED_CONFLICT_PRESERVED',
+        });
+        revA.status = 'CLAIM_CONFLICT';
+        revB.status = 'CLAIM_CONFLICT';
+      }
+    }
+  }
+
+  // Compute final verdict
+  let verdict = 'VERIFIED';
+  if (failedChecks.length > 0) {
+    verdict = 'FAILED_CHECKS';
+  } else if (conflicts.length > 0) {
+    verdict = 'CONFLICT';
+  } else if (verifiedItems.length === 0 && claimedItems.length > 0) {
+    verdict = 'CLAIMED';
+  }
+
+  return {
+    synthesis_id: synthesisId,
+    timestamp: ts,
+    checks: validChecks,
+    claims: validClaims,
+    summary: {
+      total_checks: validChecks.length,
+      passed_checks: passedChecks.length,
+      failed_checks: failedChecks.length,
+      total_claims: validClaims.length,
+      conflict_count: conflicts.length,
+      verdict,
+    },
+    verified_items: verifiedItems,
+    claimed_items: claimedItems,
+    conflicts,
+  };
+}
+
+module.exports = {
+  createImplementationCheck,
+  createEvidenceClaim,
+  synthesizeReviewResults,
+};