claude-smith 3.0.0

package/README.ko.md

@@ -0,0 +1,203 @@
+[English](README.md) | **한국어**
+
+# 🔨 claude-smith
+
+> **Claude Code의 ESLint** — AI 코딩 세션에 물리적 강제를 더합니다.
+
+## 문제
+
+Claude Code에게 이렇게 말해본 적 있나요?
+
+- "테스트 먼저 작성해줘" → 코드부터 작성하고 "작동할 겁니다" 라고 답함
+- "깨진 코드 커밋하지 마" → 테스트 실패 상태로 커밋함
+- "같은 파일 계속 고치지 말고 원인부터 파악해" → 8번째 수정 시도 중
+
+**왜 이런 일이 발생하나:** Claude Code는 *제안*만 이해하고 *제약*은 모릅니다. `CLAUDE.md`의 규칙은 요청일 뿐 — Claude가 무시해도 물리적으로 막을 수 있는 것이 없습니다. 가이드라인 ≠ 강제.
+
+비용은 누적됩니다: 낭비되는 디버깅 시간, 깨진 CI 빌드, 일관성 없는 코드, 그리고 규칙이 소용없다는 좌절감.
+
+## 해결책
+
+claude-smith는 Claude Code의 네이티브 [Hook 시스템](https://docs.anthropic.com/en/docs/claude-code/hooks)을 사용하여 도구 호출을 가로채고 규율을 강제합니다:
+
+```
+Claude가 커밋하려고 함
+    ↓
+Hook이 가로챔: "테스트 통과했어?"
+    ↓
+  통과함 → 커밋 진행
+  실패함 → exit code 2 → 커밋이 물리적으로 차단됨
+```
+
+**"규칙을 따라주세요"가 아니라 "규칙을 따르기 전까지 진행할 수 없습니다."**
+
+## 빠른 시작
+
+```bash
+npx claude-smith init
+```
+
+언어를 선택하면(en/ko/zh/ja) 끝. 12개 Hook 설치, 규칙 주입, 강제 활성화.
+
+## 12개 Hook
+
+### 차단하는 Hook (exit code 2 — 진행 자체를 막음)
+
+| Hook | 언제 | 뭘 하나 |
+|------|------|---------|
+| **Commit Guard** | `git commit` 시 | 최근 5분 내 테스트 통과 기록 없으면 차단 |
+| **Commit Message** | `git commit` 시 | Conventional Commits 형식 아니면 차단 (`feat:`, `fix:`, `docs:` 등) |
+| **Build Guard** | `git commit` 시 | 마지막 빌드가 실패했으면 차단 (기본 비활성) |
+| **Debug Loop** | 같은 파일 5회 편집 시 | 편집 차단 — 근본 원인 조사를 강제 |
+
+### 경고하는 Hook (계속 진행 가능하지만 인지시킴)
+
+| Hook | 언제 | 뭘 하나 |
+|------|------|---------|
+| **TDD Guard** | 코드 파일 편집 시 | "아직 테스트 파일을 수정하지 않았습니다" |
+| **Debug Loop** | 같은 파일 3회 편집 시 | 스마트 diff 분석: 발산형(증상 수정) vs 수렴형(의미있는 진행) |
+| **File Size Warn** | 파일 편집 시 | "이 파일이 500줄 이상입니다 — 분리를 고려하세요" |
+| **Scope Guard** | 파일 편집 시 | "변경이 5개 이상 디렉터리에 걸칩니다 — 범위가 넓지 않나요?" |
+| **Batch Checkpoint** | 3개 파일마다 | "계속하기 전에 사용자에게 진행 상황을 보고하세요" |
+| **Plan Guard** | 코드 파일 5개 이상 편집 시 | "계속하기 전에 분해 계획을 작성하세요" |
+
+### 추적하는 Hook (무음, 데이터 기록)
+
+| Hook | 언제 | 뭘 하나 |
+|------|------|---------|
+| **Test Tracker** | 테스트 명령 실행 시 | 통과/실패 기록 + 커버리지 감소 시 경고 |
+| **Build Tracker** | 빌드 명령 실행 시 | 통과/실패 기록 (Commit Guard / Build Guard가 참조) |
+
+### 주입하는 Hook (컨텍스트 삽입)
+
+| Hook | 언제 | 뭘 하나 |
+|------|------|---------|
+| **Subagent Injector** | 서브에이전트 생성 시 | CLAUDE.md 규칙을 서브에이전트에 자동 주입 |
+
+## 동작 원리
+
+```
+Claude Code 세션
+    ↓ (도구 호출: Edit, Bash, Write 등)
+┌─────────────────────────────────────────┐
+│          claude-smith hooks              │
+│                                         │
+│  PreToolUse (도구 실행 전)              │
+│    Edit/Write → TDD Guard (경고)        │
+│    git commit → Commit Guard (차단)     │
+│    git commit → Commit Message (차단)   │
+│    git commit → Build Guard (차단)      │
+│                                         │
+│  PostToolUse (도구 실행 후)             │
+│    테스트 명령 → Test Tracker (추적)    │
+│    빌드 명령 → Build Tracker (추적)     │
+│    Edit      → Debug Loop (경고/차단)   │
+│    Edit      → File Size Warn (경고)    │
+│    Edit/Write→ Scope Guard (경고)       │
+│    Edit/Write→ Batch Checkpoint (경고)  │
+│    Edit/Write→ Plan Guard (경고/차단)   │
+│                                         │
+│  SubagentStart                          │
+│    생성 시   → Rule Injector (주입)     │
+└─────────────────────────────────────────┘
+    ↓
+  코드 정상 실행
+```
+
+외부 의존성 없음. 백그라운드 프로세스 없음. Hook은 활성 Claude Code 세션 중에만 네이티브 `.claude/settings.json`을 통해 실행됩니다.
+
+## 설치되는 항목
+
+| 컴포넌트 | 위치 | 용도 |
+|---------|------|------|
+| **12개 강제 Hook** | `.claude/hooks/` | 도구 사용 중 자동 검사 |
+| **Hook 설정** | `.claude/settings.json` | Hook 실행 시점 정의 (기존 설정과 병합) |
+| **워크플로우 규칙** | `CLAUDE.md` 섹션 | 사고 패턴 교정 (문제 분해, 체계적 디버깅, 합리화 방어) |
+
+## 슬래시 커맨드
+
+설치 후 Claude Code에서 사용 가능한 커맨드:
+
+| 커맨드 | 기능 |
+|--------|------|
+| `/smith` | 세션 규정 준수 통계 |
+| `/smith-report` | 상세 규정 준수 리포트 |
+| `/smith-check` | 설치 검증 |
+| `/smith-plan` | 분해 계획 템플릿 생성 |
+| `/smith-update` | 버전 체크 + 업그레이드 |
+
+## 명령어
+
+```bash
+claude-smith init                  # 설치 (인터랙티브 언어 선택)
+claude-smith init --lang=ko        # 특정 언어로 설치
+claude-smith update                # Hook 최신 버전 업데이트
+claude-smith check                 # 설치 검증 (12개 Hook)
+claude-smith check --ci            # CI/CD용 JSON 출력
+claude-smith stats                 # 세션 규정 준수 통계
+claude-smith report                # 상세 규정 준수 리포트
+claude-smith dashboard             # HTML 시각적 대시보드 (브라우저에서 열림)
+claude-smith create-hook my-hook   # 커스텀 Hook 템플릿 생성
+claude-smith uninstall             # 모든 구성 요소 제거
+```
+
+## 설정
+
+프로젝트 레벨 설정 `.claude-smith.json` (모든 항목 선택사항):
+
+```json
+{
+  "language": "ko",
+  "hooks": {
+    "commit-guard": { "maxTestAge": 300 },
+    "debug-loop": { "warnAt": 3, "blockAt": 5 },
+    "batch-checkpoint": { "fileThreshold": 3 },
+    "file-size-warn": { "maxLines": 500 },
+    "scope-guard": { "maxDirectories": 5 },
+    "build-guard": { "enabled": false }
+  }
+}
+```
+
+팀 전체가 동일한 규칙을 공유할 수 있도록 `.claude-smith.json`을 커밋하는 것을 권장합니다. 개발자별 설정을 원하면 `.gitignore`에 추가하세요.
+
+### oh-my-claudecode 호환성
+
+[oh-my-claudecode](https://github.com/nicobailon/oh-my-claudecode)의 병렬 에이전트 모드(autopilot, ultrawork, ralph)를 사용하는 경우, `omcCompat`로 임계값을 자동 상향:
+
+```json
+{ "omcCompat": true }
+```
+
+| Hook | 기본값 | omcCompat |
+|------|--------|-----------|
+| debug-loop warnAt | 3 | 6 |
+| debug-loop blockAt | 5 | 10 |
+| batch-checkpoint fileThreshold | 3 | 10 |
+| scope-guard maxDirectories | 5 | 10 |
+| plan-guard warnAt | 5 | 10 |
+| plan-guard blockAt | 10 | 20 |
+
+사용자 설정이 항상 `omcCompat` 기본값보다 우선합니다.
+
+## 보안
+
+- **크로스 플랫폼**: macOS, Linux, Windows (`os.tmpdir()`로 임시 디렉터리)
+- **입력 검증**: 세션/에이전트 ID 검증 (`[a-zA-Z0-9_-]`, 최대 128자)
+- **안전한 권한**: 디렉터리 `0o700`, 파일 `0o600`
+- **경쟁 조건 방지**: Hook별 원자적 카운터 (공유 JSON 미사용)
+- **제로 의존성**: Node.js 기본 모듈만 사용
+- **63개 테스트**: 보안 엣지 케이스, 에러 처리, 크로스 플랫폼 시나리오
+
+## 요구 사항
+
+- Node.js >= 18
+- Hook을 지원하는 Claude Code (`.claude/settings.json`)
+
+## 라이선스
+
+MIT
+
+## 리포지토리
+
+https://github.com/lazysaturday91/claude-smith

package/README.md

@@ -0,0 +1,203 @@
+**English** | [한국어](README.ko.md)
+
+# 🔨 claude-smith
+
+> **Claude Code's ESLint** — Physical enforcement for AI coding sessions.
+
+## The Problem
+
+Have you ever said this to Claude Code?
+
+- "Write tests first" → Writes code first, claims "it should work"
+- "Don't commit broken code" → Commits with failing tests anyway
+- "Stop editing the same file" → 8th attempt, still no root cause analysis
+
+**Why it happens:** Claude Code understands *suggestions*, not *constraints*. Rules in `CLAUDE.md` are requests — Claude can ignore them because nothing physically stops it. Guidelines ≠ enforcement.
+
+The cost compounds: wasted debugging time, broken CI builds, inconsistent code, and the frustration of rules that don't stick.
+
+## The Solution
+
+claude-smith uses Claude Code's native [Hook system](https://docs.anthropic.com/en/docs/claude-code/hooks) to intercept tool calls and enforce discipline:
+
+```
+Claude tries to commit
+    ↓
+Hook intercepts: "Did tests pass?"
+    ↓
+  Yes → Commit proceeds
+  No  → exit code 2 → Commit physically blocked
+```
+
+**Not "please follow the rules" — "you cannot proceed until you follow the rules."**
+
+## Quick Start
+
+```bash
+npx claude-smith init
+```
+
+Select your language (en/ko/zh/ja), and you're done. 12 hooks installed, rules injected, enforcement active.
+
+## The 12 Hooks
+
+### Hooks That Block (exit code 2 — action physically prevented)
+
+| Hook | When | What |
+|------|------|------|
+| **Commit Guard** | `git commit` | Blocks if tests haven't passed in the last 5 minutes |
+| **Commit Message** | `git commit` | Blocks non-conventional format (`feat:`, `fix:`, `docs:`, etc.) |
+| **Build Guard** | `git commit` | Blocks if last build failed (off by default) |
+| **Debug Loop** | 5th edit to same file | Blocks editing — forces root cause investigation |
+
+### Hooks That Warn (continues but Claude sees the warning)
+
+| Hook | When | What |
+|------|------|------|
+| **TDD Guard** | Code file edit | "You haven't edited a test file yet" |
+| **Debug Loop** | 3rd edit to same file | Smart diff analysis: divergent (symptom-fixing) vs convergent (meaningful progress) |
+| **File Size Warn** | File edit | "This file is 500+ lines — consider splitting" |
+| **Scope Guard** | File edit | "Changes span 5+ directories — scope too broad?" |
+| **Batch Checkpoint** | Every 3 files | "Report progress to the user before continuing" |
+| **Plan Guard** | 5+ code files edited | "Create a decomposition plan before continuing" |
+
+### Hooks That Track (silent, records data)
+
+| Hook | When | What |
+|------|------|------|
+| **Test Tracker** | Test command runs | Records pass/fail + warns on coverage decrease |
+| **Build Tracker** | Build command runs | Records pass/fail for Commit Guard / Build Guard |
+
+### Hooks That Inject (context insertion)
+
+| Hook | When | What |
+|------|------|------|
+| **Subagent Injector** | Subagent spawns | Auto-injects CLAUDE.md rules into subagent context |
+
+## How It Works
+
+```
+Claude Code Session
+    ↓ (tool call: Edit, Bash, Write, etc.)
+┌─────────────────────────────────────────┐
+│          claude-smith hooks              │
+│                                         │
+│  PreToolUse (before tool executes)      │
+│    Edit/Write → TDD Guard (warn)        │
+│    git commit → Commit Guard (block)    │
+│    git commit → Commit Message (block)  │
+│    git commit → Build Guard (block)     │
+│                                         │
+│  PostToolUse (after tool executes)      │
+│    test cmd  → Test Tracker (track)     │
+│    build cmd → Build Tracker (track)    │
+│    Edit      → Debug Loop (warn/block)  │
+│    Edit      → File Size Warn (warn)    │
+│    Edit/Write→ Scope Guard (warn)       │
+│    Edit/Write→ Batch Checkpoint (warn)  │
+│    Edit/Write→ Plan Guard (warn/block)  │
+│                                         │
+│  SubagentStart                          │
+│    Any spawn → Rule Injector (inject)   │
+└─────────────────────────────────────────┘
+    ↓
+  Code runs normally
+```
+
+No external dependencies. No background processes. Hooks run only during active Claude Code sessions via native `.claude/settings.json`.
+
+## What Gets Installed
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| **12 Enforcement Hooks** | `.claude/hooks/` | Automated checks during tool use |
+| **Hook Configuration** | `.claude/settings.json` | Defines when hooks run (merged with existing) |
+| **Workflow Rules** | `CLAUDE.md` section | Thought-pattern coaching (problem decomposition, systematic debugging, rationalization defense) |
+
+## Slash Commands
+
+After installation, these commands are available in Claude Code:
+
+| Command | What it does |
+|---------|-------------|
+| `/smith` | Session compliance statistics |
+| `/smith-report` | Detailed compliance report |
+| `/smith-check` | Validate installation |
+| `/smith-plan` | Generate decomposition plan template |
+| `/smith-update` | Check for updates and upgrade |
+
+## Commands
+
+```bash
+claude-smith init                  # Install (interactive language selection)
+claude-smith init --lang=ko        # Install with specific language
+claude-smith update                # Update hooks to latest version
+claude-smith check                 # Validate installation (12 hooks)
+claude-smith check --ci            # JSON output for CI/CD pipelines
+claude-smith stats                 # Session compliance statistics
+claude-smith report                # Detailed compliance report
+claude-smith dashboard             # HTML visual dashboard (opens in browser)
+claude-smith create-hook my-hook   # Scaffold a custom hook
+claude-smith uninstall             # Remove all components
+```
+
+## Configuration
+
+Project-level settings in `.claude-smith.json` (all optional):
+
+```json
+{
+  "language": "en",
+  "hooks": {
+    "commit-guard": { "maxTestAge": 300 },
+    "debug-loop": { "warnAt": 3, "blockAt": 5 },
+    "batch-checkpoint": { "fileThreshold": 3 },
+    "file-size-warn": { "maxLines": 500 },
+    "scope-guard": { "maxDirectories": 5 },
+    "build-guard": { "enabled": false }
+  }
+}
+```
+
+We recommend committing `.claude-smith.json` so the whole team shares the same enforcement. For per-developer settings, add it to `.gitignore`.
+
+### oh-my-claudecode Compatibility
+
+If you use [oh-my-claudecode](https://github.com/nicobailon/oh-my-claudecode) with parallel agent modes (autopilot, ultrawork, ralph), enable `omcCompat` to auto-raise thresholds:
+
+```json
+{ "omcCompat": true }
+```
+
+| Hook | Default | omcCompat |
+|------|---------|-----------|
+| debug-loop warnAt | 3 | 6 |
+| debug-loop blockAt | 5 | 10 |
+| batch-checkpoint fileThreshold | 3 | 10 |
+| scope-guard maxDirectories | 5 | 10 |
+| plan-guard warnAt | 5 | 10 |
+| plan-guard blockAt | 10 | 20 |
+
+User settings always take priority over `omcCompat` defaults.
+
+## Security
+
+- **Cross-platform**: macOS, Linux, Windows (`os.tmpdir()` for temp dirs)
+- **Input sanitization**: Session/agent IDs validated (`[a-zA-Z0-9_-]`, max 128 chars)
+- **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
+
+## Requirements
+
+- Node.js >= 18
+- Claude Code with hook support (`.claude/settings.json`)
+
+## License
+
+MIT
+
+## Repository
+
+https://github.com/lazysaturday91/claude-smith