TorbatYar/docs/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: [project-index.yaml](project-index.yaml) · [runtime-read-policy.md](runtime-read-policy.md) · [context-cache-policy.md](context-cache-policy.md) · [service-snapshot-policy.md](service-snapshot-policy.md) · [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).

**Document loading:** Start from [project-index.yaml](project-index.yaml); resolve snapshot, roadmap, and handover from index — never scan folders.

## 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 **synthesize** every input below that applies to the phase’s service/area. **Load [project-index.yaml](project-index.yaml) first**; resolve paths from the active service entry; then follow Runtime Read Policy and Context Cache Policy. Never scan repository folders.

| Input | Required | Primary source |
| --- | --- | --- |
| Service discovery | Yes | **Project Index** active service entry |
| Service baseline | Yes | Project Index + service snapshot |
| Current Roadmap | Yes | Snapshot + policy |
| Current Architecture | When triggered | Snapshot `active_adrs` + policy |
| Service Boundaries | Yes | Snapshot + manifests |
| Previous Phase Handover | Yes | Project Index `latest_handover` |
| Existing Codebase | Yes | Code delta verification |
| Existing APIs | Yes | Snapshot `public_apis` + code |
| Existing Domain Model | Yes | Snapshot + code |
| Existing Events | Yes | Snapshot `published_events` + code |
| Existing Permissions | Yes | Snapshot + code |
| Existing Aggregates | Yes | Snapshot modules + code |
| Existing Tests | Yes | Codebase |
| Existing Documentation | Yes | Snapshot + policy |

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

## Discovery Procedure

1. **Load context** — [project-index.yaml](project-index.yaml) execution entry: index → policies → snapshot → manifests → latest handover; additional docs per Runtime Read Policy only.
2. **State phase boundary** — Objective, In Scope, Out of Scope, owning service(s), forbidden foreign ownership, next-phase exclusions.
3. **Inventory baseline** — From Project Index + snapshot (APIs, events, modules, phases, limitations, TODOs); verify deltas against codebase — not completed phase doc history.
4. **Derive target responsibility** — From snapshot + roadmap + 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

- [Project Index](project-index.yaml)
- [Runtime Read Policy](runtime-read-policy.md)
- [Context Cache Policy](context-cache-policy.md)
- [Service Snapshot Policy](service-snapshot-policy.md)
- [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)