# ADR-019: Mandatory Enterprise Phase Discovery

| Field | Value |
| --- | --- |
| Status | Accepted |
| Date | 2026-07-26 |
| Deciders | Platform Architecture |
| Supersedes | — |
| Superseded by | — |
| Extends | [ADR-018](ADR-018.md), [ADR-013](ADR-013.md) |

## Context

ADR-018 made enterprise production readiness the default via Definition of Done, mandatory artifacts, completeness verification, and boundary rules. Agents could still begin implementation from a thin phase brief and under-derive scope—shipping CRUD-shaped work while missing policies, events, list UX, ops surfaces, or other current-phase responsibilities that already existed partially in the codebase or roadmap.

The Framework needs an explicit, mandatory **Enterprise Phase Discovery** stage that inspects roadmap, architecture, boundaries, prior handover, and the live codebase/APIs/domain/events/permissions/tests/docs before coding, then promotes every missing current-phase production capability into Scope.

This ADR does **not** implement business features and does **not** retrofit completed business phases.

## Decision

1. Adopt [Enterprise Phase Discovery](../../ai-framework/enterprise-phase-discovery.md) as a **mandatory** stage before Implementation for every phase.
2. Discovery MUST use the full input set: Current Roadmap, Current Architecture, Service Boundaries, Previous Phase Handover, Existing Codebase, Existing APIs, Existing Domain Model, Existing Events, Existing Permissions, Existing Aggregates, Existing Tests, Existing Documentation.
3. Discovery MUST derive every missing production-ready capability for the **current phase** and MUST NOT assume CRUD is sufficient.
4. Missing current-phase capabilities automatically become implementation work before Complete.
5. Discovery MUST NOT pull future-phase responsibilities, violate service boundaries, or duplicate another service.
6. A Discovery Record is required in the phase document; quality gates and Definition of Done fail without it (implementation phases).
7. Framework loop, gates, templates, master prompt, and Cursor guidelines are updated accordingly.

## Consequences

### Positive

- Phase responsibility is evidence-based (docs + code), not prompt-guessed
- Gaps are closed inside the phase instead of deferred as TODOs
- Boundary and anti-duplication checks happen before code is written

### Negative

- Slightly longer pre-implementation analysis (intentional)

### Neutral

- Docs-only phases still produce a Discovery Record against documentation/manifests
- ADR-013 and ADR-018 remain Accepted; this ADR extends them

## Alternatives Considered

1. Rely only on mandatory-artifact checklists without codebase inventory — rejected (misses drift vs existing code)
2. Optional discovery “when unclear” — rejected (agents skip under time pressure)
3. Expand every phase prompt with full discovery instructions — rejected (framework is single source of truth)

## Related Documents

- [Enterprise Phase Discovery](../../ai-framework/enterprise-phase-discovery.md)
- [ADR-018](ADR-018.md)
- [ADR-013](ADR-013.md)
- [Development Loop](../../ai-framework/development-loop.md)
- [Quality Gates](../../ai-framework/quality-gates.md)
- [Definition of Done](../../ai-framework/definition-of-done.md)
- [Boundary Rules](../../ai-framework/boundary-rules.md)
