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

moai_adk/templates/.claude/skills/moai-foundation-core/modules/trust-5-framework.md

@@ -0,0 +1,239 @@
+# TRUST 5 Framework - Quality Assurance System
+
+Purpose: Automated quality gates ensuring code quality, security, maintainability, and traceability through five core principles.
+
+Version: 2.0.0 (Modular Split)
+Last Updated: 2026-01-06
+
+---
+
+## Quick Reference (30 seconds)
+
+TRUST 5 is MoAI-ADK's comprehensive quality assurance framework enforcing five pillars:
+
+1. Test-first(T) - ≥85% coverage, RED-GREEN-REFACTOR cycle
+2. Readable(R) - Clear naming, ≤10 cyclomatic complexity
+3. Unified(U) - Consistent patterns, architecture compliance
+4. Secured(S) - OWASP Top 10 compliance, security validation
+5. Trackable(T) - Clear commits, requirement traceability
+
+Integration Points:
+- Pre-commit hooks - Automated validation
+- CI/CD pipelines - Quality gate enforcement
+- quality-gate agent - TRUST 5 validation
+- /moai:2-run - Enforces ≥85% coverage
+
+Quick Validation:
+```python
+validations = [
+    test_coverage >= 85,    # T
+    complexity <= 10,       # R
+    consistency > 90,       # U
+    security_score == 100,  # S
+    has_clear_commits       # T
+]
+```
+
+Extended Documentation:
+- [Implementation Details](trust-5-implementation.md) - Detailed patterns and code examples
+- [Validation Framework](trust-5-validation.md) - CI/CD integration and metrics
+
+---
+
+## Implementation Guide (5 minutes)
+
+### Principle 1: Test-First (T)
+
+RED-GREEN-REFACTOR Cycle:
+
+```
+RED Phase: Write failing test
+    Test defines requirement
+    Code doesn't exist yet
+    Test fails as expected
+
+GREEN Phase: Write minimal code
+    Simplest code to pass test
+    Focus on making test pass
+    Test now passes
+
+REFACTOR Phase: Improve quality
+    Extract functions/classes
+    Optimize performance
+    Add documentation
+    Keep tests passing
+```
+
+Test Coverage Requirements:
+
+- Critical (≥85%): Required for merge
+- Warning (70-84%): Review required
+- Failing (<70%): Block merge, generate tests
+
+Validation Commands:
+```bash
+# Run tests with coverage
+pytest --cov=src --cov-report=html --cov-fail-under=85
+
+# Generate coverage report
+coverage report -m
+```
+
+---
+
+### Principle 2: Readable (R)
+
+Readability Metrics:
+
+- Cyclomatic Complexity: ≤10 (max 15)
+- Function Length: ≤50 lines (max 100)
+- Nesting Depth: ≤3 levels (max 5)
+- Comment Ratio: 15-20% (min 10%)
+- Type Hint Coverage: 100% (min 90%)
+
+Readability Checklist:
+
+- Clear function/variable names (noun_verb pattern)
+- Single responsibility principle
+- Type hints on all parameters and returns
+- Docstrings with examples (Google style)
+- No magic numbers (use named constants)
+- DRY principle applied (no code duplication)
+- SOLID principles followed
+
+Validation Commands:
+```bash
+# Pylint complexity check
+pylint src/ --fail-under=8.0
+
+# Black format check
+black --check src/
+
+# MyPy type check
+mypy src/ --strict
+```
+
+---
+
+### Principle 3: Unified (U)
+
+Consistency Requirements:
+
+Architecture Consistency:
+- Same pattern across all modules
+- Same error handling approach
+- Same logging strategy
+- Same naming conventions
+
+Testing Consistency:
+- Same test structure (Arrange-Act-Assert)
+- Same fixtures/factories
+- Same assertion patterns
+- Same mock strategies
+
+Documentation Consistency:
+- Same docstring format (Google style)
+- Same README structure
+- Same API documentation
+- Same changelog format (conventional commits)
+
+Validation Tools:
+```bash
+# Check architecture compliance
+python .moai/scripts/validate_architecture.py
+
+# Check consistent imports
+isort --check-only src/
+```
+
+---
+
+### Principle 4: Secured (S)
+
+OWASP Top 10 (2024) Compliance:
+
+1. Broken Access Control - RBAC, permission checks
+2. Cryptographic Failures - bcrypt, proper encryption
+3. Injection - Parameterized queries
+4. Insecure Design - Threat modeling
+5. Security Misconfiguration - Environment variables
+6. Vulnerable Components - Dependency scanning
+7. Authentication Failures - MFA, secure sessions
+8. Data Integrity - Checksums, signatures
+9. Logging Failures - Comprehensive logging
+10. SSRF - URL validation
+
+Security Validation:
+```bash
+# Bandit security scan
+bandit -r src/ -ll
+
+# Dependency audit
+pip-audit
+safety check
+
+# Secret scanning
+detect-secrets scan
+```
+
+---
+
+### Principle 5: Trackable (T)
+
+Traceability Requirements:
+
+Commit Traceability:
+- Conventional commit format
+- Link to SPEC or issue
+- Clear description of changes
+- Test evidence included
+
+Requirement Traceability:
+- SPEC-XXX-REQ-YY mapping
+- Implementation - Test linkage
+- Test - Acceptance criteria
+- Acceptance - User story
+
+Conventional Commit Format:
+```bash
+# Format: <type>(<scope>): <subject>
+feat(auth): Add OAuth2 integration
+
+Implement OAuth2 authentication flow with Google provider.
+Addresses SPEC-001-REQ-02.
+
+Closes #42
+```
+
+---
+
+## Advanced Patterns
+
+For comprehensive implementation patterns including CI/CD integration, validation frameworks, and metrics dashboards, see:
+
+- [TRUST 5 Implementation](trust-5-implementation.md) - Detailed code patterns
+- [TRUST 5 Validation](trust-5-validation.md) - CI/CD and metrics
+
+---
+
+## Works Well With
+
+Agents:
+- quality-gate - Automated TRUST 5 validation
+- tdd-implementer - RED-GREEN-REFACTOR enforcement
+- security-expert - OWASP compliance checking
+- test-engineer - Test generation and coverage
+
+Skills:
+- moai-workflow-testing - Test framework setup
+- moai-domain-security - Security patterns
+
+Commands:
+- /moai:2-run - Enforces ≥85% coverage requirement
+- /moai:9-feedback - Quality improvement suggestions
+
+---
+
+Version: 2.0.0
+Last Updated: 2026-01-06
+Status: Production Ready

moai_adk/templates/.claude/skills/moai-foundation-core/modules/trust-5-implementation.md

@@ -0,0 +1,244 @@
+# TRUST 5 Implementation Patterns
+
+Purpose: Detailed implementation patterns for TRUST 5 principles with working code examples.
+
+Version: 1.0.0
+Last Updated: 2026-01-06
+Parent: [trust-5-framework.md](trust-5-framework.md)
+
+---
+
+## Test-First Implementation
+
+### RED-GREEN-REFACTOR Example
+
+```python
+# RED: Write failing test first
+def test_calculate_total_price_with_tax():
+    item = ShoppingItem(name="Widget", price=10.00)
+    total = calculate_total_with_tax(item, tax_rate=0.10)
+    assert total == 11.00  # Fails - function doesn't exist
+
+# GREEN: Minimal implementation
+def calculate_total_with_tax(item, tax_rate):
+    return item.price * (1 + tax_rate)
+
+# REFACTOR: Improve code quality
+def calculate_total_with_tax(item: ShoppingItem, tax_rate: float) -> float:
+    """Calculate total price including tax.
+
+    Args:
+        item: Shopping item with price
+        tax_rate: Tax rate as decimal (0.10 = 10%)
+
+    Returns:
+        Total price including tax
+
+    Raises:
+        ValueError: If tax_rate not between 0 and 1
+
+    Example:
+        >>> item = ShoppingItem("Widget", 10.00)
+        >>> calculate_total_with_tax(item, 0.10)
+        11.0
+    """
+    if not 0 <= tax_rate <= 1:
+        raise ValueError("Tax rate must be between 0 and 1")
+
+    return item.price * (1 + tax_rate)
+```
+
+---
+
+## Readable Code Patterns
+
+### Bad vs Good Examples
+
+```python
+# BAD: Unreadable, no types, magic numbers
+def calc(x, y):
+    if x > 0:
+        if y > 0:
+            if x + y < 100:
+                return x * 1.1 + y * 0.9
+    return 0
+
+# GOOD: Readable, typed, constants
+TAX_RATE = 0.10
+DISCOUNT_RATE = 0.10
+MAX_TOTAL = 100.00
+
+def calculate_order_total(
+    base_amount: float,
+    discount_amount: float
+) -> float:
+    """Calculate order total with tax and discount.
+
+    Args:
+        base_amount: Base order amount before tax
+        discount_amount: Discount amount to apply
+
+    Returns:
+        Final order total with tax applied
+
+    Raises:
+        ValueError: If amounts are negative or exceed max
+    """
+    if base_amount < 0 or discount_amount < 0:
+        raise ValueError("Amounts must be non-negative")
+
+    subtotal = base_amount - discount_amount
+
+    if subtotal > MAX_TOTAL:
+        raise ValueError(f"Total exceeds maximum {MAX_TOTAL}")
+
+    return subtotal * (1 + TAX_RATE)
+```
+
+---
+
+## Unified Pattern Examples
+
+### Standard Error Handling
+
+```python
+class DomainError(Exception):
+    """Base error for domain-specific errors."""
+    pass
+
+class ValidationError(DomainError):
+    """Validation failed."""
+    pass
+
+def process_data(data: dict) -> Result:
+    """Standard processing pattern."""
+    try:
+        validated = validate_input(data)
+        result = perform_processing(validated)
+        return Result(success=True, data=result)
+
+    except ValidationError as e:
+        logger.error(f"Validation failed: {e}")
+        raise
+    except Exception as e:
+        logger.exception(f"Processing failed: {e}")
+        raise DomainError(f"Processing failed: {e}") from e
+```
+
+---
+
+## Secured Code Patterns
+
+### Access Control (RBAC)
+
+```python
+from functools import wraps
+
+def require_permission(permission: str):
+    """Decorator to enforce permission checks."""
+    def decorator(func):
+        @wraps(func)
+        def wrapper(user: User, *args, **kwargs):
+            if not user.has_permission(permission):
+                raise UnauthorizedError(
+                    f"User lacks permission: {permission}"
+                )
+            return func(user, *args, **kwargs)
+        return wrapper
+    return decorator
+
+@require_permission("user:update")
+def update_user_profile(user: User, profile_data: dict) -> UserProfile:
+    """Update user profile (requires permission)."""
+    return user.update_profile(profile_data)
+```
+
+### Password Hashing
+
+```python
+from bcrypt import hashpw, gensalt, checkpw
+
+def hash_password(plaintext: str) -> str:
+    """Hash password securely with bcrypt."""
+    salt = gensalt(rounds=12)
+    return hashpw(plaintext.encode('utf-8'), salt).decode('utf-8')
+
+def verify_password(plaintext: str, hashed: str) -> bool:
+    """Verify password against hash."""
+    return checkpw(plaintext.encode('utf-8'), hashed.encode('utf-8'))
+```
+
+### Injection Prevention
+
+```python
+from sqlalchemy import text
+
+def safe_user_query(username: str) -> List[User]:
+    """Query users safely with parameterized query."""
+    query = text("SELECT * FROM users WHERE username = :username")
+    return db.session.execute(query, {"username": username}).fetchall()
+```
+
+### Secure Configuration
+
+```python
+import os
+
+def load_secure_config() -> dict:
+    """Load configuration from environment variables."""
+    config = {
+        'DEBUG': os.getenv('DEBUG', 'false').lower() == 'true',
+        'DATABASE_URL': os.getenv('DATABASE_URL'),
+        'SECRET_KEY': os.getenv('SECRET_KEY'),
+        'ALLOWED_HOSTS': os.getenv('ALLOWED_HOSTS', '').split(',')
+    }
+
+    required = ['DATABASE_URL', 'SECRET_KEY']
+    for key in required:
+        if not config.get(key):
+            raise ValueError(f"Required config missing: {key}")
+
+    logger.info(f"Config loaded (DEBUG={config['DEBUG']})")
+    return config
+```
+
+---
+
+## Trackable Patterns
+
+### Traceability Matrix
+
+```yaml
+# .moai/specs/traceability.yaml
+requirements:
+  SPEC-001-REQ-01:
+    description: "User registration with email/password"
+    implementation:
+      - src/auth/registration.py::register_user
+      - src/models/user.py::User
+    tests:
+      - tests/auth/test_registration.py::test_register_user_success
+    coverage: 95%
+    status: Implemented
+
+  SPEC-001-REQ-02:
+    description: "OAuth2 authentication"
+    implementation:
+      - src/auth/oauth2.py::OAuth2Handler
+    tests:
+      - tests/auth/test_oauth2.py::test_oauth2_flow
+    coverage: 92%
+    status: Implemented
+```
+
+---
+
+## Works Well With
+
+- [trust-5-framework.md](trust-5-framework.md) - Overview and principles
+- [trust-5-validation.md](trust-5-validation.md) - CI/CD integration
+
+---
+
+Version: 1.0.0
+Last Updated: 2026-01-06

moai_adk/templates/.claude/skills/moai-foundation-core/modules/trust-5-validation.md

@@ -0,0 +1,219 @@
+# TRUST 5 Validation Framework
+
+Purpose: CI/CD integration, validation engine, and metrics dashboard for TRUST 5 quality gates.
+
+Version: 1.0.0
+Last Updated: 2026-01-06
+Parent: [trust-5-framework.md](trust-5-framework.md)
+
+---
+
+## CI/CD Integration
+
+### Complete Quality Gate Pipeline
+
+```yaml
+# .github/workflows/trust-5-quality-gates.yml
+name: TRUST 5 Quality Gates
+
+on:
+  pull_request:
+    branches: [main, develop]
+  push:
+    branches: [main, develop]
+
+jobs:
+  test-first:
+    name: "T1: Test Coverage ≥85%"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.13'
+      - name: Install dependencies
+        run: pip install -r requirements.txt pytest pytest-cov
+      - name: Run tests with coverage
+        run: pytest --cov=src --cov-report=xml --cov-fail-under=85
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: true
+
+  readable:
+    name: "R: Code Quality ≥8.0"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Pylint check
+        run: pip install pylint && pylint src/ --fail-under=8.0
+      - name: Black format check
+        run: pip install black && black --check src/
+      - name: MyPy type check
+        run: pip install mypy && mypy src/ --strict
+
+  unified:
+    name: "U: Consistency ≥90%"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Architecture validation
+        run: python .moai/scripts/validate_architecture.py
+      - name: Import consistency
+        run: pip install isort && isort --check-only src/
+
+  secured:
+    name: "S: Security Score 100"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Bandit security scan
+        run: pip install bandit && bandit -r src/ -ll
+      - name: Dependency audit
+        run: pip install pip-audit safety && pip-audit && safety check
+      - name: Secret scanning
+        run: pip install detect-secrets && detect-secrets scan
+
+  trackable:
+    name: "T2: Traceability Check"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate commit messages
+        run: python .moai/scripts/validate_commits.py
+      - name: Check traceability
+        run: python .moai/scripts/check_traceability.py
+
+  quality-gate:
+    name: "Final Quality Gate"
+    needs: [test-first, readable, unified, secured, trackable]
+    runs-on: ubuntu-latest
+    steps:
+      - name: All gates passed
+        run: echo "TRUST 5 quality gates passed!"
+```
+
+---
+
+## Validation Engine
+
+### TRUST5Validator Class
+
+```python
+from dataclasses import dataclass
+from typing import List
+import subprocess
+import re
+
+@dataclass
+class ValidationResult:
+    """Result of TRUST 5 validation."""
+    passed: bool
+    test_coverage: float
+    code_quality: float
+    consistency_score: float
+    security_score: int
+    traceability_score: float
+    issues: List[str]
+    warnings: List[str]
+
+    def overall_score(self) -> float:
+        """Calculate overall TRUST 5 score."""
+        weights = {'test': 0.20, 'quality': 0.20, 'consistency': 0.20,
+                   'security': 0.20, 'traceability': 0.20}
+        return (
+            self.test_coverage * weights['test'] +
+            self.code_quality * weights['quality'] +
+            self.consistency_score * weights['consistency'] +
+            self.security_score * weights['security'] +
+            self.traceability_score * weights['traceability']
+        )
+
+class TRUST5Validator:
+    """Comprehensive TRUST 5 validation engine."""
+
+    def __init__(self, src_dir: str = "src/"):
+        self.src_dir = src_dir
+        self.result = ValidationResult(
+            passed=False, test_coverage=0.0, code_quality=0.0,
+            consistency_score=0.0, security_score=0, traceability_score=0.0,
+            issues=[], warnings=[]
+        )
+
+    def validate_all(self) -> ValidationResult:
+        """Run all TRUST 5 validations."""
+        self._validate_test_coverage()
+        self._validate_readability()
+        self._validate_consistency()
+        self._validate_security()
+        self._validate_traceability()
+
+        self.result.passed = all([
+            self.result.test_coverage >= 85,
+            self.result.code_quality >= 8.0,
+            self.result.consistency_score >= 90,
+            self.result.security_score == 100,
+            self.result.traceability_score >= 80
+        ])
+        return self.result
+```
+
+---
+
+## Metrics Dashboard
+
+```python
+class TRUST5Metrics:
+    """Real-time TRUST 5 quality metrics."""
+
+    def __init__(self):
+        self.test_coverage = 0.0      # Target: ≥85%
+        self.code_quality = 0.0       # Target: ≥8.0
+        self.consistency_score = 0.0  # Target: ≥90%
+        self.security_score = 0       # Target: 100
+        self.traceability_score = 0.0 # Target: ≥80%
+
+    def get_dashboard_data(self) -> dict:
+        """Get metrics for dashboard display."""
+        return {
+            'overall_score': self.get_overall_score(),
+            'production_ready': self.is_production_ready(),
+            'metrics': {
+                'test_coverage': {'value': self.test_coverage, 'target': 85},
+                'code_quality': {'value': self.code_quality, 'target': 8.0},
+                'consistency': {'value': self.consistency_score, 'target': 90},
+                'security': {'value': self.security_score, 'target': 100},
+                'traceability': {'value': self.traceability_score, 'target': 80}
+            }
+        }
+
+    def get_overall_score(self) -> float:
+        """Calculate overall TRUST 5 score (0-100)."""
+        return (
+            self.test_coverage * 0.20 +
+            (self.code_quality * 10) * 0.20 +
+            self.consistency_score * 0.20 +
+            self.security_score * 0.20 +
+            self.traceability_score * 0.20
+        )
+
+    def is_production_ready(self) -> bool:
+        """Check if code meets production standards."""
+        return (self.test_coverage >= 85 and self.code_quality >= 8.0 and
+                self.consistency_score >= 90 and self.security_score == 100 and
+                self.traceability_score >= 80)
+```
+
+---
+
+## Works Well With
+
+- [trust-5-framework.md](trust-5-framework.md) - Overview and principles
+- [trust-5-implementation.md](trust-5-implementation.md) - Code patterns
+
+---
+
+Version: 1.0.0
+Last Updated: 2026-01-06