@equilateral_ai/mindmeld 3.0.0

package/hooks/pre-compact.js

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+/**
+ * MindMeld - Claude Code Pre-Compact Hook
+ *
+ * Harvests patterns from session transcript and validates compliance.
+ * Runs before conversation compaction to learn from the session.
+ *
+ * Features:
+ * - LLM-powered pattern detection (when ANTHROPIC_API_KEY is set)
+ * - Regex fallback for fast pattern matching
+ * - Standards validation against .equilateral-standards
+ * - Pattern promotion tracking
+ *
+ * @equilateral_ai/mindmeld v3.0.0
+ */
+
+const path = require('path');
+const fs = require('fs').promises;
+
+// LLM Pattern Detection (optional - requires ANTHROPIC_API_KEY)
+let LLMPatternDetector = null;
+try {
+    const llmModule = require('../src/core/LLMPatternDetector');
+    LLMPatternDetector = llmModule.LLMPatternDetector;
+} catch (error) {
+    // LLM module not available - will use regex fallback
+}
+
+/**
+ * Main hook execution
+ * @param {Object} sessionTranscript - Claude Code session data
+ */
+async function harvestPatterns(sessionTranscript) {
+  const startTime = Date.now();
+
+  try {
+    // Fast bail if MindMeld not configured
+    const hasMindmeld = await checkMindmeldConfiguration();
+    if (!hasMindmeld) {
+      return { skipped: true, reason: 'No MindMeld configuration' };
+    }
+
+    // Load MindmeldClient with graceful degradation
+    const { MindmeldClient } = require('../src/index');
+
+    const mindmeld = new MindmeldClient({
+      projectPath: process.cwd()
+    });
+
+    // Extract session metadata
+    const sessionId = sessionTranscript.sessionId || generateSessionId();
+    const userId = sessionTranscript.userId || process.env.USER || 'unknown';
+
+    // 1. Detect patterns from session (LLM-powered or regex fallback)
+    let patterns = [];
+    let llmAnalysis = null;
+    // Bedrock uses AWS credentials, no API key needed
+    const useLLM = LLMPatternDetector && process.env.MINDMELD_USE_LLM !== 'false';
+
+    if (useLLM) {
+      // Use LLM for semantic pattern detection via AWS Bedrock
+      const detector = new LLMPatternDetector({
+        enabled: true,
+        model: process.env.MINDMELD_LLM_MODEL || 'us.anthropic.claude-3-5-haiku-20241022-v1:0',
+        region: process.env.AWS_REGION || 'us-east-2'
+      });
+
+      const transcriptText = typeof sessionTranscript === 'string'
+        ? sessionTranscript
+        : sessionTranscript.transcript || JSON.stringify(sessionTranscript);
+
+      llmAnalysis = await detector.analyzeSessionTranscript(transcriptText, {
+        projectName: path.basename(process.cwd()),
+        filesChanged: sessionTranscript.filesChanged || []
+      });
+
+      if (llmAnalysis.success && llmAnalysis.patterns) {
+        patterns = llmAnalysis.patterns.map(p => ({
+          element: p.element,
+          type: p.type,
+          intent: p.intent,
+          category: p.category,
+          confidence: p.confidence,
+          evidence: p.evidence,
+          source: 'llm'
+        }));
+
+        console.error(`[MindMeld] LLM detected ${patterns.length} patterns (model: ${llmAnalysis.model})`);
+      }
+    }
+
+    // Fallback to regex-based detection if LLM unavailable or failed
+    if (patterns.length === 0) {
+      patterns = await mindmeld.detectPatternsFromSession(sessionTranscript);
+    }
+
+    if (!patterns || patterns.length === 0) {
+      return {
+        patternsDetected: 0,
+        violations: 0,
+        reinforced: 0,
+        llmUsed: useLLM && llmAnalysis?.success,
+        elapsed: Date.now() - startTime
+      };
+    }
+
+    // 2. Validate against standards
+    const validationResults = await validatePatterns(mindmeld, patterns);
+
+    // 3. Record violations
+    for (const result of validationResults.violations) {
+      await mindmeld.recordViolation({
+        pattern: result.pattern,
+        violations: result.violations,
+        sessionId: sessionId,
+        userId: userId
+      });
+    }
+
+    // 4. Reinforce valid patterns
+    for (const result of validationResults.valid) {
+      await mindmeld.reinforcePattern({
+        pattern: result.pattern,
+        sessionId: sessionId,
+        userId: userId
+      });
+    }
+
+    // 5. Check for promotion candidates
+    const candidates = await checkPromotionCandidates(mindmeld, validationResults.valid);
+
+    // 6. Check README staleness (documentation maintenance)
+    let readmeStatus = null;
+    try {
+      const { checkReadmeStaleness } = require('../scripts/check-readme-staleness');
+      readmeStatus = await checkReadmeStaleness(process.cwd());
+
+      if (readmeStatus.stale) {
+        console.error(`[MindMeld] 📄 README staleness detected:`);
+        console.error(`[MindMeld]    Changes since last update: ${readmeStatus.changes}`);
+        console.error(`[MindMeld]    Agent changes: ${readmeStatus.analysis.agentChanges}`);
+        console.error(`[MindMeld]    Standards changes: ${readmeStatus.analysis.standardsChanges}`);
+        console.error(`[MindMeld]    Significance: ${readmeStatus.analysis.significance}`);
+
+        if (readmeStatus.shouldTrigger) {
+          console.error(`[MindMeld] 🔧 Critical changes detected - README update recommended`);
+          console.error(`[MindMeld]    Run: node -e "const L=require('./src/agents/specialists/LibrarianAgent');new L().generateProjectReadme({projectRoot:process.cwd()})"`);
+        }
+      }
+    } catch (error) {
+      // Non-fatal - don't break pattern harvesting
+      console.error(`[MindMeld] README check skipped:`, error.message);
+    }
+
+    // 7. Log results
+    const elapsed = Date.now() - startTime;
+    const summary = {
+      patternsDetected: patterns.length,
+      violations: validationResults.violations.length,
+      reinforced: validationResults.valid.length,
+      promotionCandidates: candidates.length,
+      readmeStale: readmeStatus ? readmeStatus.stale : null,
+      readmeUpdateRecommended: readmeStatus ? readmeStatus.shouldTrigger : false,
+      llmUsed: useLLM && llmAnalysis?.success,
+      llmModel: llmAnalysis?.model || null,
+      llmSummary: llmAnalysis?.summary || null,
+      llmRecommendations: llmAnalysis?.recommendations || [],
+      elapsed: elapsed
+    };
+
+    console.error(`[MindMeld] Pattern harvesting complete in ${elapsed}ms`);
+    console.error(`[MindMeld] Detected: ${summary.patternsDetected}, Violations: ${summary.violations}, Reinforced: ${summary.reinforced}`);
+
+    if (candidates.length > 0) {
+      console.error(`[MindMeld] ${candidates.length} pattern(s) eligible for standards promotion:`);
+      for (const candidate of candidates) {
+        console.error(`  - ${candidate.element} (correlation: ${(candidate.correlation * 100).toFixed(0)}%)`);
+      }
+    }
+
+    return summary;
+
+  } catch (error) {
+    // Graceful degradation - never block compaction
+    console.error('[MindMeld] Hook error (non-fatal):', error.message);
+    return {
+      error: error.message,
+      patternsDetected: 0,
+      violations: 0,
+      reinforced: 0
+    };
+  }
+}
+
+/**
+ * Check if MindMeld is configured for this project
+ */
+async function checkMindmeldConfiguration() {
+  try {
+    const mindmeldConfig = path.join(process.cwd(), '.mindmeld', 'config.json');
+    await fs.access(mindmeldConfig);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate patterns against standards
+ */
+async function validatePatterns(mindmeld, patterns) {
+  const violations = [];
+  const valid = [];
+
+  for (const pattern of patterns) {
+    const validation = await mindmeld.validatePattern(pattern);
+
+    if (!validation.valid) {
+      violations.push({
+        pattern: pattern,
+        violations: validation.violations
+      });
+    } else {
+      valid.push({
+        pattern: pattern
+      });
+    }
+  }
+
+  return { violations, valid };
+}
+
+/**
+ * Check for patterns eligible for promotion to standards
+ */
+async function checkPromotionCandidates(mindmeld, validPatterns) {
+  const candidates = [];
+
+  for (const result of validPatterns) {
+    const eligible = await mindmeld.evaluateForPromotion(result.pattern);
+
+    if (eligible) {
+      candidates.push(eligible);
+    }
+  }
+
+  return candidates;
+}
+
+/**
+ * Generate session ID
+ */
+function generateSessionId() {
+  return `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * Parse session transcript if provided as string
+ */
+function parseSessionTranscript(input) {
+  if (typeof input === 'string') {
+    try {
+      return JSON.parse(input);
+    } catch {
+      // Treat as raw transcript text
+      return {
+        transcript: input,
+        sessionId: generateSessionId()
+      };
+    }
+  }
+  return input;
+}
+
+/**
+ * Generate context summary to survive compaction
+ * This output goes to stdout and becomes part of the compacted summary
+ */
+async function generatePostCompactContext(summary, llmAnalysis) {
+  const fsSync = require('fs');
+  const sections = [];
+
+  sections.push('# MindMeld Context Summary');
+  sections.push(`**Session harvested**: ${new Date().toISOString()}`);
+  sections.push(`**Project**: ${path.basename(process.cwd())}`);
+  sections.push('');
+
+  // Include session stats
+  sections.push('## Session Learning');
+  sections.push(`- Patterns detected: ${summary.patternsDetected || 0}`);
+  sections.push(`- Standards violations: ${summary.violations || 0}`);
+  sections.push(`- Patterns reinforced: ${summary.reinforced || 0}`);
+  if (summary.promotionCandidates > 0) {
+    sections.push(`- Promotion candidates: ${summary.promotionCandidates}`);
+  }
+  sections.push('');
+
+  // Include LLM recommendations if available
+  if (llmAnalysis?.recommendations && llmAnalysis.recommendations.length > 0) {
+    sections.push('## Session Recommendations');
+    for (const rec of llmAnalysis.recommendations) {
+      sections.push(`- ${rec}`);
+    }
+    sections.push('');
+  }
+
+  // Include LLM summary if available
+  if (llmAnalysis?.summary) {
+    sections.push('## Session Summary');
+    sections.push(llmAnalysis.summary);
+    sections.push('');
+  }
+
+  // Load relevant standards from .equilateral-standards if available
+  const standardsPath = path.join(process.cwd(), '.equilateral-standards');
+  try {
+    await fs.access(standardsPath);
+
+    // Load top-level standards index if available
+    const indexPath = path.join(standardsPath, 'index.json');
+    try {
+      const indexContent = await fs.readFile(indexPath, 'utf-8');
+      const index = JSON.parse(indexContent);
+
+      if (index.categories && index.categories.length > 0) {
+        sections.push('## Available Standards Categories');
+        for (const cat of index.categories.slice(0, 5)) {
+          sections.push(`- ${cat.name}: ${cat.description || ''}`);
+        }
+        sections.push('');
+      }
+    } catch {
+      // No index file - that's OK
+    }
+  } catch {
+    // No standards directory - that's OK
+  }
+
+  // Load project-specific patterns from .mindmeld if available
+  const mindmeldConfigPath = path.join(process.cwd(), '.mindmeld', 'config.json');
+  try {
+    const configContent = await fs.readFile(mindmeldConfigPath, 'utf-8');
+    const config = JSON.parse(configContent);
+
+    if (config.project_name) {
+      sections.push(`## Project: ${config.project_name}`);
+    }
+    if (config.team && config.team.length > 0) {
+      sections.push('**Team**: ' + config.team.map(t => t.name || t.email).join(', '));
+    }
+    sections.push('');
+  } catch {
+    // No mindmeld config - that's OK
+  }
+
+  sections.push('---');
+  sections.push('*Context preserved by MindMeld pre-compact hook - mindmeld.dev*');
+
+  return sections.join('\n');
+}
+
+// Execute if called directly
+if (require.main === module) {
+  // Read session transcript from stdin or args
+  const input = process.argv[2];
+
+  if (!input) {
+    console.error('[MindMeld] Usage: pre-compact.js <session-transcript-json>');
+    process.exit(0);
+  }
+
+  const sessionTranscript = parseSessionTranscript(input);
+
+  harvestPatterns(sessionTranscript)
+    .then(async (result) => {
+      // Generate and output context summary for post-compaction injection
+      const postCompactContext = await generatePostCompactContext(
+        result,
+        result.llmAnalysis || { summary: result.llmSummary, recommendations: result.llmRecommendations }
+      );
+
+      // Output to stdout - this survives compaction
+      console.log(postCompactContext);
+      process.exit(0);
+    })
+    .catch(error => {
+      console.error('[MindMeld] Fatal error:', error);
+      process.exit(0); // Don't block compaction
+    });
+}
+
+module.exports = { harvestPatterns, parseSessionTranscript, generatePostCompactContext };

package/hooks/session-start.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+/**
+ * MindMeld - Claude Code Session Start Hook
+ *
+ * Injects ONLY relevant standards and team patterns at session start.
+ * Goal: < 500ms execution time for optimal UX.
+ *
+ * @equilateral_ai/mindmeld v3.0.0
+ */
+
+const path = require('path');
+const fs = require('fs').promises;
+
+/**
+ * Generate a fingerprint for standards injection tracking
+ * @param {string} userId - User identifier
+ * @param {string} companyId - Company identifier
+ * @param {string} tier - Subscription tier
+ * @returns {string} Base64-encoded fingerprint wrapped in invisible comment
+ */
+function generateFingerprint(userId, companyId, tier) {
+  const fingerprint = {
+    user_id: userId || 'anonymous',
+    company_id: companyId || 'unknown',
+    timestamp: new Date().toISOString(),
+    subscription_tier: tier || 'free'
+  };
+
+  const base64Fingerprint = Buffer.from(JSON.stringify(fingerprint)).toString('base64');
+  return `<!-- fp:${base64Fingerprint} -->`;
+}
+
+/**
+ * Load user and company info from MindMeld config
+ * @returns {Promise<{userId: string, companyId: string, tier: string}>}
+ */
+async function loadFingerprintConfig() {
+  try {
+    const configPath = path.join(process.cwd(), '.mindmeld', 'config.json');
+    const configContent = await fs.readFile(configPath, 'utf-8');
+    const config = JSON.parse(configContent);
+
+    return {
+      userId: config.user_id || process.env.MINDMELD_USER_ID || 'anonymous',
+      companyId: config.company_id || process.env.MINDMELD_COMPANY_ID || 'unknown',
+      tier: config.subscription_tier || process.env.MINDMELD_TIER || 'free'
+    };
+  } catch {
+    // Fallback to environment variables
+    return {
+      userId: process.env.MINDMELD_USER_ID || 'anonymous',
+      companyId: process.env.MINDMELD_COMPANY_ID || 'unknown',
+      tier: process.env.MINDMELD_TIER || 'free'
+    };
+  }
+}
+
+/**
+ * Main hook execution
+ */
+async function injectContext() {
+  const startTime = Date.now();
+
+  try {
+    // Fast bail if MindMeld not configured
+    const hasMindmeld = await checkMindmeldConfiguration();
+    if (!hasMindmeld) {
+      return '';
+    }
+
+    // Load fingerprint config
+    const fingerprintConfig = await loadFingerprintConfig();
+
+    // Load MindmeldClient with graceful degradation
+    const { MindmeldClient } = require('../src/index');
+
+    const mindmeld = new MindmeldClient({
+      projectPath: process.cwd(),
+      standardsPath: path.join(process.cwd(), '.equilateral-standards')
+    });
+
+    // 1. Ensure standards are ingested (cached, fast check)
+    await mindmeld.ensureStandardsIngested();
+
+    // 2. Detect project context
+    const context = await mindmeld.detectProject();
+
+    if (!context) {
+      return ''; // No MindMeld project
+    }
+
+    // 3. Generate session ID for tracking
+    const sessionId = mindmeld.generateSessionId();
+
+    // 4. Identify relevant standards (NOT all 80+)
+    const relevance = await mindmeld.getRelevantStandards(context);
+    const relevantStandards = relevance.standards.slice(0, 10); // Top 10 most relevant
+
+    // 5. Record standards shown (Phase 7 - fire and forget, non-blocking)
+    mindmeld.recordStandardsShown(sessionId, relevantStandards);
+
+    // 6. Load team patterns
+    const teamPatterns = await mindmeld.loadProjectContext(context.projectId);
+
+    // 7. Get recent learning (last 7 days)
+    const recentLearning = await mindmeld.getRecentLearning(context.projectId, 7);
+
+    // 8. Build context injection with fingerprint
+    const injection = formatContextInjection({
+      project: context.projectName,
+      sessionId: sessionId,
+      collaborators: context.collaborators,
+      relevantStandards: relevantStandards,
+      teamPatterns: teamPatterns ? teamPatterns.filter(p => p.correlation > 0.7) : [],
+      recentLearning: recentLearning || [],
+      fingerprint: fingerprintConfig
+    });
+
+    const elapsed = Date.now() - startTime;
+    console.error(`[MindMeld] Context injected in ${elapsed}ms`);
+
+    return injection;
+
+  } catch (error) {
+    // Graceful degradation - never block Claude Code session
+    console.error('[MindMeld] Hook error (non-fatal):', error.message);
+    return '';
+  }
+}
+
+/**
+ * Check if MindMeld is configured for this project
+ */
+async function checkMindmeldConfiguration() {
+  try {
+    const mindmeldConfig = path.join(process.cwd(), '.mindmeld', 'config.json');
+    await fs.access(mindmeldConfig);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Format context injection for Claude Code
+ * @param {object} data - Context data to inject
+ * @param {object} data.fingerprint - Fingerprint config {userId, companyId, tier}
+ */
+function formatContextInjection(data) {
+  const {
+    project,
+    sessionId,
+    collaborators,
+    relevantStandards,
+    teamPatterns,
+    recentLearning,
+    fingerprint
+  } = data;
+
+  const sections = [];
+
+  // Generate fingerprint string
+  const fingerprintStr = fingerprint
+    ? generateFingerprint(fingerprint.userId, fingerprint.companyId, fingerprint.tier)
+    : '';
+
+  // Header with session ID for tracking
+  sections.push(`# MindMeld Context - ${project}`);
+  if (sessionId) {
+    sections.push(`<!-- session:${sessionId} -->`);
+  }
+  sections.push('');
+
+  // Copyright/License notice
+  sections.push('© 2025 Equilateral AI (Pareidolia LLC). All rights reserved.');
+  sections.push('Licensed for use within MindMeld platform only. Redistribution prohibited.');
+  sections.push('');
+
+  // Collaborators
+  if (collaborators && collaborators.length > 0) {
+    sections.push('## Team');
+    sections.push(collaborators.map(c => `- ${c.name} (${c.email})`).join('\n'));
+    sections.push('');
+  }
+
+  // Relevant standards (top 10 only)
+  if (relevantStandards && relevantStandards.length > 0) {
+    sections.push('## Relevant Standards');
+    sections.push('');
+
+    for (const standard of relevantStandards) {
+      sections.push(`### ${standard.element}`);
+      sections.push(`**Category**: ${standard.category}`);
+      // Add fingerprint to rule text
+      sections.push(`**Rule**: ${standard.rule} ${fingerprintStr}`);
+
+      if (standard.examples && standard.examples.length > 0) {
+        sections.push('');
+        sections.push('**Example**:');
+        sections.push('```javascript');
+        sections.push(standard.examples[0].code);
+        sections.push('```');
+      }
+
+      if (standard.anti_patterns && standard.anti_patterns.length > 0) {
+        sections.push('');
+        sections.push('**Anti-patterns**:');
+        for (const antiPattern of standard.anti_patterns) {
+          sections.push(`- ❌ ${antiPattern.description}`);
+        }
+      }
+
+      sections.push('');
+    }
+  }
+
+  // Team patterns (high correlation only)
+  if (teamPatterns && teamPatterns.length > 0) {
+    sections.push('## Team Patterns');
+    sections.push('');
+
+    for (const pattern of teamPatterns) {
+      sections.push(`### ${pattern.element}`);
+      sections.push(`**Correlation**: ${(pattern.correlation * 100).toFixed(0)}%`);
+      sections.push(`**Usage**: ${pattern.usage_count} times across ${pattern.project_count} projects`);
+      // Add fingerprint to rule text
+      sections.push(`**Rule**: ${pattern.rule} ${fingerprintStr}`);
+      sections.push('');
+    }
+  }
+
+  // Recent learning
+  if (recentLearning && recentLearning.length > 0) {
+    sections.push('## Recent Team Learning');
+    sections.push('');
+
+    for (const learning of recentLearning) {
+      sections.push(`- **${learning.pattern}**: ${learning.insight} (${learning.date})`);
+    }
+    sections.push('');
+  }
+
+  sections.push('---');
+  sections.push('*Context provided by MindMeld - mindmeld.dev*');
+
+  return sections.join('\n');
+}
+
+// Execute if called directly
+if (require.main === module) {
+  injectContext()
+    .then(context => {
+      if (context) {
+        console.log(context);
+      }
+      process.exit(0);
+    })
+    .catch(error => {
+      console.error('[MindMeld] Fatal error:', error);
+      process.exit(0); // Don't block session start
+    });
+}
+
+module.exports = { injectContext, formatContextInjection, generateFingerprint };