@vibecheckai/cli 3.1.6 → 3.2.0

package/bin/runners/context/generators/mcp.js

@@ -1,8 +1,15 @@
 /**
  * MCP Context JSON Generator
  * Generates .vibecheck/context.json for MCP servers
+ * 
+ * Uses the unified EVIDENCE_SCHEMA and TRUTH_CONTRACT from proof-context.js
  */
 
+const { EVIDENCE_SCHEMA, TRUTH_CONTRACT } = require("../proof-context.js");
+
+// Context attribution message shown when AI uses vibecheck data
+const CONTEXT_ATTRIBUTION = "🧠 Context enhanced by vibecheck";
+
 /**
  * Generate universal context JSON for MCP
  */
@@ -14,6 +21,9 @@ function generateContextJson(analysis, projectPath) {
     version: "3.0.0",
     generatedAt: new Date().toISOString(),
     generator: "vibecheck-context",
+    // Reference the unified schema from proof-context.js
+    evidenceSchema: EVIDENCE_SCHEMA,
+    truthContract: TRUTH_CONTRACT,
     
     project: {
       name: analysis.name,
@@ -92,6 +102,9 @@ function generateContextJson(analysis, projectPath) {
       byExtension: analysis.stats?.byExtension || {},
       largestFiles: analysis.stats?.largestFiles || [],
     },
+    contextValidation: analysis.contextValidation || null,
+    contextDrift: analysis.contextDrift || null,
+    contextSummary: analysis.contextSummary || null,
 
     rules: {
       critical: [
@@ -143,9 +156,14 @@ function generateContextJson(analysis, projectPath) {
         },
       ],
     },
+
+    // Attribution message for AI responses
+    _attribution: CONTEXT_ATTRIBUTION,
+    _attributionNote: "Include this attribution when referencing vibecheck context in responses",
   }, null, 2);
 }
 
 module.exports = {
   generateContextJson,
+  CONTEXT_ATTRIBUTION,
 };

package/bin/runners/context/index.js

@@ -59,6 +59,67 @@ const { generateCopilotInstructions } = require("./generators/copilot");
 const { generateClaudeConfig } = require("./generators/claude");
 const { generateCodexConfig } = require("./generators/codex");
 const { generateContextJson } = require("./generators/mcp");
+let enhancedContextEngine = null;
+const enhancedCandidates = [
+  path.join(__dirname, "..", "..", "..", "src", "lib", "context", "enhanced-context-engine.js"),
+  path.join(__dirname, "..", "..", "..", "..", "..", "src", "lib", "context", "enhanced-context-engine.js"),
+];
+for (const candidate of enhancedCandidates) {
+  try {
+    if (fs.existsSync(candidate)) {
+      ({ enhancedContextEngine } = require(candidate));
+      break;
+    }
+  } catch {}
+}
+
+async function emitGuardrailMetric(projectPath, metric) {
+  try {
+    const auditDir = path.join(projectPath, ".vibecheck", "audit");
+    fs.mkdirSync(auditDir, { recursive: true });
+    const record = JSON.stringify({ ...metric, timestamp: new Date().toISOString() });
+    fs.appendFileSync(path.join(auditDir, "guardrail-metrics.jsonl"), `${record}\n`);
+  } catch {
+    // ignore metrics write failures
+  }
+}
+
+async function applyContextValidation(projectPath, analysis, opts) {
+  if (!enhancedContextEngine) return analysis;
+
+  const { context, validation, drift } = await enhancedContextEngine.getValidatedContext(projectPath, {
+    file: opts.currentFile || undefined,
+    purpose: opts.task || "general",
+    checkDrift: true,
+  });
+
+  analysis.contextValidation = validation;
+  analysis.contextDrift = drift;
+  analysis.contextSummary = {
+    confidence: validation?.confidence ?? context?.confidence ?? 0,
+    freshness: context?.freshness ?? null,
+    issues: validation?.issues?.length || 0,
+    driftScore: drift?.score ?? 0,
+    blocked: validation?.valid === false,
+  };
+
+  await emitGuardrailMetric(projectPath, {
+    event: "context_validation",
+    confidence: analysis.contextSummary.confidence,
+    freshness: analysis.contextSummary.freshness,
+    issues: analysis.contextSummary.issues,
+    driftScore: analysis.contextSummary.driftScore,
+  });
+
+  const vibecheckDir = path.join(projectPath, ".vibecheck");
+  fs.mkdirSync(vibecheckDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(vibecheckDir, "context-validation.json"),
+    JSON.stringify({ validation, drift }, null, 2),
+  );
+
+  return analysis;
+}
 
 /**
  * Parse command line arguments
@@ -357,10 +418,14 @@ function startWatchMode(projectPath, platform, verbose) {
   let debounceTimer = null;
   const watchDirs = ["src", "app", "pages", "components", "lib", "server"];
   
-  const regenerate = () => {
+  const regenerate = async () => {
     console.log(`\n${c.yellow}⟳ Change detected, regenerating...${c.reset}\n`);
     try {
-      const analysis = analyzeProject(projectPath);
+      let analysis = analyzeProject(projectPath);
+      analysis = await applyContextValidation(projectPath, analysis, {
+        currentFile: "",
+        task: "general",
+      });
       writeFiles(projectPath, platform, analysis, verbose);
       console.log(`${c.green}✓ Rules regenerated${c.reset} at ${new Date().toLocaleTimeString()}\n`);
     } catch (err) {
@@ -375,7 +440,9 @@ function startWatchMode(projectPath, platform, verbose) {
         fs.watch(watchPath, { recursive: true }, (eventType, filename) => {
           if (filename && (filename.endsWith(".ts") || filename.endsWith(".tsx") || filename.endsWith(".js") || filename.endsWith(".jsx"))) {
             if (debounceTimer) clearTimeout(debounceTimer);
-            debounceTimer = setTimeout(regenerate, 500);
+            debounceTimer = setTimeout(() => {
+              void regenerate();
+            }, 500);
           }
         });
         console.log(`${c.dim}  Watching: ${dir}/${c.reset}`);
@@ -839,7 +906,8 @@ ${c.cyan}━━━━━━━━━━━━━━━━━━━━━━━
 `);
 
   // Analyze project
-  const analysis = analyzeProject(projectPath);
+  let analysis = analyzeProject(projectPath);
+  analysis = await applyContextValidation(projectPath, analysis, opts);
   const p = analysis.patterns || {};
 
   // Display analysis - Basic info

package/bin/runners/context/proof-context.js

@@ -1,11 +1,211 @@
 /**
  * Proof-Carrying Context System
  * Every claim must have file:line evidence or it gets flagged as hypothesis
+ * 
+ * This module exports the SINGLE TRUTH CONTRACT used across CLI, MCP, and extension.
  */
 
 const fs = require("fs");
 const path = require("path");
 
+const DEFAULT_EVIDENCE_CONFIDENCE = 0.9;
+const MAX_EVIDENCE_SNIPPET = 200;
+
+// Context attribution message shown when AI uses vibecheck data
+const CONTEXT_ATTRIBUTION = "🧠 Context enhanced by vibecheck";
+
+// =============================================================================
+// UNIFIED TRUTH CONTRACT SCHEMA v1.0
+// =============================================================================
+
+/**
+ * The canonical evidence schema used across CLI, MCP, and VS Code extension.
+ * All tools emitting claims MUST include this minimal required payload.
+ */
+const EVIDENCE_SCHEMA = {
+  version: "1.0.0",
+  required: ["file", "line", "snippet", "confidence"],
+  maxSnippet: MAX_EVIDENCE_SNIPPET,
+  confidenceThresholds: {
+    strict: 0.8,     // HIGH confidence required for strict mode
+    balanced: 0.6,   // MEDIUM confidence for balanced mode
+    permissive: 0.4, // LOW confidence allowed in permissive mode
+  },
+  claimTypes: [
+    "route",
+    "schema_table",
+    "schema_column",
+    "export",
+    "default_export",
+    "middleware",
+    "env_var",
+    "auth_guard",
+    "billing_gate",
+    "hypothesis", // Claims without proof get flagged here
+  ],
+};
+
+/**
+ * The truth contract defines rules that AI must satisfy.
+ * Claims without evidence are automatically flagged as "unknown" and block actions.
+ */
+const TRUTH_CONTRACT = {
+  version: "1.0.0",
+  claimsRequireEvidence: true,
+  confidenceThresholds: EVIDENCE_SCHEMA.confidenceThresholds,
+  policies: {
+    strict: {
+      minConfidence: 0.8,
+      allowUnknown: false,
+      requireValidation: true,
+      blockOnDrift: true,
+    },
+    balanced: {
+      minConfidence: 0.6,
+      allowUnknown: false,
+      requireValidation: true,
+      blockOnDrift: false,
+    },
+    permissive: {
+      minConfidence: 0.4,
+      allowUnknown: true,
+      requireValidation: false,
+      blockOnDrift: false,
+    },
+  },
+  invariants: [
+    "No paid feature without server-side enforcement",
+    "No success UI without confirmed success",
+    "No route reference without matching route map entry",
+    "No silent catch in auth/billing flows",
+    "No hardcoded secrets in production code",
+  ],
+};
+
+/**
+ * Normalize an evidence item to the canonical schema.
+ * @param {object} item - Raw evidence item
+ * @param {string} projectPath - Project root path
+ * @param {object} fallback - Fallback values
+ * @returns {object} Normalized evidence conforming to EVIDENCE_SCHEMA
+ */
+function normalizeToEvidenceSchema(item, projectPath, fallback = {}) {
+  const file = item?.file || fallback.file || "";
+  const line = Number(item?.line || item?.lines || fallback.line || 1);
+  let snippet = item?.snippet || item?.evidence || fallback.evidence || "";
+
+  if (!snippet && file && projectPath) {
+    try {
+      const content = fs.readFileSync(path.join(projectPath, file), "utf-8");
+      const lines = content.split("\n");
+      const idx = Math.max(0, Math.min(lines.length - 1, line - 1));
+      snippet = lines[idx] || "";
+    } catch {
+      // File not readable
+    }
+  }
+
+  return {
+    file,
+    line,
+    snippet: String(snippet || "").slice(0, EVIDENCE_SCHEMA.maxSnippet),
+    confidence: item?.confidence ?? fallback.confidence ?? DEFAULT_EVIDENCE_CONFIDENCE,
+  };
+}
+
+/**
+ * Validate that evidence conforms to the schema.
+ * @param {object} evidence - Evidence object to validate
+ * @param {string} policy - Policy mode: 'strict' | 'balanced' | 'permissive'
+ * @returns {{ valid: boolean, errors: string[], confidence: number }}
+ */
+function validateEvidence(evidence, policy = "balanced") {
+  const errors = [];
+  const thresholds = EVIDENCE_SCHEMA.confidenceThresholds;
+  const minConfidence = thresholds[policy] || thresholds.balanced;
+
+  // Check required fields
+  for (const field of EVIDENCE_SCHEMA.required) {
+    if (evidence[field] === undefined || evidence[field] === null || evidence[field] === "") {
+      errors.push(`Missing required field: ${field}`);
+    }
+  }
+
+  // Check confidence threshold
+  const confidence = evidence.confidence ?? 0;
+  if (confidence < minConfidence) {
+    errors.push(`Confidence ${confidence} below threshold ${minConfidence} for ${policy} policy`);
+  }
+
+  // Check snippet length
+  if (evidence.snippet && evidence.snippet.length > EVIDENCE_SCHEMA.maxSnippet) {
+    errors.push(`Snippet exceeds max length of ${EVIDENCE_SCHEMA.maxSnippet}`);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    confidence,
+  };
+}
+
+/**
+ * Create a claim with proper evidence attachment.
+ * @param {string} type - Claim type from EVIDENCE_SCHEMA.claimTypes
+ * @param {string} claim - Human-readable claim text
+ * @param {object} evidence - Evidence object
+ * @param {object} metadata - Additional metadata
+ * @returns {object} Properly formatted claim
+ */
+function createClaim(type, claim, evidence, metadata = {}) {
+  const isHypothesis = !evidence || !evidence.file;
+  
+  return {
+    id: `claim_${hashString(claim + (evidence?.file || ""))}`,
+    type: isHypothesis ? "hypothesis" : type,
+    claim,
+    evidence: evidence ? [evidence] : [],
+    metadata,
+    isVerified: !isHypothesis,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+function normalizeEvidenceItem(projectPath, fact, item) {
+  const file = item?.file || fact.file || "";
+  const line = Number(item?.line || item?.lines || fact.line || 1);
+  let snippet = item?.snippet || item?.evidence || fact.evidence || "";
+
+  if (!snippet && file) {
+    try {
+      const content = fs.readFileSync(path.join(projectPath, file), "utf-8");
+      const lines = content.split("\n");
+      const idx = Math.max(0, Math.min(lines.length - 1, line - 1));
+      snippet = lines[idx] || "";
+    } catch {}
+  }
+
+  return {
+    file,
+    line,
+    snippet: String(snippet || "").slice(0, MAX_EVIDENCE_SNIPPET),
+    confidence: item?.confidence ?? fact.confidence ?? DEFAULT_EVIDENCE_CONFIDENCE,
+  };
+}
+
+function normalizeFactEvidence(projectPath, fact) {
+  const raw = Array.isArray(fact.evidence) ? fact.evidence : [fact.evidence];
+  const evidence = raw
+    .filter(Boolean)
+    .map((item) => normalizeEvidenceItem(projectPath, fact, item));
+
+  return {
+    ...fact,
+    confidence: fact.confidence ?? DEFAULT_EVIDENCE_CONFIDENCE,
+    evidence,
+  };
+}
+
 /**
  * Extract proof-carrying facts with exact file:line references
  */
@@ -32,6 +232,13 @@ function extractProofCarryingFacts(projectPath) {
   const middlewareFacts = extractVerifiedMiddleware(projectPath);
   facts.verified.push(...middlewareFacts);
 
+  facts.verified = facts.verified.map((fact) =>
+    normalizeFactEvidence(projectPath, fact),
+  );
+  facts.hypotheses = facts.hypotheses.map((fact) =>
+    normalizeFactEvidence(projectPath, fact),
+  );
+
   // Build proof map
   facts.verified.forEach(f => {
     facts.proofMap[f.claim] = {
@@ -609,6 +816,72 @@ function hashString(str) {
   return Math.abs(hash).toString(16);
 }
 
+/**
+ * Emit guardrail metrics to .vibecheck/audit/guardrail-metrics.jsonl
+ * KPIs tracked: false_positive_rate, unknown_rate, drift_score
+ */
+async function emitGuardrailMetric(projectPath, metric) {
+  const auditDir = path.join(projectPath, ".vibecheck", "audit");
+  try {
+    fs.mkdirSync(auditDir, { recursive: true });
+    const record = JSON.stringify({
+      ...metric,
+      timestamp: new Date().toISOString(),
+    });
+    fs.appendFileSync(
+      path.join(auditDir, "guardrail-metrics.jsonl"),
+      `${record}\n`
+    );
+  } catch {
+    // Ignore write failures in metrics
+  }
+}
+
+/**
+ * Aggregate guardrail KPIs from audit logs
+ * Returns: { falsePositiveRate, unknownRate, avgDriftScore, totalValidations }
+ */
+function aggregateGuardrailKPIs(projectPath) {
+  const auditLogPath = path.join(projectPath, ".vibecheck", "audit", "guardrail-metrics.jsonl");
+  
+  try {
+    const content = fs.readFileSync(auditLogPath, "utf-8");
+    const lines = content.trim().split("\n").filter(Boolean).map(l => JSON.parse(l));
+    
+    // Filter claim validations
+    const validations = lines.filter(l => l.event === "claim_validation");
+    const unknowns = validations.filter(l => l.result === "unknown");
+    const falsePositives = validations.filter(l => l.falsePositive === true);
+    
+    // Filter drift events
+    const drifts = lines.filter(l => l.event === "drift_detected");
+    const avgDriftScore = drifts.length > 0
+      ? drifts.reduce((sum, d) => sum + (d.score || 0), 0) / drifts.length
+      : 0;
+    
+    // Filter firewall blocks
+    const blocks = lines.filter(l => l.event === "truth_firewall_block");
+    
+    return {
+      totalValidations: validations.length,
+      unknownRate: validations.length > 0 ? unknowns.length / validations.length : 0,
+      falsePositiveRate: validations.length > 0 ? falsePositives.length / validations.length : 0,
+      avgDriftScore,
+      totalBlocks: blocks.length,
+      lastUpdated: new Date().toISOString(),
+    };
+  } catch {
+    return {
+      totalValidations: 0,
+      unknownRate: 0,
+      falsePositiveRate: 0,
+      avgDriftScore: 0,
+      totalBlocks: 0,
+      lastUpdated: new Date().toISOString(),
+    };
+  }
+}
+
 /**
  * Golden Path Replay Templates - recorded successful change patterns
  */
@@ -951,13 +1224,25 @@ function generateTruthPack(projectPath, analysis) {
       framework: analysis.framework,
       routes: analysis.proofCarryingFacts?.verified?.length,
       packages: analysis.symbolReality?.installedPackages?.size
-    }))
+    })),
+    
+    // Attribution message for AI responses
+    _attribution: CONTEXT_ATTRIBUTION,
+    _attributionNote: "Include this note when referencing vibecheck data: " + CONTEXT_ATTRIBUTION,
   };
 
   return pack;
 }
 
 module.exports = {
+  // Unified Truth Contract Schema (v1.0)
+  EVIDENCE_SCHEMA,
+  TRUTH_CONTRACT,
+  normalizeToEvidenceSchema,
+  validateEvidence,
+  createClaim,
+  
+  // Proof-Carrying Context Functions
   extractProofCarryingFacts,
   symbolVibecheck,
   computeFileImportanceScore,
@@ -969,4 +1254,11 @@ module.exports = {
   detectDrift,
   enforceOneFileRule,
   generateTruthPack,
+  
+  // Audit Metrics and KPIs
+  emitGuardrailMetric,
+  aggregateGuardrailKPIs,
+  
+  // Context Attribution
+  CONTEXT_ATTRIBUTION,
 };