start-vibing 2.0.44 → 2.0.46

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "start-vibing",
-	"version": "2.0.44",
+	"version": "2.0.46",
 	"description": "Setup Claude Code agents, skills, and hooks in your project. Smart copy that preserves your custom domains and configurations.",
 	"type": "module",
 	"bin": {

package/template/.claude/CLAUDE.md

@@ -13,6 +13,7 @@ The stop hook validates `/CLAUDE.md` before allowing task completion:
 | Character limit   | Max 40,000 chars                                          |
 | Required sections | Last Change, 30s Overview, Stack, Architecture            |
 | Last Change       | Must be updated with session info (branch, date, summary) |
+| Content depth     | Relevant rule/flow sections must also be updated          |
 | No stacking       | Only ONE Last Change section (latest only)                |
 | Branch            | Must be on main (PR merged)                               |
 | Git tree          | Must be clean (no uncommitted changes)                    |
@@ -21,6 +22,27 @@ The stop hook validates `/CLAUDE.md` before allowing task completion:
 
 **If not on main:** Complete PR workflow (commit, push, PR, merge, checkout main).
 
+### Content Depth Rule (CLAUDE_MD_SHALLOW_UPDATE)
+
+> **"Last Change" = WHAT was done. Other sections = HOW things work NOW. Both MUST be current.**
+
+The stop-validator categorizes changed files and maps them to CLAUDE.md sections:
+
+| Changed Files | Must Also Update |
+|---------------|-----------------|
+| API/CRUD routes | Critical Rules, HTTP Requests |
+| UI components | UI Architecture, Component Organization |
+| Pages/layouts | Architecture, Next.js App Router Patterns |
+| Styling/aesthetics | UI Architecture, Design System |
+| Auth/middleware | Critical Rules, Workflow |
+| Database/models | Architecture, Critical Rules |
+| Config files | Stack, Configuration |
+| Hooks/scripts | Workflow, Stop Hook Validations |
+
+If ONLY "Last Change" was modified but **significant** categorized source files changed, `CLAUDE_MD_SHALLOW_UPDATE` blocks completion.
+
+**Exempt (minor changes):** < 3 categorized files AND < 30 lines changed AND no new files = Last Change only is OK.
+
 ---
 
 ## System Architecture
@@ -213,45 +235,139 @@ All implementations MUST:
 
 ---
 
-## Opus 4.6 Best Practices
+## Claude 4.6 Best Practices
+
+> **Source:** [Anthropic Claude 4 Best Practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices)
+
+### Model Selection
+
+| Model | API ID | Cost (In/Out) | Best For |
+|-------|--------|---------------|----------|
+| **Opus 4.6** | `claude-opus-4-6` | $5/$25 MTok | Orchestrators, long-horizon tasks, 128K output |
+| **Sonnet 4.6** | `claude-sonnet-4-6` | $3/$15 MTok | Daily coding, teammates (5x cheaper) |
+| **Haiku 4.5** | `claude-haiku-4-5-20251001` | $1/$5 MTok | Classification, simple tasks |
 
 ### Effort Levels
 
-| Level | Use For |
-|-------|---------|
-| `max` | Orchestrators, complex architecture (Opus only) |
-| `high` | Default - complex agentic tasks |
-| `medium` | Most workloads, balance speed/cost |
-| `low` | Subagents, high-volume tasks |
+| Level | Behavior | Use Case |
+|-------|----------|----------|
+| `max` | Always thinks, no limits | Complex architecture (**Opus ONLY**) |
+| `high` | Deep thinking (DEFAULT) | Agentic tasks, complex coding |
+| `medium` | Moderate, may skip simple | Most workloads |
+| `low` | Minimal thinking | Subagents, teammates, high-volume |
 
-### Prompting Rules
+**CLI:** `/model` then arrow keys to adjust effort.
 
-- **AVOID**: Words like "CRITICAL", "MUST", "be thorough" - causes overtriggering
-- **USE**: "Use this tool when it would enhance understanding"
-- Keep prompts minimal - Opus 4.6 overthinks with verbose instructions
-- Explicit instructions work better than implied expectations
+### Adaptive Thinking (Replaces budget_tokens)
 
-### Model Selection
+```typescript
+// CORRECT for 4.6 models
+thinking: { type: "adaptive" },
+output_config: { effort: "medium" }
 
-| Model | Use Case |
-|-------|----------|
-| **Opus 4.6** | Team leads, orchestrators, deep reasoning |
-| **Sonnet 4.6** | Teammates, subagents (5x cheaper, near-identical performance) |
-| **Haiku 4.5** | Simple classification, no thinking needed |
+// DEPRECATED (will be removed)
+thinking: { type: "enabled", budget_tokens: 10000 }
+```
+
+Adaptive thinking enables **interleaved thinking** — Claude reasons BETWEEN tool calls.
+
+### Prompting Rules (CRITICAL)
+
+**AVOID (causes overtriggering):**
+- "CRITICAL: You MUST use..."
+- "be thorough", "think carefully", "do not be lazy"
+- "use the think tool to plan your approach"
+
+**USE INSTEAD:**
+- "Use this tool when..." (softer language)
+- Remove anti-laziness prompts entirely
+- Lower effort level instead of adding constraints
 
-### Interleaved Thinking
+**Why:** Opus 4.6 does MORE upfront exploration than older models. Anti-laziness prompts cause runaway thinking.
 
-- Enabled automatically with adaptive thinking
-- Claude reasons between every tool call
-- Pass thinking blocks back unmodified in tool loops
-- Provides transparency into Claude's reasoning process
+### Tool Use Patterns
+
+```text
+# Claude will only SUGGEST:
+"Can you suggest some changes?"
+
+# Claude will IMPLEMENT:
+"Change this function to improve performance."
+```
+
+For proactive action by default, add to system prompt:
+```text
+By default, implement changes rather than only suggesting them.
+```
+
+### Subagent Control
+
+Opus 4.6 has a **strong predilection for subagents** — may spawn them when direct grep/read is faster.
+
+**Use subagents when:** Parallel tasks, isolated context, independent workstreams
+**Work directly when:** Sequential operations, single-file edits, shared state needed
+
+```text
+# Add if seeing excessive subagent use:
+For simple tasks, sequential operations, or single-file edits, work directly.
+```
+
+### Avoid Over-Engineering
+
+Opus 4.6 tends to create extra files and unnecessary abstractions.
+
+```text
+# Add to prompt:
+Avoid over-engineering. Only make changes directly requested.
+Don't add features, docstrings, or error handling beyond what's asked.
+```
+
+### Parallel Tool Calls
+
+```text
+# Add for maximum efficiency:
+If calling multiple tools with no dependencies, make all calls in parallel.
+```
 
 ### Cost Control
 
-- Set `max_tokens` to 64K+ at high effort
-- Use `low` effort for subagents
-- Billed for FULL thinking tokens (not summarized output)
-- Thinking tokens count toward context window
+| Issue | Solution |
+|-------|----------|
+| Runaway thinking | Lower effort (not prompt constraints) |
+| `stop_reason: "max_tokens"` | Increase `max_tokens` to 64K+ |
+| High costs | Use `low` effort for subagents |
+| Billing confusion | Billed for FULL thinking, not visible summary |
+
+### Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| `max` effort on Sonnet/Haiku | Error — Opus only |
+| Prefilled responses | Deprecated in 4.6 |
+| Multiple agents editing same file | Isolate files per agent |
+| Aggressive prompts from older models | Remove "MUST", "CRITICAL" |
+
+### API Examples
+
+```typescript
+// Standard agentic call
+await client.messages.create({
+  model: "claude-opus-4-6",
+  max_tokens: 64000,
+  thinking: { type: "adaptive" },
+  output_config: { effort: "high" },
+  messages: [...]
+});
+
+// Cost-optimized subagent
+await client.messages.create({
+  model: "claude-sonnet-4-6",
+  max_tokens: 16000,
+  thinking: { type: "adaptive" },
+  output_config: { effort: "low" },
+  messages: [...]
+});
+```
 
 ---
 

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

@@ -54,6 +54,93 @@ const IGNORE_PATTERNS = [
 
 const DOC_EXTENSIONS = new Set(['.md', '.mdx', '.txt', '.rst']);
 
+// ============================================================================
+// FILE CHANGE CATEGORIES → CLAUDE.MD SECTIONS MAPPING
+// ============================================================================
+
+interface ChangeCategory {
+	name: string;
+	claudeMdSections: string[];
+	filePatterns: RegExp[];
+}
+
+const CHANGE_CATEGORIES: ChangeCategory[] = [
+	{
+		name: 'API/CRUD',
+		claudeMdSections: ['Critical Rules', 'HTTP Requests'],
+		filePatterns: [/\/api\//, /\/routers\//, /\/server\//, /\.route\./, /\.controller\./],
+	},
+	{
+		name: 'UI Components',
+		claudeMdSections: ['UI Architecture', 'Component Organization', 'Design System'],
+		filePatterns: [/\/components\//, /\/ui\//],
+	},
+	{
+		name: 'Pages/Layouts',
+		claudeMdSections: ['Next.js App Router Patterns', 'Architecture'],
+		filePatterns: [/\/app\/.*page\.tsx/, /\/app\/.*layout\.tsx/, /\/app\/.*loading\.tsx/],
+	},
+	{
+		name: 'Styling/Aesthetics',
+		claudeMdSections: ['UI Architecture', 'Design System', 'Design Trends'],
+		filePatterns: [/\.css$/, /globals\.css/, /theme/, /tailwind\.config/],
+	},
+	{
+		name: 'Auth/Middleware',
+		claudeMdSections: ['Critical Rules', 'Workflow'],
+		filePatterns: [/middleware/, /auth/, /session/],
+	},
+	{
+		name: 'Database/Models',
+		claudeMdSections: ['Architecture', 'Critical Rules'],
+		filePatterns: [/\/models\//, /\.model\./, /\/schema\//, /\.schema\./],
+	},
+	{
+		name: 'Configuration',
+		claudeMdSections: ['Stack', 'Configuration'],
+		filePatterns: [/\.config\./, /next\.config/, /tsconfig/],
+	},
+	{
+		name: 'Testing',
+		claudeMdSections: ['Quality Gates'],
+		filePatterns: [/\.test\./, /\.spec\./, /playwright/, /vitest/],
+	},
+	{
+		name: 'Workflow/Hooks',
+		claudeMdSections: ['Workflow', 'Stop Hook Validations'],
+		filePatterns: [/\.claude\/hooks\//, /\.claude\/scripts\//, /\.husky\//],
+	},
+];
+
+function categorizeChangedFiles(
+	files: string[]
+): Array<{ category: string; sections: string[]; files: string[] }> {
+	const result = new Map<string, { sections: string[]; files: string[] }>();
+
+	for (const file of files) {
+		const normalizedFile = file.replace(/\\/g, '/');
+		for (const cat of CHANGE_CATEGORIES) {
+			for (const pattern of cat.filePatterns) {
+				if (pattern.test(normalizedFile)) {
+					if (!result.has(cat.name)) {
+						result.set(cat.name, { sections: [...cat.claudeMdSections], files: [] });
+					}
+					const entry = result.get(cat.name)!;
+					if (!entry.files.includes(file)) {
+						entry.files.push(file);
+					}
+					break;
+				}
+			}
+		}
+	}
+
+	return Array.from(result.entries()).map(([category, data]) => ({
+		category,
+		...data,
+	}));
+}
+
 const SOURCE_EXTENSIONS = new Set([
 	'.ts',
 	'.tsx',
@@ -603,7 +690,8 @@ 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);
+	// Use negative lookbehind to avoid matching ### Last Change (H3 subheadings)
+	const multipleChanges = content.match(/(?<!#)## Last Change/g);
 	if (multipleChanges && multipleChanges.length > 1) {
 		return {
 			type: 'CLAUDE_MD_STACKED_CHANGES',
@@ -628,8 +716,10 @@ This keeps the file focused and within the 40k character limit.
 	return null;
 }
 
-function validateClaudeMdUpdated(modifiedFiles: string[]): ValidationError | null {
-	// Files that don't require CLAUDE.md update (auto-generated, locks, etc)
+/**
+ * Helper: Get files exempt from CLAUDE.md update requirement
+ */
+function getSignificantFiles(modifiedFiles: string[]): string[] {
 	const EXEMPT_PATTERNS = [
 		'bun.lockb',
 		'package-lock.json',
@@ -641,13 +731,10 @@ function validateClaudeMdUpdated(modifiedFiles: string[]): ValidationError | nul
 		/^packages\/start-vibing\/template\//,
 	];
 
-	// Filter out exempt files
-	const significantFiles = modifiedFiles.filter((f) => {
-		// Always exempt CLAUDE.md itself
+	return modifiedFiles.filter((f) => {
 		if (f === 'CLAUDE.md' || f.endsWith('/CLAUDE.md') || f.endsWith('\\CLAUDE.md')) {
 			return false;
 		}
-		// Check exempt patterns
 		for (const pattern of EXEMPT_PATTERNS) {
 			if (typeof pattern === 'string') {
 				if (f === pattern || f.includes(pattern)) return false;
@@ -657,17 +744,39 @@ function validateClaudeMdUpdated(modifiedFiles: string[]): ValidationError | nul
 		}
 		return true;
 	});
+}
+
+/**
+ * Helper: Build categorized section guidance for error messages
+ */
+function buildSectionGuidance(significantFiles: string[]): string {
+	const categories = categorizeChangedFiles(significantFiles);
+	if (categories.length === 0) return '';
+
+	const lines = categories.map((c) => {
+		const uniqueSections = [...new Set(c.sections)];
+		return `  - ${c.category} (${c.files.length} file${c.files.length > 1 ? 's' : ''}) → Update sections: ${uniqueSections.join(', ')}`;
+	});
+
+	return `
+DETECTED CHANGE CATEGORIES (update these CLAUDE.md sections):
+
+${lines.join('\n')}
+`;
+}
 
-	// If no significant files modified, no need to check
+function validateClaudeMdUpdated(modifiedFiles: string[]): ValidationError | null {
+	const significantFiles = getSignificantFiles(modifiedFiles);
 	if (significantFiles.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;
 
+	const sectionGuidance = buildSectionGuidance(significantFiles);
+
 	return {
 		type: 'CLAUDE_MD_NOT_UPDATED',
 		message: `${significantFiles.length} file(s) were modified but CLAUDE.md was not updated.`,
@@ -683,7 +792,7 @@ ${significantFiles
 	.slice(0, 10)
 	.map((f) => `  - ${f}`)
 	.join('\n')}${significantFiles.length > 10 ? '\n  ... and more' : ''}
-
+${sectionGuidance}
 REQUIRED UPDATES TO CLAUDE.MD:
 
 1. Update "## Last Change" section:
@@ -691,24 +800,315 @@ REQUIRED UPDATES TO CLAUDE.MD:
    **Date:** ${new Date().toISOString().split('T')[0]}
    **Summary:** What you implemented/fixed
 
-2. If architecture changed:
-   Update "## Architecture" section
+2. UPDATE RELEVANT RULE/FLOW SECTIONS (NOT just Last Change!):
+   - Changed API/CRUD logic? → Update "Critical Rules" or "HTTP Requests"
+   - Changed UI components? → Update "UI Architecture" or "Component Organization"
+   - Changed page structure? → Update "Architecture" or "Next.js App Router Patterns"
+   - Changed aesthetic rules? → Update "Design System" or "UI Architecture"
+   - Changed auth/middleware? → Update "Critical Rules" or "Workflow"
+   - Changed config? → Update "Stack" or "Configuration"
+   - Changed testing? → Update "Quality Gates"
+
+3. CONTEXT SYNTHESIS:
+   Think about what the user asked and what you learned.
+   If a rule changed, document the NEW rule in the relevant section.
+   If a flow changed, document the NEW flow.
+   CLAUDE.md is the single source of truth for ALL project rules.
+
+The stop hook will BLOCK until CLAUDE.md is updated with ALL relevant sections.
+================================================================================`,
+	};
+}
+
+// ============================================================================
+// CHANGE RELEVANCE ASSESSMENT
+// ============================================================================
+
+/**
+ * Minimum thresholds for changes to be considered "relevant enough" to require
+ * updating CLAUDE.md sections beyond "Last Change".
+ *
+ * Minor changes (small fixes, typos, internal refactors) that don't affect
+ * project rules, flows, or patterns should NOT require deep section updates.
+ */
+const RELEVANCE_THRESHOLDS = {
+	/** Minimum total lines added+removed across categorized files to require section updates */
+	minLinesChanged: 30,
+	/** Minimum number of categorized files changed to require section updates */
+	minFilesChanged: 3,
+	/** If ANY new files were created in categorized areas, always require section updates */
+	newFilesAlwaysRelevant: true,
+};
+
+/**
+ * Assess whether the changes in categorized files are significant enough
+ * to require updating CLAUDE.md sections beyond "Last Change".
+ *
+ * Returns true if changes are relevant (should require deep updates).
+ * Returns false if changes are minor (Last Change only is acceptable).
+ */
+function areChangesRelevantForClaudeMd(
+	categories: Array<{ category: string; sections: string[]; files: string[] }>
+): boolean {
+	const totalCategorizedFiles = categories.reduce((sum, c) => sum + c.files.length, 0);
 
-3. If new patterns/rules were established:
-   Add to appropriate section
+	// Check for new files (new files = new patterns/features = always relevant)
+	if (RELEVANCE_THRESHOLDS.newFilesAlwaysRelevant) {
+		try {
+			const untrackedRaw = execSync('git ls-files --others --exclude-standard', {
+				cwd: PROJECT_DIR,
+				encoding: 'utf8',
+				stdio: ['pipe', 'pipe', 'pipe'],
+			}).trim();
+			const newInLastCommitRaw = execSync('git diff --name-only --diff-filter=A HEAD~1 HEAD 2>/dev/null || echo ""', {
+				cwd: PROJECT_DIR,
+				encoding: 'utf8',
+				stdio: ['pipe', 'pipe', 'pipe'],
+			}).trim();
+
+			const newFiles = [...untrackedRaw.split('\n'), ...newInLastCommitRaw.split('\n')].filter(Boolean);
+			const allCategorizedFiles = categories.flatMap((c) => c.files);
+			const newCategorizedFiles = newFiles.filter((f) =>
+				allCategorizedFiles.some((cf) => f.includes(cf) || cf.includes(f))
+			);
+
+			if (newCategorizedFiles.length > 0) {
+				return true; // New files in categorized areas = always relevant
+			}
+		} catch {
+			// Can't determine, continue with other checks
+		}
+	}
 
-4. If user mentioned preferences or corrections:
-   Add as rules in relevant section
+	// Check minimum files threshold
+	if (totalCategorizedFiles < RELEVANCE_THRESHOLDS.minFilesChanged) {
+		// Few files changed - check if the diff is substantial
+		try {
+			const allCategorizedFiles = categories.flatMap((c) => c.files);
+			let totalLinesChanged = 0;
+
+			// Try to get numstat from various diff sources
+			const numstatCommands = [
+				'git diff --numstat',
+				'git diff --cached --numstat',
+				'git diff --numstat HEAD~1 HEAD',
+			];
+
+			for (const cmd of numstatCommands) {
+				try {
+					const numstat = execSync(cmd, {
+						cwd: PROJECT_DIR,
+						encoding: 'utf8',
+						stdio: ['pipe', 'pipe', 'pipe'],
+					}).trim();
+
+					if (!numstat) continue;
+
+					for (const line of numstat.split('\n')) {
+						const parts = line.split('\t');
+						if (parts.length < 3) continue;
+						const added = parseInt(parts[0] || '0', 10) || 0;
+						const removed = parseInt(parts[1] || '0', 10) || 0;
+						const file = parts[2] || '';
+
+						// Only count lines in categorized files
+						if (allCategorizedFiles.some((cf) => file.includes(cf) || cf.includes(file))) {
+							totalLinesChanged += added + removed;
+						}
+					}
+
+					if (totalLinesChanged > 0) break;
+				} catch {
+					continue;
+				}
+			}
+
+			if (totalLinesChanged < RELEVANCE_THRESHOLDS.minLinesChanged) {
+				return false; // Small diff + few files = minor change, Last Change is enough
+			}
+		} catch {
+			// Can't determine line count, fall through to relevant
+		}
+	}
 
-CONTEXT SYNTHESIS:
-Think about what the user asked and what you learned.
-Capture important decisions and patterns for the next session.
+	return true; // Meets thresholds = relevant, require section updates
+}
 
-The stop hook will BLOCK until CLAUDE.md is updated.
+/**
+ * Content depth validation: Checks if CLAUDE.md was updated but only the
+ * "Last Change" section was modified (shallow update).
+ *
+ * ALLOWS shallow updates when changes are minor:
+ * - Few files changed (< 3 categorized files)
+ * - Small diff (< 30 lines total in categorized files)
+ * - No new files created in categorized areas
+ *
+ * BLOCKS shallow updates when changes are significant:
+ * - Many categorized files changed
+ * - Large diffs that likely introduce new rules/flows
+ * - New files created (new patterns/features)
+ */
+function validateClaudeMdContentDepth(modifiedFiles: string[]): ValidationError | null {
+	const significantFiles = getSignificantFiles(modifiedFiles);
+	if (significantFiles.length === 0) return null;
+
+	// Only run if CLAUDE.md WAS modified (otherwise validateClaudeMdUpdated handles it)
+	const claudeMdModified = modifiedFiles.some(
+		(f) => f === 'CLAUDE.md' || f.endsWith('/CLAUDE.md') || f.endsWith('\\CLAUDE.md')
+	);
+	if (!claudeMdModified) return null;
+
+	// Categorize the source changes
+	const categories = categorizeChangedFiles(significantFiles);
+	if (categories.length === 0) return null; // No categorizable changes, Last Change is enough
+
+	// RELEVANCE CHECK: Skip if changes are minor/not relevant enough
+	if (!areChangesRelevantForClaudeMd(categories)) {
+		return null; // Minor changes - Last Change only is acceptable
+	}
+
+	// Try to detect if only "Last Change" section was modified in CLAUDE.md
+	// Check git diff of CLAUDE.md (staged, unstaged, or last commit)
+	let claudeMdDiff = '';
+	const diffCommands = [
+		'git diff -- CLAUDE.md',
+		'git diff --cached -- CLAUDE.md',
+		'git diff HEAD~1 HEAD -- CLAUDE.md',
+	];
+
+	for (const cmd of diffCommands) {
+		try {
+			const result = execSync(cmd, {
+				cwd: PROJECT_DIR,
+				encoding: 'utf8',
+				stdio: ['pipe', 'pipe', 'pipe'],
+			}).trim();
+			if (result) {
+				claudeMdDiff = result;
+				break;
+			}
+		} catch {
+			continue;
+		}
+	}
+
+	if (!claudeMdDiff) return null; // Can't determine diff, skip this check
+
+	// Parse the diff to detect which sections were modified
+	const modifiedSections = parseClaudeMdDiffSections(claudeMdDiff);
+
+	// Check if ONLY "Last Change" was modified
+	const onlyLastChange =
+		modifiedSections.size > 0 &&
+		modifiedSections.size === 1 &&
+		modifiedSections.has('Last Change');
+
+	if (!onlyLastChange) return null; // Other sections were also modified, good
+
+	// Build specific guidance for what sections need updating
+	const totalFiles = categories.reduce((sum, c) => sum + c.files.length, 0);
+	const sectionGuidance = categories
+		.map((c) => {
+			const uniqueSections = [...new Set(c.sections)];
+			const fileExamples = c.files.slice(0, 3).join(', ');
+			return `  - ${c.category}: ${fileExamples}\n    → Must review/update: ${uniqueSections.join(', ')}`;
+		})
+		.join('\n');
+
+	return {
+		type: 'CLAUDE_MD_SHALLOW_UPDATE',
+		message: `CLAUDE.md was updated but ONLY "Last Change" was modified. ${categories.length} category(ies) with ${totalFiles} file(s) require updating additional rule/flow sections.`,
+		action: `
+================================================================================
+CLAUDE.MD SHALLOW UPDATE DETECTED - MUST UPDATE RELEVANT SECTIONS
+================================================================================
+
+You updated CLAUDE.md but ONLY modified the "Last Change" section.
+The changes are significant enough to require updating rule/flow sections.
+
+(Minor changes with < ${RELEVANCE_THRESHOLDS.minFilesChanged} files and < ${RELEVANCE_THRESHOLDS.minLinesChanged} lines are exempt from this check.)
+
+CHANGES DETECTED THAT REQUIRE SECTION UPDATES:
+
+${sectionGuidance}
+
+--------------------------------------------------------------------------------
+WHAT TO DO
+--------------------------------------------------------------------------------
+
+For EACH category above, review the corresponding CLAUDE.md section and:
+
+1. If a RULE changed (e.g., CRUD validation, auth flow):
+   → UPDATE the rule in its section (Critical Rules, Workflow, etc.)
+
+2. If an AESTHETIC/UI pattern changed (e.g., new component style):
+   → UPDATE UI Architecture, Design System, or Component Organization
+
+3. If a FLOW changed (e.g., new middleware, data fetching pattern):
+   → UPDATE Workflow, Architecture, or Next.js App Router Patterns
+
+4. If NOTHING changed in rules/flows (just implementation details):
+   → This should not happen for significant changes. Review again.
+
+RULE: "Last Change" documents WHAT was done.
+      Other sections document HOW things work NOW.
+      Both must be current for significant changes.
+
+The stop hook will BLOCK until relevant sections are also updated.
 ================================================================================`,
 	};
 }
 
+/**
+ * Parse a git diff of CLAUDE.md to determine which ## sections were modified.
+ * Returns a Set of section names that had actual content changes.
+ */
+function parseClaudeMdDiffSections(diff: string): Set<string> {
+	const modifiedSections = new Set<string>();
+	const lines = diff.split('\n');
+	let currentSection = '';
+
+	for (const line of lines) {
+		// Skip diff metadata
+		if (
+			line.startsWith('diff ') ||
+			line.startsWith('index ') ||
+			line.startsWith('--- ') ||
+			line.startsWith('+++ ')
+		) {
+			continue;
+		}
+
+		// Parse @@ hunk headers - they sometimes contain section context
+		const hunkMatch = line.match(/^@@ .+ @@\s*(## .+)?/);
+		if (hunkMatch && hunkMatch[1]) {
+			currentSection = hunkMatch[1].replace('## ', '').trim();
+			continue;
+		}
+		if (line.startsWith('@@')) continue;
+
+		// Detect section headers in changed or context lines
+		const sectionMatch = line.match(/^[+ -]?## (.+)/);
+		if (sectionMatch) {
+			currentSection = sectionMatch[1].trim();
+			// If the section header itself is a change, count it
+			if (line.startsWith('+') || line.startsWith('-')) {
+				modifiedSections.add(currentSection);
+			}
+			continue;
+		}
+
+		// Track actual content changes (+ or - lines, not context)
+		if (line.startsWith('+') || line.startsWith('-')) {
+			if (currentSection) {
+				modifiedSections.add(currentSection);
+			}
+		}
+	}
+
+	return modifiedSections;
+}
+
 function validateDocumentation(sourceFiles: string[]): ValidationError | null {
 	if (sourceFiles.length === 0) return null;
 
@@ -996,7 +1396,13 @@ Validate with: wc -m CLAUDE.md (must be < 40000)`,
 	},
 	CLAUDE_MD_NOT_UPDATED: {
 		agent: 'documenter',
-		prompt: 'Update CLAUDE.md Last Change section with current session summary',
+		prompt:
+			'Update CLAUDE.md: Last Change section AND all relevant rule/flow sections based on what files were changed (API rules, UI rules, workflow, architecture, etc.)',
+	},
+	CLAUDE_MD_SHALLOW_UPDATE: {
+		agent: 'documenter',
+		prompt:
+			'CLAUDE.md was updated but only Last Change was modified. Review changed source files, categorize them, and update the corresponding CLAUDE.md sections (Critical Rules, UI Architecture, Workflow, etc.) to reflect current rules and flows.',
 	},
 	SOURCE_FILES_NOT_DOCUMENTED: {
 		agent: 'documenter',
@@ -1087,11 +1493,15 @@ function collectAllErrors(
 	const updatedError = validateClaudeMdUpdated(modifiedFiles);
 	if (updatedError) errors.push(updatedError);
 
-	// 9. Source files must be documented
+	// 9. CLAUDE.md must have relevant sections updated (not just Last Change)
+	const contentDepthError = validateClaudeMdContentDepth(modifiedFiles);
+	if (contentDepthError) errors.push(contentDepthError);
+
+	// 11. Source files must be documented
 	const docError = validateDocumentation(sourceFiles);
 	if (docError) errors.push(docError);
 
-	// 10. Domain documentation must be complete
+	// 12. Domain documentation must be complete
 	const domainDocError = validateDomainDocumentation(modifiedFiles);
 	if (domainDocError) errors.push(domainDocError);
 

package/template/.claude/hooks/user-prompt-submit.ts

@@ -75,16 +75,21 @@ async function main(): Promise<void> {
 
 5. COMMIT using conventional commits via commit-manager agent.
 
-6. UPDATE CLAUDE.md BEFORE finishing (MANDATORY):
+6. UPDATE CLAUDE.md BEFORE finishing (MANDATORY - NOT JUST "Last Change"!):
    a. "## Last Change" section (date: ${today}, branch, summary). Keep only latest.
-   b. Architecture changes: Update Architecture section with new patterns, file locations.
-   c. Business rules: Add new rules to relevant sections (not just summary).
-   d. UI patterns: Document new components, design decisions, aesthetic rules.
-   e. Workflows: Update Workflow section if process changed.
-   f. Gotchas: Add to FORBIDDEN or NRY sections if discovered.
-   g. Config/Stack: Update if tooling changed.
-
-   CLAUDE.md is the SINGLE SOURCE OF TRUTH. Document everything that affects future sessions.
+   b. THEN update ALL sections affected by your changes:
+      - Changed API/CRUD rules? → Update "Critical Rules" or "HTTP Requests"
+      - Changed UI components/aesthetics? → Update "UI Architecture", "Design System", "Component Organization"
+      - Changed pages/layouts? → Update "Architecture" or "Next.js App Router Patterns"
+      - Changed auth/middleware? → Update "Critical Rules" or "Workflow"
+      - Changed config/stack? → Update "Stack" or "Configuration"
+      - Changed testing patterns? → Update "Quality Gates"
+      - Changed workflow/hooks? → Update "Workflow" or "Stop Hook Validations"
+      - New gotchas discovered? → Add to "FORBIDDEN" or "NRY"
+
+   RULE: "Last Change" = WHAT was done. Other sections = HOW things work NOW.
+   If you ONLY update Last Change, the stop-validator will BLOCK with CLAUDE_MD_SHALLOW_UPDATE.
+   CLAUDE.md is the SINGLE SOURCE OF TRUTH for ALL project rules and flows.
 
 7. RUN stop-validator before finishing: npx tsx .claude/hooks/stop-validator.ts`;