moai-adk 0.32.8__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/commands/moai/9-feedback.md

@@ -2,23 +2,23 @@
 name: moai:9-feedback
 description: "Submit feedback or report issues"
 argument-hint: "[issue|suggestion|question]"
-allowed-tools: Read, Write, Edit, Grep, Glob, WebFetch, WebSearch, Bash, TodoWrite, AskUserQuestion, Task, Skill
+allowed-tools: Task, AskUserQuestion, TodoWrite
 model: haiku
 ---
 
-##  Pre-execution Context
+## Pre-execution Context
 
 !git status --porcelain
 !git branch --show-current
 !git log --oneline -1
 
-##  Essential Files
+## Essential Files
 
 @.moai/config/config.yaml
 
 ---
 
-#  MoAI-ADK Step 9: Feedback Loop
+# MoAI-ADK Step 9: Feedback Loop
 
 > Architecture: Commands → Agents → Skills. This command orchestrates ONLY through `Task()` tool.
 > Delegation Model: Feedback collection delegated to `manager-quality` agent.
@@ -27,7 +27,7 @@ Workflow Integration: This command implements the feedback loop of the MoAI work
 
 ---
 
-##  Command Purpose
+## Command Purpose
 
 Collect user feedback, bug reports, or feature suggestions and create GitHub issues automatically.
 
@@ -35,20 +35,17 @@ Run on: `$ARGUMENTS` (Feedback type)
 
 ---
 
-##  Execution Philosophy
+## Execution Philosophy
 
-`/moai:9-feedback` performs feedback collection through agent delegation:
+/moai:9-feedback performs feedback collection through agent delegation:
 
-```
-User Command: /moai:9-feedback [type]
-    ↓
-Phase 1: Task(subagent_type="manager-quality")
-    → Analyze feedback type
-    → Collect details via AskUserQuestion
-    → Create GitHub Issue via Skill
-    ↓
-Output: Issue created with link
-```
+Execution Flow:
+- User Command: /moai:9-feedback [type]
+- Phase 1: Task with subagent_type "manager-quality"
+  - Analyze feedback type
+  - Collect details via AskUserQuestion
+  - Create GitHub Issue via Skill
+- Output: Issue created with link
 
 ### Key Principle: Full Delegation Pattern
 
@@ -69,11 +66,11 @@ This command exclusively uses these tools:
 
 ---
 
-##  Associated Agents & Skills
+## Associated Agents and Skills
 
-| Agent/Skill     | Purpose                                       |
-| --------------- | --------------------------------------------- |
-| manager-quality | Feedback collection and GitHub issue creation |
+Associated Agents for Feedback Collection:
+
+- manager-quality: Feedback collection and GitHub issue creation
 
 ---
 
@@ -81,7 +78,7 @@ This command exclusively uses these tools:
 
 This command uses agent execution patterns defined in CLAUDE.md (lines 96-120).
 
-### Sequential Phase-Based Chaining ✅
+### Sequential Phase-Based Chaining PASS
 
 Command implements simple sequential execution through 2 phases:
 
@@ -97,7 +94,7 @@ WHY: Sequential execution ensures complete feedback capture before submission
 
 IMPACT: Skipping Phase 1 would create incomplete GitHub issues
 
-### Parallel Execution ❌
+### Parallel Execution FAIL
 
 Not applicable - simple linear workflow
 
@@ -108,7 +105,7 @@ WHY: Feedback workflow has minimal complexity
 
 IMPACT: Parallel execution unnecessary for single-agent linear workflow
 
-### Resumable Agent Support ❌
+### Resumable Agent Support FAIL
 
 Not applicable - command completes in single execution
 
@@ -125,7 +122,7 @@ Refer to CLAUDE.md "Agent Chaining Patterns" (lines 96-120) for complete pattern
 
 ---
 
-##  Execution Process
+## Execution Process
 
 ### Step 1: Delegate to Quality Gate Agent
 
@@ -204,7 +201,7 @@ Language and Accessibility:
 
 ---
 
-##  Summary: Execution Verification Checklist
+## Summary: Execution Verification Checklist
 
 Before considering command execution complete, verify all requirements:
 
@@ -226,14 +223,23 @@ Before considering command execution complete, verify all requirements:
 
 ---
 
-##  Quick Reference
+## Quick Reference
+
+Scenario: Report bug
+- Entry Point: /moai:9-feedback issue
+- Expected Outcome: GitHub issue created with bug label
+
+Scenario: Request feature
+- Entry Point: /moai:9-feedback suggestion
+- Expected Outcome: GitHub issue created with enhancement label
+
+Scenario: Ask question
+- Entry Point: /moai:9-feedback question
+- Expected Outcome: GitHub issue created with question label
 
-| Scenario         | Entry Point                   | Expected Outcome                            |
-| ---------------- | ----------------------------- | ------------------------------------------- |
-| Report bug       | `/moai:9-feedback issue`      | GitHub issue created with bug label         |
-| Request feature  | `/moai:9-feedback suggestion` | GitHub issue created with enhancement label |
-| Ask question     | `/moai:9-feedback question`   | GitHub issue created with question label    |
-| General feedback | `/moai:9-feedback`            | Interactive feedback collection             |
+Scenario: General feedback
+- Entry Point: /moai:9-feedback
+- Expected Outcome: Interactive feedback collection
 
 Associated Agent:
 
@@ -306,7 +312,7 @@ Requirements:
 
 ---
 
-##  EXECUTION DIRECTIVE
+## EXECUTION DIRECTIVE
 
 You must NOW execute the command following the "Execution Process" described above.
 

moai_adk/templates/.claude/hooks/moai/lib/README.md

@@ -0,0 +1,143 @@
+# MoAI-ADK Hooks Library
+
+Shared utilities for Claude Code hooks in MoAI-ADK.
+
+## Module Overview
+
+```
+lib/
+├── __init__.py           # Package exports
+├── common.py             # Shared utilities (format_duration, merge_configs)
+├── config_manager.py     # Configuration loading and management
+├── config_validator.py   # Configuration schema validation
+├── exceptions.py         # Exception hierarchy
+├── models.py             # Data structures (HookPayload, HookResult)
+├── path_utils.py         # Project root detection, safe paths
+├── project.py            # Project metadata (language, Git, SPEC)
+├── timeout.py            # Cross-platform timeout (Windows/Unix)
+├── unified_timeout_manager.py  # Advanced timeout with retry
+├── git_operations_manager.py   # Optimized Git operations
+├── checkpoint.py         # Risky operation detection
+├── language_validator.py # Language config validation
+└── tool_registry.py      # Formatter/linter tool registry
+```
+
+## Exit Codes
+
+| Code | Meaning | Usage |
+|------|---------|-------|
+| 0 | Success | Normal completion |
+| 1 | Warning/Error | Non-critical error, logged |
+| 2 | Critical Error | Blocks operation |
+| 3 | Configuration Error | Invalid config |
+
+## Exception Hierarchy
+
+```
+HooksBaseError (base)
+├── TimeoutError
+│   └── HookTimeoutError (with context)
+├── GitOperationError
+├── ConfigurationError
+├── ValidationError
+└── SecurityError
+```
+
+## Key Functions
+
+### Path Management (`path_utils.py`)
+
+```python
+from lib.path_utils import find_project_root, get_safe_moai_path
+
+# Find project root (with caching)
+root = find_project_root()
+
+# Get safe path within .moai/
+cache_path = get_safe_moai_path("cache/version.json")
+```
+
+### Configuration (`config_manager.py`)
+
+```python
+from lib.config_manager import ConfigManager, get_config
+
+# Load configuration
+config = ConfigManager().load_config()
+
+# Get specific value
+timeout = get_config("hooks.timeout_ms", default=5000)
+```
+
+### Timeout Handling (`timeout.py`, `unified_timeout_manager.py`)
+
+```python
+# Basic timeout
+from lib.timeout import CrossPlatformTimeout
+
+with CrossPlatformTimeout(5):
+    long_running_operation()
+
+# Advanced timeout with retry
+from lib.unified_timeout_manager import get_timeout_manager
+
+manager = get_timeout_manager()
+result = manager.execute_with_timeout("hook_name", func, config=config)
+```
+
+### Common Utilities (`common.py`)
+
+```python
+from lib.common import merge_configs, format_duration
+
+# Merge configs recursively
+merged = merge_configs(base_config, override_config)
+
+# Format duration
+formatted = format_duration(125.5)  # "2.1m"
+```
+
+## Configuration Files
+
+### Main Config
+Location: `.moai/config/config.yaml`
+
+### Section Files
+Location: `.moai/config/sections/`
+- `user.yaml` - User name
+- `language.yaml` - Language preferences
+- `project.yaml` - Project metadata
+- `git-strategy.yaml` - Git workflow
+- `quality.yaml` - TDD settings
+
+## Hook Data Flow
+
+```
+Claude Code Event
+    ↓
+stdin (JSON)
+    ↓
+Hook Process
+    ↓
+stdout (JSON response)
+    ↓
+Claude Code
+```
+
+### Response Format
+
+```json
+{
+  "continue": true,
+  "systemMessage": "...",
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow|deny|ask"
+  }
+}
+```
+
+## Version
+
+- Library Version: 1.0.0
+- Last Updated: 2025-01

moai_adk/templates/.claude/hooks/moai/lib/__init__.py

@@ -24,6 +24,7 @@ try:
         get_file_pattern_category,
         get_summary_stats,
         is_root_whitelisted,
+        merge_configs,
         suggest_moai_location,
     )
     from lib.config_manager import (
@@ -35,6 +36,16 @@ try:
         get_timeout_seconds,
     )
 
+    # Import exceptions
+    from lib.exceptions import (
+        ConfigurationError,
+        GitOperationError,
+        HooksBaseError,
+        HookTimeoutError,
+        SecurityError,
+        ValidationError,
+    )
+
     # Import models
     from lib.models import HookPayload, HookResult
 
@@ -51,6 +62,13 @@ try:
         "CrossPlatformTimeout",
         "TimeoutError",
         "timeout_context",
+        # Core - Exceptions
+        "HooksBaseError",
+        "HookTimeoutError",
+        "GitOperationError",
+        "ConfigurationError",
+        "ValidationError",
+        "SecurityError",
         # Core - Configuration
         "ConfigManager",
         "get_config_manager",
@@ -64,6 +82,7 @@ try:
         "is_root_whitelisted",
         "get_file_pattern_category",
         "suggest_moai_location",
+        "merge_configs",
         # Models
         "HookPayload",
         "HookResult",

moai_adk/templates/.claude/hooks/moai/lib/checkpoint.py

@@ -70,9 +70,12 @@ def detect_risky_operation(tool_name: str, tool_args: dict[str, Any], cwd: str)
         critical_files = [
             "CLAUDE.md",
             "config.json",
+            "config.yaml",
             ".claude/skills/moai-core-dev-guide/reference.md",
             ".claude/skills/moai-core-spec-metadata-extended/reference.md",
-            ".moai/config/config.json",
+            ".moai/config/config.json",  # Legacy monolithic config
+            ".moai/config/config.yaml",  # Legacy monolithic config
+            ".moai/config/sections/",  # Section-based config (any file in sections/)
         ]
 
         if any(cf in file_path for cf in critical_files):

moai_adk/templates/.claude/hooks/moai/lib/common.py

@@ -3,9 +3,39 @@
 Consolidated fallback implementations used across multiple hooks.
 """
 
+from __future__ import annotations
+
 import re
 import statistics
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any
+
+
+def merge_configs(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge configuration dictionaries.
+
+    Deep merges two configuration dictionaries, with override values
+    taking precedence. Nested dictionaries are merged recursively.
+
+    Args:
+        base: Base configuration dictionary
+        override: Override configuration dictionary (values take precedence)
+
+    Returns:
+        Merged configuration dictionary
+
+    Examples:
+        >>> base = {"a": 1, "b": {"c": 2}}
+        >>> override = {"b": {"d": 3}}
+        >>> merge_configs(base, override)
+        {'a': 1, 'b': {'c': 2, 'd': 3}}
+    """
+    result = base.copy()
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = merge_configs(result[key], value)
+        else:
+            result[key] = value
+    return result
 
 
 def format_duration(seconds: float) -> str:
@@ -28,7 +58,7 @@ def format_duration(seconds: float) -> str:
     return f"{hours:.1f}h"
 
 
-def get_summary_stats(values: List[float]) -> Dict[str, float]:
+def get_summary_stats(values: list[float]) -> dict[str, float]:
     """Get summary statistics for a list of values.
 
     Calculates mean, min, max, and standard deviation.
@@ -50,7 +80,7 @@ def get_summary_stats(values: List[float]) -> Dict[str, float]:
     }
 
 
-def is_root_whitelisted(filename: str, config: Dict[str, Any]) -> bool:
+def is_root_whitelisted(filename: str, config: dict[str, Any]) -> bool:
     """Check if file is allowed in project root.
 
     Consolidated from pre_tool__document_management.py and session_end__auto_cleanup.py
@@ -73,7 +103,7 @@ def is_root_whitelisted(filename: str, config: Dict[str, Any]) -> bool:
     return False
 
 
-def get_file_pattern_category(filename: str, config: Dict[str, Any]) -> Optional[Tuple[str, str]]:
+def get_file_pattern_category(filename: str, config: dict[str, Any]) -> tuple[str, str] | None:
     """Match filename against patterns to determine category.
 
     Consolidated from pre_tool__document_management.py and session_end__auto_cleanup.py
@@ -98,7 +128,7 @@ def get_file_pattern_category(filename: str, config: Dict[str, Any]) -> Optional
     return None
 
 
-def suggest_moai_location(filename: str, config: Dict[str, Any]) -> str:
+def suggest_moai_location(filename: str, config: dict[str, Any]) -> str:
     """Suggest appropriate .moai/ location based on file pattern.
 
     Consolidated from pre_tool__document_management.py and session_end__auto_cleanup.py

moai_adk/templates/.claude/hooks/moai/lib/config_manager.py

@@ -121,14 +121,16 @@ class ConfigManager:
                     else:
                         file_config = json.load(f)
                         config = self._merge_configs(DEFAULT_CONFIG.copy(), file_config)
-            except (
-                json.JSONDecodeError,
-                yaml.YAMLError if YAML_AVAILABLE else Exception,
-                IOError,
-                OSError,
-            ):
+            except (json.JSONDecodeError, IOError, OSError):
                 # Use defaults if file is corrupted or unreadable
                 config = DEFAULT_CONFIG.copy()
+            except Exception as e:
+                # Handle YAML errors or other parsing issues
+                if YAML_AVAILABLE and isinstance(e, yaml.YAMLError):
+                    config = DEFAULT_CONFIG.copy()
+                else:
+                    # Re-raise unexpected exceptions
+                    raise
         else:
             # Use defaults if file doesn't exist
             config = DEFAULT_CONFIG.copy()
@@ -342,6 +344,8 @@ class ConfigManager:
     def _merge_configs(self, base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any]:
         """Recursively merge two configuration dictionaries.
 
+        This method delegates to common.merge_configs() for consistent behavior.
+
         Args:
             base: Base configuration dictionary
             override: Override configuration dictionary
@@ -349,15 +353,9 @@ class ConfigManager:
         Returns:
             Merged configuration dictionary
         """
-        result = base.copy()
-
-        for key, value in override.items():
-            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
-                result[key] = self._merge_configs(result[key], value)
-            else:
-                result[key] = value
+        from .common import merge_configs
 
-        return result
+        return merge_configs(base, override)
 
 
 # Module-level helper functions

moai_adk/templates/.claude/hooks/moai/lib/exceptions.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Exception hierarchy for MoAI-ADK hooks system.
+
+Provides a consistent exception hierarchy for all hooks-related errors.
+This enables structured error handling and proper exception chaining.
+
+Hierarchy:
+    HooksBaseError
+    ├── TimeoutError (base timeout from timeout.py)
+    │   └── HookTimeoutError (enhanced with context)
+    ├── GitOperationError
+    ├── ConfigurationError
+    └── ValidationError
+"""
+
+from __future__ import annotations
+
+
+class HooksBaseError(Exception):
+    """Base exception for all hooks system errors.
+
+    All hook-related exceptions should inherit from this class
+    to enable consistent exception handling.
+    """
+
+    pass
+
+
+# Re-export TimeoutError from timeout module for convenience
+try:
+    from .timeout import TimeoutError
+except ImportError:
+
+    class TimeoutError(HooksBaseError):  # type: ignore[no-redef]
+        """Timeout exception (fallback if timeout module unavailable)."""
+
+        pass
+
+
+# Re-export HookTimeoutError from unified_timeout_manager for convenience
+try:
+    from .unified_timeout_manager import HookTimeoutError
+except ImportError:
+
+    class HookTimeoutError(TimeoutError):  # type: ignore[no-redef]
+        """Hook-specific timeout with context (fallback)."""
+
+        def __init__(
+            self,
+            message: str,
+            hook_id: str = "",
+            timeout_seconds: float = 0,
+            execution_time: float = 0,
+            will_retry: bool = False,
+        ):
+            super().__init__(message)
+            self.hook_id = hook_id
+            self.timeout_seconds = timeout_seconds
+            self.execution_time = execution_time
+            self.will_retry = will_retry
+
+
+class GitOperationError(HooksBaseError):
+    """Exception for Git operation failures.
+
+    Attributes:
+        command: The Git command that failed
+        exit_code: Git command exit code (if available)
+        stderr: Error output from Git command
+    """
+
+    def __init__(
+        self,
+        message: str,
+        command: str = "",
+        exit_code: int | None = None,
+        stderr: str = "",
+    ):
+        super().__init__(message)
+        self.command = command
+        self.exit_code = exit_code
+        self.stderr = stderr
+
+    def __str__(self) -> str:
+        parts = [super().__str__()]
+        if self.command:
+            parts.append(f"Command: {self.command}")
+        if self.exit_code is not None:
+            parts.append(f"Exit code: {self.exit_code}")
+        if self.stderr:
+            parts.append(f"Stderr: {self.stderr[:200]}")
+        return " | ".join(parts)
+
+
+class ConfigurationError(HooksBaseError):
+    """Exception for configuration-related errors.
+
+    Raised when configuration files are missing, malformed,
+    or contain invalid values.
+
+    Attributes:
+        config_path: Path to the configuration file (if applicable)
+        key: Configuration key that caused the error (if applicable)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        config_path: str = "",
+        key: str = "",
+    ):
+        super().__init__(message)
+        self.config_path = config_path
+        self.key = key
+
+
+class ValidationError(HooksBaseError):
+    """Exception for validation failures.
+
+    Raised when input validation or schema validation fails.
+
+    Attributes:
+        field: The field that failed validation
+        value: The invalid value (if safe to include)
+        expected: Description of expected value format
+    """
+
+    def __init__(
+        self,
+        message: str,
+        field: str = "",
+        value: str | None = None,
+        expected: str = "",
+    ):
+        super().__init__(message)
+        self.field = field
+        self.value = value
+        self.expected = expected
+
+
+class SecurityError(HooksBaseError):
+    """Exception for security-related issues.
+
+    Raised when security checks fail (e.g., path traversal attempts,
+    unauthorized file access).
+
+    Attributes:
+        operation: The operation that was blocked
+        resource: The resource that was accessed
+    """
+
+    def __init__(
+        self,
+        message: str,
+        operation: str = "",
+        resource: str = "",
+    ):
+        super().__init__(message)
+        self.operation = operation
+        self.resource = resource
+
+
+__all__ = [
+    "HooksBaseError",
+    "TimeoutError",
+    "HookTimeoutError",
+    "GitOperationError",
+    "ConfigurationError",
+    "ValidationError",
+    "SecurityError",
+]

moai_adk/templates/.claude/hooks/moai/lib/git_operations_manager.py

@@ -188,7 +188,7 @@ class GitOperationsManager:
             # Fallback to simple key
             key_data = f"{operation_type.value}:{args}"
 
-        return hashlib.md5(key_data.encode(), usedforsecurity=False).hexdigest()
+        return hashlib.md5(key_data.encode()).hexdigest()
 
     def _is_cache_valid(self, entry: CacheEntry) -> bool:
         """Check if cache entry is still valid"""