TorbatYar/docs-runtime/ai-framework/enterprise-phase-discovery.md

# Enterprise Phase Discovery

Mandatory **pre-implementation** process for every phase.

Before writing production code for a phase, the Framework **MUST** automatically perform Enterprise Phase Discovery. Discovery determines the **complete responsibility** of the current phase and derives every missing production-ready capability inside that phase boundary.

This rule extends [ADR-018](../architecture/adr/ADR-018.md) via [ADR-019](../architecture/adr/ADR-019.md). Companions: [definition-of-done.md](definition-of-done.md) · [mandatory-phase-artifacts.md](mandatory-phase-artifacts.md) · [boundary-rules.md](boundary-rules.md) · [enterprise-completeness.md](enterprise-completeness.md).

## Absolute Rules

1. **Discovery runs before Implementation** (and before Domain Modeling finalizes the build list).
2. **Never assume CRUD is sufficient.**
3. **Automatically derive** every missing production-ready capability required for the **current phase**.
4. If anything required for the current phase is missing, it **MUST** become part of the implementation before Complete.
5. **Never move responsibilities from future phases.**
6. **Never violate Service Boundaries** ([boundary-rules.md](boundary-rules.md)).
7. **Never duplicate another service.**

## Discovery Inputs (mandatory sources)

The agent must inspect and synthesize **all** of the following that exist for the phase’s service/area:

| Input | Where to look |
| --- | --- |
| Current Roadmap | [roadmap.md](../roadmap.md), area roadmaps (`*-roadmap.md`), [phase-manifest.yaml](phase-manifest.yaml), [next-steps.md](../next-steps.md) |
| Current Architecture | `docs/architecture/*`, `docs/architecture/adr/*` |
| Service Boundaries | [module-boundaries.md](../architecture/module-boundaries.md), [module-registry.md](../module-registry.md), [service-manifest.yaml](service-manifest.yaml) |
| Previous Phase Handover | `docs/phase-handover/*`, prior phase docs |
| Existing Codebase | `backend/services/<name>/` (or owning path) — models, services, repos, APIs, tests |
| Existing APIs | Routers, OpenAPI, [api-reference.md](../reference/api-reference.md), [services-contracts.md](../reference/services-contracts.md) |
| Existing Domain Model | Models, schemas, validators, phase domain sections |
| Existing Events | `app/events/`, outbox, [event-catalog.md](../reference/event-catalog.md) |
| Existing Permissions | `app/permissions/`, registry permission trees |
| Existing Aggregates | Models + service ownership docs |
| Existing Tests | `app/tests/`, pytest suites |
| Existing Documentation | Phase docs, service README, registries, progress |

Docs-only / registration-only phases still run Discovery against documentation and manifests (codebase may be N/A).

## Discovery Procedure

1. **Load context** — Read framework docs, then every Discovery Input above for the current phase.
2. **State phase boundary** — Objective, In Scope, Out of Scope, owning service(s), forbidden foreign ownership, next-phase exclusions.
3. **Inventory baseline** — Record what already exists (aggregates, APIs, events, permissions, tests, docs, ops surfaces).
4. **Derive target responsibility** — From roadmap + architecture + handover + boundaries, state the complete capability set this phase must own when Complete.
5. **Gap analysis** — Diff baseline vs target using the Missing Capability Checklist below.
6. **Promote gaps to Scope** — Every gap that belongs to **this** phase becomes mandatory implementation work (not a TODO, not a “limitation”).
7. **Reject illegal gaps** — Gaps owned by another service → integrate via API/Events/Providers only. Gaps owned by a future phase → leave Out of Scope.
8. **Publish Discovery Record** — Write the Enterprise Phase Discovery section into the phase doc (see template) before coding.
9. **Gate** — Architecture Validation and Implementation may proceed only after the Discovery Record is complete.

## Missing Capability Checklist

Identify missing items for the **current phase** (mark Present / Missing→Implement / N/A justified / Future-phase / Other-service):

| Capability class | Examples |
| --- | --- |
| Business Capabilities | End-to-end use cases, not mere table CRUD |
| Entities | ORM/domain entities for in-scope data |
| Value Objects | Money, codes, periods, identifiers as needed |
| Aggregates | Consistency boundaries and invariants |
| Services | Domain orchestration |
| Policies | Authz / entitlement / domain policies |
| Specifications | Reusable predicates / query specs |
| Repositories | Tenant-scoped persistence |
| Commands | State-changing use cases |
| Queries | Read use cases without write side-effects |
| REST APIs | Resource endpoints for in-scope capabilities |
| Capability APIs | `/capabilities` or equivalent |
| Permission APIs / tree | `{service}.*` registration and checks |
| Health APIs | `/health` |
| Metrics | `/metrics` or justified ops alternative |
| Events | Outbox domain/integration events |
| Background Jobs | Async/scheduled work when required |
| Configurations | Env/settings keys |
| Feature Flags | Gated capabilities when required |
| Provider Interfaces | Protocols for external systems |
| Validation Rules | Edge + domain validators |
| Audit | Trail for state-changing actions |
| Search | Collection search |
| Filtering | Collection filters |
| Sorting | Stable sort keys |
| Pagination | Page/cursor meta |
| Soft Delete | Master/business record policy |
| Optimistic Locking | When concurrency risk exists |
| Tenant Isolation | Schema, queries, APIs, tests |
| Documentation | Phase, registries, OpenAPI, handover |
| Tests | Unit, integration, architecture, security, tenant, etc. |
| Operational Readiness | Health, metrics/logging, config, jobs |
| Developer Experience | README, clear errors, runnable tests |

## Discovery Record (required in phase doc)

```markdown
## Enterprise Phase Discovery

| Field | Value |
| --- | --- |
| Phase ID | |
| Owning service(s) | |
| Discovery date | |
| Inputs reviewed | Roadmap · Architecture · Boundaries · Prior handover · Code · APIs · Domain · Events · Permissions · Aggregates · Tests · Docs |

### Baseline Inventory (exists today)
-

### Target Responsibility (this phase when Complete)
-

### Gap Analysis

| Capability | Status | Action |
| --- | --- | --- |
| ... | Present / Missing / N/A / Future / Other-service | Implement / Skip-justify / Integrate / Defer |

### Promoted to Implementation Scope
-

### Explicitly Excluded (future phase or other service)
-

### Boundary Confirmations
- [ ] No future-phase pull-forward
- [ ] No service-boundary violation
- [ ] No duplication of another service’s logic
- [ ] CRUD-only delivery rejected
```

## Relationship to Other Framework Stages

| Stage | Relationship |
| --- | --- |
| Business Analysis | Discovery includes and extends BA with codebase/API/test inventory |
| Architecture Validation | Uses Discovery boundary conclusions |
| Domain Modeling | Models only what Discovery promoted into scope |
| Implementation | Must cover every Discovery gap marked Missing→Implement |
| Enterprise Completeness / Quality Gates | Fail if Discovery was skipped or gaps remain unimplemented |
| Definition of Done | Incomplete without a Discovery Record for implementation phases |

## Failure Policy

| Situation | Action |
| --- | --- |
| Discovery skipped | Phase incomplete — run Discovery before claiming progress |
| Gap marked Missing but not implemented | Must implement before Complete |
| Agent “assumes CRUD enough” | Fail Business Completeness + Discovery gates |
| Gap belongs to future phase | Document under Excluded; do not implement |
| Gap belongs to another service | Integrate only; do not re-implement |

## Related Documents

- [Development Loop](development-loop.md)
- [Definition of Done](definition-of-done.md)
- [Mandatory Phase Artifacts](mandatory-phase-artifacts.md)
- [Enterprise Completeness](enterprise-completeness.md)
- [Boundary Rules](boundary-rules.md)
- [Quality Gates](quality-gates.md)
- [Phase Template](phase-template.md)
- [ADR-019](../architecture/adr/ADR-019.md)