@massu/core 0.8.0 → 0.9.0

package/dist/hooks/post-tool-use.js

@@ -1666,11 +1666,10 @@ function storeSecurityScore(db, sessionId, filePath, riskScore, findings) {
 // src/hooks/post-tool-use.ts
 import { readFileSync as readFileSync6, existsSync as existsSync7 } from "fs";
 import { join as join2 } from "path";
-import { parse as parseYaml3 } from "yaml";
+import { parse as parseYaml2 } from "yaml";
 
 // src/memory-file-ingest.ts
 import { readFileSync as readFileSync5, existsSync as existsSync6, readdirSync } from "fs";
-import { parse as parseYaml2 } from "yaml";
 function ingestMemoryFile(db, sessionId, filePath) {
   if (!existsSync6(filePath)) return "skipped";
   const content = readFileSync5(filePath, "utf-8");
@@ -1682,7 +1681,13 @@ function ingestMemoryFile(db, sessionId, filePath) {
   let confidence;
   if (frontmatterMatch) {
     try {
-      const fm = parseYaml2(frontmatterMatch[1]);
+      const fm = {};
+      for (const line of frontmatterMatch[1].split("\n")) {
+        const sep = line.indexOf(":");
+        if (sep > 0) {
+          fm[line.slice(0, sep).trim()] = line.slice(sep + 1).trim();
+        }
+      }
       name = fm.name ?? basename2;
       description = fm.description ?? "";
       type = fm.type ?? "discovery";
@@ -1897,7 +1902,7 @@ function readConventions(cwd) {
     const configPath = join2(projectRoot, "massu.config.yaml");
     if (!existsSync7(configPath)) return defaults;
     const content = readFileSync6(configPath, "utf-8");
-    const parsed = parseYaml3(content);
+    const parsed = parseYaml2(content);
     if (!parsed || typeof parsed !== "object") return defaults;
     const conventions = parsed.conventions;
     if (!conventions || typeof conventions !== "object") return defaults;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massu/core",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "AI Engineering Governance MCP Server - Session memory, knowledge system, feature registry, code intelligence, rule enforcement, auto-learning pipeline, tiered tooling (12 free / 72 total), 55+ workflow commands, 15 agents, 20+ patterns",
   "main": "src/server.ts",

package/src/claude-md-templates.ts

@@ -0,0 +1,342 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * CLAUDE.md content generation — framework-aware templates and directory scanning.
+ *
+ * Used by `massu init` to generate a tailored CLAUDE.md for the detected project.
+ */
+
+import { readdirSync, statSync } from 'fs';
+import { resolve, relative, basename } from 'path';
+
+// ============================================================
+// Types (re-used from init.ts but kept minimal to avoid circular deps)
+// ============================================================
+
+interface FrameworkInfo {
+  type: string;
+  router: string;
+  orm: string;
+  ui: string;
+}
+
+interface PythonInfo {
+  detected: boolean;
+  root: string;
+  hasFastapi: boolean;
+  hasSqlalchemy: boolean;
+  hasAlembic: boolean;
+}
+
+// ============================================================
+// Directory Structure Scanner (P-A03)
+// ============================================================
+
+const EXCLUDED_DIRS = new Set([
+  'node_modules', '.git', '.venv', 'venv', '__pycache__',
+  'dist', 'build', '.next', '.nuxt', '.svelte-kit', 'coverage',
+  '.massu', '.turbo', '.cache', '.output',
+]);
+
+export function scanDirectoryStructure(projectRoot: string, maxDepth: number = 2): string {
+  const lines: string[] = [];
+  const rootName = basename(projectRoot);
+  lines.push(`${rootName}/`);
+  scanLevel(projectRoot, '', maxDepth, 0, lines);
+  return lines.join('\n');
+}
+
+function scanLevel(
+  dir: string,
+  prefix: string,
+  maxDepth: number,
+  currentDepth: number,
+  lines: string[],
+): void {
+  if (currentDepth >= maxDepth) return;
+
+  let entries: string[];
+  try {
+    entries = readdirSync(dir).sort();
+  } catch {
+    return;
+  }
+
+  // Separate dirs and files, filter excluded
+  const dirs: string[] = [];
+  const files: string[] = [];
+  for (const entry of entries) {
+    if (entry.startsWith('.') && EXCLUDED_DIRS.has(entry)) continue;
+    if (EXCLUDED_DIRS.has(entry)) continue;
+    try {
+      const stat = statSync(resolve(dir, entry));
+      if (stat.isDirectory()) dirs.push(entry);
+      else files.push(entry);
+    } catch {
+      // Skip unreadable entries
+    }
+  }
+
+  const allEntries = [...dirs, ...files];
+  for (let i = 0; i < allEntries.length; i++) {
+    const entry = allEntries[i];
+    const isLast = i === allEntries.length - 1;
+    const connector = isLast ? '\u2514\u2500\u2500 ' : '\u251c\u2500\u2500 ';
+    const childPrefix = isLast ? '    ' : '\u2502   ';
+    const isDir = dirs.includes(entry);
+
+    lines.push(`${prefix}${connector}${entry}${isDir ? '/' : ''}`);
+
+    if (isDir) {
+      scanLevel(resolve(dir, entry), prefix + childPrefix, maxDepth, currentDepth + 1, lines);
+    }
+  }
+}
+
+// ============================================================
+// Content Builder (P-A02)
+// ============================================================
+
+export function buildClaudeMdContent(
+  projectName: string,
+  projectRoot: string,
+  framework: FrameworkInfo,
+  python: PythonInfo,
+): string {
+  const sections: string[] = [];
+
+  // 1. Project Overview
+  sections.push(buildProjectOverview(projectName, framework, python));
+
+  // 2. Tech Stack
+  sections.push(buildTechStack(framework, python));
+
+  // 3. Directory Structure
+  sections.push(buildDirectorySection(projectRoot));
+
+  // 4. Coding Conventions
+  sections.push(buildCodingConventions(framework, python));
+
+  // 5. Testing
+  sections.push(buildTestingSection(framework, python));
+
+  // 6. Massu Workflow
+  sections.push(buildMassuWorkflow());
+
+  // 7. Memory System
+  sections.push(buildMemorySystem());
+
+  // 8. Critical Rules
+  sections.push(buildCriticalRules());
+
+  return sections.join('\n\n---\n\n') + '\n';
+}
+
+// ---- Section Builders ----
+
+function buildProjectOverview(
+  projectName: string,
+  framework: FrameworkInfo,
+  python: PythonInfo,
+): string {
+  const stack: string[] = [];
+  if (framework.type !== 'javascript') stack.push(capitalize(framework.type));
+  if (framework.ui !== 'none') stack.push(formatUiName(framework.ui));
+  if (framework.router !== 'none') stack.push(framework.router.toUpperCase());
+  if (framework.orm !== 'none') stack.push(capitalize(framework.orm));
+  if (python.detected) {
+    stack.push('Python');
+    if (python.hasFastapi) stack.push('FastAPI');
+  }
+
+  const stackStr = stack.length > 0 ? stack.join(', ') : 'JavaScript';
+
+  return `# ${projectName}
+
+## Project Overview
+
+${projectName} is a ${stackStr} project.
+
+<!-- Add a brief description of what this project does -->`;
+}
+
+function buildTechStack(framework: FrameworkInfo, python: PythonInfo): string {
+  const rows: string[] = [];
+  rows.push('| Technology | Details |');
+  rows.push('|-----------|---------|');
+
+  rows.push(`| Language | ${capitalize(framework.type)} |`);
+  if (framework.ui !== 'none') rows.push(`| UI Framework | ${formatUiName(framework.ui)} |`);
+  if (framework.router !== 'none') rows.push(`| Router/API | ${framework.router.toUpperCase()} |`);
+  if (framework.orm !== 'none') rows.push(`| ORM | ${capitalize(framework.orm)} |`);
+  if (python.detected) {
+    rows.push('| Python | Yes |');
+    if (python.hasFastapi) rows.push('| Python Framework | FastAPI |');
+    if (python.hasSqlalchemy) rows.push('| Python ORM | SQLAlchemy |');
+    if (python.hasAlembic) rows.push('| Migrations | Alembic |');
+  }
+
+  return `## Tech Stack\n\n${rows.join('\n')}`;
+}
+
+function buildDirectorySection(projectRoot: string): string {
+  const tree = scanDirectoryStructure(projectRoot);
+  return `## Directory Structure\n\n\`\`\`\n${tree}\n\`\`\``;
+}
+
+function buildCodingConventions(framework: FrameworkInfo, python: PythonInfo): string {
+  const rules: string[] = [];
+
+  // Language-level conventions
+  if (framework.type === 'typescript') {
+    rules.push('- Use ESM imports (`import`), not CommonJS (`require`)');
+    rules.push('- Enable strict TypeScript (`strict: true` in tsconfig.json)');
+    rules.push('- Prefer explicit types over `any`');
+  }
+
+  // UI framework conventions
+  switch (framework.ui) {
+    case 'nextjs':
+      rules.push('- Use App Router conventions (`app/` directory)');
+      rules.push('- Default to Server Components; add `"use client"` only when needed');
+      rules.push('- Use `next/image` for images, `next/link` for navigation');
+      rules.push('- API routes go in `app/api/` using Route Handlers');
+      break;
+    case 'sveltekit':
+      rules.push('- Use load functions for data fetching (`+page.server.ts`)');
+      rules.push('- Use form actions for mutations');
+      rules.push('- Server-only code in `+server.ts` files');
+      break;
+    case 'react':
+      rules.push('- Prefer functional components with hooks');
+      rules.push('- Colocate component, styles, and tests');
+      break;
+  }
+
+  // Router conventions
+  if (framework.router === 'trpc') {
+    rules.push('- Define tRPC routers with Zod input validation');
+    rules.push('- Keep router files focused (one domain per router)');
+  }
+
+  // ORM conventions
+  if (framework.orm === 'prisma') {
+    rules.push('- Define models in `prisma/schema.prisma`');
+    rules.push('- Run `npx prisma generate` after schema changes');
+  } else if (framework.orm === 'drizzle') {
+    rules.push('- Define schemas with Drizzle table builders');
+    rules.push('- Run migrations with `drizzle-kit`');
+  }
+
+  // Python conventions
+  if (python.detected) {
+    rules.push('- Use type hints for function signatures');
+    rules.push('- Use `async def` for async endpoints');
+    if (python.hasFastapi) {
+      rules.push('- Use Pydantic models for request/response schemas');
+      rules.push('- Organize routes with `APIRouter`');
+    }
+    if (python.hasSqlalchemy) {
+      rules.push('- Use SQLAlchemy 2.0 style (select/insert builders)');
+    }
+  }
+
+  if (rules.length === 0) {
+    rules.push('- Follow consistent naming conventions');
+    rules.push('- Keep functions small and focused');
+  }
+
+  return `## Coding Conventions\n\n${rules.join('\n')}`;
+}
+
+function buildTestingSection(framework: FrameworkInfo, python: PythonInfo): string {
+  const lines: string[] = [];
+
+  if (framework.type === 'typescript') {
+    lines.push('- Test framework: vitest (or jest)');
+    lines.push('- Test files: `__tests__/*.test.ts` or `*.test.ts` colocated');
+    lines.push('- Run tests: `npm test`');
+  }
+
+  if (python.detected) {
+    lines.push('- Python tests: pytest');
+    lines.push('- Test files: `tests/` directory or `test_*.py` files');
+    lines.push('- Run: `pytest`');
+  }
+
+  if (lines.length === 0) {
+    lines.push('- Configure a test framework for this project');
+    lines.push('- Run tests before committing changes');
+  }
+
+  return `## Testing\n\n${lines.join('\n')}`;
+}
+
+function buildMassuWorkflow(): string {
+  return `## Massu Workflow
+
+This project uses [Massu AI](https://massu.ai) for development governance.
+
+### Common Commands
+
+| Command | Purpose |
+|---------|---------|
+| \`/massu-create-plan\` | Create an implementation plan |
+| \`/massu-plan\` | Audit and improve a plan |
+| \`/massu-golden-path\` | Full implementation flow (plan to push) |
+| \`/massu-test\` | Run tests with failure analysis |
+| \`/massu-commit\` | Pre-commit verification gate |
+| \`/massu-push\` | Pre-push verification gate |
+| \`/massu-status\` | Project health dashboard |
+| \`/massu-debug\` | Systematic debugging |
+
+### Workflow Flow
+
+\`\`\`
+/massu-create-plan -> /massu-plan (audit) -> /massu-golden-path (implement + push)
+\`\`\``;
+}
+
+function buildMemorySystem(): string {
+  return `## Memory System
+
+Massu maintains persistent memory across sessions in \`~/.claude/projects/.../memory/\`.
+
+- **User memories**: Your role, preferences, and expertise
+- **Feedback memories**: Corrections and validated approaches
+- **Project memories**: Ongoing work, decisions, deadlines
+- **Reference memories**: External resources and tools
+
+Memory is automatically loaded at session start and updated as you work.`;
+}
+
+function buildCriticalRules(): string {
+  return `## Critical Rules
+
+1. **Never commit secrets** — no API keys, tokens, or credentials in code
+2. **Run tests before committing** — all tests must pass
+3. **Verify before claiming done** — use VR-* verification checks
+4. **Fix all issues encountered** — pre-existing issues get fixed too
+5. **Read before editing** — understand existing code before modifying
+
+<!-- Add project-specific rules as you discover them -->`;
+}
+
+// ---- Helpers ----
+
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+function formatUiName(name: string): string {
+  const names: Record<string, string> = {
+    nextjs: 'Next.js',
+    sveltekit: 'SvelteKit',
+    nuxt: 'Nuxt',
+    angular: 'Angular',
+    vue: 'Vue',
+    react: 'React',
+  };
+  return names[name] ?? capitalize(name);
+}

package/src/commands/doctor.ts

@@ -15,6 +15,7 @@
  * 8. better-sqlite3 native module loads
  * 9. Node.js version >= 18
  * 10. Git repository detected
+ * 11. CLAUDE.md exists with content
  */
 
 import { existsSync, readFileSync, readdirSync } from 'fs';
@@ -373,6 +374,32 @@ function checkPythonHealth(projectRoot: string): CheckResult | null {
   };
 }
 
+function checkClaudeMd(projectRoot: string): CheckResult {
+  const claudeMdPath = resolve(projectRoot, 'CLAUDE.md');
+  if (!existsSync(claudeMdPath)) {
+    return {
+      name: 'CLAUDE.md',
+      status: 'warn',
+      detail: 'CLAUDE.md not found. Run: npx massu init (or create manually)',
+    };
+  }
+
+  const content = readFileSync(claudeMdPath, 'utf-8');
+  if (content.trim().length < 50) {
+    return {
+      name: 'CLAUDE.md',
+      status: 'warn',
+      detail: 'CLAUDE.md exists but appears empty or minimal',
+    };
+  }
+
+  return {
+    name: 'CLAUDE.md',
+    status: 'pass',
+    detail: 'CLAUDE.md found and has content',
+  };
+}
+
 // ============================================================
 // Main Doctor Flow
 // ============================================================
@@ -397,6 +424,7 @@ export async function runDoctor(): Promise<void> {
     checkNodeVersion(),
     await checkGitRepo(projectRoot),
     await checkLicenseStatus(),
+    checkClaudeMd(projectRoot),
   ];
 
   // Add Python health check if configured

package/src/commands/init.ts

@@ -18,6 +18,7 @@ import { resolve, basename, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { homedir } from 'os';
 import { backfillMemoryFiles } from '../memory-file-ingest.ts';
+import { buildClaudeMdContent } from '../claude-md-templates.ts';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -37,6 +38,8 @@ interface FrameworkDetection {
 }
 
 interface InitResult {
+  claudeMdCreated: boolean;
+  claudeMdSkipped: boolean;
   configCreated: boolean;
   configSkipped: boolean;
   mcpRegistered: boolean;
@@ -289,6 +292,28 @@ ${yamlStringify(config)}`;
   return true;
 }
 
+// ============================================================
+// CLAUDE.md Generation
+// ============================================================
+
+export function generateClaudeMd(
+  projectRoot: string,
+  framework: FrameworkDetection,
+  python: PythonDetection,
+): { created: boolean; skipped: boolean } {
+  const claudeMdPath = resolve(projectRoot, 'CLAUDE.md');
+
+  // NEVER overwrite existing CLAUDE.md
+  if (existsSync(claudeMdPath)) {
+    return { created: false, skipped: true };
+  }
+
+  const projectName = basename(projectRoot);
+  const content = buildClaudeMdContent(projectName, projectRoot, framework, python);
+  writeFileSync(claudeMdPath, content, 'utf-8');
+  return { created: true, skipped: false };
+}
+
 // ============================================================
 // MCP Server Registration
 // ============================================================
@@ -346,25 +371,18 @@ type HooksConfig = Record<string, HookGroup[]>;
  * Handles both local development and npm-installed scenarios.
  */
 export function resolveHooksDir(): string {
-  // Try to find the hooks in node_modules first (installed via npm)
-  const cwd = process.cwd();
-  const nodeModulesPath = resolve(cwd, 'node_modules/@massu/core/dist/hooks');
-  if (existsSync(nodeModulesPath)) {
-    return 'node_modules/@massu/core/dist/hooks';
-  }
-
-  // Fall back to finding relative to this source file
-  const localPath = resolve(__dirname, '../dist/hooks');
-  if (existsSync(localPath)) {
-    return localPath;
-  }
-
-  // Default to node_modules path (will be created on npm install)
+  // Always use node_modules/@massu/core/dist/hooks relative to project root.
+  // hookCmd() wraps each command with a parent-directory walk to find the
+  // project root, so hooks resolve correctly even from subdirectories.
   return 'node_modules/@massu/core/dist/hooks';
 }
 
 function hookCmd(hooksDir: string, hookFile: string): string {
-  return `node ${hooksDir}/${hookFile}`;
+  // Walk up from cwd to find the directory containing node_modules/@massu/core,
+  // then cd there before running the hook. This handles subdirectories like
+  // website/, packages/foo/, etc. where node_modules doesn't exist.
+  const hookPath = `${hooksDir}/${hookFile}`;
+  return `d="$PWD"; while [ "$d" != "/" ] && [ ! -f "$d/${hookPath}" ]; do d="$(dirname "$d")"; done; cd "$d" && node ${hookPath}`;
 }
 
 export function buildHooksConfig(hooksDir: string): HooksConfig {
@@ -559,6 +577,14 @@ export async function runInit(): Promise<void> {
     console.log(`  Detected: ${pyParts.join(', ')} (root: ${python.root})`);
   }
 
+  // Step 1.5: Generate CLAUDE.md (MUST be first content step — incident 2026-04-13)
+  const claudeMdResult = generateClaudeMd(projectRoot, framework, python);
+  if (claudeMdResult.created) {
+    console.log('  Created CLAUDE.md (project instructions for Claude Code)');
+  } else {
+    console.log('  CLAUDE.md already exists (preserved)');
+  }
+
   // Step 2: Create config
   const configCreated = generateConfig(projectRoot, framework);
   if (configCreated) {

package/src/knowledge-indexer.ts

@@ -599,7 +599,7 @@ export function indexAllKnowledge(db: Database.Database): IndexStats {
       // Parse plan documents for structured metadata
       if (category === 'plan') {
         // Extract plan items (P1-001, P2-001, etc.)
-        const planItemRegex = /^###\s+(P\d+-\d+):\s+(.+)$/gm;
+        const planItemRegex = /^###\s+(P[-A-Z]*\d*-?\w+):\s+(.+)$/gm;
         let planMatch;
         while ((planMatch = planItemRegex.exec(content)) !== null) {
           insertChunk.run(docId, 'pattern', planMatch[1], `${planMatch[1]}: ${planMatch[2]}`, null, null, JSON.stringify({ plan_item_id: planMatch[1] }));

package/src/mcp-bridge-tools.ts

@@ -50,7 +50,6 @@ process.on('exit', () => {
 });
 process.on('SIGTERM', () => {
   for (const [name] of connections) disconnectServer(name);
-  process.exit(0);
 });
 
 // Environment variables safe to forward to MCP subprocesses.

package/src/memory-file-ingest.ts

@@ -11,7 +11,6 @@
 import type Database from 'better-sqlite3';
 import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join } from 'path';
-import { parse as parseYaml } from 'yaml';
 import { addObservation } from './memory-db.ts';
 
 export type IngestResult = 'inserted' | 'updated' | 'skipped';
@@ -42,13 +41,21 @@ export function ingestMemoryFile(
 
   if (frontmatterMatch) {
     try {
-      const fm = parseYaml(frontmatterMatch[1]) as Record<string, unknown>;
-      name = (fm.name as string) ?? basename;
-      description = (fm.description as string) ?? '';
-      type = (fm.type as string) ?? 'discovery';
+      // Simple key: value parser for memory file frontmatter
+      // (avoids importing yaml library — frontmatter is flat key-value pairs)
+      const fm: Record<string, string> = {};
+      for (const line of frontmatterMatch[1].split('\n')) {
+        const sep = line.indexOf(':');
+        if (sep > 0) {
+          fm[line.slice(0, sep).trim()] = line.slice(sep + 1).trim();
+        }
+      }
+      name = fm.name ?? basename;
+      description = fm.description ?? '';
+      type = fm.type ?? 'discovery';
       confidence = fm.confidence != null ? Number(fm.confidence) : undefined;
     } catch {
-      // Use defaults if YAML parsing fails
+      // Use defaults if frontmatter parsing fails
     }
   }