# 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](../architecture/adr/ADR-018.md))

## Artifact Matrix

| # | Artifact | Required when | Primary standard |
| --- | --- | --- | --- |
| 0 | Enterprise Phase Discovery | Always (before Implementation) | [enterprise-phase-discovery.md](enterprise-phase-discovery.md) |
| 1 | Business Analysis | Always (implementation phases) | [phase-template.md](phase-template.md) · [definition-of-done.md](definition-of-done.md) |
| 2 | Architecture Validation | Always | [development-loop.md](development-loop.md) · ADRs · [module-boundaries.md](../architecture/module-boundaries.md) |
| 3 | Domain Modeling | New/changed domain surface | Phase doc Domain Model section |
| 4 | Aggregate Design | New/changed aggregates | [entity-template.md](entity-template.md) · DDD aggregate rules |
| 5 | Entity Design | New/changed tables/models | [entity-template.md](entity-template.md) |
| 6 | DTO Design | Any API surface | [api-template.md](api-template.md) |
| 7 | Repository Design | Persistence for aggregates | [repository-template.md](repository-template.md) |
| 8 | Service Design | Business logic | [service-layer-template.md](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](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](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](event-template.md) · [ADR-006](../architecture/adr/ADR-006.md) |
| 28 | Tenant Isolation | All business data | [ADR-003](../architecture/adr/ADR-003.md) |
| 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](../provider-registry.md) |
| 35 | Dependency Injection | Always | Explicit FastAPI/deps or constructor injection |
| 36 | Unit Tests | Always when logic exists | [testing-template.md](testing-template.md) |
| 37 | Integration Tests | Always when APIs/flows exist | [testing-template.md](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](documentation-template.md) |
| 42 | Self Audit | Always | [development-loop.md](development-loop.md) |
| 43 | Service Snapshot | Service-scoped phases on Complete | [service-snapshot-policy.md](service-snapshot-policy.md) · Project Index `snapshot_file` |
| 44 | Project Index Update | Service registration or phase Complete | [project-index.yaml](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](project-index.yaml)
- [Service Snapshot Policy](service-snapshot-policy.md)
- [Enterprise Phase Discovery](enterprise-phase-discovery.md)
- [Definition of Done](definition-of-done.md)
- [Enterprise Completeness](enterprise-completeness.md)
- [Service Template](service-template.md)
- [Module Template](module-template.md)