moai-adk 0.8.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

moai_adk/templates/.claude/hooks/alfred/HOOK_SCHEMA_VALIDATION.md

@@ -1,313 +0,0 @@
-# Hook JSON 스키마 검증 및 해결 보고서
-
-**작성일**: 2025-10-23  
-**태그**: @CODE:HOOKS-REFACTOR-001  
-**상태**: ✅ 해결 완료
-
----
-
-## 📋 문제 요약
-
-### 초기 오류
-```
-SessionStart:startup hook error: JSON validation failed: Hook JSON output validation failed
-Expected schema: { ... "systemMessage": ... }
-```
-
-### 근본 원인
-Claude Code Hook 스키마에서 `systemMessage`가 **최상위 필드**여야 하지만, 일부 구현에서는 이를 `hookSpecificOutput` 내부에 중첩시키고 있었습니다.
-
----
-
-## 🔍 분석 결과
-
-### Claude Code 공식 Hook 스키마
-
-#### 1. 일반 Hook 이벤트 (SessionStart, PreToolUse, PostToolUse, SessionEnd 등)
-
-```json
-{
-  "continue": true|false,                  // ✅ 기본 필드
-  "systemMessage": "string",               // ✅ 최상위 필드 (NOT in hookSpecificOutput)
-  "decision": "approve"|"block"|undefined, // ✅ 선택적
-  "reason": "string",                      // ✅ 선택적
-  "permissionDecision": "allow"|"deny"|"ask"|undefined,  // ✅ 선택적
-  "suppressOutput": true|false             // ✅ 선택적
-}
-```
-
-#### 2. UserPromptSubmit 전용 스키마
-
-```json
-{
-  "continue": true,
-  "hookSpecificOutput": {                  // ✅ UserPromptSubmit에만 사용
-    "hookEventName": "UserPromptSubmit",
-    "additionalContext": "string"
-  }
-}
-```
-
-### 핵심 규칙
-
-| 규칙 | 설명 |
-|------|------|
-| **systemMessage 위치** | 최상위 필드 (`output["systemMessage"]`) |
-| **hookSpecificOutput** | UserPromptSubmit 전용 |
-| **내부 필드** | `context_files`, `suggestions`, `exit_code`는 Python 로직용 (JSON 출력 제외) |
-| **JSON 직렬화** | 모든 필드는 JSON 직렬화 가능해야 함 |
-
----
-
-## ✅ 해결 방안
-
-### 1. 코드 수정
-
-**파일**: `.claude/hooks/alfred/core/__init__.py`
-
-#### `to_dict()` 메서드 (라인 63-118)
-```python
-def to_dict(self) -> dict[str, Any]:
-    """Claude Code 표준 Hook 출력 스키마로 변환"""
-    output: dict[str, Any] = {}
-
-    # 1. decision 또는 continue 추가
-    if self.decision:
-        output["decision"] = self.decision
-    else:
-        output["continue"] = self.continue_execution
-
-    # 2. reason 추가 (decision 또는 permissionDecision과 함께)
-    if self.reason:
-        output["reason"] = self.reason
-
-    # 3. suppressOutput 추가 (True인 경우만)
-    if self.suppress_output:
-        output["suppressOutput"] = True
-
-    # 4. permissionDecision 추가
-    if self.permission_decision:
-        output["permissionDecision"] = self.permission_decision
-
-    # 5. ⭐ systemMessage를 최상위 필드로 추가 (NOT in hookSpecificOutput)
-    if self.system_message:
-        output["systemMessage"] = self.system_message
-
-    # 🚫 내부 필드는 JSON 출력에서 제외
-    # - context_files: JIT 문맥 로드 (내부용)
-    # - suggestions: 제안 (내부용)
-    # - exit_code: 진단 (내부용)
-
-    return output
-```
-
-#### `to_user_prompt_submit_dict()` 메서드 (라인 120-160)
-```python
-def to_user_prompt_submit_dict(self) -> dict[str, Any]:
-    """UserPromptSubmit Hook 전용 스키마"""
-    if self.context_files:
-        context_str = "\n".join([f"📎 Context: {f}" for f in self.context_files])
-    else:
-        context_str = ""
-
-    if self.system_message:
-        if context_str:
-            context_str = f"{self.system_message}\n\n{context_str}"
-        else:
-            context_str = self.system_message
-
-    return {
-        "continue": self.continue_execution,
-        "hookSpecificOutput": {
-            "hookEventName": "UserPromptSubmit",
-            "additionalContext": context_str
-        }
-    }
-```
-
-### 2. 설정 검증
-
-**파일**: `.claude/settings.json` (라인 8-60)
-
-```json
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/alfred_hooks.py SessionStart",
-            "type": "command"
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/alfred_hooks.py UserPromptSubmit",
-            "type": "command"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
----
-
-## 🧪 검증 결과
-
-### 1. 자동 테스트 (8/8 통과)
-
-**파일**: `.claude/hooks/alfred/test_hook_output.py`
-
-```bash
-$ cd .claude/hooks/alfred && python test_hook_output.py
-
-✅ Test 1: Basic output - PASSED
-✅ Test 2: systemMessage (top-level) - PASSED
-✅ Test 3: decision + reason - PASSED
-✅ Test 4: UserPromptSubmit schema - PASSED
-✅ Test 5: permissionDecision - PASSED
-✅ Test 6: SessionStart typical output - PASSED
-✅ Test 7: JSON serializable - PASSED
-✅ Test 8: UserPromptSubmit with system_message - PASSED
-
-✅ ALL 8 TESTS PASSED
-```
-
-### 2. 실제 Hook 실행 검증
-
-#### SessionStart (compact phase)
-```bash
-$ echo '{"cwd": ".", "phase": "compact"}' | uv run .claude/hooks/alfred/alfred_hooks.py SessionStart
-
-{
-  "continue": true,
-  "systemMessage": "🚀 MoAI-ADK Session Started\n   Language: python\n   Branch: develop (d905363)\n   Changes: 215\n   SPEC Progress: 30/31 (96%)\n   Checkpoints: 2 available\n      - delete-20251022-134841\n      - critical-file-20251019-230247\n   Restore: /alfred:0-project restore"
-}
-```
-
-✅ **검증**: 
-- `systemMessage`가 최상위 필드
-- JSON 유효성 확인
-- `hookSpecificOutput` 없음 (올바름)
-
-#### SessionStart (clear phase)
-```bash
-$ echo '{"cwd": ".", "phase": "clear"}' | uv run .claude/hooks/alfred/alfred_hooks.py SessionStart
-
-{"continue": true}
-```
-
-✅ **검증**: 
-- 최소 스키마 (continue만)
-- clear 단계에서 중복 출력 방지
-
-#### UserPromptSubmit
-```bash
-$ echo '{"cwd": ".", "userPrompt": "test"}' | uv run .claude/hooks/alfred/alfred_hooks.py UserPromptSubmit
-
-{
-  "continue": true,
-  "hookSpecificOutput": {
-    "hookEventName": "UserPromptSubmit",
-    "additionalContext": "📎 Loaded 1 context file(s)\n\n📎 Context: tests/"
-  }
-}
-```
-
-✅ **검증**: 
-- UserPromptSubmit 특수 스키마
-- `hookSpecificOutput` 사용 (올바름)
-
----
-
-## 📚 각 Hook 이벤트별 스키마 가이드
-
-| 이벤트 | 최소 JSON | 예시 | 차단 가능 |
-|--------|-----------|------|----------|
-| **SessionStart** | `{"continue": true}` | 프로젝트 상태 표시 | ❌ No |
-| **SessionEnd** | `{"continue": true}` | 정리 작업 | ❌ No |
-| **PreToolUse** | `{"continue": true}` | 도구 실행 승인/차단 | ✅ Yes |
-| **PostToolUse** | `{"continue": true}` | 도구 실행 후 피드백 | ❌ No* |
-| **UserPromptSubmit** | 특수 스키마 | 프롬프트 문맥 추가 | ✅ Yes |
-| **Notification** | `{"continue": true}` | 알림 처리 | ❌ No |
-| **Stop** | `{"continue": true}` | 종료 차단 | ✅ Yes |
-| **SubagentStop** | `{"continue": true}` | 서브에이전트 종료 차단 | ✅ Yes |
-
-*: PostToolUse는 도구가 이미 실행되었으므로 차단 불가능하지만, 피드백 제공 가능
-
----
-
-## 🔧 구현 세부사항
-
-### HookResult 클래스 필드
-
-```python
-@dataclass
-class HookResult:
-    # ✅ Claude Code 표준 필드 (JSON에 포함)
-    continue_execution: bool = True
-    suppress_output: bool = False
-    decision: Literal["approve", "block"] | None = None
-    reason: str | None = None
-    permission_decision: Literal["allow", "deny", "ask"] | None = None
-    system_message: str | None = None  # ⭐ TOP-LEVEL in JSON
-    
-    # 🚫 내부 필드 (JSON 출력 제외)
-    context_files: list[str] = field(default_factory=list)
-    suggestions: list[str] = field(default_factory=list)
-    exit_code: int = 0
-```
-
-### 메서드별 역할
-
-| 메서드 | 사용 사건 | 반환 스키마 |
-|--------|---------|----------|
-| `to_dict()` | 일반 Hook 이벤트 | 표준 Claude Code 스키마 |
-| `to_user_prompt_submit_dict()` | UserPromptSubmit 이벤트 | 특수 스키마 + hookSpecificOutput |
-
----
-
-## 📖 참고 문서
-
-### 공식 Claude Code 문서
-- **Claude Code Hooks**: https://docs.claude.com/en/docs/claude-code/hooks
-- **Hook Output Schema**: https://docs.claude.com/en/docs/claude-code/hooks#output-schema
-
-### Context7 참고 자료
-- **Claude Code Hooks Mastery** (Trust Score: 8.3, 100+ 코드 스니펫)
-- **Claude Code Templates** (Trust Score: 10)
-
-### 프로젝트 문서
-- **CLAUDE.md**: `Error Message Standard (Shared)` 섹션
-- **Hook 구현**: `.claude/hooks/alfred/handlers/` 디렉토리
-
----
-
-## 🎯 결론
-
-✅ **상태**: 해결 완료  
-✅ **검증**: 8/8 자동 테스트 통과  
-✅ **실제 실행**: 모든 Hook 이벤트 정상 작동  
-
-### 핵심 수정사항
-1. `systemMessage`를 최상위 필드로 이동 (NOT in hookSpecificOutput)
-2. UserPromptSubmit 특수 스키마 분리
-3. 내부 필드 JSON 출력 제외
-4. 모든 Hook 이벤트 스키마 정규화
-
-### 다음 단계
-- ✅ Hook 스키마 검증 자동화
-- ✅ 테스트 스크립트 작성
-- ⏭️ 현재 상태 유지 및 모니터링
-
----
-
-**검증 완료**: 2025-10-23  
-**담당자**: @agent-cc-manager  
-**참고**: @CODE:HOOKS-REFACTOR-001

moai_adk/templates/.claude/hooks/alfred/README.md

@@ -1,230 +0,0 @@
-# Alfred Hooks System
-
-**Event-Driven Context Management for MoAI-ADK**
-
-Alfred Hooks integrates with Claude Code's event system to automatically manage project context, create checkpoints before risky operations, and provide just-in-time (JIT) document loading.
-
----
-
-## 📐 Architecture
-
-### Modular Design (9 Files, ≤284 LOC each)
-
-```
-.claude/hooks/alfred/
-├── alfred_hooks.py          # Main entry point (CLI router)
-├── core/                    # Core business logic
-│   ├── __init__.py         # Type definitions (HookPayload, HookResult)
-│   ├── project.py          # Language detection, Git info, SPEC counting
-│   ├── context.py          # JIT retrieval, workflow context
-│   ├── checkpoint.py       # Event-driven checkpoint creation
-│   └── tags.py             # TAG search, verification, caching
-└── handlers/                # Event handlers
-    ├── __init__.py         # Handler exports
-    ├── session.py          # SessionStart, SessionEnd
-    ├── user.py             # UserPromptSubmit
-    ├── tool.py             # PreToolUse, PostToolUse
-    └── notification.py     # Notification, Stop, SubagentStop
-```
-
-### Design Principles
-
-- **Single Responsibility**: Each module has one clear responsibility
-- **Separation of Concerns**: core (business logic) vs handlers (event processing)
-- **CODE-FIRST**: Scan code directly without intermediate cache (mtime Based invalidation)
-- **Context Engineering**: Minimize initial context burden with JIT Retrieval
-
----
-
-## 🎯 Core Modules
-
-### `core/project.py` (284 LOC)
-
-**Project metadata and language detection**
-
-```python
-# Public API
-detect_language(cwd: str) -> str
-get_project_language(cwd: str) -> str
-get_git_info(cwd: str) -> dict[str, Any]
-count_specs(cwd: str) -> dict[str, int]
-```
-
-**Features**:
-- Automatic detection of 20 languages ​​(Python, TypeScript, Java, Go, Rust, etc.)
-- `.moai/config.json` First, fallback to auto-detection
-- Check Git information (branch, commit, changes)
-- SPEC progress calculation (total, completed, percentage)
-
-### `core/context.py` (110 LOC)
-
-**JIT Context Retrieval and Workflow Management**
-
-```python
-# Public API
-get_jit_context(prompt: str, cwd: str) -> list[str]
-save_phase_context(phase: str, data: Any, ttl: int = 600)
-load_phase_context(phase: str, ttl: int = 600) -> Any | None
-clear_workflow_context()
-```
-
-**Features**:
-- Automatically recommend documents based on prompt analysis
-  - `/alfred:1-plan` → `spec-metadata.md`
-  - `/alfred:2-run` → `development-guide.md`
-- Context caching for each workflow step (TTL 10 minutes)
-- Compliance with Anthropic Context Engineering principles
-
-### `core/checkpoint.py` (244 LOC)
-
-**Event-Driven Checkpoint Automation**
-
-```python
-# Public API
-detect_risky_operation(tool: str, args: dict, cwd: str) -> tuple[bool, str]
-create_checkpoint(cwd: str, operation: str) -> str
-log_checkpoint(cwd: str, branch: str, description: str)
-list_checkpoints(cwd: str, max_count: int = 10) -> list[dict]
-```
-
-**Features**:
-- Automatic detection of dangerous tasks:
-  - Bash: `rm -rf`, `git merge`, `git reset --hard`
-  - Edit/Write: `CLAUDE.md`, `config.json`
-  - MultiEdit: ≥10 files
-- Automatic creation of Git checkpoint: `checkpoint/before-{operation}-{timestamp}`
-- Checkpoint history management and recovery guide
-
-### `core/tags.py` (244 LOC)
-
-**CODE-FIRST TAG SYSTEM**
-
-```python
-# Public API
-search_tags(pattern: str, scope: list[str], cache_ttl: int = 60) -> list[dict]
-verify_tag_chain(tag_id: str) -> dict[str, Any]
-find_all_tags_by_type(tag_type: str) -> dict[str, list[str]]
-suggest_tag_reuse(keyword: str) -> list[str]
-get_library_version(library: str, cache_ttl: int = 86400) -> str | None
-set_library_version(library: str, version: str)
-```
-
-**Features**:
-- ripgrep-based TAG search (parsing JSON output)
-- mtime-based cache invalidation (CODE-FIRST guaranteed)
-- TAG chain verification (@SPEC → @TEST → @CODE completeness check)
-- Library version caching (TTL 24 hours)
-
----
-
-## 🎬 Event Handlers
-
-### `handlers/session.py`
-
-**SessionStart, SessionEnd handlers**
-
-- **SessionStart**: Display project information
- - Language, Git status, SPEC progress, recent checkpoint
- - Display directly to user with `systemMessage` field
-- **SessionEnd**: Cleanup task (stub)
-
-### `handlers/user.py`
-
-**UserPromptSubmit Handler**
-
-- Return list of JIT Context recommended documents
-- Analyze user prompt patterns and load related documents
-
-### `handlers/tool.py`
-
-**PreToolUse, PostToolUse handlers**
-
-- **PreToolUse**: Automatic checkpoint creation when dangerous operation is detected
-- **PostToolUse**: Post-processing operation (stub)
-
-### `handlers/notification.py`
-
-**Notification, Stop, SubagentStop handlers**
-
-- Basic implementation (stub, can be expanded in the future)
-
----
-
-## 🧪 Testing
-
-### Test Suite
-
-```bash
-# Run all tests
-uv run pytest tests/unit/test_alfred_hooks_*.py -v --no-cov
-
-# Run specific module tests
-uv run pytest tests/unit/test_alfred_hooks_core_tags.py -v
-uv run pytest tests/unit/test_alfred_hooks_core_context.py -v
-uv run pytest tests/unit/test_alfred_hooks_core_project.py -v
-```
-
-### Test Coverage (18 tests)
-
-- ✅ **tags.py**: 7 tests (cache, TAG verification, version management)
-- ✅ **context.py**: 5 tests (JIT, workflow context)
-- ✅ **project.py**: 6 tests (language detection, Git, SPEC count)
-
-### Test Structure
-
-```python
-# Dynamic module loading for isolated testing
-def _load_{module}_module(module_name: str):
-    repo_root = Path(__file__).resolve().parents[2]
-    hooks_dir = repo_root / ".claude" / "hooks" / "alfred"
-    sys.path.insert(0, str(hooks_dir))
-    
-    module_path = hooks_dir / "core" / "{module}.py"
-    spec = importlib.util.spec_from_file_location(module_name, module_path)
-    # ...
-```
-
----
-
-## 🔄 Migration from moai_hooks.py
-
-### Before (Monolithic)
-
-- **1 file**: 1233 LOC
-- **Issues**: 
-- All functions concentrated in one file
- - Difficult to test, complex to maintain
- - Unclear separation of responsibilities
-
-### After (Modular)
-
-- **9 files**: ≤284 LOC each
-- **Benefits**:
-- Clear separation of responsibilities (SRP)
- - Independent module testing possible
- - Easy to expand, easy to maintain
- - Compliance with Context Engineering principles
-
-### Breaking Changes
-
-**None** - External APIs remain the same.
-
----
-
-## 📚 References
-
-### Internal Documents
-
-- **CLAUDE.md**: MoAI-ADK User Guide
-- **.moai/memory/development-guide.md**: SPEC-First TDD Workflow
-- **.moai/memory/spec-metadata.md**: SPEC metadata standard
-
-### External Resources
-
-- [Claude Code Hooks Documentation](https://docs.claude.com/en/docs/claude-code)
-- [Anthropic Context Engineering](https://docs.anthropic.com/claude/docs/context-engineering)
-
----
-
-**Last Updated**: 2025-10-16  
-**Author**: @Alfred (MoAI-ADK SuperAgent)