@massu/core 0.1.1 → 0.4.0

package/src/config.ts

@@ -3,6 +3,7 @@
 
 import { resolve, dirname } from 'path';
 import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
 import { parse as parseYaml } from 'yaml';
 import { z } from 'zod';
 
@@ -159,6 +160,45 @@ const CloudConfigSchema = z.object({
 }).optional();
 export type CloudConfig = z.infer<typeof CloudConfigSchema>;
 
+// --- Conventions Config ---
+const ConventionsConfigSchema = z.object({
+  claudeDirName: z.string().default('.claude').refine(
+    s => !s.includes('..') && !s.startsWith('/'),
+    { message: 'claudeDirName must not contain ".." or start with "/"' }
+  ),
+  sessionStatePath: z.string().default('.claude/session-state/CURRENT.md').refine(
+    s => !s.includes('..') && !s.startsWith('/'),
+    { message: 'sessionStatePath must not contain ".." or start with "/"' }
+  ),
+  sessionArchivePath: z.string().default('.claude/session-state/archive').refine(
+    s => !s.includes('..') && !s.startsWith('/'),
+    { message: 'sessionArchivePath must not contain ".." or start with "/"' }
+  ),
+  knowledgeCategories: z.array(z.string()).default([
+    'patterns', 'commands', 'incidents', 'reference', 'protocols',
+    'checklists', 'playbooks', 'critical', 'scripts', 'status',
+    'templates', 'loop-state', 'session-state', 'agents',
+  ]),
+  knowledgeSourceFiles: z.array(z.string()).default(['CLAUDE.md', 'MEMORY.md', 'corrections.md']),
+  excludePatterns: z.array(z.string()).default(['/ARCHIVE/', '/SESSION-HISTORY/']),
+}).optional();
+export type ConventionsConfig = z.infer<typeof ConventionsConfigSchema>;
+
+// --- Python Config ---
+const PythonDomainConfigSchema = z.object({
+  name: z.string(),
+  packages: z.array(z.string()),
+  allowed_imports_from: z.array(z.string()).default([]),
+});
+
+const PythonConfigSchema = z.object({
+  root: z.string(),
+  alembic_dir: z.string().optional(),
+  domains: z.array(PythonDomainConfigSchema).default([]),
+  exclude_dirs: z.array(z.string()).default(['__pycache__', '.venv', 'venv', '.mypy_cache', '.pytest_cache']),
+}).optional();
+export type PythonConfig = z.infer<typeof PythonConfigSchema>;
+
 // --- Paths Config ---
 const PathsConfigSchema = z.object({
   source: z.string().default('src'),
@@ -198,6 +238,8 @@ const RawConfigSchema = z.object({
   team: TeamConfigSchema,
   regression: RegressionConfigSchema,
   cloud: CloudConfigSchema,
+  conventions: ConventionsConfigSchema,
+  python: PythonConfigSchema,
 }).passthrough();
 
 // --- Final Config interface (derived from Zod) ---
@@ -217,6 +259,8 @@ export interface Config {
   team?: TeamConfig;
   regression?: RegressionConfig;
   cloud?: CloudConfig;
+  conventions?: ConventionsConfig;
+  python?: PythonConfig;
 }
 
 let _config: Config | null = null;
@@ -312,8 +356,20 @@ export function getConfig(): Config {
     team: parsed.team,
     regression: parsed.regression,
     cloud: parsed.cloud,
+    conventions: parsed.conventions,
+    python: parsed.python,
   };
 
+  // Allow environment variable override for API key (security best practice)
+  if (!_config.cloud?.apiKey && process.env.MASSU_API_KEY) {
+    _config.cloud = {
+      enabled: true,
+      sync: { memory: true, analytics: true, audit: true },
+      ..._config.cloud,
+      apiKey: process.env.MASSU_API_KEY,
+    };
+  }
+
   return _config;
 }
 
@@ -324,6 +380,7 @@ export function getConfig(): Config {
 export function getResolvedPaths() {
   const config = getConfig();
   const root = getProjectRoot();
+  const claudeDirName = config.conventions?.claudeDirName ?? '.claude';
 
   return {
     codegraphDbPath: resolve(root, '.codegraph/codegraph.db'),
@@ -340,11 +397,20 @@ export function getResolvedPaths() {
     ) as Record<string, string>,
     extensions: ['.ts', '.tsx', '.js', '.jsx'] as const,
     indexFiles: ['index.ts', 'index.tsx', 'index.js', 'index.jsx'] as const,
-    patternsDir: resolve(root, '.claude/patterns'),
-    claudeMdPath: resolve(root, '.claude/CLAUDE.md'),
+    patternsDir: resolve(root, claudeDirName, 'patterns'),
+    claudeMdPath: resolve(root, claudeDirName, 'CLAUDE.md'),
     docsMapPath: resolve(root, '.massu/docs-map.json'),
     helpSitePath: resolve(root, '../' + config.project.name + '-help'),
     memoryDbPath: resolve(root, '.massu/memory.db'),
+    knowledgeDbPath: resolve(root, '.massu/knowledge.db'),
+    plansDir: resolve(root, 'docs/plans'),
+    docsDir: resolve(root, 'docs'),
+    claudeDir: resolve(root, claudeDirName),
+    memoryDir: resolve(homedir(), claudeDirName, 'projects', root.replace(/\//g, '-'), 'memory'),
+    sessionStatePath: resolve(root, config.conventions?.sessionStatePath ?? `${claudeDirName}/session-state/CURRENT.md`),
+    sessionArchivePath: resolve(root, config.conventions?.sessionArchivePath ?? `${claudeDirName}/session-state/archive`),
+    mcpJsonPath: resolve(root, '.mcp.json'),
+    settingsLocalPath: resolve(root, claudeDirName, 'settings.local.json'),
   };
 }
 

package/src/cost-tracker.ts

@@ -2,8 +2,7 @@
 // Licensed under BSL 1.1 - see LICENSE file for details.
 
 import type Database from 'better-sqlite3';
-import type { ToolDefinition, ToolResult } from './tool-helpers.ts';
-import { p, text } from './tool-helpers.ts';
+import type { ToolDefinition, ToolResult } from './tools.ts';
 import type { TranscriptEntry } from './transcript-parser.ts';
 import { getConfig } from './config.ts';
 
@@ -11,13 +10,17 @@ import { getConfig } from './config.ts';
 // Cost Attribution Tracking
 // ============================================================
 
+/** Prefix a base tool name with the configured tool prefix. */
+function p(baseName: string): string {
+  return `${getConfig().toolPrefix}_${baseName}`;
+}
+
 /** Default model pricing (Claude models). Can be overridden via config.analytics.cost.models */
 const DEFAULT_MODEL_PRICING: Record<string, { input_per_million: number; output_per_million: number; cache_read_per_million?: number; cache_write_per_million?: number }> = {
-  'claude-opus-4-6': { input_per_million: 5.00, output_per_million: 25.00, cache_read_per_million: 0.50, cache_write_per_million: 6.25 },
+  'claude-opus-4-6': { input_per_million: 15.00, output_per_million: 75.00, cache_read_per_million: 1.50, cache_write_per_million: 18.75 },
   'claude-sonnet-4-6': { input_per_million: 3.00, output_per_million: 15.00, cache_read_per_million: 0.30, cache_write_per_million: 3.75 },
   'claude-sonnet-4-5': { input_per_million: 3.00, output_per_million: 15.00, cache_read_per_million: 0.30, cache_write_per_million: 3.75 },
-  'claude-3-5-haiku-20241022': { input_per_million: 0.80, output_per_million: 4.00, cache_read_per_million: 0.08, cache_write_per_million: 1.00 },
-  'claude-haiku-4-5-20251001': { input_per_million: 1.00, output_per_million: 5.00, cache_read_per_million: 0.10, cache_write_per_million: 1.25 },
+  'claude-haiku-4-5-20251001': { input_per_million: 0.80, output_per_million: 4.00, cache_read_per_million: 0.08, cache_write_per_million: 1.00 },
   'default': { input_per_million: 3.00, output_per_million: 15.00, cache_read_per_million: 0.30, cache_write_per_million: 3.75 },
 };
 
@@ -134,7 +137,6 @@ export function backfillSessionCosts(db: Database.Database): number {
     FROM sessions s
     LEFT JOIN session_costs c ON s.session_id = c.session_id
     WHERE c.session_id IS NULL
-    LIMIT 1000
   `).all() as Array<{ session_id: string }>;
 
   // Backfilling requires transcript data which may not be available
@@ -348,3 +350,6 @@ function handleCostFeature(args: Record<string, unknown>, db: Database.Database)
   return text(lines.join('\n'));
 }
 
+function text(content: string): ToolResult {
+  return { content: [{ type: 'text', text: content }] };
+}

package/src/db.ts

@@ -2,8 +2,8 @@
 // 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 { dirname, join } from 'path';
+import { existsSync, mkdirSync, readdirSync, statSync } from 'fs';
 import { getResolvedPaths } from './config.ts';
 
 /**
@@ -96,6 +96,84 @@ function initDataSchema(db: Database.Database): void {
       value TEXT NOT NULL
     );
 
+    -- ============================================================
+    -- Python Code Intelligence Tables
+    -- ============================================================
+
+    CREATE TABLE IF NOT EXISTS massu_py_imports (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      source_file TEXT NOT NULL,
+      target_file TEXT NOT NULL,
+      import_type TEXT NOT NULL CHECK(import_type IN ('absolute', 'relative', 'from_absolute', 'from_relative')),
+      imported_names TEXT NOT NULL DEFAULT '[]',
+      line INTEGER NOT NULL DEFAULT 0
+    );
+    CREATE INDEX IF NOT EXISTS idx_massu_py_imports_source ON massu_py_imports(source_file);
+    CREATE INDEX IF NOT EXISTS idx_massu_py_imports_target ON massu_py_imports(target_file);
+
+    CREATE TABLE IF NOT EXISTS massu_py_meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS massu_py_routes (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file TEXT NOT NULL,
+      method TEXT NOT NULL,
+      path TEXT NOT NULL,
+      function_name TEXT NOT NULL,
+      dependencies TEXT NOT NULL DEFAULT '[]',
+      request_model TEXT,
+      response_model TEXT,
+      is_authenticated INTEGER NOT NULL DEFAULT 0,
+      line INTEGER NOT NULL DEFAULT 0
+    );
+    CREATE INDEX IF NOT EXISTS idx_massu_py_routes_path ON massu_py_routes(path);
+    CREATE INDEX IF NOT EXISTS idx_massu_py_routes_file ON massu_py_routes(file);
+
+    CREATE TABLE IF NOT EXISTS massu_py_route_callers (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      route_id INTEGER NOT NULL REFERENCES massu_py_routes(id) ON DELETE CASCADE,
+      frontend_file TEXT NOT NULL,
+      line INTEGER NOT NULL DEFAULT 0,
+      call_pattern TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_massu_py_route_callers_route ON massu_py_route_callers(route_id);
+
+    CREATE TABLE IF NOT EXISTS massu_py_models (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      class_name TEXT NOT NULL,
+      table_name TEXT,
+      file TEXT NOT NULL,
+      line INTEGER NOT NULL DEFAULT 0,
+      columns TEXT NOT NULL DEFAULT '[]',
+      relationships TEXT NOT NULL DEFAULT '[]',
+      foreign_keys TEXT NOT NULL DEFAULT '[]'
+    );
+    CREATE INDEX IF NOT EXISTS idx_massu_py_models_file ON massu_py_models(file);
+    CREATE INDEX IF NOT EXISTS idx_massu_py_models_table ON massu_py_models(table_name);
+
+    CREATE TABLE IF NOT EXISTS massu_py_fk_edges (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      source_table TEXT NOT NULL,
+      source_column TEXT NOT NULL,
+      target_table TEXT NOT NULL,
+      target_column TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_massu_py_fk_source ON massu_py_fk_edges(source_table);
+    CREATE INDEX IF NOT EXISTS idx_massu_py_fk_target ON massu_py_fk_edges(target_table);
+
+    CREATE TABLE IF NOT EXISTS massu_py_migrations (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      revision TEXT NOT NULL UNIQUE,
+      down_revision TEXT,
+      file TEXT NOT NULL,
+      description TEXT,
+      operations TEXT NOT NULL DEFAULT '[]',
+      is_head INTEGER NOT NULL DEFAULT 0
+    );
+    CREATE INDEX IF NOT EXISTS idx_massu_py_migrations_rev ON massu_py_migrations(revision);
+
     -- ============================================================
     -- Sentinel: Feature Registry Tables
     -- ============================================================
@@ -231,3 +309,38 @@ export function isDataStale(dataDb: Database.Database, codegraphDb: Database.Dat
 export function updateBuildTimestamp(dataDb: Database.Database): void {
   dataDb.prepare("INSERT OR REPLACE INTO massu_meta (key, value) VALUES ('last_build_time', ?)").run(new Date().toISOString());
 }
+
+/**
+ * Check if Python indexes are stale based on massu_py_meta.last_build_time.
+ */
+export function isPythonDataStale(dataDb: Database.Database, pythonRoot: string): boolean {
+  const lastBuild = dataDb.prepare("SELECT value FROM massu_py_meta WHERE key = 'last_build_time'").get() as { value: string } | undefined;
+  if (!lastBuild) return true;
+
+  const lastBuildTime = new Date(lastBuild.value).getTime();
+  // Check if any .py file is newer than last build
+  function checkDir(dir: string): boolean {
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          if (['__pycache__', '.venv', 'venv', 'node_modules', '.mypy_cache', '.pytest_cache'].includes(entry.name)) continue;
+          if (checkDir(fullPath)) return true;
+        } else if (entry.name.endsWith('.py')) {
+          if (statSync(fullPath).mtimeMs > lastBuildTime) return true;
+        }
+      }
+    } catch { /* directory may not exist */ }
+    return false;
+  }
+
+  return checkDir(pythonRoot);
+}
+
+/**
+ * Update the Python build timestamp in massu_py_meta.
+ */
+export function updatePythonBuildTimestamp(dataDb: Database.Database): void {
+  dataDb.prepare("INSERT OR REPLACE INTO massu_py_meta (key, value) VALUES ('last_build_time', ?)").run(new Date().toISOString());
+}

package/src/dependency-scorer.ts

@@ -2,8 +2,7 @@
 // Licensed under BSL 1.1 - see LICENSE file for details.
 
 import type Database from 'better-sqlite3';
-import type { ToolDefinition, ToolResult } from './tool-helpers.ts';
-import { p, text } from './tool-helpers.ts';
+import type { ToolDefinition, ToolResult } from './tools.ts';
 import { getConfig } from './config.ts';
 import { existsSync, readFileSync } from 'fs';
 import { resolve } from 'path';
@@ -12,6 +11,11 @@ import { resolve } from 'path';
 // Dependency Risk Scoring
 // ============================================================
 
+/** Prefix a base tool name with the configured tool prefix. */
+function p(baseName: string): string {
+  return `${getConfig().toolPrefix}_${baseName}`;
+}
+
 export interface DepRiskFactors {
   vulnerabilities: number;
   lastPublishDays: number | null;
@@ -328,3 +332,6 @@ function handleDepAlternatives(args: Record<string, unknown>, db: Database.Datab
   return text(lines.filter(Boolean).join('\n'));
 }
 
+function text(content: string): ToolResult {
+  return { content: [{ type: 'text', text: content }] };
+}

package/src/docs-tools.ts

@@ -3,23 +3,20 @@
 
 import { readFileSync, existsSync } from 'fs';
 import { resolve, basename } from 'path';
-import { getConfig, getResolvedPaths } from './config.ts';
-import type { ToolDefinition, ToolResult } from './tool-helpers.ts';
-import { p, text } from './tool-helpers.ts';
+import { getConfig, getResolvedPaths, getProjectRoot } from './config.ts';
+import { ensureWithinRoot } from './security-utils.ts';
+import type { ToolDefinition, ToolResult } from './tools.ts';
+
+/** Prefix a base tool name with the configured tool prefix. */
+function p(baseName: string): string {
+  return `${getConfig().toolPrefix}_${baseName}`;
+}
 
 // ============================================================
 // Help Site Auto-Sync: MCP Docs Tools
 // docs_audit + docs_coverage
 // ============================================================
 
-const DOCS_BASE_NAMES = new Set(['docs_audit', 'docs_coverage']);
-
-export function isDocsTool(name: string): boolean {
-  const pfx = getConfig().toolPrefix + '_';
-  const baseName = name.startsWith(pfx) ? name.slice(pfx.length) : name;
-  return DOCS_BASE_NAMES.has(baseName);
-}
-
 interface DocsMapping {
   id: string;
   helpPage: string;
@@ -256,10 +253,11 @@ function extractFrontmatter(content: string): Record<string, string> | null {
  * Extract procedure names from a router file.
  */
 function extractProcedureNames(routerPath: string): string[] {
-  const absPath = resolve(getResolvedPaths().srcDir, '..', routerPath);
+  const root = getProjectRoot();
+  const absPath = ensureWithinRoot(resolve(getResolvedPaths().srcDir, '..', routerPath), root);
   if (!existsSync(absPath)) {
     // Try from project root
-    const altPath = resolve(getResolvedPaths().srcDir, '../server/api/routers', basename(routerPath));
+    const altPath = ensureWithinRoot(resolve(getResolvedPaths().srcDir, '../server/api/routers', basename(routerPath)), root);
     if (!existsSync(altPath)) return [];
     return extractProcedureNamesFromContent(readFileSync(altPath, 'utf-8'));
   }
@@ -329,7 +327,7 @@ function handleDocsAudit(args: Record<string, unknown>): ToolResult {
     const mapping = docsMap.mappings.find(m => m.id === mappingId);
     if (!mapping) continue;
 
-    const helpPagePath = resolve(getResolvedPaths().helpSitePath, mapping.helpPage);
+    const helpPagePath = ensureWithinRoot(resolve(getResolvedPaths().helpSitePath, mapping.helpPage), getProjectRoot());
 
     if (!existsSync(helpPagePath)) {
       results.push({
@@ -398,7 +396,7 @@ function handleDocsAudit(args: Record<string, unknown>): ToolResult {
     // Also flag inherited user guides
     for (const [guideName, parentId] of Object.entries(docsMap.userGuideInheritance.examples)) {
       if (parentId === mappingId) {
-        const guidePath = resolve(getResolvedPaths().helpSitePath, `pages/user-guides/${guideName}/index.mdx`);
+        const guidePath = ensureWithinRoot(resolve(getResolvedPaths().helpSitePath, `pages/user-guides/${guideName}/index.mdx`), getProjectRoot());
         if (existsSync(guidePath)) {
           const guideContent = readFileSync(guidePath, 'utf-8');
           const guideFrontmatter = extractFrontmatter(guideContent);
@@ -443,7 +441,7 @@ function handleDocsCoverage(args: Record<string, unknown>): ToolResult {
     : docsMap.mappings;
 
   for (const mapping of mappings) {
-    const helpPagePath = resolve(getResolvedPaths().helpSitePath, mapping.helpPage);
+    const helpPagePath = ensureWithinRoot(resolve(getResolvedPaths().helpSitePath, mapping.helpPage), getProjectRoot());
     const exists = existsSync(helpPagePath);
     let hasContent = false;
     let lineCount = 0;
@@ -512,3 +510,10 @@ function handleDocsCoverage(args: Record<string, unknown>): ToolResult {
   return text(lines.join('\n'));
 }
 
+// ============================================================
+// Utilities
+// ============================================================
+
+function text(content: string): ToolResult {
+  return { content: [{ type: 'text', text: content }] };
+}

package/src/hooks/post-edit-context.ts

@@ -37,7 +37,7 @@ async function main(): Promise<void> {
     const rel = filePath.startsWith(root + '/') ? filePath.slice(root.length + 1) : filePath;
 
     // Only process src/ files
-    if (!rel.startsWith('src/')) {
+    if (!rel.startsWith('src/') && !rel.endsWith('.py')) {
       process.exit(0);
       return;
     }
@@ -54,12 +54,12 @@ async function main(): Promise<void> {
       }
     }
 
-    // 2. Check middleware tree membership (CR-16)
+    // 2. Check middleware tree membership
     try {
       const dataDb = new Database(getResolvedPaths().dataDbPath, { readonly: true });
       try {
         if (isInMiddlewareTree(dataDb, rel)) {
-          warnings.push('[CRITICAL] CR-16: This file is in the middleware import tree. No Node.js deps allowed.');
+          warnings.push('[CRITICAL] This file is in the middleware import tree. No Node.js deps allowed.');
         }
       } finally {
         dataDb.close();
@@ -70,7 +70,7 @@ async function main(): Promise<void> {
 
     // 3. Output warnings if any
     if (warnings.length > 0) {
-      console.log(`[CS CONTEXT] ${warnings.join(' | ')}`);
+      console.log(`[Massu] ${warnings.join(' | ')}`);
     }
   } catch (_e) {
     // Best-effort: never block Claude Code

package/src/hooks/post-tool-use.ts

@@ -14,6 +14,9 @@ import { logAuditEntry } from '../audit-trail.ts';
 import { trackModification } from '../regression-detector.ts';
 import { validateFile, storeValidationResult } from '../validation-engine.ts';
 import { scoreFileSecurity, storeSecurityScore } from '../security-scorer.ts';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { parse as parseYaml } from 'yaml';
 
 interface HookInput {
   session_id: string;
@@ -126,6 +129,41 @@ async function main(): Promise<void> {
       } catch (_securityErr) {
         // Best-effort: never block post-tool-use
       }
+
+      // MEMORY.md integrity check on write
+      try {
+        if (tool_name === 'Edit' || tool_name === 'Write') {
+          const filePath = (tool_input.file_path as string) ?? '';
+          if (filePath && filePath.endsWith('MEMORY.md') && filePath.includes('/memory/')) {
+            const issues = checkMemoryFileIntegrity(filePath);
+            if (issues.length > 0) {
+              addObservation(db, session_id, 'incident_near_miss',
+                'MEMORY.md integrity issue detected',
+                issues.join('; '),
+                { importance: 4 }
+              );
+            }
+          }
+        }
+      } catch (_memoryErr) {
+        // Best-effort: never block post-tool-use
+      }
+
+      // Knowledge index staleness check on knowledge file edits
+      try {
+        if (tool_name === 'Edit' || tool_name === 'Write') {
+          const filePath = (tool_input.file_path as string) ?? '';
+          if (filePath && isKnowledgeSourceFile(filePath)) {
+            addObservation(db, session_id, 'discovery',
+              'Knowledge source file modified - index may be stale',
+              `Edited ${filePath.split('/').pop() ?? filePath}. Run knowledge re-index to update.`,
+              { importance: 3 }
+            );
+          }
+        }
+      } catch (_knowledgeErr) {
+        // Best-effort: never block post-tool-use
+      }
     } finally {
       db.close();
     }
@@ -172,4 +210,96 @@ function readStdin(): Promise<string> {
   });
 }
 
+/**
+ * Read the conventions section from massu.config.yaml directly.
+ * Hooks are compiled with esbuild and cannot use getConfig() from config.ts.
+ * Falls back to sensible defaults if the config file is not found.
+ */
+function readConventions(cwd?: string): {
+  knowledgeSourceFiles: string[];
+  claudeDirName: string;
+} {
+  const defaults = {
+    knowledgeSourceFiles: ['CLAUDE.md', 'MEMORY.md', 'corrections.md'],
+    claudeDirName: '.claude',
+  };
+  try {
+    const projectRoot = cwd ?? process.cwd();
+    const configPath = join(projectRoot, 'massu.config.yaml');
+    if (!existsSync(configPath)) return defaults;
+    const content = readFileSync(configPath, 'utf-8');
+    const parsed = parseYaml(content) as Record<string, unknown> | null;
+    if (!parsed || typeof parsed !== 'object') return defaults;
+    const conventions = parsed.conventions as Record<string, unknown> | undefined;
+    if (!conventions || typeof conventions !== 'object') return defaults;
+    return {
+      knowledgeSourceFiles: Array.isArray(conventions.knowledgeSourceFiles)
+        ? conventions.knowledgeSourceFiles as string[]
+        : defaults.knowledgeSourceFiles,
+      claudeDirName: typeof conventions.claudeDirName === 'string'
+        ? conventions.claudeDirName
+        : defaults.claudeDirName,
+    };
+  } catch {
+    return defaults;
+  }
+}
+
+/**
+ * Check if a file path is a knowledge source file (CLAUDE.md, corrections.md,
+ * memory files, or knowledge system source files).
+ * When these are edited, the knowledge index may become stale.
+ */
+function isKnowledgeSourceFile(filePath: string): boolean {
+  const basename = filePath.split('/').pop() ?? '';
+  const conventions = readConventions();
+  const knowledgeSourcePatterns = [
+    ...conventions.knowledgeSourceFiles,
+    'file-index.md',
+    'knowledge-db.ts',
+    'knowledge-indexer.ts',
+    'knowledge-tools.ts',
+  ];
+  return knowledgeSourcePatterns.some(p => basename === p) ||
+    filePath.includes('/memory/') ||
+    filePath.includes(conventions.claudeDirName + '/');
+}
+
+/**
+ * Check MEMORY.md file integrity after a write.
+ * Verifies: file exists, has expected structure, and is under line limit.
+ * Returns array of issue descriptions (empty = all good).
+ */
+function checkMemoryFileIntegrity(filePath: string): string[] {
+  const issues: string[] = [];
+
+  try {
+    if (!existsSync(filePath)) {
+      issues.push('MEMORY.md file does not exist after write');
+      return issues;
+    }
+
+    const content = readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+
+    // Check line count (CLAUDE.md truncates after ~200 lines)
+    const MAX_LINES = 200;
+    if (lines.length > MAX_LINES) {
+      issues.push(`MEMORY.md exceeds ${MAX_LINES} lines (currently ${lines.length}). Consider archiving old entries.`);
+    }
+
+    // Check required structure sections
+    const requiredSections = ['# Massu Memory', '## Key Learnings', '## Common Gotchas'];
+    for (const section of requiredSections) {
+      if (!content.includes(section)) {
+        issues.push(`Missing required section: "${section}"`);
+      }
+    }
+  } catch (_e) {
+    // Graceful degradation: don't report issues if we can't check
+  }
+
+  return issues;
+}
+
 main();

package/src/hooks/pre-compact.ts

@@ -7,7 +7,7 @@
 // Captures current session state into DB before compaction destroys context.
 // ============================================================
 
-import { getMemoryDb, addSummary, createSession } from '../memory-db.ts';
+import { getMemoryDb, addSummary, createSession, addObservation } from '../memory-db.ts';
 import { logAuditEntry } from '../audit-trail.ts';
 import type { SessionSummary } from '../memory-db.ts';
 
@@ -45,6 +45,28 @@ async function main(): Promise<void> {
       // 4. Store with pre_compact marker in plan_progress
       addSummary(db, session_id, summary);
 
+      // 5. Preserve knowledge system state for post-compaction context
+      try {
+        const knowledgeObs = observations.filter(
+          o => (o.title as string)?.includes('knowledge') ||
+               (o.title as string)?.includes('Knowledge') ||
+               (o.detail as string)?.includes('knowledge')
+        );
+        if (knowledgeObs.length > 0) {
+          const knowledgeContext = knowledgeObs
+            .map(o => `[${o.type}] ${o.title}`)
+            .join('; ');
+          // Store as a high-importance observation so session-start picks it up
+          addObservation(db, session_id, 'discovery',
+            'Knowledge context preserved before compaction',
+            knowledgeContext,
+            { importance: 4 }
+          );
+        }
+      } catch (_knowledgeErr) {
+        // Best-effort: never block compaction
+      }
+
       // Log compaction event for audit trail continuity
       try {
         logAuditEntry(db, {