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 via ADR-019. Companions: project-index.yaml · runtime-read-policy.md · context-cache-policy.md · service-snapshot-policy.md · definition-of-done.md · mandatory-phase-artifacts.md · boundary-rules.md · enterprise-completeness.md.

Document loading: Start from 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).
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 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 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)

## 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
• Runtime Read Policy
• Context Cache Policy
• Service Snapshot Policy
• Development Loop
• Definition of Done
• Mandatory Phase Artifacts
• Enterprise Completeness
• Boundary Rules
• Quality Gates
• Phase Template
• ADR-019