moai-adk 0.8.1__py3-none-any.whl → 0.8.2__py3-none-any.whl

moai_adk/templates/CLAUDE.md

@@ -61,47 +61,43 @@ You are the SuperAgent **🎩 Alfred** of **🗿 MoAI-ADK**. Follow these core p
 
 ## 🌍 Alfred's Language Boundary Rule
 
-Alfred operates with a **crystal-clear three-layer language architecture** to support global users while keeping all Skills in English only:
+Alfred operates with a **clear two-layer language architecture** to support global users while keeping the infrastructure in English:
 
-### Layer 1: User Conversation
+### Layer 1: User Conversation & Dynamic Content
 **ALWAYS use user's `conversation_language` for ALL user-facing content:**
 - 🗣️ **Responses to user**: User's configured language (Korean, Japanese, Spanish, etc.)
 - 📝 **Explanations**: User's language
 - ❓ **Questions to user**: User's language
 - 💬 **All dialogue**: User's language
-
-### Layer 2: Internal Operations
-**EVERYTHING internal MUST be in English:**
-- `Task(prompt="...")` invocations → **English**
-- `Skill("skill-name")` calls → **English**
-- Sub-agent communication → **English**
-- Error messages (internal) → **English**
+- 📄 **Generated documents**: User's language (SPEC, reports, analysis)
+- 🔧 **Task prompts**: User's language (passed directly to Sub-agents)
+- 📨 **Sub-agent communication**: User's language
+
+### Layer 2: Static Infrastructure (English Only)
+**MoAI-ADK package and templates stay in English:**
+- `Skill("skill-name")` → **Skill names always English** (explicit invocation)
+- `.claude/skills/` → **Skill content in English** (technical documentation standard)
+- `.claude/agents/` → **Agent templates in English**
+- `.claude/commands/` → **Command templates in English**
+- Code comments → **English**
 - Git commit messages → **English**
-- All technical instructions → **English**
-
-### Layer 3: Skills & Code
-**Skills maintain English-only for infinite scalability:**
-- Skill descriptions → **English only**
-- Skill examples → **English only**
-- Skill guides → **English only**
-- Code comments → **English only**
-- No multilingual versions needed! ✅
+- @TAG identifiers → **English**
+- Technical function/variable names → **English**
 
 ### Execution Flow Example
 
 ```
-User Input (any language):  "Check code quality" / "コード品質をチェック" / "Verificar calidad del código"
+User Input (any language):  "코드 품질 검사해줘" / "Check code quality" / "コード品質をチェック"
                               ↓
-Alfred (internal translation): "Check code quality" (→ English)
+Alfred (passes directly):  Task(prompt="코드 품질 검사...", subagent_type="trust-checker")
                               ↓
-Invoke Sub-agent:          Task(prompt="Validate TRUST 5 principles",
-                                subagent_type="trust-checker")
+Sub-agent (receives Korean): Recognizes quality check task
                               ↓
-Sub-agent (receives English): Skill("moai-foundation-trust") ← 100% match!
+Sub-agent (explicit call):  Skill("moai-foundation-trust") ✅
                               ↓
-Alfred (receives results):  English TRUST report
+Skill loads (English content): Sub-agent reads English Skill guidance
                               ↓
-Alfred (translates back):    User's language response
+Sub-agent generates output:  Korean report based on user's language
                               ↓
 User Receives:             Response in their configured language
 ```
@@ -109,23 +105,25 @@ User Receives:             Response in their configured language
 ### Why This Pattern Works
 
 1. **Scalability**: Support any language without modifying 55 Skills
-2. **Maintainability**: Skills stay in English (single source of truth)
-3. **Reliability**: English keywords always match English Skill descriptions = 100% success rate
-4. **Best Practice**: Follows standard i18n architecture (localized frontend, English backend lingua franca)
-5. **Future-proof**: Add new languages instantly (Korean → Japanese → Spanish → Russian, etc.)
+2. **Maintainability**: Skills stay in English (single source of truth, industry standard for technical docs)
+3. **Reliability**: **Explicit Skill() invocation** = 100% success rate (no keyword matching needed)
+4. **Simplicity**: No translation layer overhead, direct language pass-through
+5. **Future-proof**: Add new languages instantly without code changes
 
 ### Key Rules for Sub-agents
 
-**All 12 Sub-agents MUST receive English prompts**, regardless of user's conversation language:
+**All 12 Sub-agents work in user's configured language:**
 
 | Sub-agent | Input Language | Output Language | Notes |
 |-----------|---|---|---|
-| spec-builder | **English** | English (reports to Alfred) | User requests translated to English before Task() call |
-| tdd-implementer | **English** | English | Receives English SPEC references |
-| doc-syncer | **English** | English | Processes English file descriptions |
-| implementation-planner | **English** | English | Architecture analysis in English |
-| debug-helper | **English** | English | Error analysis in English |
-| All others | **English** | English | Consistency across entire team |
+| spec-builder | **User's language** | User's language | Invokes Skills explicitly: Skill("moai-foundation-ears") |
+| tdd-implementer | **User's language** | User's language | Code comments in English, narratives in user's language |
+| doc-syncer | **User's language** | User's language | Generated docs in user's language |
+| implementation-planner | **User's language** | User's language | Architecture analysis in user's language |
+| debug-helper | **User's language** | User's language | Error analysis in user's language |
+| All others | **User's language** | User's language | Explicit Skill() invocation regardless of prompt language |
+
+**CRITICAL**: Skills are invoked **explicitly** using `Skill("skill-name")` syntax, NOT auto-triggered by keywords.
 
 ---
 
@@ -305,10 +303,11 @@ Your project is ready. You can now run `/alfred:1-plan` to start planning specs.
 - `.moai/memory/`
 - `CLAUDE.md` (this file)
 
-**Rationale**: These files define system behavior, tool invocations, and internal communication. English ensures:
-1. Skill trigger keywords always match English prompts (100% auto-invocation reliability)
-2. Global maintainability without translation burden
-3. Infinite language scalability (support any user language without code changes)
+**Rationale**: These files define system behavior, tool invocations, and internal infrastructure. English ensures:
+1. **Industry standard**: Technical documentation in English (single source of truth)
+2. **Global maintainability**: No translation burden for 55 Skills, 12 agents, 4 commands
+3. **Infinite scalability**: Support any user language without modifying infrastructure
+4. **Reliable invocation**: Explicit Skill("name") calls work regardless of prompt language
 
 ---
 

moai_adk/templates/src/moai_adk/core/__init__.py

@@ -0,0 +1,5 @@
+"""MoAI-ADK core modules
+
+This package contains core functionality for MoAI-ADK including:
+- TAG validation and management
+"""

moai_adk/templates/src/moai_adk/core/tags/__init__.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+# @CODE:DOC-TAG-004 | TAG validation core module (Components 1, 2, 3 & 4)
+"""TAG validation and management for MoAI-ADK
+
+This module provides TAG validation functionality for:
+- Pre-commit hook validation (Component 1)
+- CI/CD pipeline validation (Component 2)
+- Central validation system (Component 3)
+- Documentation & Reporting (Component 4)
+- TAG format checking
+- Duplicate detection
+- Orphan detection
+- Chain integrity validation
+"""
+
+# Component 1: Pre-commit validator
+from .pre_commit_validator import (
+    PreCommitValidator,
+    ValidationResult,
+    ValidationError,
+    ValidationWarning,
+)
+
+# Component 2: CI/CD validator
+from .ci_validator import CIValidator
+
+# Component 3: Central validation system
+from .validator import (
+    ValidationConfig,
+    TagValidator,
+    DuplicateValidator,
+    OrphanValidator,
+    ChainValidator,
+    FormatValidator,
+    CentralValidator,
+    CentralValidationResult,
+    ValidationIssue,
+    ValidationStatistics,
+)
+
+# Component 4: Documentation & Reporting
+from .reporter import (
+    TagInventory,
+    TagMatrix,
+    InventoryGenerator,
+    MatrixGenerator,
+    CoverageAnalyzer,
+    StatisticsGenerator,
+    ReportFormatter,
+    ReportGenerator,
+    CoverageMetrics,
+    StatisticsReport,
+    ReportResult,
+)
+
+__all__ = [
+    # Component 1
+    "PreCommitValidator",
+    "ValidationResult",
+    "ValidationError",
+    "ValidationWarning",
+    # Component 2
+    "CIValidator",
+    # Component 3
+    "ValidationConfig",
+    "TagValidator",
+    "DuplicateValidator",
+    "OrphanValidator",
+    "ChainValidator",
+    "FormatValidator",
+    "CentralValidator",
+    "CentralValidationResult",
+    "ValidationIssue",
+    "ValidationStatistics",
+    # Component 4
+    "TagInventory",
+    "TagMatrix",
+    "InventoryGenerator",
+    "MatrixGenerator",
+    "CoverageAnalyzer",
+    "StatisticsGenerator",
+    "ReportFormatter",
+    "ReportGenerator",
+    "CoverageMetrics",
+    "StatisticsReport",
+    "ReportResult",
+]

moai_adk/templates/src/moai_adk/core/tags/ci_validator.py

@@ -0,0 +1,435 @@
+#!/usr/bin/env python3
+# @CODE:DOC-TAG-004 | Component 2: CI/CD pipeline TAG validator
+"""CI/CD TAG validation module for GitHub Actions
+
+This module extends PreCommitValidator for CI/CD environments:
+- Fetches PR changed files via GitHub API
+- Generates structured validation reports (JSON/markdown)
+- Posts validation results as PR comments
+- Supports strict mode (block merge on warnings) and info mode
+
+Used by GitHub Actions workflow to validate TAGs on every PR.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import List, Dict, Any, Optional, Tuple
+import requests
+
+from .pre_commit_validator import (
+    PreCommitValidator,
+    ValidationResult,
+    ValidationError,
+    ValidationWarning,
+)
+
+
+class CIValidator(PreCommitValidator):
+    """CI/CD TAG validator for GitHub Actions
+
+    Extends PreCommitValidator with CI/CD-specific features:
+    - GitHub API integration for PR file detection
+    - Structured report generation for automation
+    - Markdown comment formatting for PR feedback
+    - Environment variable support for GitHub Actions
+
+    Args:
+        github_token: GitHub API token (default: from GITHUB_TOKEN env)
+        repo_owner: Repository owner (default: from GITHUB_REPOSITORY env)
+        repo_name: Repository name (default: from GITHUB_REPOSITORY env)
+        strict_mode: Treat warnings as errors
+        check_orphans: Enable orphan TAG detection
+        tag_pattern: Custom TAG regex pattern
+    """
+
+    def __init__(
+        self,
+        github_token: Optional[str] = None,
+        repo_owner: Optional[str] = None,
+        repo_name: Optional[str] = None,
+        strict_mode: bool = False,
+        check_orphans: bool = True,
+        tag_pattern: Optional[str] = None
+    ):
+        super().__init__(strict_mode, check_orphans, tag_pattern)
+
+        # GitHub configuration from environment or parameters
+        self.github_token = github_token or os.environ.get('GITHUB_TOKEN', '')
+
+        # Parse repo info from GITHUB_REPOSITORY (format: "owner/repo")
+        repo_full = os.environ.get('GITHUB_REPOSITORY', '')
+        if '/' in repo_full and not repo_owner and not repo_name:
+            parts = repo_full.split('/', 1)
+            self.repo_owner = parts[0]
+            self.repo_name = parts[1]
+        else:
+            self.repo_owner = repo_owner or ''
+            self.repo_name = repo_name or ''
+
+    def get_pr_changed_files(self, pr_number: int) -> List[str]:
+        """Fetch list of changed files in a PR via GitHub API
+
+        Args:
+            pr_number: Pull request number
+
+        Returns:
+            List of relative file paths changed in the PR
+        """
+        if not self.github_token or not self.repo_owner or not self.repo_name:
+            return []
+
+        url = (
+            f"https://api.github.com/repos/"
+            f"{self.repo_owner}/{self.repo_name}/pulls/{pr_number}/files"
+        )
+
+        headers = {
+            'Authorization': f'Bearer {self.github_token}',
+            'Accept': 'application/vnd.github.v3+json'
+        }
+
+        try:
+            response = requests.get(url, headers=headers, timeout=10)
+            response.raise_for_status()
+
+            files_data = response.json()
+            return [file_info['filename'] for file_info in files_data]
+
+        except Exception:
+            # Return empty list on any error (network, auth, etc.)
+            return []
+
+    def validate_pr_changes(
+        self,
+        pr_number: int,
+        base_branch: str = "main"
+    ) -> ValidationResult:
+        """Validate TAG annotations in PR changed files
+
+        Main CI/CD validation method:
+        1. Fetch changed files from GitHub API
+        2. Run validation checks on those files
+        3. Return structured validation result
+
+        Args:
+            pr_number: Pull request number
+            base_branch: Base branch name (not used currently)
+
+        Returns:
+            ValidationResult with errors and warnings
+        """
+        # Get PR changed files
+        files = self.get_pr_changed_files(pr_number)
+
+        if not files:
+            return ValidationResult(is_valid=True)
+
+        # Validate the changed files
+        return self.validate_files(files)
+
+    def generate_report(self, result: ValidationResult) -> Dict[str, Any]:
+        """Generate structured validation report
+
+        Creates JSON-serializable report with:
+        - Status (success/failure/success_with_warnings)
+        - Error details (message, tag, locations)
+        - Warning details (message, tag, location)
+        - Statistics (counts)
+        - Configuration (strict_mode)
+
+        Args:
+            result: ValidationResult from validation
+
+        Returns:
+            Dictionary with structured report data
+        """
+        # Determine status
+        if not result.is_valid:
+            status = 'failure'
+        elif result.warnings:
+            status = 'success_with_warnings'
+        else:
+            status = 'success'
+
+        # Build error list
+        errors = []
+        for error in result.errors:
+            errors.append({
+                'message': error.message,
+                'tag': error.tag,
+                'locations': [
+                    {'file': filepath, 'line': line_num}
+                    for filepath, line_num in error.locations
+                ]
+            })
+
+        # Build warning list
+        warnings = []
+        for warning in result.warnings:
+            warnings.append({
+                'message': warning.message,
+                'tag': warning.tag,
+                'location': {
+                    'file': warning.location[0],
+                    'line': warning.location[1]
+                }
+            })
+
+        # Calculate statistics
+        statistics = {
+            'total_errors': len(result.errors),
+            'total_warnings': len(result.warnings),
+            'total_issues': len(result.errors) + len(result.warnings)
+        }
+
+        # Build complete report
+        report = {
+            'status': status,
+            'is_valid': result.is_valid,
+            'strict_mode': self.strict_mode,
+            'summary': self._generate_summary(result),
+            'errors': errors,
+            'warnings': warnings,
+            'statistics': statistics
+        }
+
+        return report
+
+    def _generate_summary(self, result: ValidationResult) -> str:
+        """Generate human-readable summary text
+
+        Args:
+            result: ValidationResult
+
+        Returns:
+            Summary string
+        """
+        if result.is_valid and not result.warnings:
+            return "All TAG validations passed. No issues found."
+        elif result.is_valid and result.warnings:
+            return f"Validation passed with {len(result.warnings)} warning(s)."
+        else:
+            return f"Validation failed with {len(result.errors)} error(s)."
+
+    def format_pr_comment(
+        self,
+        result: ValidationResult,
+        pr_url: str
+    ) -> str:
+        """Format validation result as markdown PR comment
+
+        Creates formatted markdown comment with:
+        - Status indicator (emoji)
+        - Summary message
+        - Error/warning table
+        - Action items
+        - Documentation links
+
+        Args:
+            result: ValidationResult from validation
+            pr_url: URL of the pull request
+
+        Returns:
+            Markdown-formatted comment string
+        """
+        lines = []
+
+        # Header with status indicator
+        if result.is_valid and not result.warnings:
+            lines.append("## ✅ TAG Validation Passed")
+            lines.append("")
+            lines.append("All TAG annotations are valid. No issues found.")
+        elif result.is_valid and result.warnings:
+            lines.append("## ⚠️ TAG Validation Passed with Warnings")
+            lines.append("")
+            lines.append(f"Validation passed but found {len(result.warnings)} warning(s).")
+        else:
+            lines.append("## ❌ TAG Validation Failed")
+            lines.append("")
+            lines.append(f"Found {len(result.errors)} error(s) that must be fixed.")
+
+        lines.append("")
+
+        # Error table
+        if result.errors:
+            lines.append("### Errors")
+            lines.append("")
+            lines.append("| TAG | Issue | Location |")
+            lines.append("|-----|-------|----------|")
+
+            for error in result.errors:
+                tag = error.tag
+                message = error.message
+                locations = ', '.join([
+                    f"`{f}:{l}`" for f, l in error.locations[:3]
+                ])
+                if len(error.locations) > 3:
+                    locations += f" (+{len(error.locations) - 3} more)"
+
+                lines.append(f"| `{tag}` | {message} | {locations} |")
+
+            lines.append("")
+
+        # Warning table
+        if result.warnings:
+            lines.append("### Warnings")
+            lines.append("")
+            lines.append("| TAG | Issue | Location |")
+            lines.append("|-----|-------|----------|")
+
+            for warning in result.warnings:
+                tag = warning.tag
+                message = warning.message
+                location = f"`{warning.location[0]}:{warning.location[1]}`"
+
+                lines.append(f"| `{tag}` | {message} | {location} |")
+
+            lines.append("")
+
+        # Action items
+        if result.errors or result.warnings:
+            lines.append("### How to Fix")
+            lines.append("")
+
+            if result.errors:
+                lines.append("**Errors (must fix):**")
+                lines.append("- Remove duplicate TAG declarations")
+                lines.append("- Ensure TAGs follow format: `@PREFIX:DOMAIN-TYPE-NNN`")
+                lines.append("")
+
+            if result.warnings:
+                lines.append("**Warnings (recommended):**")
+                lines.append("- Add corresponding TEST tags for CODE tags")
+                lines.append("- Add corresponding CODE tags for TEST tags")
+                lines.append("- Complete TAG chain: SPEC → CODE → TEST → DOC")
+                lines.append("")
+
+        # Documentation link
+        lines.append("---")
+        lines.append("")
+        lines.append("📚 **Documentation:** [TAG System Guide](.moai/memory/tag-system-guide.md)")
+        lines.append("")
+        lines.append(f"🔗 **PR:** {pr_url}")
+
+        return "\n".join(lines)
+
+    def get_pr_number_from_event(self) -> Optional[int]:
+        """Extract PR number from GitHub Actions event file
+
+        Reads GITHUB_EVENT_PATH to get PR number from event payload.
+
+        Returns:
+            PR number or None if not found
+        """
+        event_path = os.environ.get('GITHUB_EVENT_PATH')
+        if not event_path:
+            return None
+
+        try:
+            with open(event_path, 'r') as f:
+                event_data = json.load(f)
+                return event_data.get('pull_request', {}).get('number')
+        except Exception:
+            return None
+
+    def generate_tag_report_link(self, pr_number: int) -> str:
+        """Generate link to TAG reports for this PR
+
+        Integration point with Component 4 (Reporting).
+        Provides link to automated TAG reports generated by GitHub Actions.
+
+        Args:
+            pr_number: Pull request number
+
+        Returns:
+            Markdown link to TAG reports
+        """
+        # Link to GitHub Actions artifacts or docs directory
+        if self.repo_owner and self.repo_name:
+            docs_url = (
+                f"https://github.com/{self.repo_owner}/{self.repo_name}/tree/main/docs"
+            )
+            return f"📊 [View TAG Reports]({docs_url})"
+        else:
+            return "📊 TAG Reports: See docs/ directory"
+
+
+def main():
+    """CLI entry point for CI/CD validation"""
+    import sys
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Validate TAG annotations in GitHub PR"
+    )
+    parser.add_argument(
+        "--pr-number",
+        type=int,
+        help="Pull request number (default: from GitHub Actions event)"
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Treat warnings as errors"
+    )
+    parser.add_argument(
+        "--no-orphan-check",
+        action="store_true",
+        help="Disable orphan TAG checking"
+    )
+    parser.add_argument(
+        "--output-json",
+        help="Output report to JSON file"
+    )
+    parser.add_argument(
+        "--output-comment",
+        help="Output PR comment to file"
+    )
+
+    args = parser.parse_args()
+
+    validator = CIValidator(
+        strict_mode=args.strict,
+        check_orphans=not args.no_orphan_check
+    )
+
+    # Get PR number
+    pr_number = args.pr_number
+    if not pr_number:
+        pr_number = validator.get_pr_number_from_event()
+
+    if not pr_number:
+        print("Error: Could not determine PR number", file=sys.stderr)
+        sys.exit(1)
+
+    # Run validation
+    result = validator.validate_pr_changes(pr_number)
+
+    # Generate report
+    report = validator.generate_report(result)
+
+    # Output JSON report if requested
+    if args.output_json:
+        with open(args.output_json, 'w') as f:
+            json.dump(report, f, indent=2)
+
+    # Output PR comment if requested
+    if args.output_comment:
+        pr_url = (
+            f"https://github.com/{validator.repo_owner}/"
+            f"{validator.repo_name}/pull/{pr_number}"
+        )
+        comment = validator.format_pr_comment(result, pr_url)
+        with open(args.output_comment, 'w') as f:
+            f.write(comment)
+
+    # Print summary
+    print(result.format())
+
+    # Exit with error code if validation failed
+    sys.exit(0 if result.is_valid else 1)
+
+
+if __name__ == "__main__":
+    main()