Foundation: TRUST Validation

Skill Metadata

What it does

Validates MoAI-ADK's TRUST 5-principles compliance using the latest 2025 testing frameworks, SAST tools, and CI/CD automation to ensure code quality, testability, security, and traceability.

When to use

• Activates when TRUST compliance or release readiness needs evaluation
• "Check the TRUST principle", "Quality verification", "Check code quality"
• Automatically invoked by /alfred:3-sync
• Before merging PR or releasing
• During CI/CD pipeline execution

How it works

T - Test First (Coverage ≥85%)

Supported Testing Frameworks (2025-10-22):

TDD Cycle Verification:

• RED: Failing test exists before implementation (@TEST:ID)
• GREEN: Implementation passes test (@CODE:ID)
• REFACTOR: Code quality improvements documented

Quality Gates:

• Line coverage ≥85%
• Branch coverage ≥80%
• No skipped tests in production code
• Test execution time <5 minutes for unit tests

R - Readable (Code Quality)

Constraints:

• File ≤300 LOC
• Function ≤50 LOC
• Parameters ≤5
• Cyclomatic complexity ≤10

Linting Tools (2025-10-22):

Formatting Standards:

• Consistent indentation (language-specific)
• Meaningful variable/function names
• Early return pattern (guard clauses)
• Comments only for "why", not "what"

U - Unified (Architecture)

Verification Points:

• SPEC-driven architecture consistency
• Clear module boundaries and responsibilities
• Type safety (TypeScript strict mode, mypy strict, etc.)
• Interface/Protocol compliance
• Dependency direction (inward toward domain)

Type Checking Tools:

S - Secured (Security & SAST)

SAST Tools (2025-10-22):

Security Checklist:

• No hardcoded secrets (API keys, passwords, tokens)
• Input validation on all external data
• Proper error handling (no sensitive info in errors)
• Dependency vulnerability scan passed
• Access control enforced
• HTTPS/TLS for network calls

T - Trackable (TAG Chain Integrity)

TAG Structure Validation:

• @SPEC:ID in specs (.moai/specs/SPEC-<ID>/spec.md)
• @TEST:ID in tests (tests/)
• @CODE:ID in source (src/)
• @DOC:ID in docs (docs/)

Chain Verification:

# Scan all TAGs
rg '@(SPEC|TEST|CODE|DOC):' -n .moai/specs/ tests/ src/ docs/

# Detect orphans
rg '@CODE:AUTH-001' -n src/          # CODE exists
rg '@SPEC:AUTH-001' -n .moai/specs/  # SPEC missing → orphan

Traceability Requirements:

• Every @CODE:ID must reference @SPEC:ID and @TEST:ID
• TAG block includes file paths: SPEC: <path> | TEST: <path>
• HISTORY section tracks all changes with dates
• No duplicate TAG IDs across project

Inputs

• Project configuration (.moai/config.json, CLAUDE.md)
• Source code (src/, tests/)
• SPEC documents (.moai/specs/)
• CI/CD configuration (.github/workflows/)

Outputs

• TRUST compliance report (pass/fail per principle)
• Coverage metrics with delta from previous run
• Security scan results
• TAG chain validation report
• Quality gate decision (block/allow merge)

CI/CD Integration

GitHub Actions Example (.github/workflows/trust-validation.yml):

name: TRUST Validation

on: [pull_request, push]

jobs:
  trust-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # T - Test First (Python example)
      - name: Run tests with coverage
        run: |
          pip install pytest pytest-cov
          pytest --cov=src --cov-report=xml --cov-fail-under=85

      # R - Readable
      - name: Lint code
        run: |
          pip install ruff
          ruff check .

      # U - Unified
      - name: Type check
        run: |
          pip install mypy
          mypy src/ --strict

      # S - Secured
      - name: Security scan
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: 'fs'
          severity: 'HIGH,CRITICAL'
          exit-code: '1'

      - name: Secret detection
        run: |
          pip install detect-secrets
          detect-secrets scan --baseline .secrets.baseline

      # T - Trackable
      - name: TAG validation
        run: |
          # Check for orphaned TAGs
          ./scripts/validate-tags.sh

Quality Gate Enforcement

Merge Requirements:

• All 5 TRUST principles must pass
• Test coverage ≥85% (no regression from baseline)
• Zero high/critical security vulnerabilities
• All TAGs have valid chains
• Code review approved

Failure Actions:

• Block PR merge
• Post detailed failure report as PR comment
• Suggest remediation steps
• Link to relevant documentation

Failure Modes

• Missing standard files (.moai/config.json, CLAUDE.md)
• Insufficient file access permissions
• Conflicting policies requiring coordination
• Tool version mismatches in CI vs local
• Network failures during dependency scans

Dependencies

• Works synergistically with moai-foundation-tags (TAG traceability)
• Requires moai-foundation-specs (SPEC validation)
• Integrates with cc-manager for session management

References

• pytest Documentation. "Coverage Reporting." https://docs.pytest.org/en/stable/how-to/coverage.html (accessed 2025-10-22).
• Vitest Documentation. "Coverage Guide." https://vitest.dev/guide/coverage.html (accessed 2025-10-22).
• Go Testing Package. "Coverage Testing." https://go.dev/blog/coverage (accessed 2025-10-22).
• Trivy Documentation. "Vulnerability Scanning." https://trivy.dev/ (accessed 2025-10-22).
• detect-secrets. "Secret Detection Tool." https://github.com/Yelp/detect-secrets (accessed 2025-10-22).
• SemGrep. "Lightweight SAST." https://semgrep.dev/docs/ (accessed 2025-10-22).
• SonarSource. "Quality Gate: Developer's Guide." https://www.sonarsource.com/company/newsroom/white-papers/quality-gate/ (accessed 2025-03-29).
• ISO/IEC 25010. "Systems and software quality models." (accessed 2025-03-29).

Changelog

• 2025-10-22: v2.0.0 - Added latest tool versions (pytest 8.4.2, Vitest 2.0.5, trivy 0.56.x, etc.), CI/CD automation, SAST tools, quality gate enforcement
• 2025-03-29: v1.0.0 - Foundation skill templates enhanced to align with best practice structures

Works well with

• moai-foundation-tags (TAG traceability)
• moai-foundation-specs (SPEC validation)
• moai-alfred-trust-validation (Alfred workflow integration)
• cc-manager (session management)

Examples

Scenario 1: Pre-merge TRUST validation

# Run full TRUST check before merging
pytest --cov=src --cov-fail-under=85
ruff check .
mypy src/ --strict
trivy fs --severity HIGH,CRITICAL .
detect-secrets scan
rg '@(SPEC|TEST|CODE):' -n .moai/specs/ tests/ src/

Scenario 2: CI/CD pipeline integration

# GitHub Actions workflow snippet
- name: TRUST Gate
  run: |
    chmod +x scripts/trust-check.sh
    ./scripts/trust-check.sh || exit 1

Scenario 3: Local development pre-commit

# .git/hooks/pre-commit
#!/bin/bash
pytest --cov=src --cov-fail-under=85 --quiet || exit 1
ruff check . --quiet || exit 1
mypy src/ --strict --no-error-summary || exit 1

Best Practices

• Run TRUST validation locally before pushing
• Configure IDE to show coverage inline
• Automate quality gates in CI/CD (never manual)
• Track coverage trends over time
• Document reasons for TRUST exceptions (with approval)
• Update tool versions quarterly
• Use pre-commit hooks for fast feedback
• Fail fast on security violations
• Generate coverage reports for review
• Archive TRUST reports per release