@massu/core 0.1.1 → 0.4.0

package/src/hooks/pre-delete-check.ts

@@ -6,6 +6,7 @@
 // PreToolUse Hook: Pre-Deletion Feature Impact Check
 // Detects file deletion patterns (rm, git rm, Write with empty content)
 // and runs sentinel impact analysis. Blocks if critical features orphaned.
+// Also protects knowledge system files from accidental deletion (P7-005).
 // Must complete in <500ms.
 // ============================================================
 
@@ -27,6 +28,14 @@ interface HookInput {
 
 const PROJECT_ROOT = getProjectRoot();
 
+// Knowledge system files that must never be silently deleted.
+// These files underpin knowledge indexing and memory retrieval.
+const KNOWLEDGE_PROTECTED_FILES = [
+  'knowledge-db.ts',
+  'knowledge-indexer.ts',
+  'knowledge-tools.ts',
+];
+
 function getDataDb(): Database.Database | null {
   const dbPath = getResolvedPaths().dataDbPath;
   if (!existsSync(dbPath)) return null;
@@ -39,6 +48,43 @@ function getDataDb(): Database.Database | null {
   }
 }
 
+/**
+ * P7-005: Check if the tool call targets a protected knowledge system file.
+ * Returns a warning message if a protected file would be deleted/emptied.
+ */
+function checkKnowledgeFileProtection(input: HookInput): string | null {
+  const candidateFiles: string[] = [];
+
+  if (input.tool_name === 'Bash' && input.tool_input.command) {
+    const cmd = input.tool_input.command;
+    const rmMatch = cmd.match(/(?:rm|git\s+rm)\s+(?:-[rf]*\s+)*(.+)/);
+    if (rmMatch) {
+      const parts = rmMatch[1].split(/\s+/).filter(p => !p.startsWith('-'));
+      candidateFiles.push(...parts);
+    }
+  }
+
+  if (input.tool_name === 'Write' && input.tool_input.file_path) {
+    const content = input.tool_input.content || '';
+    if (content.trim().length === 0) {
+      candidateFiles.push(input.tool_input.file_path);
+    }
+  }
+
+  for (const f of candidateFiles) {
+    const basename = f.split('/').pop() ?? f;
+    if (KNOWLEDGE_PROTECTED_FILES.includes(basename)) {
+      return (
+        `KNOWLEDGE SYSTEM PROTECTION: "${basename}" is a core knowledge system file. ` +
+        `Deleting it will break knowledge indexing and memory retrieval. ` +
+        `Create a replacement before removing.`
+      );
+    }
+  }
+
+  return null;
+}
+
 function extractDeletedFiles(input: HookInput): string[] {
   const files: string[] = [];
 
@@ -51,7 +97,7 @@ function extractDeletedFiles(input: HookInput): string[] {
       const paths = rmMatch[1].split(/\s+/).filter(p => !p.startsWith('-'));
       for (const p of paths) {
         const relPath = p.startsWith('src/') ? p : p.replace(PROJECT_ROOT + '/', '');
-        if (relPath.startsWith('src/')) {
+        if (relPath.startsWith('src/') || relPath.endsWith('.py')) {
           files.push(relPath);
         }
       }
@@ -63,7 +109,7 @@ function extractDeletedFiles(input: HookInput): string[] {
     const content = input.tool_input.content || '';
     if (content.trim().length === 0) {
       const relPath = input.tool_input.file_path.replace(PROJECT_ROOT + '/', '');
-      if (relPath.startsWith('src/')) {
+      if (relPath.startsWith('src/') || relPath.endsWith('.py')) {
         files.push(relPath);
       }
     }
@@ -77,6 +123,14 @@ async function main(): Promise<void> {
     const input = await readStdin();
     const hookInput = JSON.parse(input) as HookInput;
 
+    // P7-005: Check knowledge file protection before anything else
+    const knowledgeWarning = checkKnowledgeFileProtection(hookInput);
+    if (knowledgeWarning) {
+      process.stdout.write(JSON.stringify({ message: knowledgeWarning }));
+      process.exit(0);
+      return;
+    }
+
     const deletedFiles = extractDeletedFiles(hookInput);
     if (deletedFiles.length === 0) {
       process.exit(0);
@@ -90,11 +144,14 @@ async function main(): Promise<void> {
       return;
     }
 
+    // The sentinel registry table name (defined by sentinel-db schema)
+    const SENTINEL_TABLE = 'massu_sentinel';
+
     try {
       // Check if any sentinel tables exist
       const tableExists = db.prepare(
-        "SELECT name FROM sqlite_master WHERE type='table' AND name='massu_sentinel'"
-      ).get();
+        `SELECT name FROM sqlite_master WHERE type='table' AND name=?`
+      ).get(SENTINEL_TABLE);
 
       if (!tableExists) {
         process.exit(0);
@@ -129,6 +186,37 @@ async function main(): Promise<void> {
         // Output warning but don't block (user can proceed)
         process.stdout.write(JSON.stringify({ message: msg.join('\n') }));
       }
+      // Check Python import graph for deleted .py files
+      const pyFiles = deletedFiles.filter(f => f.endsWith('.py'));
+      if (pyFiles.length > 0) {
+        try {
+          for (const pyFile of pyFiles) {
+            const importers = db.prepare(
+              'SELECT source_file FROM massu_py_imports WHERE target_file = ?'
+            ).all(pyFile) as { source_file: string }[];
+
+            const routes = db.prepare(
+              'SELECT method, path FROM massu_py_routes WHERE file = ?'
+            ).all(pyFile) as { method: string; path: string }[];
+
+            const models = db.prepare(
+              'SELECT class_name FROM massu_py_models WHERE file = ?'
+            ).all(pyFile) as { class_name: string }[];
+
+            if (importers.length > 0 || routes.length > 0 || models.length > 0) {
+              const parts: string[] = [];
+              if (importers.length > 0) parts.push(`imported by ${importers.length} files`);
+              if (routes.length > 0) parts.push(`defines ${routes.length} routes`);
+              if (models.length > 0) parts.push(`defines ${models.length} models`);
+
+              const msg = `PYTHON IMPACT: "${pyFile}" ${parts.join(', ')}. Check dependents before deleting.`;
+              process.stdout.write(JSON.stringify({ message: msg }));
+            }
+          }
+        } catch {
+          // Python tables may not exist yet
+        }
+      }
     } finally {
       db.close();
     }

package/src/hooks/security-gate.ts

@@ -20,6 +20,7 @@ interface HookInput {
     command?: string;
     file_path?: string;
     content?: string;
+    new_string?: string;
   };
 }
 
@@ -77,6 +78,26 @@ function checkFilePath(filePath: string): string | null {
   return null;
 }
 
+const DANGEROUS_PYTHON_PATTERNS: Array<{ pattern: RegExp; label: string }> = [
+  { pattern: /\beval\s*\(/, label: 'Python eval() — arbitrary code execution' },
+  { pattern: /\bexec\s*\(/, label: 'Python exec() — arbitrary code execution' },
+  { pattern: /\b__import__\s*\(/, label: 'Python __import__() — dynamic import (potential code injection)' },
+  { pattern: /subprocess\.call\([^)]*shell\s*=\s*True/, label: 'subprocess.call(shell=True) — shell injection risk' },
+  { pattern: /subprocess\.Popen\([^)]*shell\s*=\s*True/, label: 'subprocess.Popen(shell=True) — shell injection risk' },
+  { pattern: /os\.system\s*\(/, label: 'os.system() — shell injection risk' },
+  { pattern: /\bf['"].*\{.*\}.*['"].*(?:execute|cursor|query)/, label: 'f-string in SQL — SQL injection risk' },
+  { pattern: /['"].*%s.*['"].*%.*(?:execute|cursor|query)/, label: 'String formatting in SQL — SQL injection risk' },
+];
+
+function checkPythonContent(content: string): string | null {
+  for (const { pattern, label } of DANGEROUS_PYTHON_PATTERNS) {
+    if (pattern.test(content)) {
+      return label;
+    }
+  }
+  return null;
+}
+
 async function main(): Promise<void> {
   try {
     const input = await readStdin();
@@ -100,6 +121,17 @@ async function main(): Promise<void> {
         }));
       }
     }
+
+    // Check Python file content for dangerous patterns (Write uses content, Edit uses new_string)
+    const pyContent = tool_input.content || tool_input.new_string;
+    if ((tool_name === 'Write' || tool_name === 'Edit') && tool_input.file_path?.endsWith('.py') && pyContent) {
+      const pyViolation = checkPythonContent(pyContent);
+      if (pyViolation) {
+        process.stdout.write(JSON.stringify({
+          message: `SECURITY GATE: Dangerous Python pattern detected: ${pyViolation}\nFile: ${tool_input.file_path}\nReview carefully before proceeding.`,
+        }));
+      }
+    }
   } catch {
     // Hooks must never crash
   }

package/src/hooks/session-end.ts

@@ -8,10 +8,10 @@
 // Dependencies: P1-002, P5-001, P5-002
 // ============================================================
 
-import { getMemoryDb, endSession, addSummary, getRecentObservations, createSession, addConversationTurn, addToolCallDetail, getLastProcessedLine, setLastProcessedLine } from '../memory-db.ts';
+import { getMemoryDb, endSession, addSummary, createSession, addConversationTurn, addToolCallDetail, getLastProcessedLine, setLastProcessedLine } from '../memory-db.ts';
 import { generateCurrentMd } from '../session-state-generator.ts';
 import { archiveAndRegenerate } from '../session-archiver.ts';
-import { parseTranscriptFrom, extractUserMessages, extractAssistantMessages, extractToolCalls, estimateTokens } from '../transcript-parser.ts';
+import { parseTranscriptFrom, estimateTokens } from '../transcript-parser.ts';
 import { syncToCloud, drainSyncQueue } from '../cloud-sync.ts';
 import { calculateQualityScore, storeQualityScore, backfillQualityScores } from '../analytics.ts';
 import { extractTokenUsage, calculateCost, storeSessionCost } from '../cost-tracker.ts';
@@ -64,7 +64,7 @@ async function main(): Promise<void> {
       // 4.6. Calculate and store quality score
       try {
         const { score, breakdown } = calculateQualityScore(db, session_id);
-        if (score > 0) {
+        if (score !== 50) {
           storeQualityScore(db, session_id, score, breakdown);
         }
         backfillQualityScores(db);

package/src/hooks/session-start.ts

@@ -9,7 +9,9 @@
 // ============================================================
 
 import { getMemoryDb, getSessionSummaries, getRecentObservations, getFailedAttempts, getCrossTaskProgress, autoDetectTaskId, linkSessionToTask, createSession } from '../memory-db.ts';
-import { getConfig } from '../config.ts';
+import { getConfig, getResolvedPaths } from '../config.ts';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
 import type Database from 'better-sqlite3';
 
 interface HookInput {
@@ -56,7 +58,7 @@ async function main(): Promise<void> {
       }
 
       // Build context
-      const context = buildContext(db, session_id, source ?? 'startup', tokenBudget, session?.task_id ?? null);
+      const context = await buildContext(db, session_id, source ?? 'startup', tokenBudget, session?.task_id ?? null);
 
       if (context.trim()) {
         process.stdout.write(context);
@@ -80,7 +82,7 @@ function getTokenBudget(source: string): number {
   }
 }
 
-function buildContext(db: Database.Database, sessionId: string, source: string, tokenBudget: number, taskId: string | null): string {
+async function buildContext(db: Database.Database, sessionId: string, source: string, tokenBudget: number, taskId: string | null): Promise<string> {
   const sections: Array<{ text: string; importance: number }> = [];
 
   // 1. Failed attempts (highest priority - DON'T RETRY warnings)
@@ -138,7 +140,50 @@ function buildContext(db: Database.Database, sessionId: string, source: string,
     }
   }
 
-  // 5. Recent observations sorted by importance
+  // 5. Prevention rules from corrections.md
+  const preventionRules = loadCorrectionsPreventionRules();
+  if (preventionRules.length > 0) {
+    let rulesText = '### Active Prevention Rules (from corrections.md)\n';
+    for (const rule of preventionRules) {
+      rulesText += `- ${rule}\n`;
+    }
+    sections.push({ text: rulesText, importance: 9 });
+  }
+
+  // 6. Knowledge index status (warm-up check)
+  try {
+    const knowledgeDbPath = getResolvedPaths().knowledgeDbPath;
+    if (existsSync(knowledgeDbPath)) {
+      const Database = (await import('better-sqlite3')).default;
+      const kdb = new Database(knowledgeDbPath, { readonly: true });
+      try {
+        const stats = kdb.prepare(
+          'SELECT COUNT(*) as doc_count, MAX(indexed_at) as last_indexed FROM knowledge_documents'
+        ).get() as { doc_count: number; last_indexed: string | null };
+        if (stats.doc_count > 0 && stats.last_indexed) {
+          const ageMs = Date.now() - new Date(stats.last_indexed).getTime();
+          const ageHours = Math.round(ageMs / 3600000);
+          if (ageHours > 24) {
+            sections.push({
+              text: `### Knowledge Index Status\nIndex has ${stats.doc_count} documents, last indexed ${ageHours}h ago. Consider re-indexing.\n`,
+              importance: 3,
+            });
+          }
+        } else if (stats.doc_count === 0) {
+          sections.push({
+            text: '### Knowledge Index Status\nKnowledge index is empty. Run knowledge indexing to populate it.\n',
+            importance: 2,
+          });
+        }
+      } finally {
+        kdb.close();
+      }
+    }
+  } catch (_knowledgeErr) {
+    // Best-effort: never block session start
+  }
+
+  // 7. Recent observations sorted by importance
   const recentObs = getRecentObservations(db, 20);
   if (recentObs.length > 0) {
     let obsText = '### Recent Observations\n';
@@ -153,7 +198,7 @@ function buildContext(db: Database.Database, sessionId: string, source: string,
   sections.sort((a, b) => b.importance - a.importance);
 
   let usedTokens = 0;
-  const headerTokens = estimateTokens('=== CS MEMORY: Previous Session Context ===\n\n=== END CS MEMORY ===\n');
+  const headerTokens = estimateTokens('=== Massu Memory: Previous Session Context ===\n\n=== END Massu Memory ===\n');
   usedTokens += headerTokens;
 
   const includedSections: string[] = [];
@@ -167,7 +212,7 @@ function buildContext(db: Database.Database, sessionId: string, source: string,
 
   if (includedSections.length === 0) return '';
 
-  return `=== CS MEMORY: Previous Session Context ===\n\n${includedSections.join('\n')}\n=== END CS MEMORY ===\n`;
+  return `=== Massu Memory: Previous Session Context ===\n\n${includedSections.join('\n')}\n=== END Massu Memory ===\n`;
 }
 
 function estimateTokens(text: string): number {
@@ -207,4 +252,52 @@ function safeParseJson(json: string): Record<string, string> | null {
   }
 }
 
+/**
+ * Load prevention rules from corrections.md in the memory directory.
+ * Parses the markdown table format: | Date | Wrong Behavior | Correction | Prevention Rule |
+ * Returns only the prevention rule column values.
+ * Graceful degradation: returns empty array if file doesn't exist or can't be parsed.
+ */
+function loadCorrectionsPreventionRules(): string[] {
+  try {
+    // Memory path follows Claude's project directory convention
+    const homeDir = process.env.HOME ?? process.env.USERPROFILE ?? '';
+    const cwd = process.cwd();
+    const config = getConfig();
+    const claudeDirName = config.conventions?.claudeDirName ?? '.claude';
+    // Convert cwd to Claude's directory format: /Users/x/project -> -Users-x-project
+    const projectDirName = cwd.replace(/\//g, '-').replace(/^-/, '');
+    const correctionsPath = join(homeDir, claudeDirName, 'projects', projectDirName, 'memory', 'corrections.md');
+
+    if (!existsSync(correctionsPath)) return [];
+
+    const content = readFileSync(correctionsPath, 'utf-8');
+    const lines = content.split('\n');
+    const rules: string[] = [];
+
+    for (const line of lines) {
+      // Match table rows: | date | wrong | correction | prevention |
+      // Skip header row and separator row
+      const trimmed = line.trim();
+      if (!trimmed.startsWith('|') || !trimmed.endsWith('|')) continue;
+
+      const cells = trimmed.split('|').map(c => c.trim()).filter(c => c.length > 0);
+      if (cells.length < 4) continue;
+
+      // Skip header and separator rows
+      if (cells[0] === 'Date' || cells[0].startsWith('-')) continue;
+
+      const preventionRule = cells[3];
+      if (preventionRule && !preventionRule.startsWith('-') && !preventionRule.startsWith('<!--')) {
+        rules.push(preventionRule);
+      }
+    }
+
+    return rules;
+  } catch (_e) {
+    // Graceful degradation: never block session start
+    return [];
+  }
+}
+
 main();

package/src/hooks/user-prompt.ts

@@ -7,7 +7,9 @@
 // Captures user prompts for search and context.
 // ============================================================
 
-import { getMemoryDb, createSession, addUserPrompt, linkSessionToTask, autoDetectTaskId } from '../memory-db.ts';
+import { getMemoryDb, createSession, addUserPrompt, linkSessionToTask, autoDetectTaskId, addObservation } from '../memory-db.ts';
+import { existsSync } from 'fs';
+import { getResolvedPaths } from '../config.ts';
 
 interface HookInput {
   session_id: string;
@@ -55,6 +57,35 @@ async function main(): Promise<void> {
 
       // 4. Insert prompt
       addUserPrompt(db, session_id, prompt.trim(), promptNumber);
+
+      // 5. Knowledge-aware prompt enrichment: detect file references and check knowledge index
+      try {
+        const fileRefs = extractFileReferences(prompt);
+        if (fileRefs.length > 0) {
+          const knowledgeDbPath = getResolvedPaths().knowledgeDbPath;
+          if (knowledgeDbPath && existsSync(knowledgeDbPath)) {
+            const Database = (await import('better-sqlite3')).default;
+            const kdb = new Database(knowledgeDbPath, { readonly: true });
+            try {
+              const placeholders = fileRefs.map(() => '?').join(',');
+              const matches = kdb.prepare(
+                `SELECT DISTINCT file_path FROM knowledge_documents WHERE file_path IN (${placeholders})`
+              ).all(...fileRefs) as Array<{ file_path: string }>;
+              if (matches.length > 0) {
+                addObservation(db, session_id, 'discovery',
+                  `Knowledge entries exist for referenced files`,
+                  `Files with knowledge context: ${matches.map(m => m.file_path).join(', ')}`,
+                  { importance: 2 }
+                );
+              }
+            } finally {
+              kdb.close();
+            }
+          }
+        }
+      } catch (_knowledgeErr) {
+        // Best-effort: never block prompt capture
+      }
     } finally {
       db.close();
     }
@@ -64,6 +95,20 @@ async function main(): Promise<void> {
   process.exit(0);
 }
 
+/**
+ * Extract file path references from user prompt text.
+ * Matches patterns like src/foo/bar.ts, packages/core/src/x.ts, etc.
+ */
+function extractFileReferences(prompt: string): string[] {
+  const filePattern = /(?:^|\s)((?:src|packages|lib)\/[\w./-]+\.(?:ts|tsx|js|jsx|md))/g;
+  const matches: string[] = [];
+  let match: RegExpExecArray | null;
+  while ((match = filePattern.exec(prompt)) !== null) {
+    matches.push(match[1]);
+  }
+  return [...new Set(matches)];
+}
+
 async function getGitBranch(): Promise<string | undefined> {
   try {
     const { spawnSync } = await import('child_process');

package/src/import-resolver.ts

@@ -5,6 +5,7 @@ import { readFileSync, existsSync, statSync } from 'fs';
 import { resolve, dirname, join } from 'path';
 import type Database from 'better-sqlite3';
 import { getResolvedPaths, getProjectRoot } from './config.ts';
+import { ensureWithinRoot } from './security-utils.ts';
 
 interface ImportEdge {
   source_file: string;
@@ -182,7 +183,7 @@ export function buildImportIndex(dataDb: Database.Database, codegraphDb: Databas
   let batch: ImportEdge[] = [];
 
   for (const file of files) {
-    const absPath = resolve(projectRoot, file.path);
+    const absPath = ensureWithinRoot(resolve(projectRoot, file.path), projectRoot);
     if (!existsSync(absPath)) continue;
 
     let source: string;

package/src/knowledge-db.ts

@@ -0,0 +1,169 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+import Database from 'better-sqlite3';
+import { dirname } from 'path';
+import { existsSync, mkdirSync } from 'fs';
+import { getConfig, getResolvedPaths } from './config.ts';
+
+/**
+ * Connection to Massu Knowledge's SQLite database.
+ * Stores indexed .claude/ knowledge: rules, patterns, incidents, verifications, cross-references.
+ * Separate from codegraph.db (CodeGraph data) and memory.db (session memory).
+ */
+export function getKnowledgeDb(): Database.Database {
+  const dbPath = getResolvedPaths().knowledgeDbPath;
+  const dir = dirname(dbPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+  initKnowledgeSchema(db);
+  return db;
+}
+
+export function initKnowledgeSchema(db: Database.Database): void {
+  db.exec(`
+    -- Core document chunks (parsed from .claude/**/*.md)
+    CREATE TABLE IF NOT EXISTS knowledge_documents (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file_path TEXT NOT NULL,
+      category TEXT NOT NULL,
+      title TEXT NOT NULL,
+      description TEXT,
+      content_hash TEXT NOT NULL,
+      indexed_at TEXT NOT NULL,
+      indexed_at_epoch INTEGER NOT NULL
+    );
+
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_kd_filepath ON knowledge_documents(file_path);
+    CREATE INDEX IF NOT EXISTS idx_kd_category ON knowledge_documents(category);
+
+    -- Structured chunks within documents
+    CREATE TABLE IF NOT EXISTS knowledge_chunks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      document_id INTEGER NOT NULL REFERENCES knowledge_documents(id) ON DELETE CASCADE,
+      chunk_type TEXT NOT NULL CHECK(chunk_type IN (
+        'section', 'table_row', 'code_block', 'rule', 'incident', 'pattern', 'command', 'mismatch'
+      )),
+      heading TEXT,
+      content TEXT NOT NULL,
+      line_start INTEGER,
+      line_end INTEGER,
+      metadata TEXT DEFAULT '{}'
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_kc_doc ON knowledge_chunks(document_id);
+    CREATE INDEX IF NOT EXISTS idx_kc_type ON knowledge_chunks(chunk_type);
+    CREATE INDEX IF NOT EXISTS idx_kc_heading ON knowledge_chunks(heading);
+
+    -- Canonical Rules index
+    CREATE TABLE IF NOT EXISTS knowledge_rules (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      rule_id TEXT UNIQUE NOT NULL,
+      rule_text TEXT NOT NULL,
+      vr_type TEXT,
+      reference_path TEXT,
+      severity TEXT DEFAULT 'HIGH',
+      prevention_summary TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_kr_id ON knowledge_rules(rule_id);
+
+    -- Verification Requirements index
+    CREATE TABLE IF NOT EXISTS knowledge_verifications (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      vr_type TEXT UNIQUE NOT NULL,
+      command TEXT NOT NULL,
+      expected TEXT NOT NULL,
+      use_when TEXT NOT NULL,
+      catches TEXT,
+      category TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_kv_type ON knowledge_verifications(vr_type);
+    CREATE INDEX IF NOT EXISTS idx_kv_category ON knowledge_verifications(category);
+
+    -- Incident index
+    CREATE TABLE IF NOT EXISTS knowledge_incidents (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      incident_num INTEGER UNIQUE NOT NULL,
+      date TEXT NOT NULL,
+      type TEXT NOT NULL,
+      gap_found TEXT NOT NULL,
+      prevention TEXT NOT NULL,
+      cr_added TEXT,
+      root_cause TEXT,
+      user_quote TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_ki_num ON knowledge_incidents(incident_num);
+    CREATE INDEX IF NOT EXISTS idx_ki_type ON knowledge_incidents(type);
+    CREATE INDEX IF NOT EXISTS idx_ki_cr ON knowledge_incidents(cr_added);
+
+    -- Schema mismatch quick lookup
+    CREATE TABLE IF NOT EXISTS knowledge_schema_mismatches (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      table_name TEXT NOT NULL,
+      wrong_column TEXT NOT NULL,
+      correct_column TEXT NOT NULL,
+      source TEXT DEFAULT '${getConfig().conventions?.knowledgeSourceFiles?.[0] ?? 'CLAUDE.md'}'
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_ksm_table ON knowledge_schema_mismatches(table_name);
+
+    -- Cross-reference graph
+    CREATE TABLE IF NOT EXISTS knowledge_edges (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      source_type TEXT NOT NULL,
+      source_id TEXT NOT NULL,
+      target_type TEXT NOT NULL,
+      target_id TEXT NOT NULL,
+      edge_type TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_ke_source ON knowledge_edges(source_type, source_id);
+    CREATE INDEX IF NOT EXISTS idx_ke_target ON knowledge_edges(target_type, target_id);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_ke_unique ON knowledge_edges(source_type, source_id, target_type, target_id, edge_type);
+
+    -- Staleness tracking
+    CREATE TABLE IF NOT EXISTS knowledge_meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+  `);
+
+  // FTS5 in separate exec (can fail if schema mismatch on existing table)
+  try {
+    db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS knowledge_fts USING fts5(
+        heading, content, chunk_type, file_path
+      );
+
+      CREATE TRIGGER IF NOT EXISTS kc_fts_insert AFTER INSERT ON knowledge_chunks BEGIN
+        INSERT INTO knowledge_fts(rowid, heading, content, chunk_type, file_path)
+        SELECT new.id, new.heading, new.content, new.chunk_type, kd.file_path
+        FROM knowledge_documents kd WHERE kd.id = new.document_id;
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS kc_fts_delete AFTER DELETE ON knowledge_chunks BEGIN
+        INSERT INTO knowledge_fts(knowledge_fts, rowid, heading, content, chunk_type, file_path)
+        SELECT 'delete', old.id, old.heading, old.content, old.chunk_type, kd.file_path
+        FROM knowledge_documents kd WHERE kd.id = old.document_id;
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS kc_fts_update AFTER UPDATE ON knowledge_chunks BEGIN
+        INSERT INTO knowledge_fts(knowledge_fts, rowid, heading, content, chunk_type, file_path)
+        SELECT 'delete', old.id, old.heading, old.content, old.chunk_type, kd.file_path
+        FROM knowledge_documents kd WHERE kd.id = old.document_id;
+        INSERT INTO knowledge_fts(rowid, heading, content, chunk_type, file_path)
+        SELECT new.id, new.heading, new.content, new.chunk_type, kd.file_path
+        FROM knowledge_documents kd WHERE kd.id = new.document_id;
+      END;
+    `);
+  } catch {
+    // FTS5 table may already exist with different schema — not fatal
+  }
+}