claude-smith 3.2.0 → 3.4.0

package/README.ko.md

@@ -142,6 +142,7 @@ Claude Code 세션
 | `/smith-report` | 상세 규정 준수 리포트 |
 | `/smith-check` | 설치 검증 |
 | `/smith-plan` | 분해 계획 템플릿 생성 |
+| `/smith-decompose` | 복잡한 작업을 위한 5단계 가이드 분해 |
 | `/smith-update` | 버전 체크 + 업그레이드 |
 
 ## 명령어

package/README.md

@@ -142,6 +142,7 @@ After installation, these commands are available in Claude Code:
 | `/smith-report` | Detailed compliance report |
 | `/smith-check` | Validate installation |
 | `/smith-plan` | Generate decomposition plan template |
+| `/smith-decompose` | Guided 5-step problem decomposition for complex tasks |
 | `/smith-update` | Check for updates and upgrade |
 
 ## Commands

package/bin/cli.mjs

@@ -403,14 +403,14 @@ function check() {
 
   // Check commands
   const commandsDir = join(cwd, '.claude', 'commands');
-  const expectedCommands = ['smith.md', 'smith-report.md', 'smith-check.md', 'smith-plan.md'];
+  const expectedCommands = ['smith.md', 'smith-report.md', 'smith-check.md', 'smith-plan.md', 'smith-decompose.md'];
   const missingCommands = expectedCommands.filter(c => !existsSync(join(commandsDir, c)));
-  results.commands = { installed: 4 - missingCommands.length, total: 4, missing: missingCommands };
+  results.commands = { installed: 5 - missingCommands.length, total: 5, missing: missingCommands };
 
   if (!ciMode) {
     console.log(missingCommands.length === 0
-      ? `✅ Commands: 4/4 installed`
-      : `❌ Commands: ${4 - missingCommands.length}/4 (missing: ${missingCommands.join(', ')})`);
+      ? `✅ Commands: 5/5 installed`
+      : `❌ Commands: ${5 - missingCommands.length}/5 (missing: ${missingCommands.join(', ')})`);
   }
   if (missingCommands.length > 0) results.ok = false;
 

package/hooks/batch-checkpoint.mjs

@@ -11,7 +11,7 @@ import { tmpdir } from 'os';
 import { getHookConfig } from '../lib/config.mjs';
 import { recordEvent } from '../lib/stats.mjs';
 import { appendEvent } from '../lib/event-log.mjs';
-import { sanitizeId, parseHookInput, isOmcAutoMode, notifyUser } from '../lib/hook-utils.mjs';
+import { sanitizeId, parseHookInput, isOmcAutoMode, notifyUser, writeHookOutput } from '../lib/hook-utils.mjs';
 
 const config = getHookConfig('batch-checkpoint', process.cwd());
 if (!config.enabled) process.exit(0);
@@ -57,12 +57,6 @@ if (!editedFiles.includes(filePath)) {
 if (editedFiles.length > 0 && editedFiles.length % config.fileThreshold === 0) {
   recordEvent(sessionId, 'batch-checkpoint', 'warn');
   appendEvent(process.cwd(), { hook: 'batch-checkpoint', event: 'warn', message: `${editedFiles.length} files edited` });
-  notifyUser(config.notify, 'Batch Checkpoint', 'warn', `${editedFiles.length}개 파일 편집`);
-  const output = JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: "PostToolUse",
-      additionalContext: `🕵️ Smith 📋 Batch Checkpoint (rule 2-9): ${editedFiles.length} files edited. Report progress to user before continuing.`
-    }
-  });
-  process.stdout.write(output);
+  const notify = notifyUser(config.notify, 'Batch Checkpoint', 'warn', `${editedFiles.length}개 파일 편집`);
+  writeHookOutput('PostToolUse', [notify, `🕵️ Smith 📋 Batch Checkpoint (rule 2-9): ${editedFiles.length} files edited. Report progress to user before continuing.`].filter(Boolean).join('\n'));
 }

package/hooks/build-guard.mjs

@@ -36,8 +36,8 @@ if (existsSync(lastBuildResult)) {
   if (result === 'fail') {
     recordEvent(sessionId, 'build-guard', 'block');
     appendEvent(process.cwd(), { hook: 'build-guard', event: 'block', message: 'Build failing' });
-    notifyUser(config.notify, 'Build Guard', 'block', '빌드 실패 — 커밋 차단');
-    process.stderr.write("🕵️ Smith ✋ Commit blocked: last build FAILED. Run build and fix errors before committing.");
+    const notify = notifyUser(config.notify, 'Build Guard', 'block', '빌드 실패 — 커밋 차단');
+    process.stderr.write([notify, "🕵️ Smith ✋ Commit blocked: last build FAILED. Run build and fix errors before committing."].filter(Boolean).join('\n'));
     process.exit(2);
   }
 }

package/hooks/build-tracker.mjs

@@ -11,7 +11,7 @@ import { tmpdir } from 'os';
 import { getHookConfig } from '../lib/config.mjs';
 import { recordEvent } from '../lib/stats.mjs';
 import { appendEvent } from '../lib/event-log.mjs';
-import { sanitizeId, parseHookInput, notifyUser } from '../lib/hook-utils.mjs';
+import { sanitizeId, parseHookInput, notifyUser, writeHookOutput } from '../lib/hook-utils.mjs';
 
 const config = getHookConfig('build-tracker', process.cwd());
 if (!config.enabled) process.exit(0);
@@ -36,5 +36,6 @@ if (/pnpm build|npm run build|yarn build|tsc|next build/.test(command)) {
   writeFileSync(join(stateDir, 'last-build-result'), result, { mode: 0o600 });
   recordEvent(sessionId, 'build-tracker', 'fire');
   appendEvent(process.cwd(), { hook: 'build-tracker', event: 'fire', message: result });
-  notifyUser(config.notify, 'Build Tracker', 'track', failed ? '❌ fail' : '✅ pass');
+  const notify = notifyUser(config.notify, 'Build Tracker', 'track', failed ? '❌ fail' : '✅ pass');
+  if (notify) writeHookOutput('PostToolUse', notify);
 }

package/hooks/commit-guard.mjs

@@ -13,7 +13,7 @@ import { tmpdir } from 'os';
 import { getHookConfig } from '../lib/config.mjs';
 import { recordEvent } from '../lib/stats.mjs';
 import { appendEvent } from '../lib/event-log.mjs';
-import { sanitizeId, parseHookInput, notifyUser } from '../lib/hook-utils.mjs';
+import { sanitizeId, parseHookInput, notifyUser, writeHookOutput } from '../lib/hook-utils.mjs';
 
 const config = getHookConfig('commit-guard', process.cwd());
 if (!config.enabled) process.exit(0);
@@ -41,8 +41,8 @@ if (existsSync(lastResultFile)) {
   if (result === 'fail') {
     recordEvent(sessionId, 'commit-guard', 'block');
     appendEvent(process.cwd(), { hook: 'commit-guard', event: 'block', message: 'Tests failing' });
-    notifyUser(config.notify, 'Commit Guard', 'block', '테스트 실패 — 커밋 차단');
-    process.stderr.write("🕵️ Smith ✋ Commit blocked: last test run FAILED. Run your test suite and fix failures before committing.\n💡 Coaching: 1) Run your test suite. 2) Fix failing tests one at a time. 3) Verify all pass. 4) Then commit.");
+    const notifyBlock = notifyUser(config.notify, 'Commit Guard', 'block', '테스트 실패 — 커밋 차단');
+    process.stderr.write([notifyBlock, "🕵️ Smith ✋ Commit blocked: last test run FAILED. Run your test suite and fix failures before committing.\n💡 Coaching: 1) Run your test suite. 2) Fix failing tests one at a time. 3) Verify all pass. 4) Then commit."].filter(Boolean).join('\n'));
     process.exit(2);
   }
 }
@@ -55,31 +55,20 @@ if (existsSync(lastTestFile)) {
   if (diff > config.maxTestAge) {
     recordEvent(sessionId, 'commit-guard', 'warn');
     appendEvent(process.cwd(), { hook: 'commit-guard', event: 'warn', message: 'Tests stale' });
-    notifyUser(config.notify, 'Commit Guard', 'warn', '테스트 경과 시간 초과');
-    const output = JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: "PreToolUse",
-        additionalContext: `🕵️ Smith > Commit Guard: Last test run was ${Math.floor(diff / 60)}min ago (>5min). Run tests before committing.`
-      }
-    });
-    process.stdout.write(output);
+    const notifyStale = notifyUser(config.notify, 'Commit Guard', 'warn', '테스트 경과 시간 초과');
+    writeHookOutput('PreToolUse', [notifyStale, `🕵️ Smith > Commit Guard: Last test run was ${Math.floor(diff / 60)}min ago (>5min). Run tests before committing.`].filter(Boolean).join('\n'));
     process.exit(0);
   }
 } else {
   recordEvent(sessionId, 'commit-guard', 'warn');
   appendEvent(process.cwd(), { hook: 'commit-guard', event: 'warn', message: 'No test run detected' });
-  notifyUser(config.notify, 'Commit Guard', 'warn', '테스트 실행 기록 없음');
-  const output = JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: "PreToolUse",
-      additionalContext: "🕵️ Smith > Commit Guard: No test run detected this session. Consider running tests before committing.\n💡 Coaching: Run your test suite to verify nothing is broken. Even a quick smoke test prevents broken commits."
-    }
-  });
-  process.stdout.write(output);
+  const notifyNoTest = notifyUser(config.notify, 'Commit Guard', 'warn', '테스트 실행 기록 없음');
+  writeHookOutput('PreToolUse', [notifyNoTest, "🕵️ Smith > Commit Guard: No test run detected this session. Consider running tests before committing.\n💡 Coaching: Run your test suite to verify nothing is broken. Even a quick smoke test prevents broken commits."].filter(Boolean).join('\n'));
   process.exit(0);
 }
 
 // All checks passed - commit allowed
 recordEvent(sessionId, 'commit-guard', 'fire');
 appendEvent(process.cwd(), { hook: 'commit-guard', event: 'fire', message: 'Commit allowed' });
-notifyUser(config.notify, 'Commit Guard', 'fire', '커밋 허용');
+const notify = notifyUser(config.notify, 'Commit Guard', 'fire', '커밋 허용');
+if (notify) writeHookOutput('PreToolUse', notify);

package/hooks/commit-message.mjs

@@ -8,7 +8,7 @@
 import { getHookConfig } from '../lib/config.mjs';
 import { recordEvent } from '../lib/stats.mjs';
 import { appendEvent } from '../lib/event-log.mjs';
-import { sanitizeId, parseHookInput, notifyUser } from '../lib/hook-utils.mjs';
+import { sanitizeId, parseHookInput, notifyUser, writeHookOutput } from '../lib/hook-utils.mjs';
 
 const config = getHookConfig('commit-message', process.cwd());
 if (!config.enabled) process.exit(0);
@@ -39,17 +39,12 @@ const pattern = /^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)
 if (!pattern.test(firstLine)) {
   recordEvent(sessionId, 'commit-message', 'warn');
   appendEvent(process.cwd(), { hook: 'commit-message', event: 'warn', message: `Non-conventional: ${firstLine.slice(0, 50)}` });
-  notifyUser(config.notify, 'Commit Message', 'warn', `비표준 형식: ${firstLine.slice(0, 40)}`);
-  const output = JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: "PreToolUse",
-      additionalContext: `🕵️ Smith > Commit Message: "${firstLine}" doesn't follow conventional commits. Expected: type(scope): description (e.g., feat(auth): add login, fix: resolve crash)`
-    }
-  });
-  process.stdout.write(output);
+  const notifyWarn = notifyUser(config.notify, 'Commit Message', 'warn', `비표준 형식: ${firstLine.slice(0, 40)}`);
+  writeHookOutput('PreToolUse', [notifyWarn, `🕵️ Smith > Commit Message: "${firstLine}" doesn't follow conventional commits. Expected: type(scope): description (e.g., feat(auth): add login, fix: resolve crash)`].filter(Boolean).join('\n'));
 } else {
   // Format is valid
   recordEvent(sessionId, 'commit-message', 'fire');
   appendEvent(process.cwd(), { hook: 'commit-message', event: 'fire', message: 'Format valid' });
-  notifyUser(config.notify, 'Commit Message', 'fire', '형식 유효');
+  const notify = notifyUser(config.notify, 'Commit Message', 'fire', '형식 유효');
+  if (notify) writeHookOutput('PreToolUse', notify);
 }

package/hooks/debug-loop.mjs

@@ -12,7 +12,7 @@ import { createHash } from 'crypto';
 import { getHookConfig } from '../lib/config.mjs';
 import { recordEvent } from '../lib/stats.mjs';
 import { appendEvent } from '../lib/event-log.mjs';
-import { sanitizeId, parseHookInput, isOmcAutoMode, notifyUser } from '../lib/hook-utils.mjs';
+import { sanitizeId, parseHookInput, isOmcAutoMode, notifyUser, writeHookOutput } from '../lib/hook-utils.mjs';
 
 const config = getHookConfig('debug-loop', process.cwd());
 if (!config.enabled) process.exit(0);
@@ -86,18 +86,12 @@ const patternHint = pattern === 'divergent'
 if (count === config.warnAt) {
   recordEvent(sessionId, 'debug-loop', 'warn');
   appendEvent(process.cwd(), { hook: 'debug-loop', event: 'warn', file: filePath, message: `Edit #${count}${patternHint ? ' ' + patternHint : ''}` });
-  notifyUser(config.notify, 'Debug Loop', 'warn', `${name} ${count}회 편집${pattern === 'divergent' ? ' (반복 패턴)' : ''}`);
-  const output = JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: "PostToolUse",
-      additionalContext: `🕵️ Smith > Debug Loop: ${name} edited ${config.warnAt} times.${patternHint}\n💡 Coaching: 1) STOP editing. Read the error message carefully. 2) Add logging to trace data flow. 3) Check recent git changes: git diff HEAD~3. 4) Find a working similar pattern and compare. 5) Form a hypothesis before making the next edit.`
-    }
-  });
-  process.stdout.write(output);
+  const notify = notifyUser(config.notify, 'Debug Loop', 'warn', `${name} ${count}회 편집${pattern === 'divergent' ? ' (반복 패턴)' : ''}`);
+  writeHookOutput('PostToolUse', [notify, `🕵️ Smith > Debug Loop: ${name} edited ${config.warnAt} times.${patternHint}\n💡 Coaching: 1) STOP editing. Read the error message carefully. 2) Add logging to trace data flow. 3) Check recent git changes: git diff HEAD~3. 4) Find a working similar pattern and compare. 5) Form a hypothesis before making the next edit.`].filter(Boolean).join('\n'));
 } else if (count >= config.blockAt) {
   recordEvent(sessionId, 'debug-loop', 'block');
   appendEvent(process.cwd(), { hook: 'debug-loop', event: 'block', file: filePath, message: `Edit #${count} - blocked` });
-  notifyUser(config.notify, 'Debug Loop', 'block', `${name} ${count}회 편집 — 차단`);
-  process.stderr.write(`🕵️ Smith ✋ Debug Loop blocked: ${name} edited ${count} times.${patternHint}\nPer rule 2-6: 3+ failed fixes → question architecture. Discuss with user before continuing.`);
+  const notify = notifyUser(config.notify, 'Debug Loop', 'block', `${name} ${count}회 편집 — 차단`);
+  process.stderr.write([notify, `🕵️ Smith ✋ Debug Loop blocked: ${name} edited ${count} times.${patternHint}\nPer rule 2-6: 3+ failed fixes → question architecture. Discuss with user before continuing.`].filter(Boolean).join('\n'));
   process.exit(2);
 }

package/hooks/file-size-warn.mjs

@@ -10,7 +10,7 @@ import { basename } from 'path';
 import { getHookConfig } from '../lib/config.mjs';
 import { recordEvent } from '../lib/stats.mjs';
 import { appendEvent } from '../lib/event-log.mjs';
-import { sanitizeId, parseHookInput, notifyUser } from '../lib/hook-utils.mjs';
+import { sanitizeId, parseHookInput, notifyUser, writeHookOutput } from '../lib/hook-utils.mjs';
 
 const config = getHookConfig('file-size-warn', process.cwd());
 if (!config.enabled) process.exit(0);
@@ -36,12 +36,6 @@ const threshold = config.maxLines || 500;
 if (lines > threshold) {
   recordEvent(sessionId, 'file-size-warn', 'warn');
   appendEvent(process.cwd(), { hook: 'file-size-warn', event: 'warn', file: filePath, message: `${lines} lines` });
-  notifyUser(config.notify, 'File Size', 'warn', `${basename(filePath)} ${lines}줄 (>${threshold})`);
-  const output = JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: "PostToolUse",
-      additionalContext: `🕵️ Smith > File Size: ${basename(filePath)} has ${lines} lines (>${threshold}). Consider splitting into smaller modules.`
-    }
-  });
-  process.stdout.write(output);
+  const notify = notifyUser(config.notify, 'File Size', 'warn', `${basename(filePath)} ${lines}줄 (>${threshold})`);
+  writeHookOutput('PostToolUse', [notify, `🕵️ Smith > File Size: ${basename(filePath)} has ${lines} lines (>${threshold}). Consider splitting into smaller modules.`].filter(Boolean).join('\n'));
 }

package/hooks/plan-guard.mjs

@@ -13,7 +13,7 @@ import { tmpdir } from 'os';
 import { getHookConfig } from '../lib/config.mjs';
 import { recordEvent } from '../lib/stats.mjs';
 import { appendEvent } from '../lib/event-log.mjs';
-import { sanitizeId, parseHookInput, isOmcAutoMode, notifyUser } from '../lib/hook-utils.mjs';
+import { sanitizeId, parseHookInput, isOmcAutoMode, notifyUser, writeHookOutput } from '../lib/hook-utils.mjs';
 
 const config = getHookConfig('plan-guard', process.cwd());
 if (!config.enabled) process.exit(0);
@@ -88,12 +88,18 @@ const isOmc = isOmcAutoMode(process.cwd());
 const warnAt = isOmc ? (config.warnAt || 5) * 2 : (config.warnAt || 5);
 const blockAt = isOmc ? (config.blockAt || 10) * 2 : (config.blockAt || 10);
 
+// Early suggestion on first code edit (gentle, non-blocking)
+if (count === 1) {
+  const notify = notifyUser(config.notify, 'Plan Guard', 'warn', '첫 코드 편집 — 복잡한 작업이면 /smith-decompose 먼저');
+  writeHookOutput('PreToolUse', [notify, `🕵️ Smith > Plan Guard: First code file edit detected without a plan. If this is a complex or abstract task, consider running /smith-decompose first to break it down into verifiable units.\n💡 Simple task? Ignore this and continue. Complex task? Decompose first, implement second.`].filter(Boolean).join('\n'));
+}
+
 // Block if threshold reached
 if (count >= blockAt) {
   recordEvent(sessionId, 'plan-guard', 'block');
   appendEvent(process.cwd(), { hook: 'plan-guard', event: 'block', message: `${count} files without plan` });
-  notifyUser(config.notify, 'Plan Guard', 'block', `${count}개 파일 계획 없이 편집 — 차단`);
-  process.stderr.write(`🕵️ Smith ✋ Plan Guard: ${count} code files edited without a decomposition plan. Create a plan first.`);
+  const notify = notifyUser(config.notify, 'Plan Guard', 'block', `${count}개 파일 계획 없이 편집 — 차단`);
+  process.stderr.write([notify, `🕵️ Smith ✋ Plan Guard: ${count} code files edited without a decomposition plan. Create a plan first.`].filter(Boolean).join('\n'));
   process.exit(2);
 }
 
@@ -101,17 +107,11 @@ if (count >= blockAt) {
 if (count >= warnAt) {
   recordEvent(sessionId, 'plan-guard', 'warn');
   appendEvent(process.cwd(), { hook: 'plan-guard', event: 'warn', message: `${count} files without plan` });
-  notifyUser(config.notify, 'Plan Guard', 'warn', `${count}개 파일 계획 없이 편집`);
-  const output = JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: "PreToolUse",
-      additionalContext: `🕵️ Smith > Plan Guard: ${count} code files edited without a plan. Complex work needs decomposition first.
+  const notify = notifyUser(config.notify, 'Plan Guard', 'warn', `${count}개 파일 계획 없이 편집`);
+  writeHookOutput('PreToolUse', [notify, `🕵️ Smith > Plan Guard: ${count} code files edited without a plan. Complex work needs decomposition first.
 💡 Create a plan file (docs/plans/*.md or plan.md) that includes:
 1. Each unit's responsibility (one sentence)
 2. Dependency direction between units
 3. Implementation order and rationale
-4. Verification method for each unit`
-    }
-  });
-  process.stdout.write(output);
+4. Verification method for each unit`].filter(Boolean).join('\n'));
 }

package/hooks/scope-guard.mjs

@@ -11,7 +11,7 @@ import { tmpdir } from 'os';
 import { getHookConfig } from '../lib/config.mjs';
 import { recordEvent } from '../lib/stats.mjs';
 import { appendEvent } from '../lib/event-log.mjs';
-import { sanitizeId, parseHookInput, isOmcAutoMode, notifyUser } from '../lib/hook-utils.mjs';
+import { sanitizeId, parseHookInput, isOmcAutoMode, notifyUser, writeHookOutput } from '../lib/hook-utils.mjs';
 
 const config = getHookConfig('scope-guard', process.cwd());
 if (!config.enabled) process.exit(0);
@@ -55,12 +55,6 @@ const threshold = isOmcAutoMode(process.cwd()) ? Math.max((config.maxDirectories
 if (dirs.length >= threshold && (dirs.length === threshold || dirs.length % threshold === 0)) {
   recordEvent(sessionId, 'scope-guard', 'warn');
   appendEvent(process.cwd(), { hook: 'scope-guard', event: 'warn', message: `${dirs.length} directories` });
-  notifyUser(config.notify, 'Scope Guard', 'warn', `${dirs.length}개 디렉토리 변경`);
-  const output = JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: "PostToolUse",
-      additionalContext: `🕵️ Smith > Scope Guard: Changes span ${dirs.length} directories (>=${threshold}). Is the scope too broad? Consider breaking into smaller tasks.`
-    }
-  });
-  process.stdout.write(output);
+  const notify = notifyUser(config.notify, 'Scope Guard', 'warn', `${dirs.length}개 디렉토리 변경`);
+  writeHookOutput('PostToolUse', [notify, `🕵️ Smith > Scope Guard: Changes span ${dirs.length} directories (>=${threshold}). Is the scope too broad? Consider breaking into smaller tasks.`].filter(Boolean).join('\n'));
 }

package/hooks/subagent-inject.mjs

@@ -8,7 +8,7 @@
 import { getHookConfig } from '../lib/config.mjs';
 import { recordEvent } from '../lib/stats.mjs';
 import { appendEvent } from '../lib/event-log.mjs';
-import { sanitizeId, parseHookInput, notifyUser } from '../lib/hook-utils.mjs';
+import { sanitizeId, parseHookInput, notifyUser, writeHookOutput } from '../lib/hook-utils.mjs';
 
 const config = getHookConfig('subagent-inject', process.cwd());
 if (!config.enabled) process.exit(0);
@@ -21,11 +21,5 @@ const sessionId = sanitizeId(input.session_id);
 
 recordEvent(sessionId, 'subagent-inject', 'fire');
 appendEvent(process.cwd(), { hook: 'subagent-inject', event: 'fire', message: 'Rules injected into subagent' });
-notifyUser(config.notify, 'Subagent Inject', 'inject', '규칙 주입됨');
-const output = JSON.stringify({
-  hookSpecificOutput: {
-    hookEventName: "SubagentStart",
-    additionalContext: "🔨 SMITH ENFORCEMENT: TDD Iron Law - write failing test BEFORE code. Run tests BEFORE commit. Never claim completion without fresh test evidence. Systematic debugging: 3+ failed fixes on same file → stop and question architecture."
-  }
-});
-process.stdout.write(output);
+const notify = notifyUser(config.notify, 'Subagent Inject', 'inject', '규칙 주입됨');
+writeHookOutput('SubagentStart', [notify, '🔨 SMITH ENFORCEMENT: TDD Iron Law - write failing test BEFORE code. Run tests BEFORE commit. Never claim completion without fresh test evidence. Systematic debugging: 3+ failed fixes on same file → stop and question architecture.'].filter(Boolean).join('\n'));

package/hooks/tdd-guard.mjs

@@ -10,7 +10,7 @@ import { dirname, basename, join, extname } from 'path';
 import { getHookConfig } from '../lib/config.mjs';
 import { recordEvent } from '../lib/stats.mjs';
 import { appendEvent } from '../lib/event-log.mjs';
-import { sanitizeId, parseHookInput, notifyUser } from '../lib/hook-utils.mjs';
+import { sanitizeId, parseHookInput, notifyUser, writeHookOutput } from '../lib/hook-utils.mjs';
 
 const config = getHookConfig('tdd-guard', process.cwd());
 if (!config.enabled) process.exit(0);
@@ -53,12 +53,6 @@ const testFileTs = join(dir, `${name}.test.ts`);
 if (!existsSync(testFile) && !existsSync(specFile) && !existsSync(testFileTsx) && !existsSync(testFileTs)) {
   recordEvent(sessionId, 'tdd-guard', 'warn');
   appendEvent(process.cwd(), { hook: 'tdd-guard', event: 'warn', file: filePath, message: `No test file for ${basename(filePath)}` });
-  notifyUser(config.notify, 'TDD Guard', 'warn', `${basename(filePath)} 테스트 파일 없음`);
-  const output = JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: "PreToolUse",
-      additionalContext: `🕵️ Smith > TDD Guard: ${basename(filePath)} has no test file (${name}.test${ext}). TDD Iron Law: write failing test FIRST.\n💡 Coaching: 1) Create ${name}.test${ext} in the same directory. 2) Write a test that describes expected behavior. 3) Run the test to confirm it fails. 4) Then implement the code.`
-    }
-  });
-  process.stdout.write(output);
+  const notify = notifyUser(config.notify, 'TDD Guard', 'warn', `${basename(filePath)} 테스트 파일 없음`);
+  writeHookOutput('PreToolUse', [notify, `🕵️ Smith > TDD Guard: ${basename(filePath)} has no test file (${name}.test${ext}). TDD Iron Law: write failing test FIRST.\n💡 Coaching: 1) Create ${name}.test${ext} in the same directory. 2) Write a test that describes expected behavior. 3) Run the test to confirm it fails. 4) Then implement the code.`].filter(Boolean).join('\n'));
 }

package/hooks/test-tracker.mjs

@@ -11,7 +11,7 @@ import { tmpdir } from 'os';
 import { getHookConfig } from '../lib/config.mjs';
 import { recordEvent } from '../lib/stats.mjs';
 import { appendEvent } from '../lib/event-log.mjs';
-import { sanitizeId, parseHookInput, notifyUser } from '../lib/hook-utils.mjs';
+import { sanitizeId, parseHookInput, notifyUser, writeHookOutput } from '../lib/hook-utils.mjs';
 
 const config = getHookConfig('test-tracker', process.cwd());
 if (!config.enabled) process.exit(0);
@@ -42,7 +42,7 @@ if (/pnpm test|npm test|yarn test|bun test|vitest|jest|pytest|go test|cargo test
   writeFileSync(join(stateDir, 'last-test-result'), failed ? 'fail' : 'pass', { mode: 0o600 });
   recordEvent(sessionId, 'test-tracker', 'fire');
   appendEvent(process.cwd(), { hook: 'test-tracker', event: 'fire', message: `${failed ? 'fail' : 'pass'}` });
-  notifyUser(config.notify, 'Test Tracker', 'track', failed ? '❌ fail' : '✅ pass');
+  const notify = notifyUser(config.notify, 'Test Tracker', 'track', failed ? '❌ fail' : '✅ pass');
 
   // Extract coverage percentage from test output
   function parseCoverage(text) {
@@ -60,6 +60,7 @@ if (/pnpm test|npm test|yarn test|bun test|vitest|jest|pytest|go test|cargo test
     return null;
   }
 
+  let coverageMsg = '';
   const coverage = parseCoverage(response);
   if (coverage !== null) {
     const covFile = join(stateDir, 'last-coverage');
@@ -72,13 +73,11 @@ if (/pnpm test|npm test|yarn test|bun test|vitest|jest|pytest|go test|cargo test
     if (prevCoverage !== null && coverage < prevCoverage) {
       const delta = (coverage - prevCoverage).toFixed(1);
       appendEvent(process.cwd(), { hook: 'test-tracker', event: 'warn', message: `Coverage: ${prevCoverage}% → ${coverage}%` });
-      const output = JSON.stringify({
-        hookSpecificOutput: {
-          hookEventName: "PostToolUse",
-          additionalContext: `🕵️ Smith 📊 Coverage Delta: ${prevCoverage}% → ${coverage}% (${delta}%). Test coverage decreased.\n💡 Coaching: 1) Check which lines lost coverage. 2) Add tests for uncovered paths. 3) Run coverage report: your-test-cmd --coverage`
-        }
-      });
-      process.stdout.write(output);
+      coverageMsg = `🕵️ Smith 📊 Coverage Delta: ${prevCoverage}% → ${coverage}% (${delta}%). Test coverage decreased.\n💡 Coaching: 1) Check which lines lost coverage. 2) Add tests for uncovered paths. 3) Run coverage report: your-test-cmd --coverage`;
     }
   }
+
+  // Single stdout write combining notify + coverage (if any)
+  const combined = [notify, coverageMsg].filter(Boolean).join('\n');
+  if (combined) writeHookOutput('PostToolUse', combined);
 }

package/lib/config.mjs

@@ -9,7 +9,7 @@ import { join } from 'path';
 const DEFAULTS = {
   language: 'en',
   omcCompat: false,
-  notify: false,
+  notify: true,
   hooks: {
     'tdd-guard': { enabled: true },
     'commit-guard': { enabled: true, maxTestAge: 300 },

package/lib/hook-utils.mjs

@@ -48,15 +48,17 @@ export function parseHookInput() {
 }
 
 /**
- * Send a brief notification to stderr for user visibility
+ * Build a brief notification string for user visibility
  * Only active when notify: true in .claude-smith.json
+ * Returns formatted string (empty string if notify is disabled)
  * @param {boolean} notify - Whether notifications are enabled
  * @param {string} hookName - Display name of the hook
  * @param {string} eventType - fire|warn|block|inject|track
  * @param {string} message - Brief description
+ * @returns {string} Formatted notification or empty string
  */
 export function notifyUser(notify, hookName, eventType, message) {
-  if (!notify) return;
+  if (!notify) return '';
   const icons = {
     fire: '✅',
     warn: '⚠️',
@@ -65,5 +67,16 @@ export function notifyUser(notify, hookName, eventType, message) {
     track: '📊'
   };
   const icon = icons[eventType] || '📝';
-  process.stderr.write(`🕵️ Smith — ${icon} ${hookName}: ${message}\n`);
+  return `🕵️ Smith — ${icon} ${hookName}: ${message}`;
+}
+
+/**
+ * Write hook output to stdout as JSON (additionalContext)
+ * @param {string} hookEventName - e.g. "PreToolUse", "PostToolUse", "SubagentStart"
+ * @param {string} additionalContext - Message to inject into conversation
+ */
+export function writeHookOutput(hookEventName, additionalContext) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: { hookEventName, additionalContext }
+  }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-smith",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Claude Code workflow enforcement CLI - forging coding discipline into every session",
   "type": "module",
   "scripts": {

package/templates/commands/smith-decompose.md

@@ -0,0 +1,63 @@
+Decompose a complex or abstract request into verifiable work units.
+
+Follow this 5-step framework strictly. Do NOT skip steps or jump to implementation.
+
+## Step 1: Essence Extraction
+
+Ask yourself: **"What is the user actually trying to achieve?"**
+
+- Strip away implementation details and restate the core problem in one sentence
+- Identify the success criteria: "How will we know this is done?"
+- Output: `Core Problem: ...` and `Success Criteria: ...`
+
+## Step 2: Uncertainty Map
+
+List what you DON'T know. Be honest about assumptions.
+
+| What I Know | What I Assume | What I Don't Know |
+|-------------|---------------|-------------------|
+| (facts)     | (guesses)     | (unknowns)        |
+
+Every item in "Assume" and "Don't Know" is a candidate for a user question.
+
+## Step 3: Clarifying Questions
+
+Use the AskUserQuestion tool to ask 1-2 targeted questions based on Step 2.
+
+Rules:
+- Ask about the MOST impactful unknowns only (not everything)
+- Provide 2-3 concrete options per question with trade-offs
+- Include your recommendation
+- WAIT for user answers before proceeding to Step 4
+
+## Step 4: Unit Decomposition
+
+Break the work into independently verifiable units:
+
+For each unit:
+- **Name**: Short descriptive name
+- **Responsibility**: One sentence (if it needs two, split the unit)
+- **Inputs/Outputs**: What it receives, what it produces
+- **Verification**: Specific test or check that proves it works
+- **Files**: Create/modify/test file paths
+
+Quality checks:
+- Each unit has exactly ONE responsibility
+- Dependencies are unidirectional (no cycles)
+- Removing any unit doesn't break the others
+- Each unit can be verified in isolation
+
+## Step 5: Plan File Generation
+
+Generate `docs/plans/YYYY-MM-DD-<topic>.md` (or `plan.md`) with:
+
+1. Goal (from Step 1)
+2. Decisions (from Step 3 answers)
+3. Unit list with dependency graph
+4. Implementation order (leaf-first: fewest dependencies first)
+5. Per-unit tasks at 2-5 minute granularity
+
+After generating the plan, report to the user:
+- How many units and tasks were created
+- Estimated implementation order
+- Which unit to start with and why