@massu/core 0.1.1 → 0.4.0

package/src/tools.ts

@@ -1,12 +1,29 @@
 // Copyright (c) 2026 Massu. All rights reserved.
 // Licensed under BSL 1.1 - see LICENSE file for details.
 
+import { readFileSync, existsSync } from 'fs';
+import { resolve, basename } from 'path';
+import { ensureWithinRoot } from './security-utils.ts';
 import type Database from 'better-sqlite3';
-import { getMemoryToolDefinitions, handleMemoryToolCall, isMemoryTool } from './memory-tools.ts';
+import { matchRules } from './rules.ts';
+import { buildImportIndex } from './import-resolver.ts';
+import { buildTrpcIndex } from './trpc-index.ts';
+import { buildPageDeps, findAffectedPages } from './page-deps.ts';
+import { buildMiddlewareTree, isInMiddlewareTree, getMiddlewareTree } from './middleware-tree.ts';
+import { classifyFile, classifyRouter, findCrossDomainImports, getFilesInDomain } from './domains.ts';
+import { parsePrismaSchema, detectMismatches, findColumnUsageInRouters } from './schema-mapper.ts';
+import { isDataStale, updateBuildTimestamp, isPythonDataStale, updatePythonBuildTimestamp } from './db.ts';
+import { buildPythonImportIndex } from './python/import-resolver.ts';
+import { buildPythonRouteIndex } from './python/route-indexer.ts';
+import { buildPythonModelIndex } from './python/model-indexer.ts';
+import { buildPythonMigrationIndex } from './python/migration-indexer.ts';
+import { buildPythonCouplingIndex } from './python/coupling-detector.ts';
+import { getMemoryToolDefinitions, handleMemoryToolCall } from './memory-tools.ts';
 import { getMemoryDb } from './memory-db.ts';
-import { getDocsToolDefinitions, handleDocsToolCall, isDocsTool } from './docs-tools.ts';
+import { getDocsToolDefinitions, handleDocsToolCall } from './docs-tools.ts';
 import { getObservabilityToolDefinitions, handleObservabilityToolCall, isObservabilityTool } from './observability-tools.ts';
-import { getSentinelToolDefinitions, handleSentinelToolCall, isSentinelTool } from './sentinel-tools.ts';
+import { getSentinelToolDefinitions, handleSentinelToolCall } from './sentinel-tools.ts';
+import { runFeatureScan } from './sentinel-scanner.ts';
 import { getAnalyticsToolDefinitions, isAnalyticsTool, handleAnalyticsToolCall } from './analytics.ts';
 import { getCostToolDefinitions, isCostTool, handleCostToolCall } from './cost-tracker.ts';
 import { getPromptToolDefinitions, isPromptTool, handlePromptToolCall } from './prompt-analyzer.ts';
@@ -17,20 +34,103 @@ import { getSecurityToolDefinitions, isSecurityTool, handleSecurityToolCall } fr
 import { getDependencyToolDefinitions, isDependencyTool, handleDependencyToolCall } from './dependency-scorer.ts';
 import { getTeamToolDefinitions, isTeamTool, handleTeamToolCall } from './team-knowledge.ts';
 import { getRegressionToolDefinitions, isRegressionTool, handleRegressionToolCall } from './regression-detector.ts';
-import { getCoreToolDefinitions, isCoreTool, handleCoreToolCall, ensureIndexes } from './core-tools.ts';
-import { getConfig } from './config.ts';
-import { text } from './tool-helpers.ts';
-import type { ToolDefinition, ToolResult } from './tool-helpers.ts';
+import { getKnowledgeToolDefinitions, isKnowledgeTool, handleKnowledgeToolCall } from './knowledge-tools.ts';
+import { getKnowledgeDb } from './knowledge-db.ts';
+import { getPythonToolDefinitions, isPythonTool, handlePythonToolCall } from './python-tools.ts';
+import { getConfig, getProjectRoot, getResolvedPaths } from './config.ts';
+import { getCurrentTier, getToolTier, isToolAllowed, annotateToolDefinitions, getLicenseToolDefinitions, isLicenseTool, handleLicenseToolCall } from './license.ts';
 
-export type { ToolDefinition, ToolResult } from './tool-helpers.ts';
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  tier?: 'free' | 'pro' | 'team' | 'enterprise';
+}
+
+export interface ToolResult {
+  content: { type: 'text'; text: string }[];
+}
+
+/** Get the configured tool prefix (e.g., 'massu' or 'myapp') */
+function prefix(): string {
+  return getConfig().toolPrefix;
+}
+
+/** Prefix a tool name with the configured prefix */
+function p(name: string): string {
+  return `${prefix()}_${name}`;
+}
 
 /**
- * Run a function with a memoryDb instance, ensuring it is closed after use.
+ * Strip the configured prefix from a tool name to get the base name.
+ * e.g., "massu_sync" -> "sync", "massu_memory_search" -> "memory_search"
  */
-function withMemoryDb<T>(fn: (db: Database.Database) => T): T {
-  const memDb = getMemoryDb();
-  try { return fn(memDb); }
-  finally { memDb.close(); }
+function stripPrefix(name: string): string {
+  const pfx = prefix() + '_';
+  if (name.startsWith(pfx)) {
+    return name.slice(pfx.length);
+  }
+  return name;
+}
+
+/**
+ * Ensure indexes are built and up-to-date.
+ * Lazy initialization: only rebuilds if stale.
+ */
+function ensureIndexes(dataDb: Database.Database, codegraphDb: Database.Database, force: boolean = false): string {
+  const results: string[] = [];
+  const config = getConfig();
+
+  // JS indexes
+  if (force || isDataStale(dataDb, codegraphDb)) {
+    const importCount = buildImportIndex(dataDb, codegraphDb);
+    results.push(`Import edges: ${importCount}`);
+
+    if (config.framework.router === 'trpc') {
+      const trpcStats = buildTrpcIndex(dataDb);
+      results.push(`tRPC procedures: ${trpcStats.totalProcedures} (${trpcStats.withCallers} with UI, ${trpcStats.withoutCallers} without)`);
+    }
+
+    const pageCount = buildPageDeps(dataDb, codegraphDb);
+    results.push(`Page deps: ${pageCount} pages`);
+
+    if (config.paths.middleware) {
+      const middlewareCount = buildMiddlewareTree(dataDb);
+      results.push(`Middleware tree: ${middlewareCount} files`);
+    }
+
+    updateBuildTimestamp(dataDb);
+  }
+
+  // Python indexes — independent of JS staleness
+  if (config.python?.root) {
+    const pythonRoot = config.python.root;
+    const excludeDirs = config.python.exclude_dirs || ['__pycache__', '.venv', 'venv', '.mypy_cache', '.pytest_cache'];
+
+    if (force || isPythonDataStale(dataDb, resolve(getProjectRoot(), pythonRoot))) {
+      const pyImports = buildPythonImportIndex(dataDb, pythonRoot, excludeDirs);
+      results.push(`Python imports: ${pyImports}`);
+
+      const pyRoutes = buildPythonRouteIndex(dataDb, pythonRoot, excludeDirs);
+      results.push(`Python routes: ${pyRoutes}`);
+
+      const pyModels = buildPythonModelIndex(dataDb, pythonRoot, excludeDirs);
+      results.push(`Python models: ${pyModels}`);
+
+      if (config.python.alembic_dir) {
+        const pyMigrations = buildPythonMigrationIndex(dataDb, config.python.alembic_dir);
+        results.push(`Python migrations: ${pyMigrations}`);
+      }
+
+      const pyCoupling = buildPythonCouplingIndex(dataDb);
+      results.push(`Python coupling: ${pyCoupling}`);
+
+      updatePythonBuildTimestamp(dataDb);
+    }
+  }
+
+  if (results.length === 0) return 'Indexes are up-to-date.';
+  return `Indexes rebuilt:\n${results.join('\n')}`;
 }
 
 /**
@@ -39,7 +139,7 @@ function withMemoryDb<T>(fn: (db: Database.Database) => T): T {
 export function getToolDefinitions(): ToolDefinition[] {
   const config = getConfig();
 
-  return [
+  return annotateToolDefinitions([
     // Memory tools
     ...getMemoryToolDefinitions(),
     // Observability tools
@@ -59,53 +159,941 @@ export function getToolDefinitions(): ToolDefinition[] {
     // Security layer (security scoring, dependency risk)
     ...getSecurityToolDefinitions(),
     ...getDependencyToolDefinitions(),
-    // Enterprise layer (team knowledge — cloud-only; regression detection — always)
-    ...(config.cloud?.enabled ? getTeamToolDefinitions() : []),
+    // Enterprise layer (team knowledge, regression detection)
+    ...getTeamToolDefinitions(),
     ...getRegressionToolDefinitions(),
-    // Core tools (sync, context, impact, domains, schema, trpc_map, coupling_check)
-    ...getCoreToolDefinitions(),
-  ];
+    // Knowledge layer (indexed .claude/ knowledge — rules, patterns, incidents)
+    ...getKnowledgeToolDefinitions(),
+    // Python code intelligence tools
+    ...getPythonToolDefinitions(),
+    // License tools (always available)
+    ...getLicenseToolDefinitions(),
+    // Core tools
+    {
+      name: p('sync'),
+      description: 'Force rebuild all indexes (import edges, tRPC mappings, page deps, middleware tree). Run this after significant code changes.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
+    },
+    {
+      name: p('context'),
+      description: 'Get context for a file: applicable rules, pattern warnings, schema mismatch alerts, and whether the file is in the middleware import tree.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file: { type: 'string', description: 'File path relative to project root' },
+        },
+        required: ['file'],
+      },
+    },
+    ...(config.framework.router === 'trpc' ? [
+      {
+        name: p('trpc_map'),
+        description: 'Map tRPC procedures to their UI call sites. Find which components call a router, which procedures have no UI callers, or list all procedures for a router.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            router: { type: 'string', description: 'Router name (e.g., "orders")' },
+            procedure: { type: 'string', description: 'Procedure name to search across all routers' },
+            uncoupled: { type: 'boolean', description: 'If true, show only procedures with ZERO UI callers' },
+          },
+          required: [],
+        },
+      },
+      {
+        name: p('coupling_check'),
+        description: 'Automated coupling check. Finds all procedures with zero UI callers and components not rendered in any page.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            staged_files: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Optional: only check these specific files',
+            },
+          },
+          required: [],
+        },
+      },
+    ] : []),
+    {
+      name: p('impact'),
+      description: 'Full impact analysis for a file: which pages are affected, which database tables are in the chain, middleware tree membership, domain crossings.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file: { type: 'string', description: 'File path relative to project root' },
+        },
+        required: ['file'],
+      },
+    },
+    ...(config.domains.length > 0 ? [{
+      name: p('domains'),
+      description: 'Domain boundary information. Classify a file into its domain, show cross-domain imports, or list all files in a domain.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file: { type: 'string', description: 'File to classify into a domain' },
+          crossings: { type: 'boolean', description: 'Show all cross-domain imports (violations highlighted)' },
+          domain: { type: 'string', description: 'Domain name to list all files for' },
+        },
+        required: [],
+      },
+    }] : []),
+    ...(config.framework.orm === 'prisma' ? [{
+      name: p('schema'),
+      description: 'Prisma schema cross-reference. Show columns for a table, detect mismatches between code and schema, or verify column references in a file.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          table: { type: 'string', description: 'Table/model name to inspect' },
+          mismatches: { type: 'boolean', description: 'Show all detected column name mismatches' },
+          verify: { type: 'string', description: 'File path to verify column references against schema' },
+        },
+        required: [],
+      },
+    }] : []),
+  ]);
 }
 
 /**
  * Handle a tool call and return the result.
  */
-export function handleToolCall(
+export async function handleToolCall(
   name: string,
   args: Record<string, unknown>,
   dataDb: Database.Database,
   codegraphDb: Database.Database
-): ToolResult {
+): Promise<ToolResult> {
+  // P3-017: Tier gate — check before any routing
+  const userTier = await getCurrentTier();
+  const requiredTier = getToolTier(name);
+  if (!isToolAllowed(name, userTier)) {
+    return text(`This tool requires ${requiredTier} tier. Current tier: ${userTier}. Upgrade at https://massu.ai/pricing`);
+  }
+
   // Ensure indexes are built before any tool call
-  ensureIndexes(dataDb, codegraphDb);
+  const syncMessage = ensureIndexes(dataDb, codegraphDb);
+  const pfx = prefix();
 
   try {
-    // Route to module tools via isTool() matchers + withMemoryDb helper
-    if (isMemoryTool(name)) return withMemoryDb(db => handleMemoryToolCall(name, args, db));
-    if (isObservabilityTool(name)) return withMemoryDb(db => handleObservabilityToolCall(name, args, db));
-    if (isDocsTool(name)) return handleDocsToolCall(name, args);
-    if (isSentinelTool(name)) return handleSentinelToolCall(name, args, dataDb);
-    if (isAnalyticsTool(name)) return withMemoryDb(db => handleAnalyticsToolCall(name, args, db));
-    if (isCostTool(name)) return withMemoryDb(db => handleCostToolCall(name, args, db));
-    if (isPromptTool(name)) return withMemoryDb(db => handlePromptToolCall(name, args, db));
-    if (isAuditTool(name)) return withMemoryDb(db => handleAuditToolCall(name, args, db));
-    if (isValidationTool(name)) return withMemoryDb(db => handleValidationToolCall(name, args, db));
-    if (isAdrTool(name)) return withMemoryDb(db => handleAdrToolCall(name, args, db));
-    if (isSecurityTool(name)) return withMemoryDb(db => handleSecurityToolCall(name, args, db));
-    if (isDependencyTool(name)) return withMemoryDb(db => handleDependencyToolCall(name, args, db));
-    if (isTeamTool(name)) {
-      if (!getConfig().cloud?.enabled) {
-        return text('This tool requires Cloud Team or Enterprise. Configure cloud sync to enable.');
+    // Route memory tools to memory handler
+    if (name.startsWith(pfx + '_memory_')) {
+      const memDb = getMemoryDb();
+      try {
+        return handleMemoryToolCall(name, args, memDb);
+      } finally {
+        memDb.close();
+      }
+    }
+
+    // Route observability tools to observability handler
+    if (isObservabilityTool(name)) {
+      const memDb = getMemoryDb();
+      try {
+        return handleObservabilityToolCall(name, args, memDb);
+      } finally {
+        memDb.close();
       }
-      return withMemoryDb(db => handleTeamToolCall(name, args, db));
     }
-    if (isRegressionTool(name)) return withMemoryDb(db => handleRegressionToolCall(name, args, db));
 
-    // Core tools (sync, context, trpc_map, coupling_check, impact, domains, schema)
-    if (isCoreTool(name)) return handleCoreToolCall(name, args, dataDb, codegraphDb);
+    // Route docs tools to docs handler
+    if (name.startsWith(pfx + '_docs_')) {
+      return handleDocsToolCall(name, args);
+    }
+
+    // Route sentinel tools to sentinel handler
+    if (name.startsWith(pfx + '_sentinel_')) {
+      return handleSentinelToolCall(name, args, dataDb);
+    }
+
+    // Route analytics layer tools
+    if (isAnalyticsTool(name)) {
+      const memDb = getMemoryDb();
+      try { return handleAnalyticsToolCall(name, args, memDb); }
+      finally { memDb.close(); }
+    }
+    if (isCostTool(name)) {
+      const memDb = getMemoryDb();
+      try { return handleCostToolCall(name, args, memDb); }
+      finally { memDb.close(); }
+    }
+    if (isPromptTool(name)) {
+      const memDb = getMemoryDb();
+      try { return handlePromptToolCall(name, args, memDb); }
+      finally { memDb.close(); }
+    }
+
+    // Route governance layer tools
+    if (isAuditTool(name)) {
+      const memDb = getMemoryDb();
+      try { return handleAuditToolCall(name, args, memDb); }
+      finally { memDb.close(); }
+    }
+    if (isValidationTool(name)) {
+      const memDb = getMemoryDb();
+      try { return handleValidationToolCall(name, args, memDb); }
+      finally { memDb.close(); }
+    }
+    if (isAdrTool(name)) {
+      const memDb = getMemoryDb();
+      try { return handleAdrToolCall(name, args, memDb); }
+      finally { memDb.close(); }
+    }
+
+    // Route security layer tools
+    if (isSecurityTool(name)) {
+      const memDb = getMemoryDb();
+      try { return handleSecurityToolCall(name, args, memDb); }
+      finally { memDb.close(); }
+    }
+    if (isDependencyTool(name)) {
+      const memDb = getMemoryDb();
+      try { return handleDependencyToolCall(name, args, memDb); }
+      finally { memDb.close(); }
+    }
+
+    // Route enterprise layer tools
+    if (isTeamTool(name)) {
+      const memDb = getMemoryDb();
+      try { return handleTeamToolCall(name, args, memDb); }
+      finally { memDb.close(); }
+    }
+    if (isRegressionTool(name)) {
+      const memDb = getMemoryDb();
+      try { return handleRegressionToolCall(name, args, memDb); }
+      finally { memDb.close(); }
+    }
+
+    // Route knowledge layer tools
+    if (isKnowledgeTool(name)) {
+      const knowledgeDb = getKnowledgeDb();
+      try { return handleKnowledgeToolCall(name, args, knowledgeDb); }
+      finally { knowledgeDb.close(); }
+    }
+
+    // Route Python tools (uses dataDb, not memDb)
+    if (isPythonTool(name)) {
+      return handlePythonToolCall(name, args, dataDb);
+    }
+
+    // Route license tools
+    if (isLicenseTool(name)) {
+      const memDb = getMemoryDb();
+      try { return await handleLicenseToolCall(name, args, memDb); }
+      finally { memDb.close(); }
+    }
 
-    return text(`Unknown tool: ${name}`);
+    // Match core tools by base name
+    const baseName = stripPrefix(name);
+    switch (baseName) {
+      case 'sync':
+        return handleSync(dataDb, codegraphDb);
+      case 'context':
+        return handleContext(args.file as string, dataDb, codegraphDb);
+      case 'trpc_map':
+        return handleTrpcMap(args, dataDb);
+      case 'coupling_check':
+        return handleCouplingCheck(args, dataDb, codegraphDb);
+      case 'impact':
+        return handleImpact(args.file as string, dataDb, codegraphDb);
+      case 'domains':
+        return handleDomains(args, dataDb, codegraphDb);
+      case 'schema':
+        return handleSchema(args);
+      default:
+        return text(`Unknown tool: ${name}`);
+    }
   } catch (error) {
-    return text(`Error in ${name}: ${error instanceof Error ? error.message : String(error)}`);
+    const msg = error instanceof Error ? error.message : String(error);
+    // Strip file paths and stack traces from error messages exposed to clients
+    const safeMsg = msg.split('\n')[0].replace(/\/(Users|home|var|tmp)\/[^\s:]+/g, '<path>');
+    return text(`Error in ${name}: ${safeMsg}`);
+  }
+}
+
+function text(content: string): ToolResult {
+  return { content: [{ type: 'text', text: content }] };
+}
+
+// === Tool Handlers ===
+
+function handleSync(dataDb: Database.Database, codegraphDb: Database.Database): ToolResult {
+  const result = ensureIndexes(dataDb, codegraphDb, true);
+
+  // Run feature auto-discovery after index rebuild
+  try {
+    const scanResult = runFeatureScan(dataDb);
+    return text(`${result}\n\nFeature scan: ${scanResult.registered} features registered (${scanResult.fromProcedures} from procedures, ${scanResult.fromPages} from pages, ${scanResult.fromComponents} from components)`);
+  } catch (error) {
+    return text(`${result}\n\nFeature scan failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function handleContext(file: string, dataDb: Database.Database, codegraphDb: Database.Database): ToolResult {
+  const lines: string[] = [];
+
+  // 1. CodeGraph context
+  const nodes = codegraphDb.prepare(
+    "SELECT name, kind, start_line, end_line FROM nodes WHERE file_path = ? ORDER BY start_line"
+  ).all(file) as { name: string; kind: string; start_line: number; end_line: number }[];
+
+  if (nodes.length > 0) {
+    lines.push('## CodeGraph Nodes');
+    for (const node of nodes.slice(0, 30)) {
+      lines.push(`- ${node.kind}: ${node.name} (L${node.start_line}-${node.end_line})`);
+    }
+    if (nodes.length > 30) {
+      lines.push(`... and ${nodes.length - 30} more`);
+    }
+    lines.push('');
+  }
+
+  // 2. Applicable rules
+  const rules = matchRules(file);
+  if (rules.length > 0) {
+    lines.push('## Applicable Rules');
+    for (const rule of rules) {
+      const severity = rule.severity ? `[${rule.severity}]` : '';
+      for (const r of rule.rules) {
+        lines.push(`- ${severity} ${r}`);
+      }
+      if (rule.patternFile) {
+        lines.push(`  See: .claude/${rule.patternFile}`);
+      }
+    }
+    lines.push('');
+  }
+
+  // 3. Middleware tree check
+  if (isInMiddlewareTree(dataDb, file)) {
+    lines.push('## WARNING: Middleware Import Tree');
+    lines.push('This file is imported (directly or transitively) by the middleware entry point.');
+    lines.push('NO Node.js dependencies allowed (pino, winston, fs, crypto, path, child_process).');
+    lines.push('');
+  }
+
+  // 4. Domain classification
+  const domain = classifyFile(file);
+  lines.push(`## Domain: ${domain}`);
+  lines.push('');
+
+  // 5. Import edges
+  const imports = dataDb.prepare(
+    'SELECT target_file, imported_names FROM massu_imports WHERE source_file = ? LIMIT 20'
+  ).all(file) as { target_file: string; imported_names: string }[];
+
+  if (imports.length > 0) {
+    lines.push('## Imports (from this file)');
+    for (const imp of imports) {
+      const names = JSON.parse(imp.imported_names);
+      lines.push(`- ${imp.target_file}${names.length > 0 ? ': ' + names.join(', ') : ''}`);
+    }
+    lines.push('');
+  }
+
+  // 6. Imported BY
+  const importedBy = dataDb.prepare(
+    'SELECT source_file FROM massu_imports WHERE target_file = ? LIMIT 20'
+  ).all(file) as { source_file: string }[];
+
+  if (importedBy.length > 0) {
+    lines.push('## Imported By');
+    for (const imp of importedBy) {
+      lines.push(`- ${imp.source_file}`);
+    }
+    lines.push('');
+  }
+
+  // 7. Knowledge context (relevant CRs, schema warnings, incidents, corrections)
+  try {
+    const knowledgeDb = getKnowledgeDb();
+    try {
+      const docCount = (knowledgeDb.prepare('SELECT COUNT(*) as cnt FROM knowledge_documents').get() as { cnt: number })?.cnt ?? 0;
+      if (docCount > 0) {
+        // Schema mismatch warnings: check if file references any known-mismatch tables
+        const mismatches = knowledgeDb.prepare('SELECT table_name, wrong_column, correct_column FROM knowledge_schema_mismatches').all() as {
+          table_name: string; wrong_column: string; correct_column: string;
+        }[];
+
+        if (mismatches.length > 0) {
+          if (file.includes('router') || file.includes('server/api')) {
+            lines.push('## Schema Mismatch Warnings');
+            lines.push('Known column name traps (from CLAUDE.md):');
+            for (const m of mismatches.slice(0, 5)) {
+              lines.push(`- \`${m.table_name}.${m.wrong_column}\` → use \`${m.correct_column}\` instead`);
+            }
+            lines.push('');
+          }
+        }
+
+        // Dynamic rule matching — combine file-type defaults with content-based FTS
+        const fileType = file.includes('router') || file.includes('server/api') ? 'router'
+          : file.includes('components') || file.includes('app/') ? 'component'
+          : file.includes('middleware') ? 'middleware'
+          : file.includes('migration') ? 'migration'
+          : 'other';
+
+        const domainDefaultCRs: Record<string, string[]> = {
+          router: ['CR-2', 'CR-6'],
+          component: ['CR-8', 'CR-12'],
+          middleware: ['CR-16', 'CR-19'],
+          migration: ['CR-2', 'CR-36'],
+        };
+
+        const defaultCRs = domainDefaultCRs[fileType] || [];
+
+        // Extract keywords from file content for FTS matching
+        let ftsRuleIds: string[] = [];
+        try {
+          const resolvedPaths = getResolvedPaths();
+          const root = getProjectRoot();
+          const absFilePath = ensureWithinRoot(resolve(resolvedPaths.srcDir, '..', file), root);
+          if (existsSync(absFilePath)) {
+            const fileContent = readFileSync(absFilePath, 'utf-8').slice(0, 3000);
+            const keywords: string[] = [];
+            if (fileContent.includes('ctx.db')) keywords.push('database', 'schema');
+            if (fileContent.includes('BigInt') || fileContent.includes('Decimal')) keywords.push('BigInt', 'serialization');
+            if (fileContent.includes('protectedProcedure') || fileContent.includes('publicProcedure')) keywords.push('procedure', 'mutation');
+            if (fileContent.includes('Select') || fileContent.includes('value=')) keywords.push('Select', 'value');
+            if (fileContent.includes('include:')) keywords.push('include', 'relation');
+            if (fileContent.includes('migration') || fileContent.includes('ALTER TABLE')) keywords.push('migration', 'schema');
+            if (fileContent.includes('RLS') || fileContent.includes('policy')) keywords.push('RLS', 'policy');
+            if (fileContent.includes('onPointerDown') || fileContent.includes('onClick')) keywords.push('stylus', 'pointer');
+
+            if (keywords.length > 0) {
+              const ftsQuery = keywords.slice(0, 5).map(k => `"${k}"`).join(' OR ');
+              try {
+                const ftsResults = knowledgeDb.prepare(`
+                  SELECT DISTINCT kc.heading as rule_id
+                  FROM knowledge_fts kf
+                  JOIN knowledge_chunks kc ON kc.id = kf.rowid
+                  WHERE kf.content MATCH ? AND kc.chunk_type = 'rule'
+                  LIMIT 8
+                `).all(ftsQuery) as { rule_id: string }[];
+                ftsRuleIds = ftsResults.map(r => r.rule_id).filter(id => id.startsWith('CR-'));
+              } catch { /* FTS syntax error — fall back to defaults */ }
+            }
+          }
+        } catch { /* File read error — fall back to defaults */ }
+
+        // Combine: defaults + FTS-discovered, deduplicated
+        const relevantCRs = [...new Set([...defaultCRs, ...ftsRuleIds])].slice(0, 10);
+
+        if (relevantCRs.length > 0) {
+          const placeholders = relevantCRs.map(() => '?').join(',');
+          const crRules = knowledgeDb.prepare(
+            `SELECT rule_id, rule_text, vr_type FROM knowledge_rules WHERE rule_id IN (${placeholders})`
+          ).all(...relevantCRs) as { rule_id: string; rule_text: string; vr_type: string }[];
+
+          if (crRules.length > 0) {
+            lines.push('## Relevant Canonical Rules');
+            for (const cr of crRules) {
+              lines.push(`- **${cr.rule_id}**: ${cr.rule_text} (${cr.vr_type})`);
+            }
+            lines.push('');
+          }
+        }
+
+        // Relevant incidents based on file type
+        const domainKeywords: Record<string, string[]> = {
+          router: ['Schema', 'Migration', 'Database', 'API'],
+          component: ['UI', 'Render', 'Component', 'UX'],
+          middleware: ['Auth', 'Edge', 'Build'],
+          migration: ['Schema', 'Migration', 'Database'],
+        };
+        const incidentKeywords = domainKeywords[fileType] || [];
+        if (incidentKeywords.length > 0) {
+          const kwPlaceholders = incidentKeywords.map(() => '?').join(' OR type LIKE ');
+          const kwParams = incidentKeywords.map(k => `%${k}%`);
+          const incidents = knowledgeDb.prepare(
+            `SELECT incident_num, date, type, gap_found, prevention FROM knowledge_incidents WHERE type LIKE ${kwPlaceholders} ORDER BY incident_num DESC LIMIT 5`
+          ).all(...kwParams) as { incident_num: number; date: string; type: string; gap_found: string; prevention: string }[];
+
+          if (incidents.length > 0) {
+            lines.push('## Related Incidents');
+            for (const inc of incidents) {
+              lines.push(`- **#${inc.incident_num}** (${inc.type}): ${inc.gap_found}`);
+            }
+            lines.push('');
+          }
+        }
+
+        // Active corrections (behavioral learning)
+        try {
+          const corrections = knowledgeDb.prepare(`
+            SELECT heading, content FROM knowledge_chunks
+            WHERE metadata LIKE '%"is_correction":true%'
+            ORDER BY CAST(json_extract(metadata, '$.date') AS TEXT) DESC
+            LIMIT 3
+          `).all() as { heading: string; content: string }[];
+
+          if (corrections.length > 0) {
+            lines.push('## Active Corrections');
+            for (const c of corrections) {
+              const ruleLine = c.content.split('\n').find(l => l.startsWith('Rule:')) || c.content.split('\n')[0];
+              lines.push(`- ${c.heading}: ${ruleLine}`);
+            }
+            lines.push('');
+          }
+        } catch { /* corrections query failed — graceful degradation */ }
+      }
+    } finally {
+      knowledgeDb.close();
+    }
+  } catch {
+    // Knowledge DB not available — graceful degradation
   }
+
+  // 8. Memory context — past bugs/fixes for this file
+  let memDb: Database.Database | null = null;
+  try {
+    memDb = getMemoryDb();
+    const fileObservations = memDb.prepare(`
+      SELECT o.type, o.title, o.cr_rule, o.importance, o.created_at
+      FROM observations o
+      WHERE o.files_involved LIKE ?
+      ORDER BY o.importance DESC, o.created_at_epoch DESC
+      LIMIT 5
+    `).all(`%${basename(file)}%`) as { type: string; title: string; cr_rule: string | null; importance: number; created_at: string }[];
+
+    if (fileObservations.length > 0) {
+      lines.push('## Past Observations (This File)');
+      for (const obs of fileObservations) {
+        const crTag = obs.cr_rule ? ` [${obs.cr_rule}]` : '';
+        const impTag = obs.importance >= 4 ? ' **HIGH**' : '';
+        lines.push(`- [${obs.type}] ${obs.title}${crTag}${impTag} (${obs.created_at})`);
+      }
+      lines.push('');
+    }
+
+    // Also check for failed attempts on this file
+    const failures = memDb.prepare(`
+      SELECT title, detail
+      FROM observations
+      WHERE type = 'failed_attempt' AND files_involved LIKE ?
+      ORDER BY recurrence_count DESC
+      LIMIT 3
+    `).all(`%${basename(file)}%`) as { title: string; detail: string }[];
+
+    if (failures.length > 0) {
+      lines.push('## Failed Attempts (DO NOT RETRY)');
+      for (const f of failures) {
+        lines.push(`- ${f.title}`);
+      }
+      lines.push('');
+    }
+  } catch { /* Memory DB not available — graceful degradation */ }
+  finally { memDb?.close(); }
+
+  return text(lines.join('\n') || 'No context available for this file.');
+}
+
+function handleTrpcMap(args: Record<string, unknown>, dataDb: Database.Database): ToolResult {
+  const lines: string[] = [];
+
+  if (args.uncoupled) {
+    const uncoupled = dataDb.prepare(
+      'SELECT router_name, procedure_name, procedure_type, router_file FROM massu_trpc_procedures WHERE has_ui_caller = 0 ORDER BY router_name, procedure_name'
+    ).all() as { router_name: string; procedure_name: string; procedure_type: string; router_file: string }[];
+
+    lines.push(`## Uncoupled Procedures (${uncoupled.length} total)`);
+    lines.push('These procedures have ZERO UI callers.');
+    lines.push('');
+
+    let currentRouter = '';
+    for (const proc of uncoupled) {
+      if (proc.router_name !== currentRouter) {
+        currentRouter = proc.router_name;
+        lines.push(`### ${currentRouter} (${proc.router_file})`);
+      }
+      lines.push(`- ${proc.procedure_name} (${proc.procedure_type})`);
+    }
+  } else if (args.router) {
+    const procs = dataDb.prepare(
+      'SELECT id, procedure_name, procedure_type, has_ui_caller FROM massu_trpc_procedures WHERE router_name = ? ORDER BY procedure_name'
+    ).all(args.router as string) as { id: number; procedure_name: string; procedure_type: string; has_ui_caller: number }[];
+
+    lines.push(`## Router: ${args.router} (${procs.length} procedures)`);
+    lines.push('');
+
+    for (const proc of procs) {
+      const status = proc.has_ui_caller ? '' : ' [NO UI CALLERS]';
+      lines.push(`### ${args.router}.${proc.procedure_name} (${proc.procedure_type})${status}`);
+
+      const callSites = dataDb.prepare(
+        'SELECT file, line, call_pattern FROM massu_trpc_call_sites WHERE procedure_id = ?'
+      ).all(proc.id) as { file: string; line: number; call_pattern: string }[];
+
+      if (callSites.length > 0) {
+        lines.push('UI Call Sites:');
+        for (const site of callSites) {
+          lines.push(`  - ${site.file}:${site.line} -> ${site.call_pattern}`);
+        }
+      } else {
+        lines.push('UI Call Sites: NONE');
+      }
+      lines.push('');
+    }
+  } else if (args.procedure) {
+    const procs = dataDb.prepare(
+      'SELECT id, router_name, router_file, procedure_type, has_ui_caller FROM massu_trpc_procedures WHERE procedure_name = ? ORDER BY router_name'
+    ).all(args.procedure as string) as { id: number; router_name: string; router_file: string; procedure_type: string; has_ui_caller: number }[];
+
+    lines.push(`## Procedure "${args.procedure}" found in ${procs.length} routers`);
+    lines.push('');
+
+    for (const proc of procs) {
+      lines.push(`### ${proc.router_name}.${args.procedure} (${proc.procedure_type})`);
+      lines.push(`File: ${proc.router_file}`);
+
+      const callSites = dataDb.prepare(
+        'SELECT file, line, call_pattern FROM massu_trpc_call_sites WHERE procedure_id = ?'
+      ).all(proc.id) as { file: string; line: number; call_pattern: string }[];
+
+      if (callSites.length > 0) {
+        lines.push('UI Call Sites:');
+        for (const site of callSites) {
+          lines.push(`  - ${site.file}:${site.line} -> ${site.call_pattern}`);
+        }
+      } else {
+        lines.push('UI Call Sites: NONE');
+      }
+      lines.push('');
+    }
+  } else {
+    const total = dataDb.prepare('SELECT COUNT(*) as count FROM massu_trpc_procedures').get() as { count: number };
+    const coupled = dataDb.prepare('SELECT COUNT(*) as count FROM massu_trpc_procedures WHERE has_ui_caller = 1').get() as { count: number };
+    const uncoupled = total.count - coupled.count;
+
+    lines.push('## tRPC Procedure Summary');
+    lines.push(`- Total procedures: ${total.count}`);
+    lines.push(`- With UI callers: ${coupled.count}`);
+    lines.push(`- Without UI callers: ${uncoupled}`);
+    lines.push('');
+    lines.push('Use { router: "name" } to see details for a specific router.');
+    lines.push('Use { uncoupled: true } to see all procedures without UI callers.');
+  }
+
+  return text(lines.join('\n'));
+}
+
+function handleCouplingCheck(args: Record<string, unknown>, dataDb: Database.Database, codegraphDb: Database.Database): ToolResult {
+  const lines: string[] = [];
+  const stagedFiles = args.staged_files as string[] | undefined;
+
+  let uncoupledProcs;
+  if (stagedFiles) {
+    uncoupledProcs = dataDb.prepare(
+      `SELECT router_name, procedure_name, procedure_type, router_file FROM massu_trpc_procedures WHERE has_ui_caller = 0 AND router_file IN (${stagedFiles.map(() => '?').join(',')})`
+    ).all(...stagedFiles) as { router_name: string; procedure_name: string; procedure_type: string; router_file: string }[];
+  } else {
+    uncoupledProcs = dataDb.prepare(
+      'SELECT router_name, procedure_name, procedure_type, router_file FROM massu_trpc_procedures WHERE has_ui_caller = 0'
+    ).all() as { router_name: string; procedure_name: string; procedure_type: string; router_file: string }[];
+  }
+
+  lines.push('## Coupling Check Results');
+  lines.push('');
+
+  if (uncoupledProcs.length > 0) {
+    lines.push(`### Uncoupled Procedures: ${uncoupledProcs.length}`);
+    for (const proc of uncoupledProcs) {
+      lines.push(`- ${proc.router_name}.${proc.procedure_name} (${proc.procedure_type}) in ${proc.router_file}`);
+    }
+    lines.push('');
+  } else {
+    lines.push('### Uncoupled Procedures: 0 (PASS)');
+    lines.push('');
+  }
+
+  const allPages = codegraphDb.prepare(
+    "SELECT path FROM files WHERE path LIKE 'src/app/%/page.tsx' OR path = 'src/app/page.tsx'"
+  ).all() as { path: string }[];
+
+  const pageImports = new Set<string>();
+  for (const page of allPages) {
+    const imports = dataDb.prepare(
+      'SELECT target_file FROM massu_imports WHERE source_file = ?'
+    ).all(page.path) as { target_file: string }[];
+    for (const imp of imports) {
+      pageImports.add(imp.target_file);
+    }
+  }
+
+  let componentFiles: { path: string }[];
+  if (stagedFiles) {
+    const placeholders = stagedFiles.map(() => '?').join(',');
+    componentFiles = codegraphDb.prepare(
+      `SELECT path FROM files WHERE path LIKE 'src/components/%' AND path IN (${placeholders})`
+    ).all(...stagedFiles) as { path: string }[];
+  } else {
+    componentFiles = [];
+  }
+
+  const orphanComponents = componentFiles.filter(f => !pageImports.has(f.path));
+  if (orphanComponents.length > 0) {
+    lines.push(`### Orphan Components: ${orphanComponents.length}`);
+    for (const comp of orphanComponents) {
+      lines.push(`- ${comp.path} (not imported by any page.tsx)`);
+    }
+    lines.push('');
+  }
+
+  const totalIssues = uncoupledProcs.length + orphanComponents.length;
+  lines.push(`### RESULT: ${totalIssues === 0 ? 'PASS' : `FAIL (${totalIssues} issues)`}`);
+
+  return text(lines.join('\n'));
+}
+
+function handleImpact(file: string, dataDb: Database.Database, codegraphDb: Database.Database): ToolResult {
+  const lines: string[] = [];
+
+  lines.push(`## Impact Analysis: ${file}`);
+  lines.push('');
+
+  const affectedPages = findAffectedPages(dataDb, file);
+
+  if (affectedPages.length > 0) {
+    const portals = [...new Set(affectedPages.map(p => p.portal))];
+    const allTables = [...new Set(affectedPages.flatMap(p => p.tables))];
+    const allRouters = [...new Set(affectedPages.flatMap(p => p.routers))];
+
+    lines.push(`### Pages Affected: ${affectedPages.length}`);
+    for (const page of affectedPages) {
+      lines.push(`- ${page.route} (${page.portal})`);
+    }
+    lines.push('');
+
+    lines.push(`### Scopes Affected: ${portals.join(', ')}`);
+    lines.push('');
+
+    if (allRouters.length > 0) {
+      lines.push(`### Routers Called (via hooks/components):`);
+      for (const router of allRouters) {
+        lines.push(`- ${router}`);
+      }
+      lines.push('');
+    }
+
+    if (allTables.length > 0) {
+      lines.push(`### Database Tables:`);
+      for (const table of allTables) {
+        lines.push(`- ${table}`);
+      }
+      lines.push('');
+    }
+  } else {
+    lines.push('No pages affected (file may not be in any page dependency chain).');
+    lines.push('');
+  }
+
+  const inMiddleware = isInMiddlewareTree(dataDb, file);
+  if (inMiddleware) {
+    lines.push('### WARNING: In Middleware Import Tree');
+    lines.push('Changes to this file affect Edge Runtime. No Node.js deps allowed.');
+  } else {
+    lines.push('### Middleware: NOT in middleware import tree (safe)');
+  }
+  lines.push('');
+
+  const fileDomain = classifyFile(file);
+  lines.push(`### Domain: ${fileDomain}`);
+
+  const imports = dataDb.prepare(
+    'SELECT target_file FROM massu_imports WHERE source_file = ?'
+  ).all(file) as { target_file: string }[];
+
+  const crossings: string[] = [];
+  for (const imp of imports) {
+    const targetDomain = classifyFile(imp.target_file);
+    if (targetDomain !== fileDomain && targetDomain !== 'Unknown') {
+      crossings.push(`${imp.target_file} (${targetDomain})`);
+    }
+  }
+
+  if (crossings.length > 0) {
+    lines.push(`### Domain Crossings: ${crossings.length}`);
+    for (const crossing of crossings) {
+      lines.push(`- -> ${crossing}`);
+    }
+  }
+
+  return text(lines.join('\n'));
+}
+
+function handleDomains(args: Record<string, unknown>, dataDb: Database.Database, codegraphDb: Database.Database): ToolResult {
+  const lines: string[] = [];
+  const domains = getConfig().domains;
+
+  if (args.file) {
+    const file = args.file as string;
+    const domain = classifyFile(file);
+    lines.push(`## ${file}`);
+    lines.push(`Domain: ${domain}`);
+
+    const domainConfig = domains.find(d => d.name === domain);
+    if (domainConfig) {
+      lines.push(`Allowed imports from: ${domainConfig.allowedImportsFrom.join(', ') || 'any domain (system)'}`);
+    }
+  } else if (args.crossings) {
+    const crossings = findCrossDomainImports(dataDb);
+    const violations = crossings.filter(c => !c.allowed);
+    const allowed = crossings.filter(c => c.allowed);
+
+    lines.push(`## Cross-Domain Import Analysis`);
+    lines.push(`Total crossings: ${crossings.length}`);
+    lines.push(`Violations: ${violations.length}`);
+    lines.push(`Allowed: ${allowed.length}`);
+    lines.push('');
+
+    if (violations.length > 0) {
+      lines.push('### Violations (Disallowed Cross-Domain Imports)');
+      for (const v of violations.slice(0, 50)) {
+        lines.push(`- ${v.source} (${v.sourceDomain}) -> ${v.target} (${v.targetDomain})`);
+      }
+      if (violations.length > 50) {
+        lines.push(`... and ${violations.length - 50} more`);
+      }
+    }
+  } else if (args.domain) {
+    const domainName = args.domain as string;
+    const files = getFilesInDomain(dataDb, codegraphDb, domainName);
+    const config = domains.find(d => d.name === domainName);
+
+    lines.push(`## Domain: ${domainName}`);
+    if (config) {
+      lines.push(`Allowed imports from: ${config.allowedImportsFrom.join(', ') || 'any domain (system)'}`);
+    }
+    lines.push('');
+
+    lines.push(`### Routers (${files.routers.length})`);
+    for (const r of files.routers) lines.push(`- ${r}`);
+    lines.push('');
+
+    lines.push(`### Pages (${files.pages.length})`);
+    for (const p of files.pages) lines.push(`- ${p}`);
+    lines.push('');
+
+    lines.push(`### Components (${files.components.length})`);
+    for (const c of files.components.slice(0, 30)) lines.push(`- ${c}`);
+    if (files.components.length > 30) lines.push(`... and ${files.components.length - 30} more`);
+  } else {
+    lines.push('## Domain Summary');
+    for (const domain of domains) {
+      lines.push(`- **${domain.name}**: ${domain.routers.length} router patterns, imports from: ${domain.allowedImportsFrom.join(', ') || 'any'}`);
+    }
+  }
+
+  return text(lines.join('\n'));
+}
+
+function handleSchema(args: Record<string, unknown>): ToolResult {
+  const lines: string[] = [];
+  const models = parsePrismaSchema();
+
+  if (args.mismatches) {
+    const mismatches = detectMismatches(models);
+
+    lines.push(`## Schema Mismatches Detected: ${mismatches.length}`);
+    lines.push('');
+
+    for (const m of mismatches) {
+      lines.push(`### ${m.table}.${m.codeColumn} [${m.severity}]`);
+      lines.push(`Code uses "${m.codeColumn}" but this column does NOT exist in the schema.`);
+      lines.push(`Files affected:`);
+      for (const f of m.files) {
+        lines.push(`  - ${f}`);
+      }
+      lines.push('');
+    }
+
+    if (mismatches.length === 0) {
+      lines.push('No known mismatches detected in code.');
+    }
+  } else if (args.table) {
+    const tableName = args.table as string;
+    const model = models.find(m => m.tableName === tableName || m.name === tableName);
+
+    if (!model) {
+      return text(`Model/table "${tableName}" not found in Prisma schema.`);
+    }
+
+    lines.push(`## ${model.name} (table: ${model.tableName})`);
+    lines.push('');
+    lines.push('### Fields');
+    for (const field of model.fields) {
+      const nullable = field.nullable ? '?' : '';
+      const relation = field.isRelation ? ' [RELATION]' : '';
+      lines.push(`- ${field.name}: ${field.type}${nullable}${relation}`);
+    }
+    lines.push('');
+
+    const usage = findColumnUsageInRouters(model.tableName);
+    if (usage.size > 0) {
+      lines.push('### Column Usage in Routers');
+      for (const [col, usages] of usage) {
+        const validField = model.fields.find(f => f.name === col);
+        const status = validField ? '' : ' [NOT IN SCHEMA]';
+        lines.push(`- ${col}${status}: ${usages.length} references`);
+      }
+    }
+  } else if (args.verify) {
+    const file = args.verify as string;
+    lines.push(`## Schema Verification: ${file}`);
+    lines.push('Checking all column references against Prisma schema...');
+    lines.push('');
+
+    const projectRoot = getProjectRoot();
+    const absPath = ensureWithinRoot(resolve(projectRoot, file), projectRoot);
+
+    if (!existsSync(absPath)) {
+      return text(`File not found: ${file}`);
+    }
+
+    const source = readFileSync(absPath, 'utf-8');
+
+    // Use configurable db access pattern
+    const config = getConfig();
+    const dbPattern = config.dbAccessPattern ?? 'ctx.db.{table}';
+    const regexStr = dbPattern
+      .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      .replace('\\{table\\}', '(\\w+)');
+    const tableRegex = new RegExp(regexStr + '\\.', 'g');
+    const tableRefs = new Set<string>();
+    let match;
+    while ((match = tableRegex.exec(source)) !== null) {
+      tableRefs.add(match[1]);
+    }
+
+    for (const table of tableRefs) {
+      const model = models.find(m => m.tableName === table || m.name.toLowerCase() === table);
+      if (!model) {
+        lines.push(`### ${table}: MODEL NOT FOUND IN SCHEMA`);
+        continue;
+      }
+
+      lines.push(`### ${table} (model: ${model.name})`);
+      const fieldNames = new Set(model.fields.map(f => f.name));
+      lines.push(`Schema has ${fieldNames.size} fields.`);
+      lines.push('');
+    }
+  } else {
+    lines.push(`## Prisma Schema Summary`);
+    lines.push(`Models: ${models.length}`);
+    lines.push('');
+
+    const mismatches = detectMismatches(models);
+    if (mismatches.length > 0) {
+      lines.push(`### Active Mismatches: ${mismatches.length}`);
+      for (const m of mismatches) {
+        lines.push(`- ${m.table}.${m.codeColumn} [${m.severity}]`);
+      }
+    }
+  }
+
+  return text(lines.join('\n'));
 }