moai-foundation-quality

# TRUST 5 Quality Principles and Enforcement

This skill provides background knowledge on MoAI's quality model: the five
TRUST 5 principles, how agents enforce them, the 3-level harness, and the
language-aware toolchains that `/moai gate` runs. MoAI does NOT ship a
quality-validation library — quality is enforced through agents
(`manager-develop`, `sync-auditor`), slash commands (`/moai gate`,
`/moai review`), and the harness (minimal/standard/thorough).

## Quick Reference

**TRUST 5 Principles** (Tested, Readable, Unified, Secured, Trackable) are
quality dimensions, not code objects. Every code change is evaluated against
all five.

**Quality Mechanisms** (the real enforcement layer):

- `/moai gate` — runs lint + format + type-check + test in parallel as a
  pre-commit quality gate (<30s). Auto-detects the project language and runs
  the appropriate toolchain.
- `manager-develop` (run-phase) — implements via `cycle_type` ∈ {tdd, ddd,
  autofix}; the chosen cycle shapes how tests and behavior are produced.
- `sync-auditor` — independent skeptical quality assessment with 4-dimension
  scoring (Functionality, Security, Craft, Consistency), scored as the
  harmonic mean of dimensions, not the average.
- 3-level harness — minimal (fast validation), standard (default checks),
  thorough (full sync-auditor + TRUST 5). Auto-determined by the Complexity
  Estimator based on SPEC scope.
- LSP quality gates — phase-specific thresholds (run: zero errors/type-errors/
  lint-errors; sync: zero errors, max 10 warnings, clean LSP).

## The MoAI Quality Model

MoAI does not provide a Python SDK or any library for quality validation.
Quality is enforced through the workflow, the agents, and the gate commands.
This skill documents how those pieces fit together so a Claude invocation
can reason about quality correctly.

### How TRUST 5 is enforced per phase

| Phase | Quality check | Owner |
|-------|--------------|-------|
| plan | Capture LSP baseline; identify quality risks in the plan | manager-spec |
| run | Zero errors/type-errors/lint-errors; tests pass; coverage met | manager-develop (cycle_type shapes the approach) |
| sync | Lint clean (≤10 warnings); docs updated; TRUST 5 re-affirmed | manager-docs, then sync-auditor scores |
| audit | Independent 4-dimension scoring (Functionality/Security/Craft/Consistency) | sync-auditor |

### cycle_type and quality (manager-develop)

The run-phase `cycle_type` selects how quality is built in:

- **tdd** — Test-Driven Development (RED-GREEN-REFACTOR). Behavior is
  specified by a failing test first, then implemented. Best for new features.
- **ddd** — Domain-Driven refactoring (ANALYZE-PRESERVE-IMPROVE).
  Behavior-preserving transformation of existing code. Best for refactoring
  and debt reduction.
- **autofix** — diagnostic-driven fixing (LSP / lint / type errors). Best for
  `/moai fix` and regression recovery.

See Skill("moai-workflow-tdd"), Skill("moai-workflow-ddd"), and
Skill("moai-workflow-loop") for the per-cycle mechanics.

## TRUST 5 Principles

TRUST 5 is a mnemonic for five quality dimensions. Treat each as a question
to ask of any change, not a score to compute.

- **T — Tested**: Does the change have tests? Are they green? Is coverage at
  or above the project threshold (85%+ by default)? For existing untested
  code, are characterization tests capturing current behavior?
- **R — Readable**: Is naming clear? Are comments in English (or the
  configured code-comments language)? Could a new contributor follow the
  logic without a walkthrough?
- **U — Unified**: Does the change match the file's existing conventions
  (naming, error handling, imports)? Is it formatted with the project's
  formatter? Consistency within a file beats personal preference.
- **S — Secured**: Are all external inputs validated? Does it follow OWASP
  guidance for web security? Are credentials kept out of version control
  (environment variables instead)? See moai-ref-owasp-checklist.
- **T — Trackable**: Does the commit follow Conventional Commits? Does it
  reference the SPEC / issue it implements? Can the change be traced back to
  a requirement?

For the per-principle assessment checklist and the "not applicable" guard,
see [TRUST 5 Principles](modules/trust5-validation.md).

## Quality Gates and the 3-Level Harness

The harness level controls how deep quality validation goes. It is
auto-determined by the Complexity Estimator based on SPEC scope.

| Level | What runs | When |
|-------|-----------|------|
| minimal | Fast validation only (lint + type + test) | Small SPECs, low risk |
| standard | Default checks (lint + type + test + format) | Most SPECs |
| thorough | Full sync-auditor + 4-dimension TRUST 5 scoring | Large SPECs, high risk |

`/moai gate` is the lightweight pre-commit entry point: it runs lint +
format + type-check + test in parallel and applies no fixes. It is the
fastest way to get a quality signal. For deeper review use `/moai review`.

## Language-Aware Toolchains

The quality gate auto-detects the project language and runs the appropriate
toolchain. Tools that are not installed are skipped gracefully; projects
with no recognized language marker pass the gate silently. This skill is
language-neutral — the 16 supported languages are treated equally.

| Language | Lint | Format | Test |
|----------|------|--------|------|
| Go | go vet → golangci-lint | gofmt | go test |
| Python | ruff | black | pytest |
| TypeScript / JavaScript | eslint | prettier | jest / mocha |
| Rust | cargo clippy | rustfmt | cargo test |
| Java / Kotlin | (per project linter) | (per project) | junit |
| Ruby | rubocop | rubocop | rspec |
| PHP | phpstan / phpcs | php-cs-fixer | pest / phpunit |
| ... | (16 languages supported; auto-detected) | | |

For the full toolchain mapping and how `/moai gate` detects the language,
see [Language-Aware Toolchains](references/reference.md#language-aware-toolkchains).

## Module Reference

Each module is loaded on demand. Load the o