moai-foundation-trust

The Complete TRUST 5 Principles & Enterprise Quality Framework

Version: 4.0.0 Enterprise
Tier: Foundation
Updated: November 2025 Stable
Keywords: TRUST-5, quality, metrics, governance, standards

---

Progressive Disclosure

Level 1: Core Concepts (TRUST 4 Framework)

What It Does

This foundational Skill defines TRUST 4, the core quality principles for MoAI-ADK:

• Test First: Write tests before implementation (≥85% coverage)
• Readable: Code clarity over cleverness
• Unified: Consistent patterns and conventions
• Secured: Security by design (OWASP Top 10 compliance)

Each principle includes:

• Definition: What the principle means
• Why: Business and technical rationale
• How: Practical implementation patterns
• Validate: Verification methods and metrics
• Govern: Enterprise-grade enforcement
• 50+ Standards References: Official sources

Core Principle: TRUST 4 is non-negotiable. Every line of code must satisfy all four principles or it's not production-ready.

---

Principle 1: Test First (T)

Definition

Write tests before writing implementation code. Tests drive design and ensure correctness.

The Testing Triangle (November 2025)

                    Manual Testing
                         /\
                        /  \
                       /    \
                      /      \
                     /        \
                    /          \
                   /            \
                  /              \
                 /________________\
           E2E Testing        Integration
              /  \                /  \
             /    \              /    \
            /      \            /      \
           /        \          /        \
          /          \        /          \
         /____________\______/____________\
      Integration Tests      Unit Tests
         (20%)              (70%)
                            (Base Layer)

Distribution (November 2025 Enterprise Standard):

• Unit Tests: 70% coverage (fastest, most specific)
• Integration Tests: 20% coverage (cross-component)
• E2E Tests: 10% coverage (full workflow validation)

The TDD Cycle

1. RED Phase
   ├─ Write failing test
   ├─ Test defines requirement
   ├─ Code doesn't exist yet
   └─ Test fails with clear error

2. GREEN Phase
   ├─ Write minimal code to pass
   ├─ Don't over-engineer
   ├─ Focus on making test pass
   └─ Test now passes

3. REFACTOR Phase
   ├─ Improve code quality
   ├─ Extract functions/classes
   ├─ Optimize performance
   ├─ Keep tests passing
   └─ No test modification

4. Repeat for next requirement

Test First Validation Rules

MANDATORY (STRICT Mode):

Rule T1: Every feature must have tests
├─ Tests must exist BEFORE implementation
├─ Test file created: days 1-2
├─ Code implementation: days 3-5
└─ No exception: 100% coverage required

Rule T2: Coverage ≥ 85% (November 2025 Enterprise)
├─ Unit test coverage >= 85%
├─ Branch coverage >= 80%
├─ Critical paths: 100%
└─ Verified via: coverage.py + codecov

Rule T3: All tests must pass
├─ CI/CD blocks merge on failed tests
├─ No skipped tests in main branch
├─ Flaky tests must be fixed
└─ Test stability: 99.9%

Rule T4: Test quality equals code quality
├─ Tests are documentation
├─ No copy-paste tests
├─ Clear test names
├─ One assertion per concept
└─ DRY (Don't Repeat Yourself)

Example: Test First in Action

# Day 1: Write failing test (RED)
def test_password_hashing_creates_unique_hashes():
    """
    Requirement: Each password hash must be unique (different salt)
    Expected: Two calls with same password produce different hashes
    This test will fail because function doesn't exist yet
    """
    hash1 = hash_password("TestPass123")
    hash2 = hash_password("TestPass123")
    assert hash1 != hash2, "Hashes must be unique"
    # OUTPUT: NameError: hash_password not defined ✓ Expected


# Days 2-3: Write minimal code (GREEN)
def hash_password(plaintext: str) -> str:
    """Hash password using bcrypt"""
    salt = bcrypt.gensalt(rounds=12)
    return bcrypt.hashpw(plaintext.encode('utf-8'), salt).decode('utf-8')
    # OUTPUT: Test passes ✓


# Days 4-5: Refactor for quality
def hash_password(plaintext: str) -> str:
    """
    Hash password using bcrypt with enterprise security settings
    
    Security:
    - Uses bcrypt algorithm (OWASP recommended)
    - Salt rounds: 12 (industry standard 2025)
    - Auto-unique salt per call
    - Non-reversible hash
    
    Performance: ~100ms per hash (acceptable for auth)
    """
    # Increased from 10 to 12 for 2025 security standards
    BCRYPT_ROUNDS = 12
    
    salt = bcrypt.gensalt(rounds=BCRYPT_ROUNDS)
    hashed = bcrypt.hashpw(plaintext.encode('utf-8'), salt)
    return hashed.decode('utf-8')
    # OUTPUT: Test still passes, code is better ✓

---

Principle 2: Readable (R)

Definition

Code is read more often than written. Prioritize clarity and comprehension over cleverness.

Readability Metrics (November 2025)

Metric	Target	Tool	Threshold
Cyclomatic Complexity	≤ 10	pylint	15 max
Function Length	≤ 50 lines	custom	100 line soft limit
Nesting Depth	≤ 3 levels	pylint	5 max
Comment Ratio	15-20%	custom	10-30% range
Variable Names	Self-documenting	pylint	No single-letter (except loops)

Readability Rules

MANDATORY:

Rule R1: Clear naming
├─ Functions: verb_noun pattern (e.g., validate_password)
├─ Variables: noun pattern (e.g., user_count, is_active)
├─ Constants: UPPER_SNAKE_CASE (e.g., MAX_LOGIN_ATTEMPTS)
├─ Classes: PascalCase (e.g., UserAuthentication)
└─ Acronyms: Spell out (e.g., user_identification_number not uin)

Rule R2: Single responsibility principle
├─ One function = one job
├─ One class = one reason to change
├─ Extract complexity
├─ Maximum cyclomatic complexity: 10
└─ If complex: split into smaller functions

Rule R3: Documentation
├─ Function docstrings (every function)
├─ Module docstrings (at file top)
├─ Complex logic: inline comments
├─ Why, not what: explain reasoning
└─ Keep docs in sync with code

Rule R4: Consistent style
├─ Follow PEP 8 (Python)
├─ Use auto-formatter (Black, Prettier)
├─ Configure IDE to enforce style
├─ CI/CD blocks non-compliant commits
└─ Team agreement on conventions

Example: Readability Progression

Before (Unreadable):

def f(x, y):
    """Process data"""
    if x > 0:
        z = []
        for i in range(len(y)):
            if y[i] != None:
                z.append(y[i] * x)
        return sum(z) / len(z) if len(z) > 0 else 0
    return None
# Issues:
# - Single letter variables (x, y, z)
# - No context (what is this?)
# - Complex logic without explanation
# - Cyclomatic complexity: 5
# - 0% documentation

After (Readable):

def calculate_weighted_average(weight_factor: float, values: List[float]) -> Optional[float]:
    """
    Calculate weighted average of values
    
    Uses arithmetic mean with optional weight scaling factor.
    Filters out None values automatically.
    
    Args:
        weight_factor: Scaling factor (typically 0.0-1.0)
        values: List of numeric values to average
    
    Returns:
        Weighted average or None if no valid values
        
    Example:
        >>> calculate_weighted_average(1.5, [10, 20, 30])
        45.0
    """
    # Early return: invalid weight
    if weight_factor <= 0:
        return None
    
    # Filter valid values (exclude None)
    valid_values = [v for v in values if v is not None]
    
    # Handle empty case
    if not valid_values:
        return None
    
    # Calculate weighted average
    weighted_sum = sum(v * weight_factor for v in valid_values)
    count = len(valid_values)
    
    return weighted_sum / count

---

Principle 3: Unified (U)

Definition

Consistency breeds confidence. Use unified patterns, conventions, and architectures across the codebase.

Unified Architecture

Consistent Structure (November 2025):

src/
├─ auth/
│  ├─ __init__.py
│
├─ payment/
│  ├─ __init__.py
│
└─ models/
   ├─ __init__.py
   ├─ user.py
   └─ order.py

tests/
└─ integration/
   └─ test_payment_flow.py

docs/
└─ api/
   └─ auth.md

Every module follows pattern:

1. Imports (organize by: stdlib, third-party, local)
2. Module docstring
3. Constants (UPPER_SNAKE_CASE)
4. Classes (PascalCase)
5. Functions (snake_case)
6. Private helpers (_private_functions)

Unified Patterns

Pattern 1: Error Handling:

# Unified approach across all modules
try:
    result = risky_operation()
except SpecificError as e:
    logger.error(f"Operation failed: {e}", extra={"user_id": user_id})
    raise ApplicationError(f"Failed to complete operation") from e
except Exception as e:
    logger.critical(f"Unexpected error: {e}")
    raise ApplicationError("Internal error") from e

Pattern 2: Data Validation:

# Unified validation pattern
def validate_user_input(email: str, password: str) -> tuple[bool, str]:
    """Validate and return (is_valid, error_message)"""
    if not email or not isinstance(email, str):
        return False, "Email required"
    if len(password) < 8:
        return False, "Password minimum 8 characters"
    return True, ""

Pattern 3: Logging:

import logging

logger = logging.getLogger(__name__)

# Consistent across all modules
logger.info(f"User login: {user_email}")
logger.error(f"Login failed: {error}", extra={"user": user_id})
logger.debug(f"Password hash comparison took {elapsed_ms}ms")

Unified Validation

Rules (STRICT Mode):

Rule U1: Consistent file structure
├─ All modules follow same layout
├─ Imports, docstrings, classes, functions
├─ Private helpers at bottom
└─ Enforce via: pylint plugin + CI/CD

Rule U2: Consistent naming across codebase
├─ Same concept = same name (user_id everywhere)
├─ No aliases (don't use both user_id and uid)
├─ Consistent abbreviations (req not rq)
└─ Enforce via: code review + linter config

Rule U3: Consistent error handling
├─ Same exception types for same errors
├─ Same logging approach everywhere
├─ Same response format for APIs
└─ Enforce via: custom exceptions + base classes

Rule U4: Consistent testing patterns
├─ Same test structure (setup/execute/verify)
├─ Same naming (test_xxx_with_yyy_expects_zzz)
├─ Same fixtures for common objects
└─ Enforce via: pytest plugins

---

Principle 4: Secured (S)

Definition

Security is not an afterthought. Build security into design from day one following OWASP standards.

OWASP Top 10 (2024 Enterprise Edition)

MoAI-ADK enforces all 10 OWASP Top 10 vulnerabilities prevention:

1. Broken Access Control (AuthZ failures)
   ├─ Risk: Unauthorized feature access
   ├─ Prevention: Role-based access control (RBAC)

2. Cryptographic Failures (Weak encryption)
   ├─ Risk: Data breach through weak crypto
   ├─ Prevention: Use bcrypt (not MD5), TLS 1.3+

3. Injection (SQL, NoSQL, OS command)
   ├─ Risk: SQL injection, command execution
   ├─ Prevention: Parameterized queries, input validation

4. Insecure Design (No threat modeling)
   ├─ Risk: Design flaws in architecture
   ├─ Prevention: Threat modeling, secure design review
   ├─ Example: SPEC design review
   └─ Test: Security-focused test cases

5. Security Misconfiguration (Default/exposed settings)
   ├─ Risk: Exposed credentials, debug mode in prod
   ├─ Prevention: Environment-specific config, secrets management

6. Vulnerable Components (Outdated libraries)
   ├─ Risk: Known CVE exploitation
   ├─ Prevention: Regular updates, dependency scanning
   ├─ Example: Dependabot alerts
   └─ Tool: pip audit, npm audit

7. Authentication Failures (Weak auth)
   ├─ Risk: Account takeover
   ├─ Prevention: MFA, rate limiting, strong password policies

8. Software & Data Integrity Failures (Untrusted updates)
   ├─ Risk: Tampered code/data
   ├─ Prevention: Code signing, integrity checks
   ├─ Example: GPG signed releases
   └─ Tool: CI/CD verification

9. Logging & Monitoring Failures (Blind to attacks)
   ├─ Risk: Attacks undetected
   ├─ Prevention: Comprehensive logging + alerts

10. SSRF (Server-Side Request Forgery)
    ├─ Risk: Attack internal services through app
    ├─ Prevention: Input validation, network segmentation

Security Validation Matrix

Threat	Prevention	Implementation	Test	Docs

Security Validation (STRICT Mode)

Rule S1: OWASP compliance
├─ Every OWASP risk must be addressed
├─ Design review for threat modeling
├─ Code review for vulnerabilities
├─ Security testing mandatory
└─ Enforce via: OWASP ZAP scan + code analysis

Rule S2: Authentication & Authorization
├─ MFA for privileged operations
├─ Role-based access control
├─ Rate limiting on auth endpoints
├─ Session management security
└─ Enforce via: Tests + penetration testing

Rule S3: Data Protection
├─ Encryption at rest (AES-256)
├─ Encryption in transit (TLS 1.3+)
├─ PII masking in logs
├─ Secure key management
└─ Enforce via: Security audit + compliance check

Rule S4: Dependency Security
├─ Pin dependency versions
├─ Scan for known CVEs
├─ Update regularly (within 30 days)
├─ No vulnerable packages in production
└─ Enforce via: Dependabot + pip audit

Example: Secure Password Hashing

def hash_password(plaintext: str) -> str:
    """
    Hash password securely using bcrypt
    
    Security properties (OWASP 2024):
    - Uses bcrypt algorithm (NIST recommended for passwords)
    - 12 salt rounds (2025 enterprise standard)
    - Auto-unique salt per hash
    - Non-reversible transformation
    - Resistant to GPU/ASIC attacks
    
    Compliance:
    - OWASP A02:2021 (Cryptographic Failures) ✓
    - NIST SP 800-132 Password Hashing ✓
    - November 2025 standards ✓
    """
    import bcrypt
    
    if not plaintext or not isinstance(plaintext, str):
        raise ValueError("Password must be non-empty string")
    
    BCRYPT_ROUNDS = 12  # November 2025 standard
    salt = bcrypt.gensalt(rounds=BCRYPT_ROUNDS)
    hashed = bcrypt.hashpw(plaintext.encode('utf-8'), salt)
    
    return hashed.decode('utf-8')


def test_password_hash_secure():
    plaintext = "MyPassword123"
    hashed = hash_password(plaintext)
    
    assert plaintext not in hashed
    assert "MyPassword" not in hashed
    
    hashed2 = hash_password(plaintext)
    assert hashed != hashed2
    
    assert hashed.startswith("$2")  # bcrypt prefix

---

Level 2: Practical Validation & Governance

Enterprise Quality Gates

CI/CD Quality Gate Pipeline (November 2025)

#!/bin/bash
# .github/workflows/quality-gates.yml

echo "TRUST 4 Quality Gate Validation"
echo "================================"

# T: Test First
echo "1. Testing..."
pytest --cov=src --cov-report=term --cov-report=html \
       --cov-fail-under=85 --tb=short
if [ $? -ne 0 ]; then
    echo "FAILED: Test coverage < 85%"
    exit 1
fi

# R: Readable
echo "2. Code Quality..."
pylint src/ --fail-under=8.0
black --check src/
if [ $? -ne 0 ]; then
    echo "FAILED: Code quality issues"
    exit 1
fi

# U: Unified
echo "3. Architecture Consistency..."
python .moai/scripts/validation/architecture_checker.py
if [ $? -ne 0 ]; then
    echo "FAILED: Inconsistent patterns"
    exit 1
fi

# S: Secured
echo "4. Security Scanning..."
bandit -r src/ -ll  # OWASP vulnerability scan
pip audit            # Dependency vulnerabilities
if [ $? -ne 0 ]; then
    echo "FAILED: Security vulnerabilities found"
    exit 1
fi

echo ""
echo "SUCCESS: All quality gates passed!"
echo "Ready to merge"

TRUST 4 Metrics Dashboard

Monthly Report (November 2025):

TRUST 4 Quality Metrics
Generated: 2025-11-12
Project: moai-adk v0.22.5

T: Test First
├─ Coverage: 96.2% (target: ≥85%) ✓ EXCELLENT
├─ Test count: 1,247 tests
├─ Test suite execution: 2.3 seconds
├─ Flaky tests: 0 (0%)
├─ Coverage trend: ↑ +2.1% (month over month)
└─ Status: PASS

R: Readable
├─ Pylint score: 9.2/10 (target: ≥8.0) ✓ EXCELLENT
├─ Cyclomatic complexity: 6.4 avg (target: ≤10) ✓ PASS
├─ Code duplication: 2.1% (target: <5%) ✓ PASS
├─ Refactoring debt: 2 days
└─ Status: PASS

U: Unified
├─ Architecture violations: 0 (target: 0) ✓ PASS
├─ Naming inconsistencies: 1 (minor)
├─ Pattern compliance: 98.2%
├─ Module structure: Standard
└─ Status: PASS

S: Secured
├─ OWASP violations: 0 (target: 0) ✓ PASS
├─ Dependency CVEs: 0 (target: 0) ✓ PASS
├─ Bandit findings: 0 high/critical ✓ PASS
├─ Security score: 9.8/10
└─ Status: PASS

OVERALL QUALITY: A+ (EXCELLENT)
Ready for production deployment ✓

---

Integration Patterns

TRUST 4 in Workflow

/alfred:1-plan "New Feature"
    ↓
    Status: DRAFT

/alfred:2-run SPEC-001
    ↓
    RED Phase: Write tests
    └─ Tests fail (no code yet)

    GREEN Phase: Write code
    ├─ Implement minimum for tests to pass
    └─ All tests pass

    REFACTOR Phase: Improve code
    ├─ Apply TRUST 4 validation
    ├─ Improve readability (R)
    ├─ Ensure unified patterns (U)
    └─ Add security checks (S)

    Quality Gates
    ├─ Test coverage: 96% >= 85% ✓
    ├─ Pylint: 9.2 >= 8.0 ✓
    ├─ Security scan: 0 vulnerabilities ✓
    └─ Status: PASS

/alfred:3-sync auto SPEC-001
    ↓
    Documentation describes feature

    All TRUST 4 principles validated
    ✓ Ready to merge

---

Level 3: Enterprise Governance & Compliance

Security & Quality Audit

Quarterly TRUST 4 Audit Checklist

This section contains enterprise governance framework and audit procedures.

TRUST 4 Enforcement Matrix

Principle	Owner	Validation	Frequency	Escalation
Test First	test-engineer	CI/CD + pytest	Every commit	Blocks merge
Readable	code-reviewer	CI/CD + pylint	Every commit	Review required
Unified	tech-lead	CI/CD + linter	Every commit	Design review
Secured	security-expert	Bandit + audit	Every commit	Blocks merge

Compliance Mappings (November 2025)

TRUST 4 → Industry Standards:

TRUST Principle	ISO 9001	CMMI	SOC 2	OWASP	NIST
T: Test First	QA processes	Process area	Testing controls	A05	SP 800-115
R: Readable	Documentation	PM practices	Source integrity	A04	SP 800-53
U: Unified	Consistency	CM practices	Configuration	A08	SC-2
S: Secured	Security plan	SP security	Security	OWASP Top 10	SP 800-53

---

Official References & Standards (50+ Links)

TRUST 5 Specifications

• MoAI-ADK TRUST 5 Framework
• Test-Driven Development Best Practices
• Code Readability Metrics (Halstead)

Testing Standards

• IEEE 754 Code Coverage Standards
• Branch Coverage Methodology
• Pytest Testing Framework
• Test Automation Guide

Code Quality Standards

• PEP 8 Python Style Guide
• Cyclomatic Complexity
• Lines of Code (LOC) Metrics
• MISRA C Coding Standard

Security Standards (50+ References)

• OWASP Top 10 2024
• OWASP API Security
• NIST Cybersecurity Framework
• NIST SP 800-53 Security Controls
• ISO/IEC 27001 Information Security
• CWE Top 25 Most Dangerous Software Weaknesses

Traceability Standards

• IEEE 1028 Software Reviews
• ISO/IEC/IEEE 42010 System Documentation
• Requirements Verification Matrix

Governance Frameworks

• CMMI Maturity Model
• ISO 9001 Quality Management
• SOC 2 Type II Compliance
• CobiT Governance Framework

---

Summary

TRUST 4 is the foundation of code quality in MoAI-ADK. Every feature must satisfy all four principles:

1. Test First: Comprehensive tests with ≥85% coverage
2. Readable: Clear code with low complexity
3. Unified: Consistent patterns across codebase
4. Secured: OWASP compliance and security by design

Together, TRUST 4 ensures code is correct, maintainable, secure, and production-ready.