RFC: ADR-008 — Definition of Done (progressive maturity)

[scottschreckengaust]

Summary

Define what "done" means at each maturity level — from basic (code compiles, tests pass) to comprehensive (tabula rasa agent can replicate, CI verifies behavior matches documentation). The definition of done evolves as the project matures.

Use case and motivation

Problem today:

1. "Done" is implicit and varies by contributor — some consider a passing build sufficient, others expect documentation, tests, and deployment verification.
2. Agents have no unambiguous checklist to know they've completed work.
3. Over-engineering "done" early (requiring everything from day one) blocks velocity.
4. Under-defining "done" (just "tests pass") ships incomplete work.

After this ADR:

• Every issue has an explicit done level
• Done criteria are checklistable (yes/no, not subjective)
• The bar rises as the project matures (progressive, not fixed)
• Agents can self-verify completion without human confirmation

Progressive levels

Level 1: Basic (minimum viable)

• Code compiles without errors
• Existing tests pass (no regressions)
• New code has tests (unit level minimum)
• Linting passes
• PR description explains what and why
• Linked issue exists

Level 2: Standard (current project default)

• All of Level 1
• Pre-commit hooks pass
• CDK synth succeeds (if infrastructure changes)
• Security scans pass (no new HIGH/CRITICAL findings)
• Documentation updated if behavior changes
• Starlight mirrors synced (if docs changed)

Level 3: Rigorous (for critical paths)

• All of Level 2
• Integration or E2E test covers the happy path
• Error paths tested (not just golden path)
• Reviewer approved (human or qualified agent)
• Deployed to ephemeral stack and smoke-tested (if infrastructure)
• ADR written (if architectural decision made)

Level 4: Self-verifying (future target)

• All of Level 3
• Tabula rasa agent can replicate the outcome using only docs
• CI includes behavioral verification (not just compilation/tests)
• Documentation drift detection passes
• Deployment verified in production-like environment

Assigning levels to issues

Issue type	Default level
Bug fix	Level 2
New feature	Level 2-3 (based on blast radius)
Infrastructure/IAM change	Level 3
Documentation only	Level 1
Security fix	Level 3
RFC/ADR implementation	Level 2 + ADR written

Issues may override the default by specifying Done: Level N in the body.

Verification responsibility

Level	Who verifies
1	CI (automated)
2	CI + self-check by implementor
3	CI + reviewer + implementor
4	CI + reviewer + independent agent (tabula rasa run)

Open questions

1. Should level assignment be enforced by labels or trust-based?
2. How do we handle disagreements on what level applies?
3. When does the project graduate from "Level 2 default" to "Level 3 default"?
4. Should there be a Level 0 for spikes/experiments that explicitly skip quality gates?

Alignment

Aligns with Platform maturity and is a prerequisite for Agent swarm (agents must know when they're done without asking).

Dependencies

• ADR-003 (RFC: ADR-003 — Contribution governance for async agents and humans #134) — governance (defines when to start; this defines when to stop)
• ADR-007 — knowledge acquisition (Level 4 depends on tabula rasa verification)

---

• RFC PR: (pending approval)
• Approved by: (pending)
• Reviewed by: (pending)

[ayushtr-aws]

Clarification Question: should ADR-008's blast radius evaluation reuse ADR-009's risk classification directly, or does it need its own distinct criteria? If they're the same concept, referencing ADR-009's table would avoid drift between the two. If they're different (ADR-009 = security risk, ADR-008 = scope/complexity risk), that distinction should be made explicit.

Otherwise- good to go!