tribunal-kit 9.2.7 → 9.2.8

package/.agent/scripts/blast_radius_engine.js

@@ -1,274 +1,274 @@
-#!/usr/bin/env node
-/**
- * blast_radius_engine.js — Tribunal Architectural Blast Radius Engine
- * ═════════════════════════════════════════════════════════════════════════════
- * Answers: "If I modify or break this component, what is affected?"
- *
- * Computes:
- *   - Direct Dependents (Immediate Callers/Importers)
- *   - Transitive Closure (Full Downstream Blast Radius)
- *   - Affected API Routes & Endpoints
- *   - Affected Data Stores & Queries
- *   - Affected Trust Boundaries & Security Zones
- *   - Required Test Suites to Re-verify
- *   - Architectural Centrality & Risk Score (0.0 to 1.0)
- *
- * Zero external dependencies.
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const {
-  GREEN,
-  YELLOW,
-  CYAN,
-  RED,
-  BOLD,
-  RESET,
-  BOX,
-  banner,
-  timer,
-  formatMs,
-} = require('./_colors');
-
-class BlastRadiusEngine {
-  constructor(model) {
-    this.model = model;
-    this.entityMap = new Map();
-    this.dependentsMap = new Map(); // target -> Set of sources that depend on target
-    this.dependenciesMap = new Map(); // source -> Set of targets that source depends on
-
-    this.initGraph();
-  }
-
-  initGraph() {
-    for (const e of this.model.entities || []) {
-      this.entityMap.set(e.id, e);
-      this.dependentsMap.set(e.id, new Set());
-      this.dependenciesMap.set(e.id, new Set());
-    }
-
-    for (const rel of this.model.relationships || []) {
-      if (this.dependentsMap.has(rel.targetId)) {
-        this.dependentsMap.get(rel.targetId).add(rel.sourceId);
-      }
-      if (this.dependenciesMap.has(rel.sourceId)) {
-        this.dependenciesMap.get(rel.sourceId).add(rel.targetId);
-      }
-    }
-  }
-
-  findEntity(query) {
-    if (!query) return null;
-    const clean = query.trim();
-
-    // Direct ID match
-    if (this.entityMap.has(clean)) return this.entityMap.get(clean);
-
-    // Path or partial match
-    for (const [id, e] of this.entityMap.entries()) {
-      if (e.name === clean || e.scope === clean) return e;
-      if (e.sources && e.sources.some(s => s.file === clean || s.file.endsWith(clean))) return e;
-      if (id.toLowerCase().includes(clean.toLowerCase())) return e;
-    }
-    return null;
-  }
-
-  computeBlastRadius(targetQuery, maxDepth = 15) {
-    const rootEntity = this.findEntity(targetQuery);
-    if (!rootEntity) {
-      return {
-        found: false,
-        query: targetQuery,
-        error: `Component or file "${targetQuery}" not found in architectural model.`,
-      };
-    }
-
-    const visited = new Set([rootEntity.id]);
-    const directDependents = new Set();
-    const transitiveRings = []; // Array of Sets per depth level
-
-    let currentLevel = new Set(this.dependentsMap.get(rootEntity.id) || []);
-    for (const d of currentLevel) directDependents.add(d);
-
-    let depth = 1;
-    while (currentLevel.size > 0 && depth <= maxDepth) {
-      const ringEntities = [];
-      const nextLevel = new Set();
-
-      for (const id of currentLevel) {
-        if (!visited.has(id)) {
-          visited.add(id);
-          const entity = this.entityMap.get(id);
-          if (entity) ringEntities.push(entity);
-
-          const upstreams = this.dependentsMap.get(id) || [];
-          for (const up of upstreams) {
-            if (!visited.has(up)) {
-              nextLevel.add(up);
-            }
-          }
-        }
-      }
-
-      if (ringEntities.length > 0) {
-        transitiveRings.push({ depth, count: ringEntities.length, entities: ringEntities });
-      }
-      currentLevel = nextLevel;
-      depth++;
-    }
-
-    // Collect all affected entities (excluding root)
-    const affectedEntities = Array.from(visited)
-      .filter(id => id !== rootEntity.id)
-      .map(id => this.entityMap.get(id))
-      .filter(Boolean);
-
-    // Categorize Impact
-    const affectedEndpoints = affectedEntities.filter(e => e.kind === 'endpoint');
-    const affectedDatastores = affectedEntities.filter(
-      e => e.kind === 'datastore' || e.kind === 'cache',
-    );
-    const affectedQueues = affectedEntities.filter(
-      e => e.kind === 'queue' || e.kind === 'event_bus',
-    );
-    const affectedTests = affectedEntities.filter(
-      e => e.kind === 'test_suite' || e.scope?.includes('test'),
-    );
-
-    // Check Trust Zone Crossings
-    const rootZone = rootEntity.trustZone || 'unknown';
-    const crossedZones = new Set();
-    for (const e of affectedEntities) {
-      if (e.trustZone && e.trustZone !== rootZone) {
-        crossedZones.add(e.trustZone);
-      }
-    }
-
-    // Risk Calculation (0.0 to 1.0)
-    // Centrality + Blast scope + Security Crossing
-    const totalEntities = this.entityMap.size || 1;
-    const impactRatio = affectedEntities.length / totalEntities;
-    const directCoupling = directDependents.size;
-    const securityPenalty =
-      crossedZones.has('public_untrusted') || crossedZones.has('dmz_gateway') ? 0.3 : 0.1;
-
-    let riskScore = Math.min(1.0, impactRatio * 2.5 + directCoupling * 0.05 + securityPenalty);
-    riskScore = Math.round(riskScore * 100) / 100;
-
-    let riskTier = 'LOW';
-    if (riskScore >= 0.7) riskTier = 'CRITICAL';
-    else if (riskScore >= 0.4) riskTier = 'HIGH';
-    else if (riskScore >= 0.2) riskTier = 'MEDIUM';
-
-    return {
-      found: true,
-      target: {
-        id: rootEntity.id,
-        name: rootEntity.name,
-        kind: rootEntity.kind,
-        scope: rootEntity.scope,
-        trustZone: rootEntity.trustZone,
-      },
-      metrics: {
-        directDependentsCount: directDependents.size,
-        transitiveDependentsCount: affectedEntities.length,
-        maxDepthReached: transitiveRings.length,
-        riskScore,
-        riskTier,
-      },
-      impactBreakdown: {
-        endpoints: affectedEndpoints.map(e => ({ id: e.id, name: e.name, scope: e.scope })),
-        datastores: affectedDatastores.map(e => ({ id: e.id, name: e.name })),
-        queues: affectedQueues.map(e => ({ id: e.id, name: e.name })),
-        testSuites: affectedTests.map(e => ({ id: e.id, name: e.name, scope: e.scope })),
-        securityZonesCrossed: Array.from(crossedZones),
-      },
-      transitiveRings,
-    };
-  }
-}
-
-// ── Standalone CLI ────────────────────────────────────────────────────────────
-if (require.main === module) {
-  const t = timer();
-  const repoRoot = process.cwd();
-  const modelFile = path.join(repoRoot, '.agent', 'history', 'architecture-model.json');
-
-  const query = process.argv[2];
-  if (!query) {
-    console.log(banner('Tribunal Architectural Blast Radius Engine'));
-    console.error(
-      `  ${YELLOW}Usage:${RESET} node blast_radius_engine.js <component-id-or-filepath>\n`,
-    );
-    process.exit(1);
-  }
-
-  if (!fs.existsSync(modelFile)) {
-    console.error(
-      `  ${RED}✖ architecture-model.json not found.${RESET} Run architecture_extractor.js first.`,
-    );
-    process.exit(1);
-  }
-
-  const model = JSON.parse(fs.readFileSync(modelFile, 'utf8'));
-  const engine = new BlastRadiusEngine(model);
-  const result = engine.computeBlastRadius(query);
-
-  console.log(banner('Tribunal Architectural Blast Radius Engine'));
-
-  if (!result.found) {
-    console.error(`  ${RED}✖ ${result.error}${RESET}`);
-    process.exit(1);
-  }
-
-  const tierColors = {
-    CRITICAL: RED,
-    HIGH: YELLOW,
-    MEDIUM: CYAN,
-    LOW: GREEN,
-  };
-  const color = tierColors[result.metrics.riskTier] || GREEN;
-
-  console.log(
-    `  Target:                 ${BOLD}${result.target.name}${RESET} (${result.target.id})`,
-  );
-  console.log(
-    `  Kind:                   ${CYAN}${result.target.kind}${RESET} | Trust Zone: ${YELLOW}${result.target.trustZone}${RESET}`,
-  );
-  console.log(
-    `  Blast Radius Risk:      ${color}${BOLD}${result.metrics.riskTier} (${result.metrics.riskScore})${RESET}`,
-  );
-  console.log(`  Direct Callers:         ${BOLD}${result.metrics.directDependentsCount}${RESET}`);
-  console.log(
-    `  Transitive Dependents:  ${BOLD}${result.metrics.transitiveDependentsCount}${RESET} across ${result.metrics.maxDepthReached} depth rings`,
-  );
-  console.log(
-    `  Impacted Endpoints:     ${result.impactBreakdown.endpoints.length > 0 ? YELLOW : GREEN}${result.impactBreakdown.endpoints.length}${RESET}`,
-  );
-  console.log(
-    `  Impacted Test Suites:   ${CYAN}${result.impactBreakdown.testSuites.length}${RESET}`,
-  );
-  console.log(
-    `  Zones Crossed:          ${result.impactBreakdown.securityZonesCrossed.join(', ') || 'None'}`,
-  );
-
-  if (result.transitiveRings.length > 0) {
-    console.log(`\n  ${BOLD}Concentric Blast Rings:${RESET}`);
-    for (const ring of result.transitiveRings) {
-      console.log(
-        `    Ring ${ring.depth} (depth ${ring.depth}): ${BOLD}${ring.count}${RESET} downstream components`,
-      );
-    }
-  }
-
-  console.log(
-    `\n  ${GREEN}${BOX.check} Blast Radius Analysis Complete${RESET} in ${formatMs(t())}\n`,
-  );
-}
-
-module.exports = {
-  BlastRadiusEngine,
-};
+#!/usr/bin/env node
+/**
+ * blast_radius_engine.js — Tribunal Architectural Blast Radius Engine
+ * ═════════════════════════════════════════════════════════════════════════════
+ * Answers: "If I modify or break this component, what is affected?"
+ *
+ * Computes:
+ *   - Direct Dependents (Immediate Callers/Importers)
+ *   - Transitive Closure (Full Downstream Blast Radius)
+ *   - Affected API Routes & Endpoints
+ *   - Affected Data Stores & Queries
+ *   - Affected Trust Boundaries & Security Zones
+ *   - Required Test Suites to Re-verify
+ *   - Architectural Centrality & Risk Score (0.0 to 1.0)
+ *
+ * Zero external dependencies.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  GREEN,
+  YELLOW,
+  CYAN,
+  RED,
+  BOLD,
+  RESET,
+  BOX,
+  banner,
+  timer,
+  formatMs,
+} = require('./_colors');
+
+class BlastRadiusEngine {
+  constructor(model) {
+    this.model = model;
+    this.entityMap = new Map();
+    this.dependentsMap = new Map(); // target -> Set of sources that depend on target
+    this.dependenciesMap = new Map(); // source -> Set of targets that source depends on
+
+    this.initGraph();
+  }
+
+  initGraph() {
+    for (const e of this.model.entities || []) {
+      this.entityMap.set(e.id, e);
+      this.dependentsMap.set(e.id, new Set());
+      this.dependenciesMap.set(e.id, new Set());
+    }
+
+    for (const rel of this.model.relationships || []) {
+      if (this.dependentsMap.has(rel.targetId)) {
+        this.dependentsMap.get(rel.targetId).add(rel.sourceId);
+      }
+      if (this.dependenciesMap.has(rel.sourceId)) {
+        this.dependenciesMap.get(rel.sourceId).add(rel.targetId);
+      }
+    }
+  }
+
+  findEntity(query) {
+    if (!query) return null;
+    const clean = query.trim();
+
+    // Direct ID match
+    if (this.entityMap.has(clean)) return this.entityMap.get(clean);
+
+    // Path or partial match
+    for (const [id, e] of this.entityMap.entries()) {
+      if (e.name === clean || e.scope === clean) return e;
+      if (e.sources && e.sources.some(s => s.file === clean || s.file.endsWith(clean))) return e;
+      if (id.toLowerCase().includes(clean.toLowerCase())) return e;
+    }
+    return null;
+  }
+
+  computeBlastRadius(targetQuery, maxDepth = 15) {
+    const rootEntity = this.findEntity(targetQuery);
+    if (!rootEntity) {
+      return {
+        found: false,
+        query: targetQuery,
+        error: `Component or file "${targetQuery}" not found in architectural model.`,
+      };
+    }
+
+    const visited = new Set([rootEntity.id]);
+    const directDependents = new Set();
+    const transitiveRings = []; // Array of Sets per depth level
+
+    let currentLevel = new Set(this.dependentsMap.get(rootEntity.id) || []);
+    for (const d of currentLevel) directDependents.add(d);
+
+    let depth = 1;
+    while (currentLevel.size > 0 && depth <= maxDepth) {
+      const ringEntities = [];
+      const nextLevel = new Set();
+
+      for (const id of currentLevel) {
+        if (!visited.has(id)) {
+          visited.add(id);
+          const entity = this.entityMap.get(id);
+          if (entity) ringEntities.push(entity);
+
+          const upstreams = this.dependentsMap.get(id) || [];
+          for (const up of upstreams) {
+            if (!visited.has(up)) {
+              nextLevel.add(up);
+            }
+          }
+        }
+      }
+
+      if (ringEntities.length > 0) {
+        transitiveRings.push({ depth, count: ringEntities.length, entities: ringEntities });
+      }
+      currentLevel = nextLevel;
+      depth++;
+    }
+
+    // Collect all affected entities (excluding root)
+    const affectedEntities = Array.from(visited)
+      .filter(id => id !== rootEntity.id)
+      .map(id => this.entityMap.get(id))
+      .filter(Boolean);
+
+    // Categorize Impact
+    const affectedEndpoints = affectedEntities.filter(e => e.kind === 'endpoint');
+    const affectedDatastores = affectedEntities.filter(
+      e => e.kind === 'datastore' || e.kind === 'cache',
+    );
+    const affectedQueues = affectedEntities.filter(
+      e => e.kind === 'queue' || e.kind === 'event_bus',
+    );
+    const affectedTests = affectedEntities.filter(
+      e => e.kind === 'test_suite' || e.scope?.includes('test'),
+    );
+
+    // Check Trust Zone Crossings
+    const rootZone = rootEntity.trustZone || 'unknown';
+    const crossedZones = new Set();
+    for (const e of affectedEntities) {
+      if (e.trustZone && e.trustZone !== rootZone) {
+        crossedZones.add(e.trustZone);
+      }
+    }
+
+    // Risk Calculation (0.0 to 1.0)
+    // Centrality + Blast scope + Security Crossing
+    const totalEntities = this.entityMap.size || 1;
+    const impactRatio = affectedEntities.length / totalEntities;
+    const directCoupling = directDependents.size;
+    const securityPenalty =
+      crossedZones.has('public_untrusted') || crossedZones.has('dmz_gateway') ? 0.3 : 0.1;
+
+    let riskScore = Math.min(1.0, impactRatio * 2.5 + directCoupling * 0.05 + securityPenalty);
+    riskScore = Math.round(riskScore * 100) / 100;
+
+    let riskTier = 'LOW';
+    if (riskScore >= 0.7) riskTier = 'CRITICAL';
+    else if (riskScore >= 0.4) riskTier = 'HIGH';
+    else if (riskScore >= 0.2) riskTier = 'MEDIUM';
+
+    return {
+      found: true,
+      target: {
+        id: rootEntity.id,
+        name: rootEntity.name,
+        kind: rootEntity.kind,
+        scope: rootEntity.scope,
+        trustZone: rootEntity.trustZone,
+      },
+      metrics: {
+        directDependentsCount: directDependents.size,
+        transitiveDependentsCount: affectedEntities.length,
+        maxDepthReached: transitiveRings.length,
+        riskScore,
+        riskTier,
+      },
+      impactBreakdown: {
+        endpoints: affectedEndpoints.map(e => ({ id: e.id, name: e.name, scope: e.scope })),
+        datastores: affectedDatastores.map(e => ({ id: e.id, name: e.name })),
+        queues: affectedQueues.map(e => ({ id: e.id, name: e.name })),
+        testSuites: affectedTests.map(e => ({ id: e.id, name: e.name, scope: e.scope })),
+        securityZonesCrossed: Array.from(crossedZones),
+      },
+      transitiveRings,
+    };
+  }
+}
+
+// ── Standalone CLI ────────────────────────────────────────────────────────────
+if (require.main === module) {
+  const t = timer();
+  const repoRoot = process.cwd();
+  const modelFile = path.join(repoRoot, '.agent', 'history', 'architecture-model.json');
+
+  const query = process.argv[2];
+  if (!query) {
+    console.log(banner('Tribunal Architectural Blast Radius Engine'));
+    console.error(
+      `  ${YELLOW}Usage:${RESET} node blast_radius_engine.js <component-id-or-filepath>\n`,
+    );
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(modelFile)) {
+    console.error(
+      `  ${RED}✖ architecture-model.json not found.${RESET} Run architecture_extractor.js first.`,
+    );
+    process.exit(1);
+  }
+
+  const model = JSON.parse(fs.readFileSync(modelFile, 'utf8'));
+  const engine = new BlastRadiusEngine(model);
+  const result = engine.computeBlastRadius(query);
+
+  console.log(banner('Tribunal Architectural Blast Radius Engine'));
+
+  if (!result.found) {
+    console.error(`  ${RED}✖ ${result.error}${RESET}`);
+    process.exit(1);
+  }
+
+  const tierColors = {
+    CRITICAL: RED,
+    HIGH: YELLOW,
+    MEDIUM: CYAN,
+    LOW: GREEN,
+  };
+  const color = tierColors[result.metrics.riskTier] || GREEN;
+
+  console.log(
+    `  Target:                 ${BOLD}${result.target.name}${RESET} (${result.target.id})`,
+  );
+  console.log(
+    `  Kind:                   ${CYAN}${result.target.kind}${RESET} | Trust Zone: ${YELLOW}${result.target.trustZone}${RESET}`,
+  );
+  console.log(
+    `  Blast Radius Risk:      ${color}${BOLD}${result.metrics.riskTier} (${result.metrics.riskScore})${RESET}`,
+  );
+  console.log(`  Direct Callers:         ${BOLD}${result.metrics.directDependentsCount}${RESET}`);
+  console.log(
+    `  Transitive Dependents:  ${BOLD}${result.metrics.transitiveDependentsCount}${RESET} across ${result.metrics.maxDepthReached} depth rings`,
+  );
+  console.log(
+    `  Impacted Endpoints:     ${result.impactBreakdown.endpoints.length > 0 ? YELLOW : GREEN}${result.impactBreakdown.endpoints.length}${RESET}`,
+  );
+  console.log(
+    `  Impacted Test Suites:   ${CYAN}${result.impactBreakdown.testSuites.length}${RESET}`,
+  );
+  console.log(
+    `  Zones Crossed:          ${result.impactBreakdown.securityZonesCrossed.join(', ') || 'None'}`,
+  );
+
+  if (result.transitiveRings.length > 0) {
+    console.log(`\n  ${BOLD}Concentric Blast Rings:${RESET}`);
+    for (const ring of result.transitiveRings) {
+      console.log(
+        `    Ring ${ring.depth} (depth ${ring.depth}): ${BOLD}${ring.count}${RESET} downstream components`,
+      );
+    }
+  }
+
+  console.log(
+    `\n  ${GREEN}${BOX.check} Blast Radius Analysis Complete${RESET} in ${formatMs(t())}\n`,
+  );
+}
+
+module.exports = {
+  BlastRadiusEngine,
+};

package/.agent/scripts/capability_evolution.js

@@ -436,6 +436,105 @@ function getPhase5MetricsTracker() {
   return _globalMetricsTracker;
 }
 
+// ============================================================================
+// 5. OBSERVABILITY & TELEMETRY SPANS (PILLAR 9)
+// ============================================================================
+
+class ObservabilityEngine {
+  constructor() {
+    this.activeSpans = new Map();
+    this.completedSpans = [];
+  }
+
+  startSkillSpan(skillName, context = {}) {
+    const spanId = `span_${skillName}_${Date.now()}_${Math.random().toString(36).substring(2, 6)}`;
+    const span = {
+      span_id: spanId,
+      skill: skillName,
+      status: 'RUNNING',
+      start_time: Date.now(),
+      context,
+    };
+    this.activeSpans.set(spanId, span);
+    return spanId;
+  }
+
+  endSkillSpan(spanId, outcome = {}, error = null) {
+    const span = this.activeSpans.get(spanId);
+    if (!span) return null;
+
+    span.status = error ? 'FAILED' : 'COMPLETED';
+    span.end_time = Date.now();
+    span.duration_ms = span.end_time - span.start_time;
+    span.outcome = outcome;
+    if (error) span.error = error.message || String(error);
+
+    this.activeSpans.delete(spanId);
+    this.completedSpans.push(span);
+
+    // Track telemetry seamlessly
+    const registry = getSkillTelemetryRegistry();
+    registry.recordSkillExecution(span.skill, {
+      is_material: outcome.material_considerations_found > 0 || !error,
+      findings_count: outcome.findings || 0,
+      verified_findings_count: outcome.verified_findings || 0,
+      task: span.context.task_id || 'unknown',
+    });
+
+    return span;
+  }
+}
+
+let _globalObservabilityEngine = null;
+function getObservabilityEngine() {
+  if (!_globalObservabilityEngine) _globalObservabilityEngine = new ObservabilityEngine();
+  return _globalObservabilityEngine;
+}
+
+// ============================================================================
+// 6. PRUNING & LIFECYCLE (PILLAR 10)
+// ============================================================================
+
+class LifecycleManager {
+  constructor(telemetryRegistry) {
+    this.registry = telemetryRegistry;
+  }
+
+  /**
+   * Scans telemetry for unused or poorly performing skills and marks them for deprecation.
+   * @param {number} thresholdDays
+   */
+  evaluateSkillLifecycle(thresholdDays = 30) {
+    const now = Date.now();
+    const thresholdMs = thresholdDays * 24 * 60 * 60 * 1000;
+    const deprecated = [];
+
+    for (const [skillName, telemetry] of this.registry.records.entries()) {
+      let lastActiveMs = 0;
+      if (telemetry.tasks && telemetry.tasks.length > 0) {
+        const lastTask = telemetry.tasks[telemetry.tasks.length - 1];
+        lastActiveMs = new Date(lastTask.recorded_at).getTime();
+      }
+
+      const isUnused =
+        now - lastActiveMs > thresholdMs && (telemetry.activations === 0 || lastActiveMs === 0);
+      const isLowPrecision =
+        telemetry.activations > 10 &&
+        (telemetry.findings > 0 ? telemetry.verified_findings / telemetry.findings < 0.2 : false);
+
+      if (isUnused || isLowPrecision) {
+        deprecated.push({
+          skill: skillName,
+          reason: isUnused ? 'Dormant beyond threshold' : 'Chronic low verification precision',
+          metrics: telemetry,
+        });
+      }
+    }
+
+    return deprecated;
+  }
+}
+
 // ============================================================================
 // EXPORTS
 // ============================================================================
@@ -450,4 +549,7 @@ module.exports = {
   getSkillImprovementManager,
   Phase5MetricsTracker,
   getPhase5MetricsTracker,
+  ObservabilityEngine,
+  getObservabilityEngine,
+  LifecycleManager,
 };