docs: ADR-013 tiered validation pyramid for agentic-first development

[scottschreckengaust]

Summary

Define the four-tier validation architecture that enables agents to self-validate locally before pushing to remote CI, eliminating the slow feedback loops that waste compute and tokens.

The problem

Current validation has two tiers:

• Pre-commit (< 5s) — formatting, secrets, lint
• Remote CI (5–20 min) — full build, test, security, deploy

The gap between these means agents discover failures only after pushing — leading to 15+ minute feedback loops, wasted inference tokens, and cascade failures in stacked PR chains.

The four tiers

Tier	Time	What	Status
0 — Pre-commit	< 5s	Format, lint, secrets	✅ Implemented
1 — Local build	30–90s	Compile, unit test, synth	⚠️ Exists but not gated
2 — Local sandbox	1–5 min	Integration, container tests	❌ Gap
3 — Remote CI	5–20 min	Full matrix, deploy, E2E	✅ Implemented

Tier 2 is the critical gap. This ADR defines what it should contain and how to build it progressively.

Scope

• ADR-013 documenting the tiered validation architecture decision
• Tier definitions with what each catches
• Progressive build-out plan for Tier 2 (LocalStack → agent smoke → ephemeral stack → full sandbox)
• Enforcement model (which tier gates which event)
• Agent interaction model (skill-driven validation before push)
• Investment priority (P0–P4)
• Escape hatches for legitimate bypasses

Acceptance criteria

• docs/decisions/013-tiered-validation-pyramid.md exists with status proposed
• All four tiers defined with time budget, scope, and current implementation status
• Tier 2 progressive build-out phases documented (2a–2d)
• Enforcement model table: event → required tier → mechanism
• Agent interaction model: skill invocation before push
• Design constraints documented (no cloud creds for basic operation, cacheable, no duplicate work)
• Escape hatches with explicit documentation requirement
• Starlight mirrors generated and pass astro check
• CI passes on PR docs: ADR-005 through ADR-013 (feedback, flags, knowledge, DoD, security, recovery, conflicts, knowledge stack, validation pyramid) #144

Dependencies

• Part of: feat(docs): ADR governance framework (ADRs 001-013) #145 (ADR governance framework)
• Delivered in: PR docs: ADR-005 through ADR-013 (feedback, flags, knowledge, DoD, security, recovery, conflicts, knowledge stack, validation pyramid) #144 (alongside ADR-005 through ADR-013)
• Related to: docs: ADR-012 operational knowledge stack (Decision → Guide → Skill) #148 — ADR-012 (skills interact with validation tier gates)
• Related to: ADR-002 / feat(bootstrap): ADR framework and least-privilege decision record #121 (Tier 2c validates IAM preflight locally)
• Related to: ADR-008 / RFC: ADR-008 — Definition of Done (progressive maturity) #139 (tier requirements map to DoD levels)

References

• LocalStack: https://localstack.cloud (candidate for Tier 2a)
• Firecracker MicroVMs: https://firecracker-microvm.github.io (candidate for Tier 2d)
• Current hooks: .pre-commit-config.yaml (Tier 0)
• Current build: mise.toml (Tier 1)