Pillars
Pillar — Quality
How to know the code works without manually reviewing every agent-produced diff.
Pillar — Quality
How to know the code works without manually reviewing every agent-produced diff.
Status
◐ Scoped, not yet detailed.
Scope
| Concern | Universal principle | Concrete pattern |
|---|---|---|
| Test pyramid | Unit > integration > E2E; cover the boundary contracts heavily | Vitest unit + Playwright E2E + contract-level params/result parse tests |
| Coverage target | >90% per shipped package, measured against statements | Per-package coverage threshold in CI; per-package, not whole-repo |
| Mutation testing | Beats coverage as a quality signal once unit suite is good | Stryker / mutation tool on stable utilities first |
| Property / fuzz | Test the laws code must obey; attack parsers + crypto with hostile bytes | Generated inputs + shrinking; fuzz at the trust boundary |
| Adversarial bug-hunt | One agent says "looks fine"; a refute-then-reproduce loop finds real logic bugs | Orthogonal lenses → skeptic refute → failing repro; loop until dry |
| Fail-loud defaults | A no-op default the test harness always overrides hides missing prod wiring | Fail loud when unwired, or assert the real binding in an integration test |
| Hermetic tests | Component-level vitest preferred over live-app E2E | Reproduce + lock bugs via in-process tests, not Playwright |
| Verify-first close | Before reproducing an issue, check if it's already fixed | Default gh issue view \<n\> at session start |
| File-size gate | See architecture pillar | Baseline shrink-only |
| Lint gates | No any, no console.log, no default exports, no nested ternaries, no raw HTML | ESLint rule pack + per-file overrides |
| Quality-gates script | One pnpm check:quality-gates for fast structural checks | Parallel: lint + typecheck + secrets + size + intl + tokens |
| Sanity script | One pnpm sanity for cross-cutting rule audit | Generates docs/audit/sanity-report.md; CI fails on regressions |
| Pre-push hook | Runs structural gates + ADR/RFC checks; not full tests | Husky pre-push; tests on CI |
| Concurrency safety | Agents merge PRs against fast-moving main | Stash-verify red, rebase, retry; never --theirs/--ours blindly |
Non-negotiables
- Tests are part of the diff. No "tests next PR".
- Coverage is per package, not aggregate. Aggregate hides which package is bad.
- Hermetic over E2E for bug repro. Component tests fail in 2s; Playwright fails in 60s and lies more.
- Gates produce actionable messages. "Lint failed" is not actionable. "src/x.ts:42 — no
anyin boundary file; useunknownand parse." is. - Pre-push is the safety net, not the proof. Run
check:allbefore a release.
See also
../architecture/file-size-budget.md../governance/README.md— PR-intent ties tests to claims.../../scripts/— gate reference impls.
Documents in this pillar
| Doc | Read when |
|---|---|
universal.md | First read; the 9 non-negotiables |
test-pyramid.md | Test-tier distribution + escalation |
quality-gates-pattern.md | Structural gate suite + orchestrator |
pre-push-pattern.md | Three-tier hook split |
sanity-pattern.md | Cross-cutting audit |
mutation-testing-pattern.md | Beyond coverage |
property-fuzz-testing-pattern.md | Test the laws, not the examples; fuzz the trust boundary |
adversarial-bug-hunt-pattern.md | Find real logic bugs: find → refute → reproduce |
fail-loud-defaults-pattern.md | No-op defaults + over-wired test harness = green CI, broken prod |
observability-pattern.md | Metrics / logs / traces / SLOs |
performance-budgets-pattern.md | Bundle / latency / resource budgets |
chaos-engineering-pattern.md | Controlled fault injection |
ci-cd-pipeline-pattern.md | Commit → prod pipeline; caching; deploy patterns; DB migrations |
alerting-runbooks-pattern.md | SLO burn-rate alerts; runbook 5-section template; tuning loop |
cost-optimization-pattern.md | FinOps; per-tenant attribution; right-sizing; commitments + spot |
contract-testing-pattern.md | Pact + schema-first; consumer-driven contracts; broker; can-i-deploy |
product-analytics-experimentation-pattern.md | Event tracking; funnels + cohorts; A/B experiments; holdouts |
agent-eval-framework-pattern.md | Measuring AI agent quality: deterministic graders + LLM-as-judge + production monitoring; eval set as a versioned asset |