moai-adk 0.4.8__tar.gz → 0.4.11__tar.gz

{moai_adk-0.4.8 → moai_adk-0.4.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moai-adk
-Version: 0.4.8
+Version: 0.4.11
 Summary: MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent & Complete Skills v2.0
 Project-URL: Homepage, https://github.com/modu-ai/moai-adk
 Project-URL: Repository, https://github.com/modu-ai/moai-adk
@@ -190,7 +190,7 @@ uv tool install moai-adk
 
 # Verify installation
 moai-adk --version
-# Output: MoAI-ADK v0.4.6
+# Output: MoAI-ADK v0.4.11
 ```
 
 Once installed, you can use the `moai-adk` command anywhere.
@@ -1108,7 +1108,7 @@ Hooks are **event-driven** scripts that trigger automatically at specific points
 #### 2. PreToolUse (Before Tool Execution)
 
 **Triggers**: Before executing file edits, Bash commands, or MultiEdit operations
-**Purpose**: Detect risky operations and automatically create safety checkpoints
+**Purpose**: Detect risky operations and automatically create safety checkpoints + TAG Guard
 
 **Protection Against**:
 - `rm -rf` (file deletion)
@@ -1116,13 +1116,30 @@ Hooks are **event-driven** scripts that trigger automatically at specific points
 - Editing critical files (`CLAUDE.md`, `config.json`)
 - Mass edits (10+ files at once via MultiEdit)
 
+**TAG Guard (New in v0.4.11)**:
+Automatically detects missing @TAG annotations in changed files:
+- Scans staged, modified, and untracked files
+- Warns when SPEC/TEST/CODE/DOC files lack required @TAG markers
+- Configurable rules via `.moai/tag-rules.json`
+- Non-blocking (gentle reminder, doesn't stop execution)
+
 **What You See**:
 ```
 🛡️ Checkpoint created: before-delete-20251023-143000
    Operation: delete
 ```
 
-**Why It Matters**: Prevents data loss from mistakes. You can always restore from the checkpoint if something goes wrong.
+Or when TAGs are missing:
+```
+⚠️ TAG 누락 감지: 생성/수정한 파일 중 @TAG가 없는 항목이 있습니다.
+ - src/auth/service.py → 기대 태그: @CODE:
+ - tests/test_auth.py → 기대 태그: @TEST:
+권장 조치:
+  1) SPEC/TEST/CODE/DOC 유형에 맞는 @TAG를 파일 상단 주석이나 헤더에 추가
+  2) rg로 확인: rg '@(SPEC|TEST|CODE|DOC):' -n <경로>
+```
+
+**Why It Matters**: Prevents data loss from mistakes and ensures @TAG traceability. You can always restore from the checkpoint if something goes wrong.
 
 #### 3. UserPromptSubmit (Prompt Input)
 
@@ -1185,7 +1202,7 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 | Hook | Status | Feature |
 |------|--------|---------|
 | **SessionStart** | ✅ Active | Project status summary (language, Git, SPEC progress, checkpoints) |
-| **PreToolUse** | ✅ Active | Risk detection + auto checkpoint (critical-delete, delete, merge, script) |
+| **PreToolUse** | ✅ Active | Risk detection + auto checkpoint (critical-delete, delete, merge, script) + **TAG Guard** (missing @TAG detection) |
 | **UserPromptSubmit** | ✅ Active | JIT context loading (auto-load related SPEC, tests, code, docs) |
 | **PostToolUse** | ✅ Active | Auto-run tests after code changes (9 languages: Python, TS, JS, Go, Rust, Java, Kotlin, Swift, Dart) |
 | **SessionEnd** | ✅ Active | Session cleanup and state saving |
@@ -1219,18 +1236,18 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 ---
 
-## v0.4 Series Updates (New!)
+## Latest Updates (New!)
 
 | Version    | Key Features                                                                         | Date       |
 | ---------- | ------------------------------------------------------------------------------------ | ---------- |
+| **v0.4.11** | ✨ TAG Guard system + CLAUDE.md formatting improvements + Code cleanup                | 2025-10-23 |
+| **v0.4.10** | 🔧 Hook robustness improvements + Bilingual documentation + Template language config | 2025-10-23 |
+| **v0.4.9** | 🎯 Hook JSON schema validation fixes + Comprehensive tests (468/468 passing)        | 2025-10-23 |
+| **v0.4.8** | 🚀 Release automation + PyPI deployment + Skills refinement                          | 2025-10-23 |
+| **v0.4.7** | 📖 Korean language optimization + SPEC-First principle documentation                 | 2025-10-22 |
 | **v0.4.6** | 🎉 Complete Skills v2.0 (100% Production-Ready) + 85,000 lines official docs + 300+ TDD examples | 2025-10-22 |
-| **v0.4.5** | ✅ CI/CD fixes + Multi-language README + Deployment cleanup                           | 2025-10-22 |
-| **v0.4.4** | Korean language support                                                              | 2025-10-21 |
-| **v0.4.3** | Interactive question tool (TUI menu)                                                 | 2025-10-21 |
-| **v0.4.1** | Skills localization                                                                  | 2025-10-21 |
-| **v0.4.0** | Claude Skills + AI team + 4-stage workflow                                          | 2025-10-21 |
 
-> 📦 **Install Now**: `pip install moai-adk==0.4.6` or `uv tool install moai-adk==0.4.6`
+> 📦 **Install Now**: `pip install moai-adk==0.4.11` or `uv tool install moai-adk==0.4.11`
 
 ---
 
@@ -1254,24 +1271,24 @@ Let’s build a Mini Kanban Board web application designed to help you master Mo
 
 ```mermaid
 gantt
-    title Mini Kanban Board — 4‑week plan
+    title Mini Kanban Board - 4-week plan
     dateFormat YYYY-MM-DD
 
     section Phase 1: Backend Basics
-    CH07: Define SPEC-001~004           :active, ch07-spec, 2025-11-03, 1d
-    CH07: Implement SpecScanner (TDD)   :active, ch07-impl, 2025-11-04, 1d
+    Define SPEC-001-004           :active, ch07-spec, 2025-11-03, 1d
+    Implement SpecScanner (TDD)   :active, ch07-impl, 2025-11-04, 1d
 
     section Phase 2: Backend Advanced
-    CH08: Implement REST API            :active, ch08-api, 2025-11-05, 1d
-    CH08: WebSocket + File Watch        :active, ch08-ws, 2025-11-06, 1d
+    Implement REST API            :active, ch08-api, 2025-11-05, 1d
+    WebSocket + File Watch        :active, ch08-ws, 2025-11-06, 1d
 
     section Phase 3: Frontend Basics
-    CH09: React init + SPEC-009~012     :active, ch09-spec, 2025-11-10, 1d
-    CH09: Kanban Board (TDD)            :active, ch09-impl, 2025-11-11, 1d
+    React init + SPEC-009-012     :active, ch09-spec, 2025-11-10, 1d
+    Kanban Board (TDD)            :active, ch09-impl, 2025-11-11, 1d
 
     section Phase 4: Advanced + Deploy
-    CH10: E2E + CI/CD                   :active, ch10-e2e, 2025-11-12, 1d
-    CH10: Docker Compose + Optimize     :active, ch10-deploy, 2025-11-13, 1d
+    E2E + CI/CD                   :active, ch10-e2e, 2025-11-12, 1d
+    Docker Compose + Optimize     :active, ch10-deploy, 2025-11-13, 1d
 ```
 
 ### 16‑SPEC Roadmap
@@ -1522,8 +1539,8 @@ cd frontend
 | ------------------------ | ------------------------------------------------------- |
 | **GitHub Repository**    | https://github.com/modu-ai/moai-adk                     |
 | **Issues & Discussions** | https://github.com/modu-ai/moai-adk/issues              |
-| **PyPI Package**         | https://pypi.org/project/moai-adk/ (Latest: v0.4.6)     |
-| **Latest Release**       | https://github.com/modu-ai/moai-adk/releases/tag/v0.4.6 |
+| **PyPI Package**         | https://pypi.org/project/moai-adk/ (Latest: v0.4.11)     |
+| **Latest Release**       | https://github.com/modu-ai/moai-adk/releases/tag/v0.4.11 |
 | **Documentation**        | See `.moai/`, `.claude/`, `docs/` within project        |
 
 ---
@@ -1544,10 +1561,12 @@ Start a new experience of **trustworthy AI development** with Alfred! 🤖
 
 ---
 
-**MoAI-ADK v0.4.6** — SPEC-First TDD with AI SuperAgent & Complete Skills v2.0
+**MoAI-ADK v0.4.11** — SPEC-First TDD with AI SuperAgent & Complete Skills v2.0 + TAG Guard
 - 📦 PyPI: https://pypi.org/project/moai-adk/
 - 🏠 GitHub: https://github.com/modu-ai/moai-adk
 - 📝 License: MIT
-- ⭐ Skills: 56/56 Complete (100% Production-Ready)
+- ⭐ Skills: 55+ Production-Ready Guides
+- ✅ Tests: 467/476 Passing (85.60% coverage)
+- 🏷️ TAG Guard: Automatic @TAG validation in PreToolUse Hook
 
 ---

{moai_adk-0.4.8 → moai_adk-0.4.11}/README.md

@@ -151,7 +151,7 @@ uv tool install moai-adk
 
 # Verify installation
 moai-adk --version
-# Output: MoAI-ADK v0.4.6
+# Output: MoAI-ADK v0.4.11
 ```
 
 Once installed, you can use the `moai-adk` command anywhere.
@@ -1069,7 +1069,7 @@ Hooks are **event-driven** scripts that trigger automatically at specific points
 #### 2. PreToolUse (Before Tool Execution)
 
 **Triggers**: Before executing file edits, Bash commands, or MultiEdit operations
-**Purpose**: Detect risky operations and automatically create safety checkpoints
+**Purpose**: Detect risky operations and automatically create safety checkpoints + TAG Guard
 
 **Protection Against**:
 - `rm -rf` (file deletion)
@@ -1077,13 +1077,30 @@ Hooks are **event-driven** scripts that trigger automatically at specific points
 - Editing critical files (`CLAUDE.md`, `config.json`)
 - Mass edits (10+ files at once via MultiEdit)
 
+**TAG Guard (New in v0.4.11)**:
+Automatically detects missing @TAG annotations in changed files:
+- Scans staged, modified, and untracked files
+- Warns when SPEC/TEST/CODE/DOC files lack required @TAG markers
+- Configurable rules via `.moai/tag-rules.json`
+- Non-blocking (gentle reminder, doesn't stop execution)
+
 **What You See**:
 ```
 🛡️ Checkpoint created: before-delete-20251023-143000
    Operation: delete
 ```
 
-**Why It Matters**: Prevents data loss from mistakes. You can always restore from the checkpoint if something goes wrong.
+Or when TAGs are missing:
+```
+⚠️ TAG 누락 감지: 생성/수정한 파일 중 @TAG가 없는 항목이 있습니다.
+ - src/auth/service.py → 기대 태그: @CODE:
+ - tests/test_auth.py → 기대 태그: @TEST:
+권장 조치:
+  1) SPEC/TEST/CODE/DOC 유형에 맞는 @TAG를 파일 상단 주석이나 헤더에 추가
+  2) rg로 확인: rg '@(SPEC|TEST|CODE|DOC):' -n <경로>
+```
+
+**Why It Matters**: Prevents data loss from mistakes and ensures @TAG traceability. You can always restore from the checkpoint if something goes wrong.
 
 #### 3. UserPromptSubmit (Prompt Input)
 
@@ -1146,7 +1163,7 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 | Hook | Status | Feature |
 |------|--------|---------|
 | **SessionStart** | ✅ Active | Project status summary (language, Git, SPEC progress, checkpoints) |
-| **PreToolUse** | ✅ Active | Risk detection + auto checkpoint (critical-delete, delete, merge, script) |
+| **PreToolUse** | ✅ Active | Risk detection + auto checkpoint (critical-delete, delete, merge, script) + **TAG Guard** (missing @TAG detection) |
 | **UserPromptSubmit** | ✅ Active | JIT context loading (auto-load related SPEC, tests, code, docs) |
 | **PostToolUse** | ✅ Active | Auto-run tests after code changes (9 languages: Python, TS, JS, Go, Rust, Java, Kotlin, Swift, Dart) |
 | **SessionEnd** | ✅ Active | Session cleanup and state saving |
@@ -1180,18 +1197,18 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 ---
 
-## v0.4 Series Updates (New!)
+## Latest Updates (New!)
 
 | Version    | Key Features                                                                         | Date       |
 | ---------- | ------------------------------------------------------------------------------------ | ---------- |
+| **v0.4.11** | ✨ TAG Guard system + CLAUDE.md formatting improvements + Code cleanup                | 2025-10-23 |
+| **v0.4.10** | 🔧 Hook robustness improvements + Bilingual documentation + Template language config | 2025-10-23 |
+| **v0.4.9** | 🎯 Hook JSON schema validation fixes + Comprehensive tests (468/468 passing)        | 2025-10-23 |
+| **v0.4.8** | 🚀 Release automation + PyPI deployment + Skills refinement                          | 2025-10-23 |
+| **v0.4.7** | 📖 Korean language optimization + SPEC-First principle documentation                 | 2025-10-22 |
 | **v0.4.6** | 🎉 Complete Skills v2.0 (100% Production-Ready) + 85,000 lines official docs + 300+ TDD examples | 2025-10-22 |
-| **v0.4.5** | ✅ CI/CD fixes + Multi-language README + Deployment cleanup                           | 2025-10-22 |
-| **v0.4.4** | Korean language support                                                              | 2025-10-21 |
-| **v0.4.3** | Interactive question tool (TUI menu)                                                 | 2025-10-21 |
-| **v0.4.1** | Skills localization                                                                  | 2025-10-21 |
-| **v0.4.0** | Claude Skills + AI team + 4-stage workflow                                          | 2025-10-21 |
 
-> 📦 **Install Now**: `pip install moai-adk==0.4.6` or `uv tool install moai-adk==0.4.6`
+> 📦 **Install Now**: `pip install moai-adk==0.4.11` or `uv tool install moai-adk==0.4.11`
 
 ---
 
@@ -1215,24 +1232,24 @@ Let’s build a Mini Kanban Board web application designed to help you master Mo
 
 ```mermaid
 gantt
-    title Mini Kanban Board — 4‑week plan
+    title Mini Kanban Board - 4-week plan
     dateFormat YYYY-MM-DD
 
     section Phase 1: Backend Basics
-    CH07: Define SPEC-001~004           :active, ch07-spec, 2025-11-03, 1d
-    CH07: Implement SpecScanner (TDD)   :active, ch07-impl, 2025-11-04, 1d
+    Define SPEC-001-004           :active, ch07-spec, 2025-11-03, 1d
+    Implement SpecScanner (TDD)   :active, ch07-impl, 2025-11-04, 1d
 
     section Phase 2: Backend Advanced
-    CH08: Implement REST API            :active, ch08-api, 2025-11-05, 1d
-    CH08: WebSocket + File Watch        :active, ch08-ws, 2025-11-06, 1d
+    Implement REST API            :active, ch08-api, 2025-11-05, 1d
+    WebSocket + File Watch        :active, ch08-ws, 2025-11-06, 1d
 
     section Phase 3: Frontend Basics
-    CH09: React init + SPEC-009~012     :active, ch09-spec, 2025-11-10, 1d
-    CH09: Kanban Board (TDD)            :active, ch09-impl, 2025-11-11, 1d
+    React init + SPEC-009-012     :active, ch09-spec, 2025-11-10, 1d
+    Kanban Board (TDD)            :active, ch09-impl, 2025-11-11, 1d
 
     section Phase 4: Advanced + Deploy
-    CH10: E2E + CI/CD                   :active, ch10-e2e, 2025-11-12, 1d
-    CH10: Docker Compose + Optimize     :active, ch10-deploy, 2025-11-13, 1d
+    E2E + CI/CD                   :active, ch10-e2e, 2025-11-12, 1d
+    Docker Compose + Optimize     :active, ch10-deploy, 2025-11-13, 1d
 ```
 
 ### 16‑SPEC Roadmap
@@ -1483,8 +1500,8 @@ cd frontend
 | ------------------------ | ------------------------------------------------------- |
 | **GitHub Repository**    | https://github.com/modu-ai/moai-adk                     |
 | **Issues & Discussions** | https://github.com/modu-ai/moai-adk/issues              |
-| **PyPI Package**         | https://pypi.org/project/moai-adk/ (Latest: v0.4.6)     |
-| **Latest Release**       | https://github.com/modu-ai/moai-adk/releases/tag/v0.4.6 |
+| **PyPI Package**         | https://pypi.org/project/moai-adk/ (Latest: v0.4.11)     |
+| **Latest Release**       | https://github.com/modu-ai/moai-adk/releases/tag/v0.4.11 |
 | **Documentation**        | See `.moai/`, `.claude/`, `docs/` within project        |
 
 ---
@@ -1505,10 +1522,12 @@ Start a new experience of **trustworthy AI development** with Alfred! 🤖
 
 ---
 
-**MoAI-ADK v0.4.6** — SPEC-First TDD with AI SuperAgent & Complete Skills v2.0
+**MoAI-ADK v0.4.11** — SPEC-First TDD with AI SuperAgent & Complete Skills v2.0 + TAG Guard
 - 📦 PyPI: https://pypi.org/project/moai-adk/
 - 🏠 GitHub: https://github.com/modu-ai/moai-adk
 - 📝 License: MIT
-- ⭐ Skills: 56/56 Complete (100% Production-Ready)
+- ⭐ Skills: 55+ Production-Ready Guides
+- ✅ Tests: 467/476 Passing (85.60% coverage)
+- 🏷️ TAG Guard: Automatic @TAG validation in PreToolUse Hook
 
 ---

{moai_adk-0.4.8 → moai_adk-0.4.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "moai-adk"
-version = "0.4.8"
+version = "0.4.11"
 description = "MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent & Complete Skills v2.0"
 readme = "README.md"
 requires-python = ">=3.13"

moai_adk-0.4.11/src/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-0.4.8 → moai_adk-0.4.11}/src/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 (