start-vibing 2.0.8 → 2.0.10

package/template/.claude/hooks/stop-validator.ts

@@ -1,353 +1,825 @@
-#!/usr/bin/env node
-/**
- * Stop Validator Hook - TypeScript version (fallback when Python not available)
- *
- * VALIDATES:
- * 1. NOT on main branch (unless no source changes)
- * 2. All modified files are documented
- * 3. Documenter agent was executed for source changes
- *
- * BLOCKS completion if validations fail.
- */
-
-import { execSync } from 'child_process';
-import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
-import { join, basename, extname } from 'path';
-
-const IGNORE_DIRS = new Set([
-  '.next', 'node_modules', 'dist', 'build', 'coverage',
-  '.git', '__pycache__', '.turbo', '.cache', '.husky',
-  'packages'
-]);
-
-const IGNORE_PATTERNS = [
-  '.lock', '.log', '.map', '.min.js', '.min.css',
-  'package-lock.json', 'bun.lockb', '.DS_Store', 'Thumbs.db'
-];
-
-const DOC_EXTENSIONS = new Set(['.md', '.mdx', '.txt', '.rst']);
-
-const SOURCE_EXTENSIONS = new Set([
-  '.ts', '.tsx', '.js', '.jsx', '.py', '.go', '.rs',
-  '.java', '.kt', '.swift', '.vue', '.svelte'
-]);
-
-const SYSTEM_CONFIG_PATTERNS = [
-  'CLAUDE.md',
-  '.claude/',
-  'PROJECT.md',
-  '.env.example',
-];
-
-function shouldIgnoreFile(filePath: string): boolean {
-  const parts = filePath.split(/[/\\]/);
-
-  for (const part of parts) {
-    if (IGNORE_DIRS.has(part)) return true;
-  }
-
-  for (const pattern of IGNORE_PATTERNS) {
-    if (filePath.includes(pattern)) return true;
-  }
-
-  return false;
-}
-
-function isSourceFile(filePath: string): boolean {
-  const ext = extname(filePath);
-  return SOURCE_EXTENSIONS.has(ext) && !shouldIgnoreFile(filePath);
-}
-
-function isSystemConfigFile(filePath: string): boolean {
-  return SYSTEM_CONFIG_PATTERNS.some(pattern => filePath.includes(pattern));
-}
-
-function getCurrentBranch(projectDir: string): string {
-  try {
-    const result = execSync('git rev-parse --abbrev-ref HEAD', {
-      cwd: projectDir,
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe']
-    });
-    return result.trim();
-  } catch {
-    return 'unknown';
-  }
-}
-
-function getModifiedFiles(projectDir: string): string[] {
-  try {
-    const staged = execSync('git diff --name-only --cached', {
-      cwd: projectDir,
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe']
-    }).trim().split('\n').filter(Boolean);
-
-    const unstaged = execSync('git diff --name-only', {
-      cwd: projectDir,
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe']
-    }).trim().split('\n').filter(Boolean);
-
-    const untracked = execSync('git ls-files --others --exclude-standard', {
-      cwd: projectDir,
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe']
-    }).trim().split('\n').filter(Boolean);
-
-    return [...new Set([...staged, ...unstaged, ...untracked])].filter(Boolean);
-  } catch {
-    return [];
-  }
-}
-
-function* walkDir(dir: string): Generator<string> {
-  if (!existsSync(dir)) return;
-
-  const entries = readdirSync(dir);
-  for (const entry of entries) {
-    const fullPath = join(dir, entry);
-    try {
-      const stat = statSync(fullPath);
-      if (stat.isDirectory()) {
-        yield* walkDir(fullPath);
-      } else if (stat.isFile()) {
-        yield fullPath;
-      }
-    } catch {
-      continue;
-    }
-  }
-}
-
-function searchInDocs(projectDir: string, filePath: string): boolean {
-  const fileName = basename(filePath);
-  const fileStem = basename(filePath, extname(filePath));
-
-  const docDirs = [
-    join(projectDir, 'docs'),
-    join(projectDir, '.claude', 'skills', 'codebase-knowledge', 'domains'),
-  ];
-
-  for (const docDir of docDirs) {
-    if (!existsSync(docDir)) continue;
-
-    for (const docFile of walkDir(docDir)) {
-      const ext = extname(docFile);
-      if (!DOC_EXTENSIONS.has(ext)) continue;
-
-      try {
-        const content = readFileSync(docFile, 'utf8');
-        if (content.includes(fileName) || content.includes(fileStem) || content.includes(filePath)) {
-          return true;
-        }
-      } catch {
-        continue;
-      }
-    }
-  }
-
-  return false;
-}
-
-function validateDocumentation(projectDir: string, modifiedFiles: string[]): { undocumented: string[], documented: string[] } {
-  const undocumented: string[] = [];
-  const documented: string[] = [];
-
-  for (const filePath of modifiedFiles) {
-    if (!isSourceFile(filePath)) continue;
-
-    if (searchInDocs(projectDir, filePath)) {
-      documented.push(filePath);
-    } else {
-      undocumented.push(filePath);
-    }
-  }
-
-  return { undocumented, documented };
-}
-
-interface HookInput {
-  stop_hook_active?: boolean;
-}
-
-interface HookResult {
-  decision: 'approve' | 'block';
-  reason: string;
-}
-
-async function readStdinWithTimeout(timeoutMs: number): Promise<string> {
-  return new Promise((resolve) => {
-    const timeout = setTimeout(() => {
-      process.stdin.destroy();
-      resolve('{}');
-    }, timeoutMs);
-
-    let data = '';
-    process.stdin.setEncoding('utf8');
-    process.stdin.on('data', (chunk: string) => {
-      data += chunk;
-    });
-    process.stdin.on('end', () => {
-      clearTimeout(timeout);
-      resolve(data || '{}');
-    });
-    process.stdin.on('error', () => {
-      clearTimeout(timeout);
-      resolve('{}');
-    });
-
-    if (process.stdin.readableEnded) {
-      clearTimeout(timeout);
-      resolve('{}');
-    }
-  });
-}
-
-async function main(): Promise<void> {
-  const projectDir = process.env['CLAUDE_PROJECT_DIR'] || process.cwd();
-
-  let hookInput: HookInput = {};
-  try {
-    const stdin = await readStdinWithTimeout(1000);
-    if (stdin && stdin.trim()) {
-      hookInput = JSON.parse(stdin);
-    }
-  } catch {
-    hookInput = {};
-  }
-
-  // Prevent infinite loops
-  if (hookInput.stop_hook_active) {
-    const result: HookResult = { decision: 'approve', reason: 'Stop hook cycle detected, allowing exit' };
-    console.log(JSON.stringify(result));
-    process.exit(0);
-  }
-
-  const currentBranch = getCurrentBranch(projectDir);
-  const modifiedFiles = getModifiedFiles(projectDir);
-  const sourceFiles = modifiedFiles.filter(isSourceFile);
-  const systemConfigFiles = modifiedFiles.filter(isSystemConfigFile);
-
-  const errors: Array<{ type: string; message: string }> = [];
-
-  // Check 1: ANY changes on main branch are FORBIDDEN
-  if ((currentBranch === 'main' || currentBranch === 'master') && modifiedFiles.length > 0) {
-    const fileList = modifiedFiles.slice(0, 15).map(f => `  - ${f}`).join('\n');
-    const more = modifiedFiles.length > 15 ? '\n  ... and more' : '';
-
-    errors.push({
-      type: 'DIRECT_MAIN_COMMIT',
-      message: `
-BLOCKED: Attempting to work directly on '${currentBranch}' branch!
-
-You have ${modifiedFiles.length} modified file(s):
-${fileList}${more}
-
-REQUIRED ACTION:
-1. Create a feature branch: git checkout -b feature/[name]
-2. Or fix/chore branch: git checkout -b fix/[name] or git checkout -b chore/[name]
-3. Continue your work on the new branch
-4. Create PR to merge back to main
-
-NEVER make ANY changes directly on main. ALL work must be done on branches.
-`
-    });
-  }
-
-  // Check 2: Documentation for source files
-  if (sourceFiles.length > 0) {
-    const { undocumented } = validateDocumentation(projectDir, sourceFiles);
-
-    if (undocumented.length > 0) {
-      const fileList = undocumented.slice(0, 15).map(f => `  - ${f}`).join('\n');
-      const more = undocumented.length > 15 ? '\n  ... and more' : '';
-
-      errors.push({
-        type: 'MISSING_DOCUMENTATION',
-        message: `
-BLOCKED: ${undocumented.length} source file(s) are NOT documented!
-
-Undocumented files:
-${fileList}${more}
-
-REQUIRED ACTION:
-Run the documenter agent to update documentation:
-
-  Task(subagent_type="documenter", prompt="Update documentation for all modified files")
-
-The documenter will:
-1. Detect changed files via git diff
-2. Update domain files in .claude/skills/codebase-knowledge/domains/
-3. Update docs/CHANGELOG.md
-4. Ensure all modified files are mentioned in documentation
-
-DOCUMENTATION IS MANDATORY before task completion.
-`
-      });
-    }
-  }
-
-  if (errors.length > 0) {
-    let errorOutput = `
-================================================================================
-STOP VALIDATOR - BLOCKING TASK COMPLETION
-================================================================================
-`;
-    for (const err of errors) {
-      errorOutput += `
---- ${err.type} ---
-${err.message}
-`;
-    }
-
-    errorOutput += `
-================================================================================
-FIX THE ABOVE ISSUES BEFORE COMPLETING THE TASK
-================================================================================
-`;
-
-    const result: HookResult = { decision: 'block', reason: errorOutput.trim() };
-    console.log(JSON.stringify(result));
-    process.exit(0);
-  }
-
-  // All validations passed
-  let nextStepMessage: string;
-  if (modifiedFiles.length > 0) {
-    nextStepMessage = `
-================================================================================
-✓ ALL VALIDATIONS PASSED
-================================================================================
-
-Branch: ${currentBranch}
-Modified files: ${modifiedFiles.length} (source: ${sourceFiles.length}, config: ${systemConfigFiles.length})
-
-MANDATORY NEXT STEP:
-You MUST now commit, push, and create a PR:
-
-1. git add -A
-2. git commit with conventional commit message
-3. git push -u origin ${currentBranch}
-4. gh pr create to main branch
-
-DO NOT ask the user - just execute the commit-manager flow.
-
-================================================================================
-`;
-  } else {
-    nextStepMessage = `All validations passed. Branch: ${currentBranch}, no files modified.`;
-  }
-
-  const result: HookResult = { decision: 'approve', reason: nextStepMessage.trim() };
-  console.log(JSON.stringify(result));
-  process.exit(0);
-}
-
-main().catch((err) => {
-  console.error('Hook error:', err);
-  // On error, allow to continue to not block user
-  const result: HookResult = { decision: 'approve', reason: 'Hook error, allowing by default' };
-  console.log(JSON.stringify(result));
-  process.exit(0);
-});
+#!/usr/bin/env node
+/**
+ * Stop Validator Hook - Complete Validation System
+ *
+ * THIS HOOK BLOCKS TASK COMPLETION IF ANY OF THESE CONDITIONS FAIL:
+ *
+ * 1. BRANCH CHECK: Must be on 'main' branch (PR must be merged)
+ * 2. GIT TREE CHECK: Working tree must be clean (no uncommitted changes)
+ * 3. CLAUDE.MD CHECK: Must be updated with session changes
+ * 4. CLAUDE.MD STRUCTURE: Must have required sections
+ * 5. CLAUDE.MD SIZE: Must not exceed 40,000 characters
+ * 6. DOCUMENTATION CHECK: All source files must be documented
+ *
+ * ERROR MESSAGES ARE DESCRIPTIVE: They guide the agent on exactly what to do.
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join, basename, extname } from 'path';
+
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+
+const PROJECT_DIR = process.env['CLAUDE_PROJECT_DIR'] || process.cwd();
+const CLAUDE_MD_PATH = join(PROJECT_DIR, 'CLAUDE.md');
+const MAX_CHARACTERS = 40000;
+
+const IGNORE_DIRS = new Set([
+	'.next',
+	'node_modules',
+	'dist',
+	'build',
+	'coverage',
+	'.git',
+	'__pycache__',
+	'.turbo',
+	'.cache',
+	'.husky',
+	'packages',
+]);
+
+const IGNORE_PATTERNS = [
+	'.lock',
+	'.log',
+	'.map',
+	'.min.js',
+	'.min.css',
+	'package-lock.json',
+	'bun.lockb',
+	'.DS_Store',
+	'Thumbs.db',
+];
+
+const DOC_EXTENSIONS = new Set(['.md', '.mdx', '.txt', '.rst']);
+
+const SOURCE_EXTENSIONS = new Set([
+	'.ts',
+	'.tsx',
+	'.js',
+	'.jsx',
+	'.py',
+	'.go',
+	'.rs',
+	'.java',
+	'.kt',
+	'.swift',
+	'.vue',
+	'.svelte',
+]);
+
+// Required sections in CLAUDE.md
+const REQUIRED_SECTIONS = [
+	{ pattern: /^# .+/m, name: 'Project Title (H1)' },
+	{ pattern: /^## Last Change/m, name: 'Last Change' },
+	{ pattern: /^## 30 Seconds Overview/m, name: '30 Seconds Overview' },
+	{ pattern: /^## Stack/m, name: 'Stack' },
+	{ pattern: /^## Architecture/m, name: 'Architecture' },
+];
+
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+
+function shouldIgnoreFile(filePath: string): boolean {
+	const parts = filePath.split(/[/\\]/);
+	for (const part of parts) {
+		if (IGNORE_DIRS.has(part)) return true;
+	}
+	for (const pattern of IGNORE_PATTERNS) {
+		if (filePath.includes(pattern)) return true;
+	}
+	return false;
+}
+
+function isSourceFile(filePath: string): boolean {
+	const ext = extname(filePath);
+	return SOURCE_EXTENSIONS.has(ext) && !shouldIgnoreFile(filePath);
+}
+
+function getCurrentBranch(): string {
+	try {
+		return execSync('git rev-parse --abbrev-ref HEAD', {
+			cwd: PROJECT_DIR,
+			encoding: 'utf8',
+			stdio: ['pipe', 'pipe', 'pipe'],
+		}).trim();
+	} catch {
+		return 'unknown';
+	}
+}
+
+function getModifiedFiles(): string[] {
+	try {
+		const staged = execSync('git diff --name-only --cached', {
+			cwd: PROJECT_DIR,
+			encoding: 'utf8',
+			stdio: ['pipe', 'pipe', 'pipe'],
+		})
+			.trim()
+			.split('\n')
+			.filter(Boolean);
+
+		const unstaged = execSync('git diff --name-only', {
+			cwd: PROJECT_DIR,
+			encoding: 'utf8',
+			stdio: ['pipe', 'pipe', 'pipe'],
+		})
+			.trim()
+			.split('\n')
+			.filter(Boolean);
+
+		const untracked = execSync('git ls-files --others --exclude-standard', {
+			cwd: PROJECT_DIR,
+			encoding: 'utf8',
+			stdio: ['pipe', 'pipe', 'pipe'],
+		})
+			.trim()
+			.split('\n')
+			.filter(Boolean);
+
+		return [...new Set([...staged, ...unstaged, ...untracked])].filter(Boolean);
+	} catch {
+		return [];
+	}
+}
+
+function* walkDir(dir: string): Generator<string> {
+	if (!existsSync(dir)) return;
+	const entries = readdirSync(dir);
+	for (const entry of entries) {
+		const fullPath = join(dir, entry);
+		try {
+			const stat = statSync(fullPath);
+			if (stat.isDirectory()) {
+				yield* walkDir(fullPath);
+			} else if (stat.isFile()) {
+				yield fullPath;
+			}
+		} catch {
+			continue;
+		}
+	}
+}
+
+function searchInDocs(filePath: string): boolean {
+	const fileName = basename(filePath);
+	const fileStem = basename(filePath, extname(filePath));
+
+	const docDirs = [
+		join(PROJECT_DIR, 'docs'),
+		join(PROJECT_DIR, '.claude', 'skills', 'codebase-knowledge', 'domains'),
+	];
+
+	for (const docDir of docDirs) {
+		if (!existsSync(docDir)) continue;
+		for (const docFile of walkDir(docDir)) {
+			const ext = extname(docFile);
+			if (!DOC_EXTENSIONS.has(ext)) continue;
+			try {
+				const content = readFileSync(docFile, 'utf8');
+				if (
+					content.includes(fileName) ||
+					content.includes(fileStem) ||
+					content.includes(filePath)
+				) {
+					return true;
+				}
+			} catch {
+				continue;
+			}
+		}
+	}
+	return false;
+}
+
+// ============================================================================
+// VALIDATION FUNCTIONS
+// ============================================================================
+
+interface ValidationError {
+	type: string;
+	message: string;
+	action: string;
+}
+
+function validateBranch(currentBranch: string, modifiedFiles: string[]): ValidationError | null {
+	const isMainBranch = currentBranch === 'main' || currentBranch === 'master';
+
+	// Case 1: On feature branch with changes - need to complete workflow
+	if (!isMainBranch && modifiedFiles.length > 0) {
+		return {
+			type: 'FEATURE_BRANCH_NOT_MERGED',
+			message: `Currently on branch '${currentBranch}' with uncommitted changes. The task cannot complete until work is merged to main.`,
+			action: `
+================================================================================
+COMPLETE THE GIT WORKFLOW BEFORE TASK COMPLETION
+================================================================================
+
+You are on branch '${currentBranch}' with ${modifiedFiles.length} modified file(s).
+
+REQUIRED STEPS (execute in order):
+
+1. STAGE all changes:
+   git add -A
+
+2. COMMIT with conventional message:
+   git commit -m "feat: description of changes"
+
+3. PUSH to remote:
+   git push -u origin ${currentBranch}
+
+4. CREATE Pull Request:
+   gh pr create --title "Title" --body "$(cat <<'EOF'
+## Summary
+- What was changed
+
+## Test plan
+- How to verify
+
+Generated with Claude Code
+EOF
+)"
+
+5. MERGE the PR (auto-delete branch):
+   gh pr merge --merge --delete-branch
+
+6. SWITCH to main and pull:
+   git checkout main && git pull
+
+THEN the task can complete. The stop hook will verify main branch + clean tree.
+================================================================================`,
+		};
+	}
+
+	// Case 2: On feature branch with clean tree - just need to switch
+	if (!isMainBranch && modifiedFiles.length === 0) {
+		return {
+			type: 'NOT_ON_MAIN_BRANCH',
+			message: `Currently on branch '${currentBranch}'. Task completion requires being on 'main'.`,
+			action: `
+================================================================================
+SWITCH TO MAIN BRANCH
+================================================================================
+
+The working tree is clean but you're on branch '${currentBranch}'.
+
+If your PR was merged:
+   git checkout main && git pull
+
+If you still need to create/merge PR:
+   gh pr create (if not created)
+   gh pr merge --merge --delete-branch (to merge)
+   git checkout main && git pull
+
+IMPORTANT: Task completion is BLOCKED until you are on 'main' with a clean tree.
+================================================================================`,
+		};
+	}
+
+	// Case 3: On main with changes - FORBIDDEN
+	if (isMainBranch && modifiedFiles.length > 0) {
+		const fileList = modifiedFiles
+			.slice(0, 10)
+			.map((f) => `  - ${f}`)
+			.join('\n');
+		return {
+			type: 'DIRECT_MAIN_COMMIT_FORBIDDEN',
+			message: `CRITICAL: Attempting to work directly on '${currentBranch}' branch with changes!`,
+			action: `
+================================================================================
+FORBIDDEN: DIRECT COMMITS TO MAIN
+================================================================================
+
+You have ${modifiedFiles.length} modified file(s) on main branch:
+${fileList}${modifiedFiles.length > 10 ? '\n  ... and more' : ''}
+
+ALL work MUST be done on feature branches. This is MANDATORY.
+
+REQUIRED STEPS:
+
+1. CREATE a feature branch:
+   git checkout -b feature/your-feature-name
+   (or fix/, refactor/, chore/, test/ as appropriate)
+
+2. CONTINUE your work on the new branch
+
+3. When done, create PR to merge back to main
+
+NEVER commit directly to main. The stop hook will BLOCK this.
+================================================================================`,
+		};
+	}
+
+	return null; // All good - on main with clean tree
+}
+
+function validateGitTree(modifiedFiles: string[]): ValidationError | null {
+	if (modifiedFiles.length === 0) return null;
+
+	const fileList = modifiedFiles
+		.slice(0, 15)
+		.map((f) => `  - ${f}`)
+		.join('\n');
+
+	return {
+		type: 'GIT_TREE_NOT_CLEAN',
+		message: `Git working tree is not clean. Found ${modifiedFiles.length} modified/untracked file(s).`,
+		action: `
+================================================================================
+GIT TREE MUST BE CLEAN FOR TASK COMPLETION
+================================================================================
+
+Modified files:
+${fileList}${modifiedFiles.length > 15 ? '\n  ... and more' : ''}
+
+The task cannot complete with uncommitted work.
+
+OPTIONS:
+
+1. COMMIT the changes (recommended):
+   git add -A
+   git commit -m "type: description"
+   git push
+
+2. STASH for later:
+   git stash push -m "WIP: description"
+
+3. DISCARD changes (use with caution):
+   git checkout -- .
+   git clean -fd
+
+After cleaning the tree, the stop hook will pass.
+================================================================================`,
+	};
+}
+
+function validateClaudeMdExists(): ValidationError | null {
+	if (!existsSync(CLAUDE_MD_PATH)) {
+		return {
+			type: 'CLAUDE_MD_MISSING',
+			message: 'CLAUDE.md file not found at project root.',
+			action: `
+================================================================================
+CLAUDE.MD IS REQUIRED
+================================================================================
+
+The project MUST have a CLAUDE.md file at the root with these sections:
+
+# Project Name
+
+## Last Change
+**Branch:** branch-name
+**Date:** YYYY-MM-DD
+**Summary:** What was done in this session
+
+## 30 Seconds Overview
+Quick description of what this project does.
+
+## Stack
+| Component | Technology |
+|-----------|------------|
+| Runtime   | Bun        |
+| Language  | TypeScript |
+| Database  | MongoDB    |
+
+## Architecture
+Project structure and key directories.
+
+CREATE this file before the task can complete.
+================================================================================`,
+		};
+	}
+	return null;
+}
+
+function validateClaudeMdSize(): ValidationError | null {
+	if (!existsSync(CLAUDE_MD_PATH)) return null;
+
+	const content = readFileSync(CLAUDE_MD_PATH, 'utf8');
+	if (content.length <= MAX_CHARACTERS) return null;
+
+	const excess = content.length - MAX_CHARACTERS;
+
+	return {
+		type: 'CLAUDE_MD_SIZE_EXCEEDED',
+		message: `CLAUDE.md exceeds 40,000 character limit by ${excess} characters (current: ${content.length}).`,
+		action: `
+================================================================================
+CLAUDE.MD MUST BE COMPACTED (MAX 40,000 CHARACTERS)
+================================================================================
+
+Current size: ${content.length} characters
+Maximum allowed: ${MAX_CHARACTERS} characters
+Excess: ${excess} characters
+
+COMPACTION RULES (what to keep vs remove):
+
+KEEP (critical):
+- # Project Title
+- ## Last Change (only the MOST RECENT)
+- ## 30 Seconds Overview
+- ## Stack
+- ## Architecture
+- ## Critical Rules
+- ## FORBIDDEN Actions
+- ## Quality Gates
+
+REMOVE/CONDENSE:
+- Verbose explanations (use bullet points)
+- Duplicate information
+- Old/outdated sections
+- Long code examples (keep minimal)
+- Multiple "Last Change" entries (keep only latest)
+
+After editing, verify: wc -m CLAUDE.md
+================================================================================`,
+	};
+}
+
+function validateClaudeMdStructure(): ValidationError | null {
+	if (!existsSync(CLAUDE_MD_PATH)) return null;
+
+	const content = readFileSync(CLAUDE_MD_PATH, 'utf8');
+	const missingSections: string[] = [];
+
+	for (const section of REQUIRED_SECTIONS) {
+		if (!section.pattern.test(content)) {
+			missingSections.push(section.name);
+		}
+	}
+
+	if (missingSections.length === 0) return null;
+
+	return {
+		type: 'CLAUDE_MD_MISSING_SECTIONS',
+		message: `CLAUDE.md is missing required sections: ${missingSections.join(', ')}`,
+		action: `
+================================================================================
+CLAUDE.MD MISSING REQUIRED SECTIONS
+================================================================================
+
+Missing sections:
+${missingSections.map((s) => `  - ${s}`).join('\n')}
+
+REQUIRED STRUCTURE:
+
+# Project Name                    <- H1 title
+
+## Last Change                    <- ONLY the most recent change
+**Branch:** feature/xxx
+**Date:** YYYY-MM-DD
+**Summary:** What was done
+
+## 30 Seconds Overview            <- Quick project description
+
+## Stack                          <- Technology table
+
+## Architecture                   <- Project structure
+
+ADD the missing sections before the task can complete.
+================================================================================`,
+	};
+}
+
+function validateClaudeMdLastChange(): ValidationError | null {
+	if (!existsSync(CLAUDE_MD_PATH)) return null;
+
+	const content = readFileSync(CLAUDE_MD_PATH, 'utf8');
+	const lastChangeMatch = content.match(/## Last Change\n([\s\S]*?)(?=\n## |$)/);
+
+	if (!lastChangeMatch) return null; // Covered by structure check
+
+	const lastChangeContent = lastChangeMatch[1].trim();
+
+	// Check for meaningful content
+	if (lastChangeContent.length < 50) {
+		return {
+			type: 'CLAUDE_MD_LAST_CHANGE_EMPTY',
+			message: 'The "Last Change" section exists but lacks sufficient content.',
+			action: `
+================================================================================
+UPDATE "LAST CHANGE" SECTION
+================================================================================
+
+The "## Last Change" section must contain:
+
+**Branch:** the-branch-name-used
+**Date:** ${new Date().toISOString().split('T')[0]}
+**Summary:** 1-2 sentences describing what was changed/implemented
+
+Example:
+## Last Change
+
+**Branch:** feature/add-auth
+**Date:** 2025-01-05
+**Summary:** Implemented JWT authentication with refresh tokens and session management.
+
+IMPORTANT: This section should ONLY contain the LAST change, not a history.
+================================================================================`,
+		};
+	}
+
+	// Check for multiple Last Change sections (stacking is forbidden)
+	const multipleChanges = content.match(/## Last Change/g);
+	if (multipleChanges && multipleChanges.length > 1) {
+		return {
+			type: 'CLAUDE_MD_STACKED_CHANGES',
+			message: `Found ${multipleChanges.length} "## Last Change" sections. Only ONE is allowed.`,
+			action: `
+================================================================================
+REMOVE STACKED CHANGES - KEEP ONLY THE LATEST
+================================================================================
+
+Rule: CLAUDE.md should only have ONE "## Last Change" section.
+Previous changes belong in git history, not in the documentation.
+
+Found ${multipleChanges.length} instances of "## Last Change".
+
+ACTION: Remove all but the most recent "## Last Change" section.
+
+This keeps the file focused and within the 40k character limit.
+================================================================================`,
+		};
+	}
+
+	return null;
+}
+
+function validateClaudeMdUpdated(modifiedFiles: string[]): ValidationError | null {
+	// If no source files modified, no need to check
+	const sourceFiles = modifiedFiles.filter(isSourceFile);
+	if (sourceFiles.length === 0) return null;
+
+	// Check if CLAUDE.md is in the modified files
+	const claudeMdModified = modifiedFiles.some(
+		(f) => f === 'CLAUDE.md' || f.endsWith('/CLAUDE.md') || f.endsWith('\\CLAUDE.md')
+	);
+
+	if (claudeMdModified) return null;
+
+	return {
+		type: 'CLAUDE_MD_NOT_UPDATED',
+		message: `${sourceFiles.length} source file(s) were modified but CLAUDE.md was not updated.`,
+		action: `
+================================================================================
+UPDATE CLAUDE.MD WITH SESSION CHANGES (MANDATORY)
+================================================================================
+
+You modified source files but did not update CLAUDE.md.
+
+Modified source files:
+${sourceFiles
+	.slice(0, 10)
+	.map((f) => `  - ${f}`)
+	.join('\n')}${sourceFiles.length > 10 ? '\n  ... and more' : ''}
+
+REQUIRED UPDATES TO CLAUDE.MD:
+
+1. Update "## Last Change" section:
+   **Branch:** current-branch-name
+   **Date:** ${new Date().toISOString().split('T')[0]}
+   **Summary:** What you implemented/fixed
+
+2. If architecture changed:
+   Update "## Architecture" section
+
+3. If new patterns/rules were established:
+   Add to appropriate section
+
+4. If user mentioned preferences or corrections:
+   Add as rules in relevant section
+
+CONTEXT SYNTHESIS:
+Think about what the user asked and what you learned.
+Capture important decisions and patterns for the next session.
+
+The stop hook will BLOCK until CLAUDE.md is updated.
+================================================================================`,
+	};
+}
+
+function validateDocumentation(sourceFiles: string[]): ValidationError | null {
+	if (sourceFiles.length === 0) return null;
+
+	const undocumented: string[] = [];
+	for (const filePath of sourceFiles) {
+		if (!searchInDocs(filePath)) {
+			undocumented.push(filePath);
+		}
+	}
+
+	if (undocumented.length === 0) return null;
+
+	const fileList = undocumented
+		.slice(0, 15)
+		.map((f) => `  - ${f}`)
+		.join('\n');
+
+	return {
+		type: 'SOURCE_FILES_NOT_DOCUMENTED',
+		message: `${undocumented.length} source file(s) are not documented.`,
+		action: `
+================================================================================
+DOCUMENT ALL MODIFIED SOURCE FILES (MANDATORY)
+================================================================================
+
+Undocumented files:
+${fileList}${undocumented.length > 15 ? '\n  ... and more' : ''}
+
+REQUIRED ACTION:
+
+Run the documenter agent to update documentation:
+
+  Task(subagent_type="documenter", prompt="Update documentation for all modified files")
+
+The documenter will:
+1. Detect changed files via git diff
+2. Update domain files in .claude/skills/codebase-knowledge/domains/
+3. Update docs/ as needed
+4. Ensure all modified files are mentioned in documentation
+
+A file is considered documented if its name appears in:
+- docs/ folder
+- .claude/skills/codebase-knowledge/domains/ folder
+
+The stop hook will BLOCK until all source files are documented.
+================================================================================`,
+	};
+}
+
+// ============================================================================
+// MAIN HOOK LOGIC
+// ============================================================================
+
+interface HookInput {
+	stop_hook_active?: boolean;
+}
+
+interface HookResult {
+	decision: 'approve' | 'block';
+	reason: string;
+}
+
+async function readStdinWithTimeout(timeoutMs: number): Promise<string> {
+	return new Promise((resolve) => {
+		const timeout = setTimeout(() => {
+			process.stdin.destroy();
+			resolve('{}');
+		}, timeoutMs);
+
+		let data = '';
+		process.stdin.setEncoding('utf8');
+		process.stdin.on('data', (chunk: string) => {
+			data += chunk;
+		});
+		process.stdin.on('end', () => {
+			clearTimeout(timeout);
+			resolve(data || '{}');
+		});
+		process.stdin.on('error', () => {
+			clearTimeout(timeout);
+			resolve('{}');
+		});
+
+		if (process.stdin.readableEnded) {
+			clearTimeout(timeout);
+			resolve('{}');
+		}
+	});
+}
+
+async function main(): Promise<void> {
+	let hookInput: HookInput = {};
+	try {
+		const stdin = await readStdinWithTimeout(1000);
+		if (stdin && stdin.trim()) {
+			hookInput = JSON.parse(stdin);
+		}
+	} catch {
+		hookInput = {};
+	}
+
+	// Prevent infinite loops
+	if (hookInput.stop_hook_active) {
+		const result: HookResult = {
+			decision: 'approve',
+			reason: 'Stop hook cycle detected, allowing exit',
+		};
+		console.log(JSON.stringify(result));
+		process.exit(0);
+	}
+
+	// Gather state
+	const currentBranch = getCurrentBranch();
+	const modifiedFiles = getModifiedFiles();
+	const sourceFiles = modifiedFiles.filter(isSourceFile);
+	const isMainBranch = currentBranch === 'main' || currentBranch === 'master';
+	const isCleanTree = modifiedFiles.length === 0;
+
+	// Run all validations
+	const errors: ValidationError[] = [];
+
+	// Validation order matters - most critical first
+	const branchError = validateBranch(currentBranch, modifiedFiles);
+	if (branchError) errors.push(branchError);
+
+	// Only check these if we're close to completion (on main or clean tree)
+	if (isMainBranch || isCleanTree) {
+		const treeError = validateGitTree(modifiedFiles);
+		if (treeError) errors.push(treeError);
+	}
+
+	const claudeMdExistsError = validateClaudeMdExists();
+	if (claudeMdExistsError) errors.push(claudeMdExistsError);
+
+	if (!claudeMdExistsError) {
+		const sizeError = validateClaudeMdSize();
+		if (sizeError) errors.push(sizeError);
+
+		const structureError = validateClaudeMdStructure();
+		if (structureError) errors.push(structureError);
+
+		const lastChangeError = validateClaudeMdLastChange();
+		if (lastChangeError) errors.push(lastChangeError);
+
+		const updatedError = validateClaudeMdUpdated(modifiedFiles);
+		if (updatedError) errors.push(updatedError);
+	}
+
+	const docError = validateDocumentation(sourceFiles);
+	if (docError) errors.push(docError);
+
+	// ============================================================================
+	// OUTPUT RESULTS
+	// ============================================================================
+
+	if (errors.length > 0) {
+		let output = `
+################################################################################
+#                    STOP VALIDATOR - TASK COMPLETION BLOCKED                  #
+################################################################################
+
+${errors.length} validation(s) failed. You MUST fix these before the task can complete.
+
+`;
+
+		for (let i = 0; i < errors.length; i++) {
+			const err = errors[i];
+			output += `
+--------------------------------------------------------------------------------
+ERROR ${i + 1}/${errors.length}: ${err.type}
+--------------------------------------------------------------------------------
+
+${err.message}
+
+${err.action}
+`;
+		}
+
+		output += `
+################################################################################
+#               FIX ALL ERRORS ABOVE BEFORE TASK CAN COMPLETE                  #
+################################################################################
+
+SYNTHESIS REMINDER:
+Before completing, ask yourself:
+- Did the user mention any preferences I should remember?
+- Did I learn any patterns that should be documented?
+- Were there any corrections I should add as rules?
+
+Update CLAUDE.md with any learnings from this session.
+`;
+
+		const result: HookResult = { decision: 'block', reason: output.trim() };
+		console.log(JSON.stringify(result));
+		process.exit(0);
+	}
+
+	// All validations passed
+	const successOutput = `
+################################################################################
+#                    STOP VALIDATOR - ALL CHECKS PASSED                        #
+################################################################################
+
+Branch: ${currentBranch}
+Tree: ${isCleanTree ? 'Clean' : `${modifiedFiles.length} modified files`}
+CLAUDE.md: Valid
+
+All validations passed. Task may complete.
+################################################################################
+`;
+
+	const result: HookResult = { decision: 'approve', reason: successOutput.trim() };
+	console.log(JSON.stringify(result));
+	process.exit(0);
+}
+
+main().catch((err) => {
+	console.error('Hook error:', err);
+	// On error, allow to continue to not block user
+	const result: HookResult = { decision: 'approve', reason: 'Hook error, allowing by default' };
+	console.log(JSON.stringify(result));
+	process.exit(0);
+});