TorbatYar/docs/ai-framework/mandatory-phase-artifacts.md

Mandatory Phase Artifacts

Every implementation phase automatically includes the artifacts below unless the phase is explicitly documentation-only or an item is marked N/A with written justification tied to the phase boundary.

This list is normative. Agents must not wait for the phase prompt to restate it. (ADR-018)

Artifact Matrix

#	Artifact	Required when	Primary standard
0	Enterprise Phase Discovery	Always (before Implementation)	enterprise-phase-discovery.md
1	Business Analysis	Always (implementation phases)	phase-template.md · definition-of-done.md
2	Architecture Validation	Always	development-loop.md · ADRs · module-boundaries.md
3	Domain Modeling	New/changed domain surface	Phase doc Domain Model section
4	Aggregate Design	New/changed aggregates	entity-template.md · DDD aggregate rules
5	Entity Design	New/changed tables/models	entity-template.md
6	DTO Design	Any API surface	api-template.md
7	Repository Design	Persistence for aggregates	repository-template.md
8	Service Design	Business logic	service-layer-template.md
9	Specification Pattern	Reusable predicates / query specs	app/specifications/ · service-layer template
10	Policy Layer	Authz, entitlement, domain policies	app/policies/ · authorization architecture
11	Commands	State-changing use cases	app/commands/ or explicit service command methods
12	Queries	Read use cases	app/queries/ or explicit query services
13	REST APIs	Externalizable capabilities	api-template.md
14	Capability APIs	Platform/discoverable services	/capabilities
15	Health APIs	Every runnable service	/health
16	Metrics	Runnable services with ops surface	/metrics or justified N/A
17	Permission APIs / tree	Privileged operations	{service}.* · permission registration
18	OpenAPI Documentation	Any new/changed HTTP routes	FastAPI OpenAPI / exported schema
19	Validation Layer	Any input or domain rule	Pydantic + app/validators/
20	Pagination	Collection list endpoints	Shared page meta
21	Filtering	List endpoints with attributes	Query params + repository filters
22	Sorting	List endpoints	Stable sort keys documented
23	Searching	List endpoints with text find	Search params + indexed fields where needed
24	Soft Delete	Master/business records	entity-template.md
25	Optimistic Locking	Concurrent update risk	Version/row version column
26	Audit Trail	State-changing business actions	Audit tables / audit service
27	Outbox Events	Cross-service-relevant changes	event-template.md · ADR-006
28	Tenant Isolation	All business data	ADR-003
29	Migration	Schema changes	Alembic in owning service only
30	Seed Data	Bootstrap/reference data required	Idempotent seeds documented
31	Background Jobs	Async/scheduled work in scope	Celery/worker pattern of the service
32	Configuration	Always for runtime services	Env / settings — no secrets in code
33	Feature Flags	Gated capabilities in scope	Entitlement / toggle pattern
34	Provider Interfaces	External systems	app/providers/ protocols · provider-registry.md
35	Dependency Injection	Always	Explicit FastAPI/deps or constructor injection
36	Unit Tests	Always when logic exists	testing-template.md
37	Integration Tests	Always when APIs/flows exist	testing-template.md
38	Architecture Tests	Service/module code phases	Boundary / layering tests
39	Security Tests	Privileged or tenant APIs	Authn/authz negatives
40	Performance Validation	Hot paths or lists	Indexes, N+1 guard, timing N/A justified
41	Documentation	Always	documentation-template.md
42	Self Audit	Always	development-loop.md
43	Service Snapshot	Service-scoped phases on Complete	service-snapshot-policy.md · Project Index snapshot_file
44	Project Index Update	Service registration or phase Complete	project-index.yaml

Package Layout Expectation

For implementation phases inside a service, prefer (create when missing for in-scope work):

app/
  api/v1/
  commands/
  queries/
  policies/
  specifications/
  validators/
  providers/
  services/
  repositories/
  models/
  schemas/
  events/
  permissions/
  tests/

Existing services that use equivalent patterns (command methods on services, inline specs) may keep their style if responsibilities are equally covered and documented. New services should follow the layout above.

N/A Rules

An artifact may be N/A only when:

1. The phase is documentation-only / registration-only, or
2. The artifact cannot apply inside the phase boundary (e.g. no list endpoints → Searching N/A), and
3. The phase doc or handover records the justification.

N/A is never allowed for Tenant Isolation, Documentation, Self Audit, Architecture Validation, Service Snapshot (when service-scoped), Project Index update (when service-scoped), or Definition of Done overall on implementation phases that touch business data.

Related Documents

• Project Index
• Service Snapshot Policy
• Enterprise Phase Discovery
• Definition of Done
• Enterprise Completeness
• Service Template
• Module Template