claude-smith 3.0.0 → 3.2.0

package/README.ko.md

@@ -1,8 +1,8 @@
 [English](README.md) | **한국어**
 
-# 🔨 claude-smith
+# 🕵️ claude-smith
 
-> **Claude Code의 ESLint** — AI 코딩 세션에 물리적 강제를 더합니다.
+> **코드의 조용한 수호자** — AI 코딩 세션의 물리적 규율 강제
 
 ## 문제
 
@@ -39,6 +39,24 @@ npx claude-smith init
 
 언어를 선택하면(en/ko/zh/ja) 끝. 12개 Hook 설치, 규칙 주입, 강제 활성화.
 
+## 실시간 알림
+
+Claude Code 세션 중 Hook 활동을 실시간으로 확인하세요:
+
+```json
+{ "notify": true }
+```
+
+활성화하면 터미널에서 간략한 상태 메시지를 볼 수 있습니다:
+```
+🕵️ Smith — ⚠️ TDD Guard: LoginForm.tsx 테스트 파일 없음
+🕵️ Smith — ✅ Commit Guard: 커밋 허용
+🕵️ Smith — 🚫 Debug Loop: app.tsx 5회 편집 차단
+🕵️ Smith — 🤖 Subagent Inject: 규칙 주입됨
+```
+
+`"notify": false` (기본값)로 설정하면 비활성화됩니다.
+
 ## 12개 Hook
 
 ### 차단하는 Hook (exit code 2 — 진행 자체를 막음)
@@ -148,6 +166,7 @@ claude-smith uninstall             # 모든 구성 요소 제거
 ```json
 {
   "language": "ko",
+  "notify": false,
   "hooks": {
     "commit-guard": { "maxTestAge": 300 },
     "debug-loop": { "warnAt": 3, "blockAt": 5 },
@@ -187,13 +206,36 @@ claude-smith uninstall             # 모든 구성 요소 제거
 - **안전한 권한**: 디렉터리 `0o700`, 파일 `0o600`
 - **경쟁 조건 방지**: Hook별 원자적 카운터 (공유 JSON 미사용)
 - **제로 의존성**: Node.js 기본 모듈만 사용
-- **63개 테스트**: 보안 엣지 케이스, 에러 처리, 크로스 플랫폼 시나리오
+- **포괄적 테스트 스위트**: 보안 엣지 케이스, 에러 처리, 크로스 플랫폼 시나리오
 
 ## 요구 사항
 
 - Node.js >= 18
 - Hook을 지원하는 Claude Code (`.claude/settings.json`)
 
+## 문제 해결
+
+### Hook이 작동하지 않음
+1. 설치 검증: `claude-smith check`
+2. `.claude/settings.json`에 Hook 정의가 있는지 확인
+3. Node.js >= 18 확인: `node --version`
+
+### 병렬 에이전트에서 오탐 발생
+`.claude-smith.json`에서 OMC 호환 모드 활성화:
+```json
+{ "omcCompat": true }
+```
+debug-loop, batch-checkpoint, scope-guard, plan-guard 임계값이 상향됩니다.
+
+### 테스트가 "실행 안 됨"으로 표시됨
+test-tracker Hook은 Bash 도구 호출의 테스트 명령만 감지합니다. 인라인이 아닌 터미널을 통해 테스트를 실행하세요.
+
+### Hook 에러
+개별 Hook을 수동으로 실행하여 디버깅:
+```bash
+echo '{"tool_name":"Edit","tool_input":{"file_path":"test.ts"},"session_id":"debug"}' | node .claude/hooks/tdd-guard.mjs
+```
+
 ## 라이선스
 
 MIT

package/README.md

@@ -1,8 +1,8 @@
 **English** | [한국어](README.ko.md)
 
-# 🔨 claude-smith
+# 🕵️ claude-smith
 
-> **Claude Code's ESLint** — Physical enforcement for AI coding sessions.
+> **Your code's silent guardian** — Physical enforcement for AI coding sessions.
 
 ## The Problem
 
@@ -39,6 +39,24 @@ npx claude-smith init
 
 Select your language (en/ko/zh/ja), and you're done. 12 hooks installed, rules injected, enforcement active.
 
+## Live Notifications
+
+See hook activity in real-time during Claude Code sessions:
+
+```json
+{ "notify": true }
+```
+
+When enabled, hooks write brief status messages visible in your terminal:
+```
+🕵️ Smith — ⚠️ TDD Guard: LoginForm.tsx test file missing
+🕵️ Smith — ✅ Commit Guard: Commit allowed
+🕵️ Smith — 🚫 Debug Loop: app.tsx 5 edits blocked
+🕵️ Smith — 🤖 Subagent Inject: Rules injected
+```
+
+Set `"notify": false` (default) to disable.
+
 ## The 12 Hooks
 
 ### Hooks That Block (exit code 2 — action physically prevented)
@@ -148,6 +166,7 @@ Project-level settings in `.claude-smith.json` (all optional):
 ```json
 {
   "language": "en",
+  "notify": false,
   "hooks": {
     "commit-guard": { "maxTestAge": 300 },
     "debug-loop": { "warnAt": 3, "blockAt": 5 },
@@ -187,13 +206,36 @@ User settings always take priority over `omcCompat` defaults.
 - **Secure permissions**: Directories `0o700`, files `0o600`
 - **Race-condition safe**: Per-hook atomic counters (no shared JSON)
 - **Zero dependencies**: Node.js built-in modules only
-- **63 tests**: Security edge cases, error handling, cross-platform scenarios
+- **Comprehensive test suite**: Security edge cases, error handling, cross-platform scenarios
 
 ## Requirements
 
 - Node.js >= 18
 - Claude Code with hook support (`.claude/settings.json`)
 
+## Troubleshooting
+
+### Hooks not firing
+1. Verify installation: `claude-smith check`
+2. Check `.claude/settings.json` contains hook definitions
+3. Ensure Node.js >= 18: `node --version`
+
+### False positives in parallel agents
+Enable OMC compatibility mode in `.claude-smith.json`:
+```json
+{ "omcCompat": true }
+```
+This raises thresholds for debug-loop, batch-checkpoint, scope-guard, and plan-guard.
+
+### Tests show as "not run"
+The test-tracker hook only detects test commands in Bash tool calls. Ensure you run tests via the terminal, not inline.
+
+### Hook errors
+Run individual hooks manually to debug:
+```bash
+echo '{"tool_name":"Edit","tool_input":{"file_path":"test.ts"},"session_id":"debug"}' | node .claude/hooks/tdd-guard.mjs
+```
+
 ## License
 
 MIT