moai-adk 0.4.8__py3-none-any.whl → 0.4.11__py3-none-any.whl

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

@@ -0,0 +1,313 @@
+# 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/alfred_hooks.py

@@ -55,6 +55,7 @@ Setup sys.path for package imports
 import json
 import sys
 from pathlib import Path
+from typing import Any
 
 from core import HookResult
 from handlers import (

moai_adk/templates/.claude/hooks/alfred/core/__init__.py

@@ -28,18 +28,23 @@ class HookResult:
     Attributes conform to Claude Code Hook output specification:
     https://docs.claude.com/en/docs/claude-code/hooks
 
-    Standard Fields (Claude Code schema):
+    Standard Fields (Claude Code schema - included in JSON output):
         continue_execution: Allow execution to continue (default True)
         suppress_output: Suppress hook output display (default False)
         decision: "approve" or "block" operation (optional)
         reason: Explanation for decision (optional)
         permission_decision: "allow", "deny", or "ask" (optional)
+        system_message: Message displayed to user (top-level field)
 
-    MoAI-ADK Fields (wrapped in hookSpecificOutput):
-        system_message: Message displayed to user
-        context_files: List of context files to load
-        suggestions: Suggestions for user
-        exit_code: Exit code (for diagnostics)
+    Internal Fields (MoAI-ADK only - NOT in JSON output):
+        context_files: List of context files to load (internal use only)
+        suggestions: Suggestions for user (internal use only)
+        exit_code: Exit code for diagnostics (internal use only)
+
+    Note:
+        - systemMessage appears at TOP LEVEL in JSON output
+        - hookSpecificOutput is ONLY used for UserPromptSubmit events
+        - Internal fields are used for Python logic but not serialized to JSON
     """
 
     # Claude Code standard fields
@@ -60,8 +65,10 @@ class HookResult:
 
         Returns:
             Dictionary conforming to Claude Code Hook specification with:
-            - Top-level fields: continue, suppressOutput, decision, reason, permissionDecision
-            - Nested field: hookSpecificOutput containing MoAI-ADK-specific data
+            - Top-level fields: continue, suppressOutput, decision, reason,
+              permissionDecision, systemMessage
+            - MoAI-ADK internal fields (context_files, suggestions, exit_code)
+              are NOT included in JSON output (used for internal logic only)
 
         Examples:
             >>> result = HookResult(continue_execution=True)
@@ -72,20 +79,27 @@ class HookResult:
             >>> result.to_dict()
             {'decision': 'block', 'reason': 'Dangerous'}
 
-            >>> result = HookResult(system_message="Test", context_files=["a.txt"])
+            >>> result = HookResult(system_message="Test")
             >>> result.to_dict()
-            {'continue': True, 'hookSpecificOutput': {'systemMessage': 'Test', 'contextFiles': ['a.txt']}}
+            {'continue': True, 'systemMessage': 'Test'}
+
+        Note:
+            - systemMessage is a TOP-LEVEL field (not nested in hookSpecificOutput)
+            - hookSpecificOutput is ONLY used for UserPromptSubmit events
+            - context_files, suggestions, exit_code are internal-only fields
         """
         output: dict[str, Any] = {}
 
         # Add decision or continue flag
         if self.decision:
             output["decision"] = self.decision
-            if self.reason:
-                output["reason"] = self.reason
         else:
             output["continue"] = self.continue_execution
 
+        # Add reason if provided (works with both decision and permissionDecision)
+        if self.reason:
+            output["reason"] = self.reason
+
         # Add suppressOutput if True
         if self.suppress_output:
             output["suppressOutput"] = True
@@ -94,24 +108,12 @@ class HookResult:
         if self.permission_decision:
             output["permissionDecision"] = self.permission_decision
 
-        # Wrap MoAI-ADK custom fields in hookSpecificOutput
-        hook_output: dict[str, Any] = {}
-
+        # Add systemMessage at TOP LEVEL (required by Claude Code schema)
         if self.system_message:
-            hook_output["systemMessage"] = self.system_message
-
-        if self.context_files:
-            hook_output["contextFiles"] = self.context_files
-
-        if self.suggestions:
-            hook_output["suggestions"] = self.suggestions
-
-        if self.exit_code != 0:
-            hook_output["exitCode"] = self.exit_code
+            output["systemMessage"] = self.system_message
 
-        # Only add hookSpecificOutput if there's custom data
-        if hook_output:
-            output["hookSpecificOutput"] = hook_output
+        # Note: context_files, suggestions, exit_code are internal-only fields
+        # and are NOT included in the JSON output per Claude Code schema
 
         return output
 
@@ -134,7 +136,8 @@ class HookResult:
         Examples:
             >>> result = HookResult(context_files=["tests/"])
             >>> result.to_user_prompt_submit_dict()
-            {'continue': True, 'hookSpecificOutput': {'hookEventName': 'UserPromptSubmit', 'additionalContext': '📎 Context: tests/'}}
+            {'continue': True, 'hookSpecificOutput': \
+{'hookEventName': 'UserPromptSubmit', 'additionalContext': '📎 Context: tests/'}}
         """
         # Convert context_files to additionalContext string
         if self.context_files:

moai_adk/templates/.claude/hooks/alfred/core/tags.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+# @CODE:HOOK-TAG-001 | SPEC: TBD | TEST: tests/hooks/test_tag_validation.py
+"""TAG validation helpers for MoAI-ADK hooks
+
+Fast checks used by PreToolUse/PostToolUse to nudge users when
+new or modified files are missing required @TAG annotations.
+
+Configurable rules with sensible defaults:
+- Load patterns from .moai/tag-rules.json if present.
+- Otherwise, apply default glob patterns (folder names are not hard-coded only).
+
+Defaults (order matters; first match wins):
+1) SPEC
+   - .moai/specs/**
+   - **/SPEC-*/spec.md
+2) TEST
+   - **/*_test.py, **/test_*.py, **/*.test.* (ts,tsx,js,jsx,go,rs)
+   - **/*.spec.* (ts,tsx,js,jsx)
+   - tests/**
+3) DOC
+   - docs/**/*.md, **/README.md, **/*.api.md
+4) CODE
+   - Source extensions: .py,.ts,.tsx,.js,.jsx,.go,.rs,.java,.kt,.rb,.php,.c,.cpp,.cs,.swift,.scala
+   - Excluding TEST patterns
+
+Notes:
+- Best-effort: skip binary/large files and non-target paths
+- Do not block execution; return a list of issues for messaging
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+DEFAULT_CODE_EXTS = (
+    ".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rs",
+    ".java", ".kt", ".rb", ".php", ".c", ".cpp", ".cs",
+    ".swift", ".scala"
+)
+
+
+@dataclass
+class TagIssue:
+    path: str
+    expected: str  # one of @SPEC, @TEST, @CODE, @DOC
+    reason: str
+
+
+@dataclass
+class Rule:
+    include: List[str]
+    expect: str  # '@SPEC:' | '@TEST:' | '@CODE:' | '@DOC:'
+    exclude: List[str]
+
+
+def _load_rules(cwd: str) -> List[Rule]:
+    """Load tag rules from .moai/tag-rules.json or return defaults.
+
+    Schema example:
+    {
+      "rules": [
+        {"include": ["**/*_test.py", "**/*.test.ts"], "expect": "@TEST:", "exclude": []},
+        {"include": ["docs/**/*.md", "**/README.md"], "expect": "@DOC:", "exclude": []}
+      ]
+    }
+    """
+    cfg = Path(cwd) / ".moai" / "tag-rules.json"
+    if cfg.exists():
+        try:
+            data = json.loads(cfg.read_text(encoding="utf-8"))
+            items = data.get("rules", [])
+            rules: List[Rule] = []
+            for it in items:
+                include = list(it.get("include", []))
+                expect = str(it.get("expect", ""))
+                exclude = list(it.get("exclude", []))
+                if include and expect in ("@SPEC:", "@TEST:", "@CODE:", "@DOC:"):
+                    rules.append(Rule(include=include, expect=expect, exclude=exclude))
+            if rules:
+                return rules
+        except Exception:
+            pass
+
+    # Defaults (ordered)
+    return [
+        Rule(
+            include=[".moai/specs/**", "**/SPEC-*/spec.md"],
+            expect="@SPEC:",
+            exclude=[]
+        ),
+        Rule(
+            include=[
+                "**/*_test.py", "**/test_*.py", "**/*.test.ts",
+                "**/*.test.tsx", "**/*.test.js", "**/*.test.jsx",
+                "**/*.test.go", "**/*.test.rs", "**/*.spec.ts",
+                "**/*.spec.tsx", "tests/**"
+            ],
+            expect="@TEST:",
+            exclude=[".claude/**"]
+        ),
+        Rule(
+            include=["docs/**/*.md", "**/README.md", "**/*.api.md"],
+            expect="@DOC:",
+            exclude=[".claude/**"]
+        ),
+        Rule(
+            include=["**/*"],
+            expect="@CODE:",
+            exclude=[
+                "tests/**", "docs/**", ".moai/**", ".claude/**",
+                "**/*.md", "**/*.json", "**/*.yml", "**/*.yaml",
+                "**/*.toml", "**/*.lock", "**/*.svg", "**/*.png",
+                "**/*.jpg", "**/*.jpeg", "**/*.gif"
+            ]
+        ),
+    ]
+
+
+def _match_any(path: str, patterns: List[str]) -> bool:
+    return any(fnmatch.fnmatch(path, pat) for pat in patterns)
+
+
+def _needs_tag_str(path_str: str, rules: List[Rule]) -> Optional[str]:
+    p = path_str
+    for rule in rules:
+        if _match_any(p, rule.include) and not _match_any(p, rule.exclude):
+            if rule.expect == "@CODE:":
+                # CODE: limit to source-like extensions to reduce noise
+                if not any(p.endswith(ext) for ext in DEFAULT_CODE_EXTS):
+                    continue
+            return rule.expect
+    return None
+
+
+def _has_tag(content: str, expected: str) -> bool:
+    return expected in content
+
+
+def _iter_recent_changes(cwd: str) -> Iterable[Path]:
+    root = Path(cwd)
+    try:
+        # Staged files
+        r1 = subprocess.run(
+            ["git", "diff", "--name-only", "--cached"],
+            cwd=cwd, capture_output=True, text=True, timeout=1
+        )
+        # Modified (unstaged) tracked files
+        r2 = subprocess.run(
+            ["git", "ls-files", "-m"],
+            cwd=cwd, capture_output=True, text=True, timeout=1
+        )
+        # Untracked (other) files respecting .gitignore
+        r3 = subprocess.run(
+            ["git", "ls-files", "-o", "--exclude-standard"],
+            cwd=cwd, capture_output=True, text=True, timeout=1
+        )
+        names = set()
+        if r1.returncode == 0:
+            names.update([line.strip() for line in r1.stdout.splitlines() if line.strip()])
+        if r2.returncode == 0:
+            names.update([line.strip() for line in r2.stdout.splitlines() if line.strip()])
+        if r3.returncode == 0:
+            names.update([line.strip() for line in r3.stdout.splitlines() if line.strip()])
+        for n in names:
+            p = (root / n).resolve()
+            if p.is_file():
+                yield p
+    except Exception:
+        return []
+
+
+def scan_recent_changes_for_missing_tags(cwd: str) -> list[TagIssue]:
+    issues: list[TagIssue] = []
+    rules = _load_rules(cwd)
+    root = Path(cwd).resolve()
+    for path in _iter_recent_changes(cwd):
+        try:
+            content = path.read_text(encoding="utf-8", errors="ignore")
+        except Exception:
+            continue
+        # compute relative path once and use for matching/excluding
+        try:
+            rel = path.resolve().relative_to(root)
+            rel_s = rel.as_posix()
+        except Exception:
+            rel_s = path.name
+
+        expected = _needs_tag_str(rel_s, rules)
+        if not expected:
+            continue
+        if not _has_tag(content, expected):
+            issues.append(TagIssue(path=rel_s, expected=expected, reason="missing tag"))
+    return issues