@massu/core 0.1.2 → 0.4.1

package/src/commands/install-commands.ts

@@ -0,0 +1,137 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * `massu install-commands` — Install massu slash commands into a project.
+ *
+ * Copies all massu command .md files from the package's commands/ directory
+ * into the project's .claude/commands/ directory. Existing massu commands
+ * are updated; non-massu commands are preserved.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { getConfig } from '../config.ts';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ============================================================
+// Command Installation
+// ============================================================
+
+/**
+ * Resolve the path to the bundled commands directory.
+ * Handles both npm-installed and local development scenarios.
+ */
+export function resolveCommandsDir(): string | null {
+  const cwd = process.cwd();
+
+  // 1. npm-installed: node_modules/@massu/core/commands
+  const nodeModulesPath = resolve(cwd, 'node_modules/@massu/core/commands');
+  if (existsSync(nodeModulesPath)) {
+    return nodeModulesPath;
+  }
+
+  // 2. Relative to compiled dist/cli.js → ../commands
+  const distRelPath = resolve(__dirname, '../commands');
+  if (existsSync(distRelPath)) {
+    return distRelPath;
+  }
+
+  // 3. Relative to source src/commands/ → ../../commands
+  const srcRelPath = resolve(__dirname, '../../commands');
+  if (existsSync(srcRelPath)) {
+    return srcRelPath;
+  }
+
+  return null;
+}
+
+export interface InstallCommandsResult {
+  installed: number;
+  updated: number;
+  skipped: number;
+  commandsDir: string;
+}
+
+export function installCommands(projectRoot: string): InstallCommandsResult {
+  const claudeDirName = getConfig().conventions?.claudeDirName ?? '.claude';
+  const targetDir = resolve(projectRoot, claudeDirName, 'commands');
+
+  // Ensure .claude/commands directory exists
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  // Find source commands
+  const sourceDir = resolveCommandsDir();
+  if (!sourceDir) {
+    console.error('  ERROR: Could not find massu commands directory.');
+    console.error('  Try reinstalling: npm install @massu/core');
+    return { installed: 0, updated: 0, skipped: 0, commandsDir: targetDir };
+  }
+
+  // Read all command files from source
+  const sourceFiles = readdirSync(sourceDir).filter(f => f.endsWith('.md'));
+
+  let installed = 0;
+  let updated = 0;
+  let skipped = 0;
+
+  for (const file of sourceFiles) {
+    const sourcePath = resolve(sourceDir, file);
+    const targetPath = resolve(targetDir, file);
+    const sourceContent = readFileSync(sourcePath, 'utf-8');
+
+    if (existsSync(targetPath)) {
+      const existingContent = readFileSync(targetPath, 'utf-8');
+      if (existingContent === sourceContent) {
+        skipped++;
+        continue;
+      }
+      // Update existing command
+      writeFileSync(targetPath, sourceContent, 'utf-8');
+      updated++;
+    } else {
+      // Install new command
+      writeFileSync(targetPath, sourceContent, 'utf-8');
+      installed++;
+    }
+  }
+
+  return { installed, updated, skipped, commandsDir: targetDir };
+}
+
+// ============================================================
+// Standalone CLI Runner
+// ============================================================
+
+export async function runInstallCommands(): Promise<void> {
+  const projectRoot = process.cwd();
+
+  console.log('');
+  console.log('Massu AI - Install Slash Commands');
+  console.log('==================================');
+  console.log('');
+
+  const result = installCommands(projectRoot);
+
+  if (result.installed > 0) {
+    console.log(`  Installed ${result.installed} new commands`);
+  }
+  if (result.updated > 0) {
+    console.log(`  Updated ${result.updated} existing commands`);
+  }
+  if (result.skipped > 0) {
+    console.log(`  ${result.skipped} commands already up to date`);
+  }
+
+  const total = result.installed + result.updated + result.skipped;
+  console.log('');
+  console.log(`  ${total} slash commands available in ${result.commandsDir}`);
+  console.log('');
+  console.log('  Restart your Claude Code session to use them.');
+  console.log('');
+}

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/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/docs-tools.ts

@@ -3,7 +3,8 @@
 
 import { readFileSync, existsSync } from 'fs';
 import { resolve, basename } from 'path';
-import { getConfig, getResolvedPaths } from './config.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. */
@@ -252,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'));
   }
@@ -325,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({
@@ -394,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);
@@ -439,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;

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;
     }

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, {