@codebakers/cli 3.9.31 → 3.9.33

package/src/mcp/server.ts

@@ -1464,6 +1464,29 @@ class CodeBakersServer {
             properties: {},
           },
         },
+        {
+          name: 'coherence_audit',
+          description:
+            'Full codebase coherence audit. Checks all imports/exports, type flows, schema dependencies, API contracts, env vars, circular dependencies, and dead code. Use this for the /coherence command or when user asks to check wiring/dependencies.',
+          inputSchema: {
+            type: 'object' as const,
+            properties: {
+              focus: {
+                type: 'string',
+                enum: ['all', 'imports', 'types', 'schema', 'api', 'env', 'circular', 'dead-code'],
+                description: 'Focus area for the audit (default: all)',
+              },
+              autoFix: {
+                type: 'boolean',
+                description: 'Automatically fix issues that can be auto-fixed (default: false)',
+              },
+              includeNodeModules: {
+                type: 'boolean',
+                description: 'Include node_modules in analysis (default: false, very slow)',
+              },
+            },
+          },
+        },
         // ============================================
         // PROJECT TRACKING - Server-Side Dashboard
         // ============================================
@@ -1808,6 +1831,9 @@ class CodeBakersServer {
         case 'guardian_status':
           return this.handleGuardianStatus();
 
+        case 'coherence_audit':
+          return this.handleCoherenceAudit(args as { focus?: string; autoFix?: boolean; includeNodeModules?: boolean });
+
         // Project Tracking - Server-Side Dashboard
         case 'project_sync':
           return this.handleProjectSync(args as {
@@ -2808,10 +2834,10 @@ Or if user declines, call without fullDeploy:
       // Use default
     }
 
-    results.push(`# 🎨 Adding CodeBakers v6.16 to: ${projectName}\n`);
+    results.push(`# 🎨 Adding CodeBakers v6.17 to: ${projectName}\n`);
 
-    // v6.16 bootstrap content - magic phrase + rules at START and END
-    const V6_CLAUDE_MD = `# CodeBakers v6.16
+    // v6.17 bootstrap content - magic phrase + rules at START and END + coherence
+    const V6_CLAUDE_MD = `# CodeBakers v6.17
 
 ## 🪄 MAGIC PHRASE: "codebakers go"
 When user says "codebakers go" in chat, start the onboarding conversation:
@@ -2838,8 +2864,11 @@ When user says "codebakers go" in chat, start the onboarding conversation:
 project_status()                                    → Verify connection FIRST
 discover_patterns({ task: "what you're building" }) → Get patterns BEFORE code
 validate_complete({ feature: "name", files: [...] }) → Validate BEFORE done
+coherence_audit()                                   → Check wiring & dependencies
 \`\`\`
 
+Commands: /build, /feature, /design, /status, /audit, /coherence, /upgrade
+
 Header (after project_status succeeds): 🍪 CodeBakers is working on this...
 Header (if project_status fails): ⚠️ CodeBakers not connected
 Footer (after code): 🍪 **CodeBakers** | Patterns: X | TSC: ✅ | Tests: ✅
@@ -2851,7 +2880,7 @@ Footer (after code): 🍪 **CodeBakers** | Patterns: X | TSC: ✅ | Tests: ✅
 4. Show footer after code responses
 `;
 
-    const V6_CURSORRULES = `# CodeBakers v6.16
+    const V6_CURSORRULES = `# CodeBakers v6.17
 
 ## 🪄 "codebakers go" = Start onboarding conversation
 Ask existing/new → Ask what to build → Call init_project() → Help them build
@@ -2868,6 +2897,9 @@ Ask existing/new → Ask what to build → Call init_project() → Help them bui
 3. Show header without project_status succeeding
 4. Skip writing tests for new features
 
+Commands: /build, /feature, /design, /status, /audit, /coherence, /upgrade
+Use coherence_audit() to check wiring & dependencies
+
 ## 🚨 ALWAYS (Repeated at End)
 1. project_status() FIRST
 2. discover_patterns() before code
@@ -2878,8 +2910,8 @@ Ask existing/new → Ask what to build → Call init_project() → Help them bui
     const claudeMdPath = path.join(cwd, 'CLAUDE.md');
     if (fs.existsSync(claudeMdPath)) {
       const content = fs.readFileSync(claudeMdPath, 'utf-8');
-      if (content.includes('v6.16') && content.includes('discover_patterns')) {
-        results.push('✓ CodeBakers v6.16 already installed\n');
+      if ((content.includes('v6.16') || content.includes('v6.17')) && content.includes('discover_patterns')) {
+        results.push('✓ CodeBakers v6.17 already installed\n');
         results.push('Patterns are server-enforced. Just call `discover_patterns` before coding!');
         return {
           content: [{ type: 'text' as const, text: results.join('\n') }],
@@ -2941,7 +2973,7 @@ Ask existing/new → Ask what to build → Call init_project() → Help them bui
       fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
 
       results.push('\n---\n');
-      results.push('## ✅ CodeBakers v6.16 Installed!\n');
+      results.push('## ✅ CodeBakers v6.17 Installed!\n');
       results.push('**How it works now:**');
       results.push('1. Call `discover_patterns` before writing code');
       results.push('2. Server returns all patterns and rules');
@@ -7486,7 +7518,7 @@ ${handlers.join('\n')}
   }
 
   /**
-   * Update to CodeBakers v6.16 - server-enforced patterns with magic phrase
+   * Update to CodeBakers v6.17 - server-enforced patterns with magic phrase + coherence
    * This is the MCP equivalent of the `codebakers upgrade` CLI command
    */
   private async handleUpdatePatterns(args: { force?: boolean }) {
@@ -7496,10 +7528,10 @@ ${handlers.join('\n')}
     const claudeDir = path.join(cwd, '.claude');
     const codebakersJson = path.join(cwd, '.codebakers.json');
 
-    let response = `# 🔄 CodeBakers v6.16 Update\n\n`;
+    let response = `# 🔄 CodeBakers v6.17 Update\n\n`;
 
-    // v6.16 bootstrap content - magic phrase + rules at START and END
-    const V6_CLAUDE_MD = `# CodeBakers v6.16
+    // v6.17 bootstrap content - magic phrase + rules at START and END + coherence
+    const V6_CLAUDE_MD = `# CodeBakers v6.17
 
 ## 🪄 MAGIC PHRASE: "codebakers go"
 When user says "codebakers go" in chat, start the onboarding conversation:
@@ -7526,8 +7558,11 @@ When user says "codebakers go" in chat, start the onboarding conversation:
 project_status()                                    → Verify connection FIRST
 discover_patterns({ task: "what you're building" }) → Get patterns BEFORE code
 validate_complete({ feature: "name", files: [...] }) → Validate BEFORE done
+coherence_audit()                                   → Check wiring & dependencies
 \`\`\`
 
+Commands: /build, /feature, /design, /status, /audit, /coherence, /upgrade
+
 Header (after project_status succeeds): 🍪 CodeBakers is working on this...
 Header (if project_status fails): ⚠️ CodeBakers not connected
 Footer (after code): 🍪 **CodeBakers** | Patterns: X | TSC: ✅ | Tests: ✅
@@ -7539,7 +7574,7 @@ Footer (after code): 🍪 **CodeBakers** | Patterns: X | TSC: ✅ | Tests: ✅
 4. Show footer after code responses
 `;
 
-    const V6_CURSORRULES = `# CodeBakers v6.16
+    const V6_CURSORRULES = `# CodeBakers v6.17
 
 ## 🪄 "codebakers go" = Start onboarding conversation
 Ask existing/new → Ask what to build → Call init_project() → Help them build
@@ -7556,6 +7591,9 @@ Ask existing/new → Ask what to build → Call init_project() → Help them bui
 3. Show header without project_status succeeding
 4. Skip writing tests for new features
 
+Commands: /build, /feature, /design, /status, /audit, /coherence, /upgrade
+Use coherence_audit() to check wiring & dependencies
+
 ## 🚨 ALWAYS (Repeated at End)
 1. project_status() FIRST
 2. discover_patterns() before code
@@ -8935,6 +8973,724 @@ ${events.includes('call-started') ? `      case 'call-started':
     return { content: [{ type: 'text' as const, text: response }] };
   }
 
+  // ============================================================================
+  // COHERENCE AUDIT - Full Codebase Wiring Check
+  // ============================================================================
+
+  /**
+   * Full coherence audit - checks all wiring, dependencies, and connections
+   */
+  private handleCoherenceAudit(args: { focus?: string; autoFix?: boolean; includeNodeModules?: boolean }) {
+    const { focus = 'all', autoFix = false } = args;
+    const cwd = process.cwd();
+
+    interface CoherenceIssue {
+      category: 'import' | 'export' | 'type' | 'schema' | 'api' | 'env' | 'circular' | 'dead-code';
+      severity: 'error' | 'warning' | 'info';
+      file: string;
+      line?: number;
+      message: string;
+      fix?: string;
+      autoFixable: boolean;
+    }
+
+    const issues: CoherenceIssue[] = [];
+    const stats = {
+      filesScanned: 0,
+      importsChecked: 0,
+      exportsFound: 0,
+      typesAnalyzed: 0,
+      envVarsFound: 0,
+    };
+
+    // Helper to extract imports from a file
+    const extractImports = (content: string): Array<{ path: string; names: string[]; line: number; isTypeOnly: boolean }> => {
+      const imports: Array<{ path: string; names: string[]; line: number; isTypeOnly: boolean }> = [];
+      const lines = content.split('\n');
+
+      lines.forEach((line, i) => {
+        // Match: import { X, Y } from 'path'
+        const namedMatch = line.match(/import\s+(type\s+)?{([^}]+)}\s+from\s+['"]([^'"]+)['"]/);
+        if (namedMatch) {
+          const isTypeOnly = !!namedMatch[1];
+          const names = namedMatch[2].split(',').map(n => n.trim().split(' as ')[0].trim()).filter(Boolean);
+          imports.push({ path: namedMatch[3], names, line: i + 1, isTypeOnly });
+        }
+
+        // Match: import X from 'path'
+        const defaultMatch = line.match(/import\s+(type\s+)?(\w+)\s+from\s+['"]([^'"]+)['"]/);
+        if (defaultMatch && !namedMatch) {
+          imports.push({ path: defaultMatch[3], names: ['default'], line: i + 1, isTypeOnly: !!defaultMatch[1] });
+        }
+
+        // Match: import * as X from 'path'
+        const namespaceMatch = line.match(/import\s+\*\s+as\s+(\w+)\s+from\s+['"]([^'"]+)['"]/);
+        if (namespaceMatch) {
+          imports.push({ path: namespaceMatch[2], names: ['*'], line: i + 1, isTypeOnly: false });
+        }
+      });
+
+      return imports;
+    };
+
+    // Helper to extract exports from a file
+    const extractExports = (content: string): string[] => {
+      const exports: string[] = [];
+
+      // Named exports: export { X, Y }
+      const namedExportMatches = content.matchAll(/export\s+{([^}]+)}/g);
+      for (const match of namedExportMatches) {
+        const names = match[1].split(',').map(n => n.trim().split(' as ').pop()?.trim() || '').filter(Boolean);
+        exports.push(...names);
+      }
+
+      // Direct exports: export const/function/class/type/interface X
+      const directExportMatches = content.matchAll(/export\s+(const|let|var|function|class|type|interface|enum)\s+(\w+)/g);
+      for (const match of directExportMatches) {
+        exports.push(match[2]);
+      }
+
+      // Default export
+      if (content.includes('export default')) {
+        exports.push('default');
+      }
+
+      // Re-exports: export * from, export { X } from
+      const reExportMatches = content.matchAll(/export\s+(?:\*|{[^}]+})\s+from\s+['"]([^'"]+)['"]/g);
+      for (const match of reExportMatches) {
+        exports.push(`__reexport:${match[1]}`);
+      }
+
+      return exports;
+    };
+
+    // Helper to resolve import path to file
+    const resolveImportPath = (importPath: string, fromFile: string): string | null => {
+      // Skip external packages
+      if (!importPath.startsWith('.') && !importPath.startsWith('@/') && !importPath.startsWith('~/')) {
+        return null;
+      }
+
+      // Handle @ alias (common Next.js pattern)
+      let resolvedPath = importPath;
+      if (importPath.startsWith('@/')) {
+        resolvedPath = path.join(cwd, 'src', importPath.slice(2));
+      } else if (importPath.startsWith('~/')) {
+        resolvedPath = path.join(cwd, importPath.slice(2));
+      } else {
+        resolvedPath = path.resolve(path.dirname(fromFile), importPath);
+      }
+
+      // Try different extensions
+      const extensions = ['', '.ts', '.tsx', '.js', '.jsx', '/index.ts', '/index.tsx', '/index.js'];
+      for (const ext of extensions) {
+        const fullPath = resolvedPath + ext;
+        if (fs.existsSync(fullPath) && fs.statSync(fullPath).isFile()) {
+          return fullPath;
+        }
+      }
+
+      return null;
+    };
+
+    // Build export map for all files
+    const exportMap: Map<string, string[]> = new Map();
+    const importGraph: Map<string, string[]> = new Map(); // file -> files it imports
+    const usedExports: Set<string> = new Set(); // track which exports are actually used
+
+    const searchDirs = ['src', 'app', 'lib', 'components', 'services', 'types', 'utils', 'hooks', 'pages'];
+    const extensions = ['.ts', '.tsx', '.js', '.jsx'];
+
+    // First pass: collect all exports
+    const collectExports = (dir: string) => {
+      if (!fs.existsSync(dir)) return;
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+
+        if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+          collectExports(fullPath);
+        } else if (entry.isFile() && extensions.some(ext => entry.name.endsWith(ext))) {
+          try {
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            const exports = extractExports(content);
+            exportMap.set(fullPath, exports);
+            stats.exportsFound += exports.length;
+            stats.filesScanned++;
+          } catch {
+            // Skip unreadable files
+          }
+        }
+      }
+    };
+
+    // Collect exports from all directories
+    for (const dir of searchDirs) {
+      collectExports(path.join(cwd, dir));
+    }
+
+    // Also check root-level files
+    try {
+      const rootEntries = fs.readdirSync(cwd, { withFileTypes: true });
+      for (const entry of rootEntries) {
+        if (entry.isFile() && extensions.some(ext => entry.name.endsWith(ext))) {
+          const fullPath = path.join(cwd, entry.name);
+          try {
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            const exports = extractExports(content);
+            exportMap.set(fullPath, exports);
+          } catch {
+            // Skip
+          }
+        }
+      }
+    } catch {
+      // Skip if can't read root
+    }
+
+    // Second pass: check imports and build graph
+    const checkImports = (dir: string) => {
+      if (!fs.existsSync(dir)) return;
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+
+        if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+          checkImports(fullPath);
+        } else if (entry.isFile() && extensions.some(ext => entry.name.endsWith(ext))) {
+          try {
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            const imports = extractImports(content);
+            const relativePath = path.relative(cwd, fullPath);
+            const importedFiles: string[] = [];
+
+            for (const imp of imports) {
+              stats.importsChecked++;
+              const resolvedPath = resolveImportPath(imp.path, fullPath);
+
+              if (resolvedPath === null) {
+                // External package or unresolvable - skip
+                continue;
+              }
+
+              importedFiles.push(resolvedPath);
+
+              // Check if file exists
+              if (!fs.existsSync(resolvedPath)) {
+                if (focus === 'all' || focus === 'imports') {
+                  issues.push({
+                    category: 'import',
+                    severity: 'error',
+                    file: relativePath,
+                    line: imp.line,
+                    message: `Import target not found: '${imp.path}'`,
+                    fix: `Create the file or update the import path`,
+                    autoFixable: false,
+                  });
+                }
+                continue;
+              }
+
+              // Check if named imports exist in the target
+              const targetExports = exportMap.get(resolvedPath) || [];
+
+              for (const name of imp.names) {
+                if (name === '*' || name === 'default') {
+                  if (name === 'default' && !targetExports.includes('default')) {
+                    if (focus === 'all' || focus === 'imports') {
+                      issues.push({
+                        category: 'import',
+                        severity: 'error',
+                        file: relativePath,
+                        line: imp.line,
+                        message: `No default export in '${imp.path}'`,
+                        fix: `Add 'export default' or change to named import`,
+                        autoFixable: false,
+                      });
+                    }
+                  }
+                  continue;
+                }
+
+                // Track that this export is used
+                usedExports.add(`${resolvedPath}:${name}`);
+
+                if (!targetExports.includes(name)) {
+                  if (focus === 'all' || focus === 'imports') {
+                    issues.push({
+                      category: 'export',
+                      severity: 'error',
+                      file: relativePath,
+                      line: imp.line,
+                      message: `'${name}' is not exported from '${imp.path}'`,
+                      fix: `Add 'export { ${name} }' to ${path.basename(resolvedPath)} or update import`,
+                      autoFixable: false,
+                    });
+                  }
+                }
+              }
+            }
+
+            importGraph.set(fullPath, importedFiles);
+          } catch {
+            // Skip unreadable files
+          }
+        }
+      }
+    };
+
+    // Run import checks
+    for (const dir of searchDirs) {
+      checkImports(path.join(cwd, dir));
+    }
+
+    // Check for circular dependencies
+    if (focus === 'all' || focus === 'circular') {
+      const visited = new Set<string>();
+      const recursionStack = new Set<string>();
+      const circularPaths: string[][] = [];
+
+      const detectCircular = (file: string, pathStack: string[]): boolean => {
+        if (recursionStack.has(file)) {
+          // Found circular dependency
+          const cycleStart = pathStack.indexOf(file);
+          if (cycleStart !== -1) {
+            circularPaths.push(pathStack.slice(cycleStart).concat(file));
+          }
+          return true;
+        }
+
+        if (visited.has(file)) return false;
+
+        visited.add(file);
+        recursionStack.add(file);
+
+        const imports = importGraph.get(file) || [];
+        for (const imported of imports) {
+          detectCircular(imported, [...pathStack, file]);
+        }
+
+        recursionStack.delete(file);
+        return false;
+      };
+
+      for (const file of importGraph.keys()) {
+        detectCircular(file, []);
+      }
+
+      // Add unique circular dependencies as issues
+      const seenCycles = new Set<string>();
+      for (const cycle of circularPaths) {
+        const cycleKey = cycle.map(f => path.relative(cwd, f)).sort().join(' -> ');
+        if (!seenCycles.has(cycleKey)) {
+          seenCycles.add(cycleKey);
+          issues.push({
+            category: 'circular',
+            severity: 'warning',
+            file: path.relative(cwd, cycle[0]),
+            message: `Circular dependency: ${cycle.map(f => path.basename(f)).join(' → ')}`,
+            fix: 'Break the cycle by extracting shared code to a separate module',
+            autoFixable: false,
+          });
+        }
+      }
+    }
+
+    // Check for dead code (unused exports)
+    if (focus === 'all' || focus === 'dead-code') {
+      for (const [file, exports] of exportMap.entries()) {
+        const relativePath = path.relative(cwd, file);
+
+        // Skip entry points and config files
+        if (
+          relativePath.includes('page.tsx') ||
+          relativePath.includes('layout.tsx') ||
+          relativePath.includes('route.ts') ||
+          relativePath.includes('middleware.ts') ||
+          relativePath.endsWith('.config.ts') ||
+          relativePath.endsWith('.config.js')
+        ) {
+          continue;
+        }
+
+        for (const exp of exports) {
+          if (exp.startsWith('__reexport:') || exp === 'default') continue;
+
+          const exportKey = `${file}:${exp}`;
+          if (!usedExports.has(exportKey)) {
+            issues.push({
+              category: 'dead-code',
+              severity: 'info',
+              file: relativePath,
+              message: `Export '${exp}' is never imported`,
+              fix: `Remove if unused, or verify it's used externally`,
+              autoFixable: true,
+            });
+          }
+        }
+      }
+    }
+
+    // Check environment variables
+    if (focus === 'all' || focus === 'env') {
+      const envVarsUsed = new Set<string>();
+      const envVarsDefined = new Set<string>();
+
+      // Scan for process.env usage
+      const scanEnvUsage = (dir: string) => {
+        if (!fs.existsSync(dir)) return;
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+
+          if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+            scanEnvUsage(fullPath);
+          } else if (entry.isFile() && extensions.some(ext => entry.name.endsWith(ext))) {
+            try {
+              const content = fs.readFileSync(fullPath, 'utf-8');
+              const envMatches = content.matchAll(/process\.env\.(\w+)|process\.env\[['"](\w+)['"]\]/g);
+              for (const match of envMatches) {
+                const varName = match[1] || match[2];
+                envVarsUsed.add(varName);
+                stats.envVarsFound++;
+              }
+            } catch {
+              // Skip
+            }
+          }
+        }
+      };
+
+      for (const dir of searchDirs) {
+        scanEnvUsage(path.join(cwd, dir));
+      }
+
+      // Check .env.example and .env.local
+      const envFiles = ['.env', '.env.local', '.env.example', '.env.development'];
+      for (const envFile of envFiles) {
+        const envPath = path.join(cwd, envFile);
+        if (fs.existsSync(envPath)) {
+          try {
+            const content = fs.readFileSync(envPath, 'utf-8');
+            const lines = content.split('\n');
+            for (const line of lines) {
+              const match = line.match(/^([A-Z][A-Z0-9_]*)=/);
+              if (match) {
+                envVarsDefined.add(match[1]);
+              }
+            }
+          } catch {
+            // Skip
+          }
+        }
+      }
+
+      // Find env vars used but not defined
+      for (const varName of envVarsUsed) {
+        // Skip common Next.js vars
+        if (varName.startsWith('NEXT_') || varName === 'NODE_ENV') continue;
+
+        if (!envVarsDefined.has(varName)) {
+          issues.push({
+            category: 'env',
+            severity: 'warning',
+            file: '.env.example',
+            message: `Environment variable '${varName}' is used but not defined in .env files`,
+            fix: `Add ${varName}= to .env.example`,
+            autoFixable: true,
+          });
+        }
+      }
+
+      // Find env vars defined but not used
+      for (const varName of envVarsDefined) {
+        if (!envVarsUsed.has(varName) && !varName.startsWith('NEXT_')) {
+          issues.push({
+            category: 'env',
+            severity: 'info',
+            file: '.env',
+            message: `Environment variable '${varName}' is defined but never used`,
+            fix: 'Remove if no longer needed',
+            autoFixable: false,
+          });
+        }
+      }
+    }
+
+    // Check for Drizzle schema issues
+    if (focus === 'all' || focus === 'schema') {
+      const schemaPath = path.join(cwd, 'src', 'db', 'schema.ts');
+      const altSchemaPath = path.join(cwd, 'drizzle', 'schema.ts');
+      const schemaFile = fs.existsSync(schemaPath) ? schemaPath : fs.existsSync(altSchemaPath) ? altSchemaPath : null;
+
+      if (schemaFile) {
+        try {
+          const schemaContent = fs.readFileSync(schemaFile, 'utf-8');
+
+          // Extract table names
+          const tableMatches = schemaContent.matchAll(/export\s+const\s+(\w+)\s*=\s*(?:pgTable|mysqlTable|sqliteTable)\s*\(/g);
+          const tableNames = new Set<string>();
+          for (const match of tableMatches) {
+            tableNames.add(match[1]);
+          }
+
+          // Scan for .insert(), .update(), .delete() calls on non-existent tables
+          const scanSchemaUsage = (dir: string) => {
+            if (!fs.existsSync(dir)) return;
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+            for (const entry of entries) {
+              const fullPath = path.join(dir, entry.name);
+
+              if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+                scanSchemaUsage(fullPath);
+              } else if (entry.isFile() && (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx'))) {
+                try {
+                  const content = fs.readFileSync(fullPath, 'utf-8');
+                  const relativePath = path.relative(cwd, fullPath);
+
+                  // Check for db operations on tables
+                  const opMatches = content.matchAll(/db\.(insert|update|delete|select)\((\w+)\)/g);
+                  for (const match of opMatches) {
+                    const tableName = match[2];
+                    if (!tableNames.has(tableName) && !tableName.startsWith('sql')) {
+                      issues.push({
+                        category: 'schema',
+                        severity: 'error',
+                        file: relativePath,
+                        message: `Database operation on unknown table '${tableName}'`,
+                        fix: `Verify table exists in schema or fix the table name`,
+                        autoFixable: false,
+                      });
+                    }
+                  }
+                } catch {
+                  // Skip
+                }
+              }
+            }
+          };
+
+          for (const dir of searchDirs) {
+            scanSchemaUsage(path.join(cwd, dir));
+          }
+        } catch {
+          // Skip if can't read schema
+        }
+      }
+    }
+
+    // Check API contracts (Next.js API routes vs fetch calls)
+    if (focus === 'all' || focus === 'api') {
+      const apiRoutes = new Map<string, { methods: string[]; file: string }>();
+
+      // Find all API routes
+      const apiDir = path.join(cwd, 'src', 'app', 'api');
+      const altApiDir = path.join(cwd, 'app', 'api');
+      const pagesApiDir = path.join(cwd, 'pages', 'api');
+
+      const scanApiRoutes = (dir: string, prefix: string = '/api') => {
+        if (!fs.existsSync(dir)) return;
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+
+          if (entry.isDirectory()) {
+            scanApiRoutes(fullPath, `${prefix}/${entry.name}`);
+          } else if (entry.name === 'route.ts' || entry.name === 'route.js') {
+            try {
+              const content = fs.readFileSync(fullPath, 'utf-8');
+              const methods: string[] = [];
+
+              if (content.includes('export async function GET') || content.includes('export function GET')) methods.push('GET');
+              if (content.includes('export async function POST') || content.includes('export function POST')) methods.push('POST');
+              if (content.includes('export async function PUT') || content.includes('export function PUT')) methods.push('PUT');
+              if (content.includes('export async function DELETE') || content.includes('export function DELETE')) methods.push('DELETE');
+              if (content.includes('export async function PATCH') || content.includes('export function PATCH')) methods.push('PATCH');
+
+              apiRoutes.set(prefix, { methods, file: path.relative(cwd, fullPath) });
+            } catch {
+              // Skip
+            }
+          }
+        }
+      };
+
+      scanApiRoutes(apiDir);
+      scanApiRoutes(altApiDir);
+
+      // Scan for fetch calls to API routes
+      const scanFetchCalls = (dir: string) => {
+        if (!fs.existsSync(dir)) return;
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+
+          if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules' && entry.name !== 'api') {
+            scanFetchCalls(fullPath);
+          } else if (entry.isFile() && (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx'))) {
+            try {
+              const content = fs.readFileSync(fullPath, 'utf-8');
+              const relativePath = path.relative(cwd, fullPath);
+
+              // Match fetch('/api/...') or fetch(`/api/...`)
+              const fetchMatches = content.matchAll(/fetch\s*\(\s*[`'"]([^`'"]+)[`'"]/g);
+              for (const match of fetchMatches) {
+                const url = match[1];
+                if (url.startsWith('/api/')) {
+                  // Extract base path (before query params or dynamic segments)
+                  const basePath = url.split('?')[0].replace(/\$\{[^}]+\}/g, '[dynamic]');
+
+                  // Check if this route exists
+                  let routeFound = false;
+                  for (const [route] of apiRoutes) {
+                    // Simple matching - could be improved
+                    if (basePath === route || basePath.startsWith(route + '/')) {
+                      routeFound = true;
+                      break;
+                    }
+                  }
+
+                  if (!routeFound && !basePath.includes('[dynamic]')) {
+                    issues.push({
+                      category: 'api',
+                      severity: 'warning',
+                      file: relativePath,
+                      message: `Fetch to '${url}' but no matching API route found`,
+                      fix: `Create the API route or fix the URL`,
+                      autoFixable: false,
+                    });
+                  }
+                }
+              }
+            } catch {
+              // Skip
+            }
+          }
+        }
+      };
+
+      for (const dir of ['src', 'app', 'components', 'lib']) {
+        scanFetchCalls(path.join(cwd, dir));
+      }
+    }
+
+    // Generate report
+    let response = `# 🔗 Coherence Audit Report\n\n`;
+
+    // Summary
+    const errorCount = issues.filter(i => i.severity === 'error').length;
+    const warningCount = issues.filter(i => i.severity === 'warning').length;
+    const infoCount = issues.filter(i => i.severity === 'info').length;
+    const autoFixableCount = issues.filter(i => i.autoFixable).length;
+
+    response += `## 📊 Summary\n\n`;
+    response += `| Metric | Value |\n`;
+    response += `|--------|-------|\n`;
+    response += `| Files scanned | ${stats.filesScanned} |\n`;
+    response += `| Imports checked | ${stats.importsChecked} |\n`;
+    response += `| Exports found | ${stats.exportsFound} |\n`;
+    response += `| 🔴 Errors | ${errorCount} |\n`;
+    response += `| 🟡 Warnings | ${warningCount} |\n`;
+    response += `| 🔵 Info | ${infoCount} |\n`;
+    response += `| 🔧 Auto-fixable | ${autoFixableCount} |\n\n`;
+
+    if (issues.length === 0) {
+      response += `## ✅ All Clear!\n\n`;
+      response += `No coherence issues found. Your codebase wiring is solid.\n`;
+    } else {
+      // Group issues by category
+      const categories: Record<string, CoherenceIssue[]> = {
+        import: [],
+        export: [],
+        type: [],
+        schema: [],
+        api: [],
+        env: [],
+        circular: [],
+        'dead-code': [],
+      };
+
+      for (const issue of issues) {
+        categories[issue.category].push(issue);
+      }
+
+      const categoryNames: Record<string, string> = {
+        import: '🔴 Broken Imports',
+        export: '🔴 Missing Exports',
+        type: '🟠 Type Mismatches',
+        schema: '🟠 Schema Issues',
+        api: '🟡 API Contract Issues',
+        env: '🟡 Environment Variables',
+        circular: '⚪ Circular Dependencies',
+        'dead-code': '🔵 Dead Code',
+      };
+
+      for (const [category, catIssues] of Object.entries(categories)) {
+        if (catIssues.length === 0) continue;
+
+        response += `## ${categoryNames[category]} (${catIssues.length})\n\n`;
+
+        // Show first 10 issues per category
+        const displayIssues = catIssues.slice(0, 10);
+        for (const issue of displayIssues) {
+          response += `### \`${issue.file}${issue.line ? `:${issue.line}` : ''}\`\n`;
+          response += `**Issue:** ${issue.message}\n`;
+          if (issue.fix) {
+            response += `**Fix:** ${issue.fix}${issue.autoFixable ? ' 🔧' : ''}\n`;
+          }
+          response += `\n`;
+        }
+
+        if (catIssues.length > 10) {
+          response += `*... and ${catIssues.length - 10} more ${category} issues*\n\n`;
+        }
+      }
+    }
+
+    // Recommendations
+    response += `## 💡 Recommendations\n\n`;
+
+    if (errorCount > 0) {
+      response += `1. **Fix ${errorCount} errors first** - These will cause runtime failures\n`;
+    }
+    if (warningCount > 0) {
+      response += `2. **Review ${warningCount} warnings** - These may cause issues\n`;
+    }
+    response += `3. Run \`npx tsc --noEmit\` to verify TypeScript compiles\n`;
+    response += `4. Run your test suite to verify functionality\n`;
+
+    if (autoFixableCount > 0) {
+      response += `\n---\n\n`;
+      response += `**${autoFixableCount} issues can be auto-fixed.** Run \`guardian_heal\` to fix them.\n`;
+    }
+
+    // Save state for guardian_heal
+    const statePath = path.join(cwd, '.codebakers', 'coherence-state.json');
+    try {
+      fs.mkdirSync(path.dirname(statePath), { recursive: true });
+      fs.writeFileSync(statePath, JSON.stringify({
+        lastAudit: new Date().toISOString(),
+        focus,
+        stats,
+        issues: issues.map(i => ({
+          ...i,
+          // Include only auto-fixable for healing
+        })),
+        summary: { errors: errorCount, warnings: warningCount, info: infoCount, autoFixable: autoFixableCount },
+      }, null, 2));
+    } catch {
+      // Ignore write errors
+    }
+
+    return { content: [{ type: 'text' as const, text: response }] };
+  }
+
   // ============================================================================
   // PROJECT TRACKING - Server-Side Dashboard
   // ============================================================================