tribunal-kit 9.2.5 → 9.2.7

package/.agent/scripts/materiality_engine.js

@@ -0,0 +1,251 @@
+'use strict';
+
+/**
+ * materiality_engine.js — Tribunal Kit Materiality & Proportionality Engine
+ * =========================================================================
+ * Implements Phase 3.2 & Section 5 / 11 of Outcome Optimization:
+ *   - Materiality Classification (MATERIAL / NON_MATERIAL / OPTIONAL)
+ *   - Materiality Rationale Generation
+ *   - Minimum Sufficient Engineering Enforcement
+ *   - Outcome Budget & Proportionality Checks
+ */
+
+const LOW_COMPLEXITY_TRIGGERS = [
+  /(?:static|landing page|read-?only|documentation|readme|format|css|typo|rename|mock|demo|poc|prototype|internal tool|cli)/i,
+];
+
+const HIGH_SCALE_OVERENGINEERING_FLAGS = [
+  {
+    match: /(?:kafka|rabbitmq|event-sourcing|cqrs)/i,
+    name: 'Event Streaming / CQRS',
+    threshold: 'Requires high-throughput async decoupling',
+  },
+  {
+    match: /(?:kubernetes|k8s|service-mesh|istio)/i,
+    name: 'Service Mesh / Container Orchestration',
+    threshold: 'Requires multi-container fleet governance',
+  },
+  {
+    match: /(?:multi-region|distributed-tracing|opentelemetry)/i,
+    name: 'Multi-Region Replication / APM Tracing',
+    threshold: 'Requires distributed enterprise architecture',
+  },
+  {
+    match: /(?:redis|memcached)/i,
+    name: 'Distributed In-Memory Caching',
+    threshold: 'Requires high-frequency query caching',
+  },
+];
+
+/**
+ * Evaluate materiality for each engineering consideration.
+ *
+ * @param {Array<Object>} considerations - List of considerations from consideration_engine
+ * @param {string} taskQuery - User task query
+ * @param {Object} [conceptData] - Extracted concept metadata
+ * @returns {Object} Materiality evaluation summary and categorized lists
+ */
+function evaluateMateriality(considerations = [], taskQuery = '', conceptData = {}) {
+  const q = (taskQuery || '').toLowerCase();
+  const isSimpleTask =
+    LOW_COMPLEXITY_TRIGGERS.some(r => r.test(q)) &&
+    !/(?:payment|auth|database|distributed|crypto|checkout)/i.test(q);
+  const risks = conceptData.risk_signals || [];
+
+  const evaluated = [];
+  const material = [];
+  const nonMaterial = [];
+  const optional = [];
+
+  for (const c of considerations) {
+    let status = 'MATERIAL';
+    let rationale = '';
+    const sev = (c.severity || 'MEDIUM').toUpperCase();
+    const title = c.title || '';
+    const cat = c.category || '';
+
+    // 1. Critical safety, financial, or auth issues are always MATERIAL
+    if (sev === 'CRITICAL') {
+      status = 'MATERIAL';
+      rationale = `Critical severity: failure directly compromises ${cat.toLowerCase()} (${title}).`;
+    }
+    // 2. High severity considerations mapped to active risk signals are MATERIAL
+    else if (sev === 'HIGH') {
+      const hasMatchingRisk = risks.some(
+        r =>
+          r.toLowerCase().includes(cat.toLowerCase()) ||
+          r.toLowerCase().includes(title.toLowerCase()),
+      );
+      if (hasMatchingRisk || !isSimpleTask) {
+        status = 'MATERIAL';
+        rationale = `High operational/integrity impact: unhandled condition causes ${title.toLowerCase()} failure under concurrent or fault conditions.`;
+      } else {
+        status = 'OPTIONAL';
+        rationale = `Task context indicates a lightweight/simple scope where ${title.toLowerCase()} provides hygiene but is not strictly blocking for MVP.`;
+      }
+    }
+    // 3. Medium severity considerations evaluated against scope
+    else if (sev === 'MEDIUM') {
+      if (isSimpleTask) {
+        status = 'NON_MATERIAL';
+        rationale = `Non-material for simple/lightweight task: implementing ${title.toLowerCase()} introduces unnecessary architectural complexity without commensurate risk reduction.`;
+      } else {
+        status = 'OPTIONAL';
+        rationale = `Recommended enhancement: ${title.toLowerCase()} improves observability/maintainability but does not block functional core.`;
+      }
+    }
+    // 4. Low severity is generally non-material or optional
+    else {
+      status = isSimpleTask ? 'NON_MATERIAL' : 'OPTIONAL';
+      rationale = `Discretionary consideration with minor risk impact.`;
+    }
+
+    const item = {
+      ...c,
+      materiality: status,
+      materiality_rationale: rationale,
+    };
+
+    evaluated.push(item);
+    if (status === 'MATERIAL') material.push(item);
+    else if (status === 'NON_MATERIAL') nonMaterial.push(item);
+    else optional.push(item);
+  }
+
+  return {
+    total_considerations: considerations.length,
+    material_count: material.length,
+    non_material_count: nonMaterial.length,
+    optional_count: optional.length,
+    material,
+    non_material: nonMaterial,
+    optional,
+    all_evaluated: evaluated,
+  };
+}
+
+/**
+ * Enforce the Minimum Sufficient Engineering principle.
+ * Detects both overengineering (introducing heavy infrastructure unnecessarily)
+ * and underengineering (omitting mandatory safeguards).
+ *
+ * @param {string} taskQuery - User task query
+ * @param {Array<string>} proposedSkillsOrComponents - Skills or components selected
+ * @param {Object} [context]
+ * @returns {Object} Proportionality evaluation
+ */
+function checkMinimumSufficientEngineering(
+  taskQuery = '',
+  proposedSkillsOrComponents = [],
+  context = {},
+) {
+  const q = (taskQuery || '').toLowerCase();
+  const isSimpleTask =
+    LOW_COMPLEXITY_TRIGGERS.some(r => r.test(q)) &&
+    !/(?:payment|auth|database|distributed|crypto|checkout)/i.test(q);
+  const isFinancialOrCritical = /(?:payment|charge|checkout|billing|order|token|jwt)/i.test(q);
+
+  const proposed = proposedSkillsOrComponents.map(s => s.toLowerCase());
+  const unnecessaryComponents = [];
+  const missingEssentials = [];
+
+  // Overengineering check for simple tasks
+  if (isSimpleTask) {
+    for (const flag of HIGH_SCALE_OVERENGINEERING_FLAGS) {
+      if (proposed.some(p => flag.match.test(p))) {
+        unnecessaryComponents.push({
+          component: flag.name,
+          reason: `Violates minimum sufficient engineering: Task is a simple/lightweight request; ${flag.threshold}.`,
+        });
+      }
+    }
+  }
+
+  // Underengineering check for critical/financial tasks
+  if (isFinancialOrCritical) {
+    const hasIdempotencyOrResilience = proposed.some(
+      p => p.includes('idempotenc') || p.includes('resilience') || p.includes('error-resilience'),
+    );
+    const hasDataIntegrityOrDB = proposed.some(
+      p => p.includes('database') || p.includes('transaction') || p.includes('sql'),
+    );
+
+    if (!hasIdempotencyOrResilience) {
+      missingEssentials.push({
+        capability: 'Idempotency & Duplicate Request Protection',
+        reason: 'Financial operations require duplicate charge defense during retries.',
+      });
+    }
+    if (!hasDataIntegrityOrDB) {
+      missingEssentials.push({
+        capability: 'Transaction Integrity & Atomic Rollback',
+        reason:
+          'Multi-step financial mutations must be scoped to atomic database transaction boundaries.',
+      });
+    }
+  }
+
+  const isOverengineered = unnecessaryComponents.length > 0;
+  const isUnderengineered = missingEssentials.length > 0;
+
+  let verdict = 'MINIMUM_SUFFICIENT';
+  if (isOverengineered && isUnderengineered) verdict = 'MISALIGNED';
+  else if (isOverengineered) verdict = 'OVERENGINEERED';
+  else if (isUnderengineered) verdict = 'UNDERENGINEERED';
+
+  return {
+    verdict,
+    is_proportional: !isOverengineered && !isUnderengineered,
+    unnecessary_components: unnecessaryComponents,
+    missing_essentials: missingEssentials,
+    rationale:
+      verdict === 'MINIMUM_SUFFICIENT'
+        ? 'Proposed engineering depth is proportional to task scope, risks, and outcome requirements.'
+        : verdict === 'OVERENGINEERED'
+          ? `Overengineering detected: ${unnecessaryComponents.map(u => u.component).join(', ')} exceed task requirements.`
+          : `Underengineering detected: Missing mandatory capabilities for ${missingEssentials.map(m => m.capability).join(', ')}.`,
+  };
+}
+
+/**
+ * Determine the outcome budget constraints for a given task.
+ *
+ * @param {string} taskQuery
+ * @param {Object} [conceptData]
+ * @returns {Object} Outcome budget
+ */
+function determineOutcomeBudget(taskQuery = '', conceptData = {}) {
+  const q = (taskQuery || '').toLowerCase();
+  const isSimple =
+    LOW_COMPLEXITY_TRIGGERS.some(r => r.test(q)) &&
+    !/(?:payment|auth|database|distributed)/i.test(q);
+  const isDistributed =
+    /(?:distributed|microservice|cluster|multi-region|consensus|raft|paxos|partition)/i.test(q);
+
+  let complexityBudget = 'MEDIUM';
+  let dependencyBudget = 'STANDARD';
+  let operationalBurden = 'LOW';
+
+  if (isSimple) {
+    complexityBudget = 'LOW';
+    dependencyBudget = 'MINIMAL (Zero external infrastructure)';
+    operationalBurden = 'MINIMAL';
+  } else if (isDistributed) {
+    complexityBudget = 'HIGH';
+    dependencyBudget = 'MODULAR (Cloud/Infrastructure supported)';
+    operationalBurden = 'HIGH';
+  }
+
+  return {
+    complexity_budget: complexityBudget,
+    dependency_budget: dependencyBudget,
+    operational_burden: operationalBurden,
+    proportionality_principle: 'MINIMUM_SUFFICIENT_ENGINEERING',
+  };
+}
+
+module.exports = {
+  evaluateMateriality,
+  checkMinimumSufficientEngineering,
+  determineOutcomeBudget,
+};

package/.agent/scripts/mcp_server.js

@@ -16,15 +16,15 @@ class McpServer {
     this.rl = readline.createInterface({
       input: process.stdin,
       output: process.stdout,
-      terminal: false
+      terminal: false,
     });
 
-    this.rl.on('line', (line) => {
+    this.rl.on('line', line => {
       try {
         const req = JSON.parse(line);
         this.handleMessage(req);
       } catch (_err) {
-        this.sendError(null, -32700, "Parse error");
+        this.sendError(null, -32700, 'Parse error');
       }
     });
 
@@ -33,31 +33,32 @@ class McpServer {
       name: `tribunal_${syscallName}`,
       description: `Executes the Tribunal Kit ${syscallName} script securely.`,
       inputSchema: {
-        type: "object",
+        type: 'object',
         properties: {
           args: {
-            type: "array",
-            items: { type: "string" },
-            description: `Arguments to pass. Allowed arguments: ${SYSCALL_MAP[syscallName].allowedArgs.join(', ')}`
-          }
-        }
-      }
+            type: 'array',
+            items: { type: 'string' },
+            description: `Arguments to pass. Allowed arguments: ${SYSCALL_MAP[syscallName].allowedArgs.join(', ')}`,
+          },
+        },
+      },
     }));
-    
+
     // Add DAG dispatch as an exposed MCP tool
     this.tools.push({
-      name: "tribunal_dispatch_dag",
-      description: "Dispatch a Dynamic Directed Acyclic Graph (DAG) for parallel, staged execution.",
+      name: 'tribunal_dispatch_dag',
+      description:
+        'Dispatch a Dynamic Directed Acyclic Graph (DAG) for parallel, staged execution.',
       inputSchema: {
-        type: "object",
+        type: 'object',
         properties: {
           payloadFile: {
-            type: "string",
-            description: "Path to the JSON payload file containing the DAG"
-          }
+            type: 'string',
+            description: 'Path to the JSON payload file containing the DAG',
+          },
         },
-        required: ["payloadFile"]
-      }
+        required: ['payloadFile'],
+      },
     });
   }
 
@@ -67,114 +68,135 @@ class McpServer {
 
   sendError(id, code, message) {
     this.send({
-      jsonrpc: "2.0",
+      jsonrpc: '2.0',
       id: id || null,
-      error: { code, message }
+      error: { code, message },
     });
   }
 
   handleMessage(req) {
-    if (req.method === "initialize") {
+    if (req.method === 'initialize') {
       this.send({
-        jsonrpc: "2.0",
+        jsonrpc: '2.0',
         id: req.id,
         result: {
-          protocolVersion: "2024-11-05",
+          protocolVersion: '2024-11-05',
           capabilities: { tools: {} },
-          serverInfo: { name: "tribunal-mcp", version: "1.0.0" }
-        }
+          serverInfo: { name: 'tribunal-mcp', version: '1.0.0' },
+        },
       });
       return;
     }
 
-    if (req.method === "tools/list") {
+    if (req.method === 'tools/list') {
       this.send({
-        jsonrpc: "2.0",
+        jsonrpc: '2.0',
         id: req.id,
-        result: { tools: this.tools }
+        result: { tools: this.tools },
       });
       return;
     }
 
-    if (req.method === "tools/call") {
+    if (req.method === 'tools/call') {
       this.handleToolCall(req);
       return;
     }
 
     // Ignore unsupported methods gracefully
-    this.sendError(req.id, -32601, "Method not found");
+    this.sendError(req.id, -32601, 'Method not found');
   }
 
   handleToolCall(req) {
     const { name, arguments: args } = req.params;
 
     // Log the MCP interaction natively into the session.jsonl log
-    const eventId = appendEvent('ToolRequested', {
-      tool: name,
-      args: args
-    }, 'mcp-server');
-
-    if (name === "tribunal_dispatch_dag") {
+    const eventId = appendEvent(
+      'ToolRequested',
+      {
+        tool: name,
+        args: args,
+      },
+      'mcp-server',
+    );
+
+    if (name === 'tribunal_dispatch_dag') {
       const payloadFile = args.payloadFile;
       if (!payloadFile) {
-        return this.sendError(req.id, -32602, "Missing payloadFile argument");
+        return this.sendError(req.id, -32602, 'Missing payloadFile argument');
       }
-      
+
       try {
         const { spawnSync } = require('child_process');
         const scriptPath = require('path').join(__dirname, 'swarm_dispatcher.js');
         const result = spawnSync('node', [scriptPath, '--mode', 'dag', '--file', payloadFile], {
           cwd: process.cwd(),
           encoding: 'utf8',
-          timeout: 120000 
+          timeout: 120000,
         });
-        
-        appendEvent('ToolCompleted', { exitCode: result.status, requestEventId: eventId }, 'mcp-server');
+
+        appendEvent(
+          'ToolCompleted',
+          { exitCode: result.status, requestEventId: eventId },
+          'mcp-server',
+        );
         this.send({
-          jsonrpc: "2.0",
+          jsonrpc: '2.0',
           id: req.id,
           result: {
-            content: [{ type: "text", text: result.stdout || (result.stderr ? "Error: " + result.stderr : "Executed.") }]
-          }
+            content: [
+              {
+                type: 'text',
+                text: result.stdout || (result.stderr ? 'Error: ' + result.stderr : 'Executed.'),
+              },
+            ],
+          },
         });
       } catch (err) {
-        this.sendError(req.id, -32603, "Internal execution error: " + err.message);
+        this.sendError(req.id, -32603, 'Internal execution error: ' + err.message);
       }
       return;
     }
 
     // Process syscall registry tools
-    const prefix = "tribunal_";
+    const prefix = 'tribunal_';
     if (name.startsWith(prefix)) {
       const syscall = name.substring(prefix.length);
       const syscallArgs = args.args || [];
-      
+
       const result = executeSyscall(syscall, syscallArgs);
-      
+
       if (result.exitCode === 0) {
-        appendEvent('ToolCompleted', { exitCode: 0, stdout: result.stdout, requestEventId: eventId }, 'mcp-server');
+        appendEvent(
+          'ToolCompleted',
+          { exitCode: 0, stdout: result.stdout, requestEventId: eventId },
+          'mcp-server',
+        );
         this.send({
-          jsonrpc: "2.0",
+          jsonrpc: '2.0',
           id: req.id,
           result: {
-            content: [{ type: "text", text: result.stdout }]
-          }
+            content: [{ type: 'text', text: result.stdout }],
+          },
         });
       } else {
-        appendEvent('ErrorEncountered', { exitCode: result.exitCode, message: result.stderr, requestEventId: eventId }, 'mcp-server');
+        appendEvent(
+          'ErrorEncountered',
+          { exitCode: result.exitCode, message: result.stderr, requestEventId: eventId },
+          'mcp-server',
+        );
         this.send({
-          jsonrpc: "2.0",
+          jsonrpc: '2.0',
           id: req.id,
           result: {
-            content: [{ type: "text", text: "Error: " + result.stderr + "\n" + result.stdout }],
-            isError: true
-          }
+            content: [{ type: 'text', text: 'Error: ' + result.stderr + '\n' + result.stdout }],
+            isError: true,
+          },
         });
       }
       return;
     }
 
-    this.sendError(req.id, -32601, "Tool not found");
+    this.sendError(req.id, -32601, 'Tool not found');
   }
 }
 

package/.agent/scripts/memory_archivist.js

@@ -44,39 +44,43 @@ function saveInstincts(instincts) {
 function archiveSession() {
   const events = readEvents();
   const instincts = loadInstincts();
-  
+
   let currentError = null;
   let newInstinctsCount = 0;
 
   for (const evt of events) {
     if (evt.type === 'ErrorEncountered') {
       currentError = evt;
-    } else if (evt.type === 'ToolCompleted' && currentError && evt.sessionId === currentError.sessionId) {
-      // If we see a successful tool completion shortly after an error in the same session, 
+    } else if (
+      evt.type === 'ToolCompleted' &&
+      currentError &&
+      evt.sessionId === currentError.sessionId
+    ) {
+      // If we see a successful tool completion shortly after an error in the same session,
       // we assume it's a resolution. In a real LLM setup, we'd use an AI pass here to summarize the fix.
       // For now, we stub the instinct generation based on the error.
-      
+
       const errorMsg = currentError.payload.message || 'Unknown error';
-      
+
       // Avoid duplicates
       const exists = instincts.find(i => i.evidence.failedEventId === currentError.eventId);
-      
+
       if (!exists && errorMsg !== 'Unknown error') {
         const newInstinct = {
           id: `instinct_${Date.now()}_${Math.floor(Math.random() * 1000)}`,
-          domain: "auto-archived",
+          domain: 'auto-archived',
           rule: `Avoid pattern that caused: ${errorMsg}`,
           evidence: {
             failedEventId: currentError.eventId,
-            resolutionEventId: evt.eventId
+            resolutionEventId: evt.eventId,
           },
-          confidence: "L3" // L3 because it's auto-generated without human verification
+          confidence: 'L3', // L3 because it's auto-generated without human verification
         };
-        
+
         instincts.push(newInstinct);
         newInstinctsCount++;
       }
-      
+
       // Reset error tracker
       currentError = null;
     }
@@ -84,7 +88,9 @@ function archiveSession() {
 
   if (newInstinctsCount > 0) {
     saveInstincts(instincts);
-    console.log(`✅ Memory Archivist mined ${newInstinctsCount} new instincts from the session log.`);
+    console.log(
+      `✅ Memory Archivist mined ${newInstinctsCount} new instincts from the session log.`,
+    );
   } else {
     console.log(`ℹ️ Memory Archivist found no new verifiable patterns in the session log.`);
   }

package/.agent/scripts/memory_consolidator.js

@@ -2,25 +2,25 @@ const { MemoryEngine } = require('./memory_engine.js');
 
 async function consolidateMemory(agentDir) {
   console.log(`Starting memory consolidation for workspace: ${agentDir}`);
-  
+
   const engine = new MemoryEngine(agentDir);
   const index = engine.loadIndex();
 
   const episodics = index.entries.filter(e => e.memory_type === 'episodic');
   const workings = index.entries.filter(e => e.memory_type === 'working');
-  
+
   if (episodics.length === 0 && workings.length === 0) {
-    console.log("No Episodic or Working memories to consolidate.");
+    console.log('No Episodic or Working memories to consolidate.');
     return;
   }
 
   console.log(`Found ${episodics.length} Episodic and ${workings.length} Working memories.`);
-  console.log("Submitting to LLM for consolidation into Semantic rules...");
+  console.log('Submitting to LLM for consolidation into Semantic rules...');
 
   // Simulation of Tribunal's Maker-Reviewer LLM invocation.
   // In production, this would pass the contexts to the `logic-reviewer` and output a compressed fact.
   const consolidatedContent = `Generalized rule derived from ${episodics.length} episodic events and ${workings.length} working sessions.`;
-  
+
   const semanticId = engine.store({
     type: 'semantic',
     content: consolidatedContent,
@@ -30,7 +30,7 @@ async function consolidateMemory(agentDir) {
   });
 
   console.log(`Generated new Semantic Memory ID: ${semanticId}`);
-  console.log("Consolidation complete. Run `tk memory gc` to clear old working entries.");
+  console.log('Consolidation complete. Run `tk memory gc` to clear old working entries.');
 }
 
 const dir = process.cwd();