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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moai-adk
-Version: 0.4.10
+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.10
+# 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 |
 
-> 📦 **Install Now**: `pip install moai-adk==0.4.10` or `uv tool install moai-adk==0.4.10`
+> 📦 **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,11 +1561,12 @@ Start a new experience of **trustworthy AI development** with Alfred! 🤖
 
 ---
 
-**MoAI-ADK v0.4.10** — 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: 55+ Production-Ready Guides
-- ✅ Tests: 468/468 Passing (86% coverage)
+- ✅ Tests: 467/476 Passing (85.60% coverage)
+- 🏷️ TAG Guard: Automatic @TAG validation in PreToolUse Hook
 
 ---

{moai_adk-0.4.10 → 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.10
+# 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 |
 
-> 📦 **Install Now**: `pip install moai-adk==0.4.10` or `uv tool install moai-adk==0.4.10`
+> 📦 **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,11 +1522,12 @@ Start a new experience of **trustworthy AI development** with Alfred! 🤖
 
 ---
 
-**MoAI-ADK v0.4.10** — 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: 55+ Production-Ready Guides
-- ✅ Tests: 468/468 Passing (86% coverage)
+- ✅ Tests: 467/476 Passing (85.60% coverage)
+- 🏷️ TAG Guard: Automatic @TAG validation in PreToolUse Hook
 
 ---

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

@@ -1,6 +1,6 @@
 [project]
 name = "moai-adk"
-version = "0.4.10"
+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.10 → 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 (

{moai_adk-0.4.10 → moai_adk-0.4.11}/src/moai_adk/templates/.claude/hooks/alfred/core/__init__.py

@@ -136,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-0.4.11/src/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

{moai_adk-0.4.10 → moai_adk-0.4.11}/src/moai_adk/templates/.claude/hooks/alfred/handlers/tool.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# @CODE:HOOK-TOOL-001 | SPEC: TBD | TEST: tests/hooks/test_handlers.py
 """Tool usage handlers
 
 PreToolUse, PostToolUse event handling
@@ -6,6 +7,7 @@ PreToolUse, PostToolUse event handling
 
 from core import HookPayload, HookResult
 from core.checkpoint import create_checkpoint, detect_risky_operation
+from core.tags import scan_recent_changes_for_missing_tags
 
 
 def handle_pre_tool_use(payload: HookPayload) -> HookResult:
@@ -44,20 +46,38 @@ def handle_pre_tool_use(payload: HookPayload) -> HookResult:
     tool_args = payload.get("arguments", {})
     cwd = payload.get("cwd", ".")
 
-    # Dangerous operation detection
-    is_risky, operation_type = detect_risky_operation(tool_name, tool_args, cwd)
-
-    # Create checkpoint when danger is detected
-    if is_risky:
-        checkpoint_branch = create_checkpoint(cwd, operation_type)
-
-        if checkpoint_branch != "checkpoint-failed":
-            system_message = (
-                f"🛡️ Checkpoint created: {checkpoint_branch}\n"
-                f"   Operation: {operation_type}"
-            )
-
-            return HookResult(system_message=system_message, continue_execution=True)
+    # Dangerous operation detection (best-effort)
+    try:
+        is_risky, operation_type = detect_risky_operation(tool_name, tool_args, cwd)
+        # Create checkpoint when danger is detected
+        if is_risky:
+            checkpoint_branch = create_checkpoint(cwd, operation_type)
+            if checkpoint_branch != "checkpoint-failed":
+                system_message = (
+                    f"🛡️ Checkpoint created: {checkpoint_branch}\n"
+                    f"   Operation: {operation_type}"
+                )
+                return HookResult(system_message=system_message, continue_execution=True)
+    except Exception:
+        # Do not fail the hook if risk detection errors out
+        pass
+
+    # TAG Guard (gentle): warn when recent changes miss @TAG
+    issues = scan_recent_changes_for_missing_tags(cwd)
+    if issues:
+        # Summarize first few issues for display
+        preview = "\n".join(
+            f" - {i.path} → 기대 태그: {i.expected}" for i in issues[:5]
+        )
+        more = "" if len(issues) <= 5 else f"\n (외 {len(issues)-5}건 더 존재)"
+        msg = (
+            "⚠️ TAG 누락 감지: 생성/수정한 파일 중 @TAG가 없는 항목이 있습니다.\n"
+            f"{preview}{more}\n"
+            "권장 조치:\n"
+            "  1) SPEC/TEST/CODE/DOC 유형에 맞는 @TAG를 파일 상단 주석이나 헤더에 추가\n"
+            "  2) rg로 확인: rg '@(SPEC|TEST|CODE|DOC):' -n <경로>\n"
+        )
+        return HookResult(system_message=msg, continue_execution=True)
 
     return HookResult(continue_execution=True)
 

{moai_adk-0.4.10 → moai_adk-0.4.11}/src/moai_adk/templates/.claude/hooks/alfred/test_hook_output.py

@@ -23,7 +23,7 @@ HOOKS_DIR = Path(__file__).parent
 if str(HOOKS_DIR) not in sys.path:
     sys.path.insert(0, str(HOOKS_DIR))
 
-from core import HookResult
+from core import HookResult  # noqa: E402
 
 
 def test_basic_output():

{moai_adk-0.4.10 → moai_adk-0.4.11}/src/moai_adk/templates/.claude/skills/moai-cc-hooks/scripts/validate-bash-command.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# @CODE:HOOK-BASH-001 | SPEC: TBD | TEST: tests/hooks/test_bash_validation.py
 # Bash command validator (from Context7 official docs)
 import json
 import re
@@ -14,11 +15,10 @@ BLOCKED = [
 try:
     data = json.load(sys.stdin)
     cmd = data.get("tool_input", {}).get("command", "")
-    
     for pattern, msg in BLOCKED:
         if re.search(pattern, cmd):
             print(f"🔴 {msg}", file=sys.stderr)
             sys.exit(2)
     sys.exit(0)
-except:
+except Exception:
     sys.exit(0)