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

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

@@ -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/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/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/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/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)

moai_adk/templates/CLAUDE.md

@@ -1,10 +1,11 @@
+<!-- @DOC:CLAUDE-001 | SPEC: TBD -->
 # MoAI-ADK - MoAI-Agentic Development Kit
 
-**SPEC-First TDD Development with Alfred SuperAgent**
+## SPEC-First TDD Development with Alfred SuperAgent
 
 > **Document Language**: {{conversation_language_name}} ({{conversation_language}})
 > **Project Owner**: {{project_owner}}
-> **Config**: `.moai/config.json` → `project.conversation_language`
+> **Config**: `.moai/config.json`
 >
 > All interactions with Alfred can use `Skill("moai-alfred-interactive-questions")` for TUI-based responses.
 
@@ -81,6 +82,7 @@ The **code-builder pipeline** runs two Sonnet specialists in sequence: **impleme
 The **Explore** agent excels at navigating large codebases.
 
 **Use cases**:
+
 - ✅ **Code analysis** (understand complex implementations, trace dependencies, study architecture)
 - ✅ Search for specific keywords or patterns (e.g., "API endpoints", "authentication logic")
 - ✅ Locate files (e.g., `src/components/**/*.tsx`)
@@ -88,6 +90,7 @@ The **Explore** agent excels at navigating large codebases.
 - ✅ Search across many files (Glob + Grep patterns)
 
 **Recommend Explore when**:
+
 - 🔍 You need to understand a complex structure
 - 🔍 The implementation spans multiple files
 - 🔍 You want the end-to-end flow of a feature
@@ -95,6 +98,7 @@ The **Explore** agent excels at navigating large codebases.
 - 🔍 You're planning a refactor and need impact analysis
 
 **Usage examples**:
+
 ```python
 # 1. Deep code analysis
 Task(
@@ -125,6 +129,9 @@ User: "Where is JWT authentication implemented in this project?"
 ```
 
 **thoroughness levels** (declare explicitly inside the prompt text):
+
+**thoroughness levels** (declare explicitly inside the prompt text):
+
 - `quick`: fast scan (basic patterns)
 - `medium`: moderate sweep (multiple locations + naming rules) — **recommended**
 - `very thorough`: exhaustive scan (full codebase analysis)
@@ -145,7 +152,7 @@ Alfred relies on 55 Claude Skills grouped by tier. Skills load via Progressive D
 | Claude Code Ops | 1      | Session management                           |
 | **Total**       | **55** | Complete knowledge capsule library           |
 
-**Foundation Tier (6)**
+### Foundation Tier (6)
 
 | Skill                   | Purpose                                 | Auto-load                      |
 | ----------------------- | --------------------------------------- | ------------------------------ |
@@ -156,7 +163,7 @@ Alfred relies on 55 Claude Skills grouped by tier. Skills load via Progressive D
 | `moai-foundation-git`   | GitFlow automation & PR policy          | Plan/Run/Sync                  |
 | `moai-foundation-langs` | Language detection & Skill preload      | SessionStart, `/alfred:2-run`  |
 
-**Essentials Tier (4)**
+### Essentials Tier (4)
 
 | Skill                      | Purpose                                       | Auto-load                                  |
 | -------------------------- | --------------------------------------------- | ------------------------------------------ |
@@ -165,7 +172,7 @@ Alfred relies on 55 Claude Skills grouped by tier. Skills load via Progressive D
 | `moai-essentials-refactor` | Refactoring patterns & code-smell remediation | `/alfred:2-run`                            |
 | `moai-essentials-review`   | Code review checklist & quality feedback      | `/alfred:3-sync`                           |
 
-**Alfred Tier (11)** — Internal workflow orchestration
+### Alfred Tier (11) — Internal workflow orchestration
 
 | Skill                                  | Purpose                              | Auto-load                         |
 | -------------------------------------- | ------------------------------------ | --------------------------------- |
@@ -181,11 +188,11 @@ Alfred relies on 55 Claude Skills grouped by tier. Skills load via Progressive D
 | `moai-alfred-trust-validation`         | TRUST 5 principle verification       | All phases                        |
 | `moai-alfred-interactive-questions`    | Interactive user surveys & menus     | On demand                         |
 
-**Domain Tier (10)** — `moai-domain-backend`, `web-api`, `frontend`, `mobile-app`, `security`, `devops`, `database`, `data-science`, `ml`, `cli-tool`.
+### Domain Tier (10) — `moai-domain-backend`, `web-api`, `frontend`, `mobile-app`, `security`, `devops`, `database`, `data-science`, `ml`, `cli-tool`
 
-**Language Tier (23)** — Python, TypeScript, Go, Rust, Java, Kotlin, Swift, Dart, C/C++, C#, Scala, Haskell, Elixir, Clojure, Lua, Ruby, PHP, JavaScript, SQL, Shell, Julia, R, plus supporting stacks.
+### Language Tier (23) — Python, TypeScript, Go, Rust, Java, Kotlin, Swift, Dart, C/C++, C#, Scala, Haskell, Elixir, Clojure, Lua, Ruby, PHP, JavaScript, SQL, Shell, Julia, R, plus supporting stacks
 
-**Claude Code Ops (1)** — `moai-claude-code` manages session settings, output styles, and Skill deployment.
+### Claude Code Ops (1) — `moai-claude-code` manages session settings, output styles, and Skill deployment
 
 Skills keep the core knowledge lightweight while allowing Alfred to assemble the right expertise for each request.
 
@@ -205,6 +212,7 @@ Skills keep the core knowledge lightweight while allowing Alfred to assemble the
 | **Claude 4.5 Sonnet** | Planning, implementation, troubleshooting, session ops               | Alfred, project-manager, spec-builder, code-builder pipeline, debug-helper, cc-manager | Deep reasoning, multi-step synthesis, creative problem solving |
 
 **Guidelines**:
+
 - Default to **Haiku** when the task is pattern-driven or requires rapid iteration; escalate to **Sonnet** for novel design, architecture, or ambiguous problem solving.
 - Record any manual model switch in the task notes (who, why, expected benefit).
 - Combine both models when needed: e.g., Sonnet plans a refactor, Haiku formats and validates the resulting docs.
@@ -230,13 +238,14 @@ Alfred commands follow a three-phase loop, with an optional bootstrap stage for
 #### Pre-suggestion Checklist
 
 Before suggesting the next step, always verify:
+
 - You have the latest status from agents.
 - All blockers are documented with context.
 - Required approvals or user confirmations are noted.
 - Suggested tasks include clear owners and outcomes.
 - There is at most one "must-do" suggestion per step.
 
-**cc-manager validation sequence**
+### cc-manager validation sequence
 
 1. **SPEC** – Confirm the SPEC file exists and note its status (`draft`, `active`, `completed`, `archived`). If missing, queue `/alfred:1-plan`.
 2. **TEST & CODE** – Check whether tests and implementation files exist and whether the latest test run passed. Address failing tests before proposing new work.
@@ -290,7 +299,7 @@ Before suggesting the next step, always verify:
 
 #### Message Format
 
-```
+```text
 🔴 <Title>
 - Cause: <root cause>
 - Scope: <affected components>
@@ -310,7 +319,7 @@ Before suggesting the next step, always verify:
 
 #### Commit Structure
 
-```
+```text
 <type>(scope): <subject>
 
 - Context of the change
@@ -374,7 +383,7 @@ Claude Code now features an **Interactive Question Tool** powered by the `moai-a
 
 When you provide a high-level request, Alfred may invoke the `moai-alfred-interactive-questions` Skill to clarify implementation details through structured TUI menus:
 
-```
+```text
 User: "Add a completion page for the competition."
          ↓
 Alfred analyzes codebase & context
@@ -410,6 +419,7 @@ Execution with confirmed specifications
 ```
 
 **Where it's used**:
+
 - Sub-agents (spec-builder, code-builder pipeline) invoke this skill when ambiguity is detected
 - Alfred commands may trigger interactive surveys during Plan/Run/Sync phases
 - User approvals and architectural decisions benefit most from TUI-based selection
@@ -427,6 +437,7 @@ Execution with confirmed specifications
 ### When to Use Interactive Questions
 
 **Ideal for**:
+
 - 🎯 Complex features with multiple valid approaches
 - 🎯 Architectural decisions with trade-offs
 - 🎯 Ambiguous or high-level requirements
@@ -434,6 +445,7 @@ Execution with confirmed specifications
 - 🎯 Decisions involving user experience or data flow
 
 **Example triggers**:
+
 - "Add a dashboard" → needs clarification on layout, data sources, authentication
 - "Refactor the auth system" → needs clarification on scope, backwards compatibility, migration strategy
 - "Optimize performance" → needs clarification on which bottleneck, acceptable trade-offs
@@ -469,14 +481,16 @@ Execution with confirmed specifications
 
 **User Request**: "Competition is over. Add a completion page."
 
-**Step 1: Code Analysis**
+#### Step 1: Code Analysis
+
 Alfred scans the codebase and detects:
+
 - Existing `/end` page (auth required, shows results)
 - Need for clarification on scope and user behavior
 
-**Step 2: Interactive Survey (moai-alfred-interactive-questions activated)**
+#### Step 2: Interactive Survey (moai-alfred-interactive-questions activated)
 
-```
+```text
 ────────────────────────────────────────────────────────────────
 ALFRED: How should the completion page be implemented?
 ────────────────────────────────────────────────────────────────
@@ -501,7 +515,7 @@ ALFRED: How should the completion page be implemented?
 → Selection: Create a new public page (/competition-closed)
 ```
 
-```
+```text
 ────────────────────────────────────────────────────────────────
 ALFRED: For logged-in participants accessing the new page?
 ────────────────────────────────────────────────────────────────
@@ -525,9 +539,9 @@ ALFRED: For logged-in participants accessing the new page?
 → Selection: Show simple completion message only
 ```
 
-**Step 3: Review & Confirmation**
+#### Step 3: Review & Confirmation
 
-```
+```text
 ────────────────────────────────────────────────────────────────
 ALFRED: Review your answers
 ────────────────────────────────────────────────────────────────
@@ -549,9 +563,10 @@ ALFRED: Review your answers
 → Action: Submit answers (enter)
 ```
 
-**Step 4: Execution**
+#### Step 4: Execution
 
 Alfred now executes with **confirmed specifications**:
+
 - ✅ Creates `/app/competition-closed/page.tsx` (public route)
 - ✅ Implements simple "Competition concluded" message
 - ✅ Handles authenticated users appropriately
@@ -655,7 +670,7 @@ Combine layers when necessary: a command triggers sub-agents, sub-agents activat
 
 ### TAG Block Template
 
-```
+```text
 // @CODE:AUTH-001 | SPEC: SPEC-AUTH-001.md | TEST: tests/auth/service.test.ts
 ```
 
@@ -686,6 +701,7 @@ Combine layers when necessary: a command triggers sub-agents, sub-agents activat
 ### TAG Validation & Integrity
 
 **Avoid duplicates**:
+
 ```bash
 rg "@SPEC:AUTH" -n          # Search AUTH specs
 rg "@CODE:AUTH-001" -n      # Targeted ID search
@@ -693,6 +709,7 @@ rg "AUTH-001" -n            # Global ID search
 ```
 
 **TAG chain verification** (`/alfred:3-sync` runs automatically):
+
 ```bash
 rg '@(SPEC|TEST|CODE|DOC):' -n .moai/specs/ tests/ src/ docs/
 
@@ -722,18 +739,21 @@ Alfred enforces these quality gates on every change:
 ## Language-specific Code Rules
 
 **Global constraints**:
+
 - Files ≤ 300 LOC
 - Functions ≤ 50 LOC
 - Parameters ≤ 5
 - Cyclomatic complexity ≤ 10
 
 **Quality targets**:
+
 - Test coverage ≥ 85%
 - Intent-revealing names
 - Early guard clauses
 - Use language-standard tooling
 
 **Testing strategy**:
+
 - Prefer the standard framework per language
 - Keep tests isolated and deterministic
 - Derive cases directly from the SPEC
@@ -743,6 +763,7 @@ Alfred enforces these quality gates on every change:
 ## TDD Workflow Checklist
 
 **Step 1: SPEC authoring** (`/alfred:1-plan`)
+
 - [ ] Create `.moai/specs/SPEC-<ID>/spec.md` (with directory structure)
 - [ ] Add YAML front matter (id, version: 0.0.1, status: draft, created)
 - [ ] Include the `@SPEC:ID` TAG
@@ -751,12 +772,14 @@ Alfred enforces these quality gates on every change:
 - [ ] Check for duplicate IDs: `rg "@SPEC:<ID>" -n`
 
 **Step 2: TDD implementation** (`/alfred:2-run`)
+
 - [ ] **RED**: Write `@TEST:ID` under `tests/` and watch it fail
 - [ ] **GREEN**: Add `@CODE:ID` under `src/` and make the test pass
 - [ ] **REFACTOR**: Improve code quality; document TDD history in comments
 - [ ] List SPEC/TEST file paths in the TAG block
 
 **Step 3: Documentation sync** (`/alfred:3-sync`)
+
 - [ ] Scan TAGs: `rg '@(SPEC|TEST|CODE):' -n`
 - [ ] Ensure no orphan TAGs remain
 - [ ] Regenerate the Living Document

{moai_adk-0.4.10.dist-info → moai_adk-0.4.11.dist-info}/METADATA

@@ -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.dist-info → moai_adk-0.4.11.dist-info}/RECORD

@@ -38,7 +38,7 @@ moai_adk/core/template/languages.py,sha256=V0wLcxCIOve9Q_0_NhrHGQevSIN_MB612GwrO
 moai_adk/core/template/merger.py,sha256=ZV8_U1HZJ3bfAtgyNmSxgj8KdTMt4eUnUG6kVVRT7bE,6909
 moai_adk/core/template/processor.py,sha256=W4M3BNrlfA0dHRwvPWIkJmJwhkNDglXaNzsYBoVTSnQ,17019
 moai_adk/templates/.gitignore,sha256=6VNKResdDpyaii3cmJA4pOLwK2PhYARIWkUODYtKyxg,310
-moai_adk/templates/CLAUDE.md,sha256=9eF_fWzNJucNBKAChoaJzVXa-LLhK4Cv7j4XZ1Whl8o,42030
+moai_adk/templates/CLAUDE.md,sha256=k4XxvngGZkdGO24As5cNIGv9R7wdA0JlLt4_FMDZ7pE,42149
 moai_adk/templates/__init__.py,sha256=6MV1gCB7PLZMiL4gaD_dZSKxtcQyo45MMTuN8fVdchA,104
 moai_adk/templates/.claude/settings.json,sha256=sXQ8gV3oyZJHqPHMxYaH-ps-LXliIMpLMj-Xx2jjE7o,3269
 moai_adk/templates/.claude/agents/alfred/cc-manager.md,sha256=nyiNtcSqvLKK8Mp88hhTFBqrpsRiTqtNTpnAo1m0qQg,8048
@@ -59,16 +59,17 @@ moai_adk/templates/.claude/commands/alfred/2-run.md,sha256=UMscmBrpqysmWoKvwyGXE
 moai_adk/templates/.claude/commands/alfred/3-sync.md,sha256=xF9XnP20cJrRuCFEG_J3RnZtwMy5Ym3nj_f6eryBFBE,21535
 moai_adk/templates/.claude/hooks/alfred/HOOK_SCHEMA_VALIDATION.md,sha256=5dd6KRFQXzp0L8lAWKRN7Momgg_8XNV1QZ6VGs03_pc,9064
 moai_adk/templates/.claude/hooks/alfred/README.md,sha256=8JirNg3Jn2OUFmHySYBd8QxQgPkG7kcev86Zkf80asY,6852
-moai_adk/templates/.claude/hooks/alfred/alfred_hooks.py,sha256=dPlwlj7LlsJd-c-D5ONiQGkih4qULFcjzNvZQyto_kc,7547
-moai_adk/templates/.claude/hooks/alfred/test_hook_output.py,sha256=zxA330umo4HHoYe_reOocqDeIU3OMBd31rcEfY9QR-U,5632
-moai_adk/templates/.claude/hooks/alfred/core/__init__.py,sha256=Cz1YeL6c5j2ZhJwG3y-lpxde7paJ00tEaYRduc5gDoM,6375
+moai_adk/templates/.claude/hooks/alfred/alfred_hooks.py,sha256=ILYbruVD1o284wmKPFaE2LPARekVtecpcovCvqy7eEc,7570
+moai_adk/templates/.claude/hooks/alfred/test_hook_output.py,sha256=3pk-JBUPdSQZBjx27qKu-db7D1WFYBmlIZmeAFBil6M,5646
+moai_adk/templates/.claude/hooks/alfred/core/__init__.py,sha256=nx_02kZDVFlKOgxBfFz3nqVrxMkmrkE0x7crJhdjl5E,6377
 moai_adk/templates/.claude/hooks/alfred/core/checkpoint.py,sha256=dsvFDSXQNSQlaQLpvhqFbytGOrOivyovi43Y18EmNeI,8483
 moai_adk/templates/.claude/hooks/alfred/core/context.py,sha256=RQd6yk8OGT-twgYtUiNmJIL-UEt_h4oktxqiRP_wXAI,2103
 moai_adk/templates/.claude/hooks/alfred/core/project.py,sha256=XVm-Y5TVjBBznW8AkFhk_uVg-EF1lZ2wx59Rxt_LOBA,9125
+moai_adk/templates/.claude/hooks/alfred/core/tags.py,sha256=XcYYCS1VmCejp7Ga9xZ3hDfrWWsKM-WyPD_N5gY1q1w,6359
 moai_adk/templates/.claude/hooks/alfred/handlers/__init__.py,sha256=j5L7nayKt7tnFQOZuO5sWiie815vmbmYJOn2VRiidLY,569
 moai_adk/templates/.claude/hooks/alfred/handlers/notification.py,sha256=8TcEqGlz4EpLf2lpouaIuhVbpKOVeY31KPmIq2snt9U,662
 moai_adk/templates/.claude/hooks/alfred/handlers/session.py,sha256=jGmiDPY-unTlQlTWQVisr82Rxhbt1Rkhrun4bggTxQ4,3374
-moai_adk/templates/.claude/hooks/alfred/handlers/tool.py,sha256=PBtx72UbHwTt59jlL3Wkv54O3_N-Px5Ow-WEmDMAEpM,2260
+moai_adk/templates/.claude/hooks/alfred/handlers/tool.py,sha256=0bNtAf2M7nupTAkcrEiZMBCmD2f-dLjjZa5p1CWiNyM,3383
 moai_adk/templates/.claude/hooks/alfred/handlers/user.py,sha256=PyQI201oezWBzLrKo8ntWoRa9GDyVwLYktdu9vLT84s,1389
 moai_adk/templates/.claude/output-styles/alfred/agentic-coding.md,sha256=nSP5iB5TOVf7WOqAibb28WpWFehCTG3-8WLY77l5o1M,19376
 moai_adk/templates/.claude/output-styles/alfred/moai-adk-learning.md,sha256=fXsSMavQ3v9l64JST1LCR3BRJ8id9AvJ4N3pf1KwCog,17294
@@ -103,7 +104,7 @@ moai_adk/templates/.claude/skills/moai-cc-commands/templates/command-template.md
 moai_adk/templates/.claude/skills/moai-cc-hooks/SKILL.md,sha256=ZZmnr68CJUVQ_nvVzISm3Dbi3CdMYbeU7y9riGQ7SN8,6114
 moai_adk/templates/.claude/skills/moai-cc-hooks/scripts/pre-bash-check.sh,sha256=_I5PrOGLp6uSDgRyoXFbO1-OpCPRte0tyPdB-JzRiMQ,319
 moai_adk/templates/.claude/skills/moai-cc-hooks/scripts/preserve-permissions.sh,sha256=aZt473lVf5zL3t3ZVwEVsFYGneeyqWgJQe6ZXA9ewBI,474
-moai_adk/templates/.claude/skills/moai-cc-hooks/scripts/validate-bash-command.py,sha256=9-7Em28aS9wGEVeo3FXGglJ_5RNKEBOOWzNzTeJb5Ps,592
+moai_adk/templates/.claude/skills/moai-cc-hooks/scripts/validate-bash-command.py,sha256=EUuQO_QFufNIRA4O1MkacM9ij0Rwsgzxe2okFcc_nJM,675
 moai_adk/templates/.claude/skills/moai-cc-mcp-plugins/SKILL.md,sha256=O2QBmBKe6lyU-sXyxhWzTdgTLuxxKvKzES-hV4EQetA,4887
 moai_adk/templates/.claude/skills/moai-cc-mcp-plugins/templates/settings-mcp-template.json,sha256=t2B7_Jd6DQbrSi2HmhdLLTYphy9UTOnch9FsV79onMw,968
 moai_adk/templates/.claude/skills/moai-cc-memory/SKILL.md,sha256=H51IpkBCD2vCYIjynO_77whsamCuPE2uieudybW0yJU,7726
@@ -260,8 +261,8 @@ moai_adk/templates/.moai/project/tech.md,sha256=REecMv8wOvutt-pQZ5nlGk5YdReTan7A
 moai_adk/utils/__init__.py,sha256=VnVfQzzKHvKw4bNdEw5xdscnRQYFrnr-v_TOBr3naPs,225
 moai_adk/utils/banner.py,sha256=znppKd5yo-tTqgyhgPVJjstrTrfcy_v3X1_RFQxP4Fk,1878
 moai_adk/utils/logger.py,sha256=g-m07PGKjK2bKRIInfSn6m-024Bedai-pV_WjZKDeu8,5064
-moai_adk-0.4.10.dist-info/METADATA,sha256=o-wzIPH9FTTUj3Ta4mbhbeepWXmxWALSCVBmySStonk,61844
-moai_adk-0.4.10.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-moai_adk-0.4.10.dist-info/entry_points.txt,sha256=P9no1794UipqH72LP-ltdyfVd_MeB1WKJY_6-JQgV3U,52
-moai_adk-0.4.10.dist-info/licenses/LICENSE,sha256=M1M2b07fWcSWRM6_P3wbZKndZvyfHyYk_Wu9bS8F7o8,1069
-moai_adk-0.4.10.dist-info/RECORD,,
+moai_adk-0.4.11.dist-info/METADATA,sha256=Aby3HbsAA95ekpDTArVQKFtTdfAsq-_Cnw-k3vpUUuU,62660
+moai_adk-0.4.11.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+moai_adk-0.4.11.dist-info/entry_points.txt,sha256=P9no1794UipqH72LP-ltdyfVd_MeB1WKJY_6-JQgV3U,52
+moai_adk-0.4.11.dist-info/licenses/LICENSE,sha256=M1M2b07fWcSWRM6_P3wbZKndZvyfHyYk_Wu9bS8F7o8,1069
+moai_adk-0.4.11.dist-info/RECORD,,