start-vibing 2.0.44 → 2.0.45

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "start-vibing",
-	"version": "2.0.44",
+	"version": "2.0.45",
 	"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,25 @@ 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 categorized source files changed, `CLAUDE_MD_SHALLOW_UPDATE` blocks completion.
+
 ---
 
 ## System Architecture
@@ -213,45 +233,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
+
+**Why:** Opus 4.6 does MORE upfront exploration than older models. Anti-laziness prompts cause runaway thinking.
+
+### Tool Use Patterns
+
+```text
+# Claude will only SUGGEST:
+"Can you suggest some changes?"
+
+# Claude will IMPLEMENT:
+"Change this function to improve performance."
+```
 
-### Interleaved Thinking
+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
 
-- 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
+```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):
 
-	// If no significant files modified, no need to check
+${lines.join('\n')}
+`;
+}
+
+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,193 @@ 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.
+================================================================================`,
+	};
+}
 
-3. If new patterns/rules were established:
-   Add to appropriate section
+/**
+ * NEW VALIDATION: Checks if CLAUDE.md was updated but only the "Last Change"
+ * section was modified (shallow update). When source files in categorized areas
+ * changed, CLAUDE.md sections beyond Last Change should also be updated.
+ *
+ * This catches the common pattern where Claude updates only "Last Change"
+ * but ignores updating the actual rules/flows that changed.
+ */
+function validateClaudeMdContentDepth(modifiedFiles: string[]): ValidationError | null {
+	const significantFiles = getSignificantFiles(modifiedFiles);
+	if (significantFiles.length === 0) return null;
 
-4. If user mentioned preferences or corrections:
-   Add as rules in relevant section
+	// 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
+
+	// 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',
+	];
 
-CONTEXT SYNTHESIS:
-Think about what the user asked and what you learned.
-Capture important decisions and patterns for the next session.
+	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 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} change category(ies) 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.
+This is NOT sufficient when source files that affect rules/flows were changed.
+
+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.)
 
-The stop hook will BLOCK until CLAUDE.md is updated.
+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):
+   → Add a comment in the relevant section noting the implementation
+
+EXAMPLES:
+  - Changed how users are fetched? → Update HTTP Requests section
+  - Changed button styles? → Update Design System section
+  - Added new page? → Update Architecture section
+  - Changed form validation? → Update Critical Rules section
+
+RULE: "Last Change" documents WHAT was done.
+      Other sections document HOW things work NOW.
+      Both must be current.
+
+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 +1274,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 +1371,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`;