TorbatYar/docs-runtime/ai-framework/definition-of-done.md

# Definition of Done

Mandatory exit criteria for every implementation phase.

A phase **cannot** be marked Complete until every item below is satisfied for **that phase’s boundary**. This document is part of the Enterprise Development Framework ([ADR-018](../architecture/adr/ADR-018.md), [ADR-019](../architecture/adr/ADR-019.md)).

## Absolute Rules

1. **Enterprise Phase Discovery first.** A Discovery Record must exist and all Missing→Implement gaps must be closed ([enterprise-phase-discovery.md](enterprise-phase-discovery.md)).
2. **Feature-complete for the phase boundary.** All required business capabilities of *this* phase must be implemented — not sketched, stubbed, or deferred as TODO.
3. **CRUD is never sufficient.** Listing create/read/update/delete endpoints does not equal a production-ready phase. Domain rules, validation, permissions, events, audit, tenancy, tests, and operational surfaces are mandatory.
4. **Derive missing technical components.** If the roadmap or phase brief describes a module only at a high level, the implementation **must** derive every missing technical component required for production readiness **while remaining inside the current phase** ([mandatory-phase-artifacts.md](mandatory-phase-artifacts.md), Discovery gap analysis).
5. **Never pull future-phase functionality forward.** Stay inside Scope; leave Out of Scope untouched ([boundary-rules.md](boundary-rules.md)).
6. **Never claim Complete with open gaps.** Missing artifacts must be implemented before status flips to Complete — not logged as “known limitations” unless truly out of phase boundary with written justification.

## Phase Definition of Done Checklist

### Discovery

- [ ] Enterprise Phase Discovery Record published in the phase doc
- [ ] All Discovery Inputs reviewed (or N/A justified for docs-only phases)
- [ ] Gap analysis complete; Missing→Implement items closed
- [ ] Future-phase and other-service items explicitly excluded

### Business

- [ ] Business Analysis for this phase recorded (objectives, actors, capabilities, non-goals)
- [ ] Every in-scope / Discovery-promoted business capability is implemented end-to-end inside the phase boundary
- [ ] Domain invariants and illegal transitions are enforced (not only happy-path CRUD)
- [ ] Seed data included when the phase requires bootstrap/reference data

### Architecture & Domain

- [ ] Architecture Validation passed against ADRs and module boundaries
- [ ] Domain Modeling complete (bounded context, aggregates, entities, value objects as needed)
- [ ] Aggregate Design documented and reflected in models
- [ ] Entity Design per [entity-template.md](entity-template.md)
- [ ] DTO Design per [api-template.md](api-template.md)
- [ ] Provider Interfaces defined when external systems are involved

### Application Layers

- [ ] Repository Design per [repository-template.md](repository-template.md)
- [ ] Service Design per [service-layer-template.md](service-layer-template.md)
- [ ] Specification Pattern for reusable query/business predicates where applicable
- [ ] Policy Layer for authorization/entitlement/domain policies where applicable
- [ ] Commands for state-changing use cases (explicit command handlers or service command methods)
- [ ] Queries for read use cases (explicit query paths; no accidental write side-effects)
- [ ] Validation Layer (Pydantic + domain validators)
- [ ] Dependency Injection / explicit deps wiring consistent with the service pattern

### APIs & Contracts

- [ ] REST APIs for in-scope resources
- [ ] Capability APIs (`/capabilities` or equivalent) when the service exposes discoverable features
- [ ] Health APIs (`/health`)
- [ ] Metrics endpoint or documented N/A with operational alternative
- [ ] Permission APIs or documented permission tree registration for the phase
- [ ] OpenAPI documentation generated/updated and accurate for new routes
- [ ] Pagination, Filtering, Sorting, Searching on list endpoints where collections exist

### Cross-Cutting

- [ ] Soft Delete policy applied where master/business records require it
- [ ] Optimistic Locking where concurrent updates are a domain risk
- [ ] Audit Trail for state-changing business actions
- [ ] Outbox Events for cross-service-relevant state changes ([event-template.md](event-template.md))
- [ ] Tenant Isolation on schema, queries, APIs, and tests
- [ ] Migration(s) in the owning service database only
- [ ] Background Jobs when the phase requires async/scheduled work
- [ ] Configuration via env/settings (no hardcoded secrets/brand)
- [ ] Feature Flags when the phase introduces gated capabilities

### Quality

- [ ] Unit Tests
- [ ] Integration / API Tests
- [ ] Architecture Tests (boundary/layering) per service pattern
- [ ] Security Tests
- [ ] Performance Validation (hot paths covered or justified N/A)
- [ ] Documentation complete per [documentation-template.md](documentation-template.md)
- [ ] Self Audit complete ([development-loop.md](development-loop.md))
- [ ] Enterprise Completeness verification passed ([enterprise-completeness.md](enterprise-completeness.md))
- [ ] All [quality-gates.md](quality-gates.md) Pass
- [ ] [phase-handover.md](phase-handover.md) filled
- [ ] No TODO/FIXME for claimed deliverables

## What “Derive Missing Components” Means

When a phase brief says only “implement X module,” the agent **must** still deliver the full production stack for X inside the phase:

| If the brief mentions… | Also deliver… |
| --- | --- |
| Entities / tables | Migrations, soft-delete, tenant_id, indexes, audit fields |
| APIs | DTOs, validation, pagination/filter/sort/search, permissions, OpenAPI |
| Business rules | Services, validators, specifications, policies, commands/queries |
| Integrations | Provider interfaces, events/outbox — never foreign DB access |
| Operability | Health, metrics (or justified N/A), config, logging |

Do **not** invent new business products outside the phase. Do **derive** engineering completeness for what the phase owns.

## Relationship to Quality Gates

Definition of Done is the **product completeness** bar. Quality Gates are the **verification** bar. Both must pass ([quality-gates.md](quality-gates.md), [enterprise-completeness.md](enterprise-completeness.md)).

## Related Documents

- [Enterprise Phase Discovery](enterprise-phase-discovery.md)
- [Mandatory Phase Artifacts](mandatory-phase-artifacts.md)
- [Enterprise Completeness](enterprise-completeness.md)
- [Boundary Rules](boundary-rules.md)
- [Development Loop](development-loop.md)
- [Phase Handover](phase-handover.md)
- [ADR-018](../architecture/adr/ADR-018.md)
- [ADR-019](../architecture/adr/ADR-019.md)