TorbatYar/docs/ai-framework/phase-handover.md

# Phase Handover

Every implementation phase must deliver this package before completion.

Copy the sections below into the phase document (or attach a phase-specific handover file) and fill every field. Empty sections are only allowed when marked **N/A** with justification.

Enterprise mandates: [enterprise-phase-discovery.md](enterprise-phase-discovery.md) · [definition-of-done.md](definition-of-done.md) · [enterprise-completeness.md](enterprise-completeness.md) · [service-snapshot-policy.md](service-snapshot-policy.md) · [project-index.yaml](project-index.yaml) · [ADR-018](../architecture/adr/ADR-018.md) · [ADR-019](../architecture/adr/ADR-019.md).

## Metadata

| Field | Value |
| --- | --- |
| Phase ID | (from [phase-manifest.yaml](phase-manifest.yaml)) |
| Title | |
| Status | Complete |
| Service(s) | |
| Version | |
| Date | |
| ADR(s) | |

## Enterprise Phase Discovery Summary

| Item | Detail |
| --- | --- |
| Discovery Record location | Phase doc section link |
| Gaps promoted & closed | |
| Exclusions (future / other service) | |
| CRUD-only rejected | Yes |

## Business Analysis Summary

| Item | Detail |
| --- | --- |
| Capabilities delivered | |
| Explicit non-goals honored | |

## Reusable Components

List libraries, engines, providers, shared helpers, or patterns introduced for reuse.

| Component | Location | Reuse notes |
| --- | --- | --- |
| | | |

## Public APIs

| Method | Path | Auth / Permission | Notes |
| --- | --- | --- | --- |
| | | | |

Include Health / Capabilities / Metrics when applicable. Link detailed contracts: [api-reference.md](../reference/api-reference.md), [services-contracts.md](../reference/services-contracts.md). Confirm OpenAPI updated.

## Events

| Event type | Domain / Integration | Payload summary | Version |
| --- | --- | --- | --- |
| | | | |

Catalog: [event-catalog.md](../reference/event-catalog.md). Standards: [event-template.md](event-template.md).

## Permissions

| Permission | Routes / actions |
| --- | --- |
| | |

## Extension Points

Document intentional hooks for future phases (provider protocols, strategy interfaces, feature flags, entitlement keys).

| Extension point | How to extend | Forbidden uses |
| --- | --- | --- |
| | | |

## Known Limitations

Explicit non-goals and temporary constraints (must not be silently omitted).  
**Do not** list missing current-phase mandatory artifacts here — those must be implemented before Complete.

-

## Migration Notes

| Item | Detail |
| --- | --- |
| Alembic revision(s) | |
| Upgrade steps | |
| Downgrade support | |
| Data backfill / seeds | |
| Breaking changes | None / described |

## Dependencies

| Dependency | Type | Required for |
| --- | --- | --- |
| | Core / Service / Provider / Docs | |

## Boundary Compliance

- [ ] No foreign service ownership implemented
- [ ] No business logic duplication
- [ ] No cross-DB access
- [ ] Integrations only via API / Events / Providers
- [ ] No future-phase functionality pulled forward

## Enterprise Completeness Sign-Off

Copy from [enterprise-completeness.md](enterprise-completeness.md):

- [ ] Discovery completeness
- [ ] Business completeness
- [ ] Architectural completeness
- [ ] API completeness
- [ ] Permission completeness
- [ ] Capability completeness
- [ ] Event completeness
- [ ] Migration completeness
- [ ] Repository completeness
- [ ] Validation completeness
- [ ] Security completeness
- [ ] Performance completeness
- [ ] Documentation completeness
- [ ] Testing completeness
- [ ] Tenant isolation
- [ ] Provider abstraction
- [ ] Integration completeness
- [ ] Operational readiness
- [ ] Developer experience
- [ ] Maintainability
- [ ] Self Audit

## Definition of Done

- [ ] [definition-of-done.md](definition-of-done.md) checklist satisfied for this phase boundary
- [ ] [enterprise-phase-discovery.md](enterprise-phase-discovery.md) Record complete; Missing→Implement gaps closed
- [ ] CRUD-only delivery rejected / not claimed as complete
- [ ] Applicable [mandatory-phase-artifacts.md](mandatory-phase-artifacts.md) delivered or justified N/A

## Service Snapshot Update

Regenerate after every Complete phase for the owning service ([service-snapshot-policy.md](service-snapshot-policy.md)).

| Field | Value |
| --- | --- |
| Snapshot path | From Project Index `snapshot_file` |
| Snapshot version | |
| Last updated | |
| Fields changed | |

Confirm all required snapshot fields reflect this phase's deliverables.

## Project Index Update

Update [project-index.yaml](project-index.yaml) for the owning service on every Complete phase and on service registration.

| Field | Value |
| --- | --- |
| Service identifier | |
| Current version | |
| Current phase | |
| Next phase | |
| Latest handover | |
| Snapshot file | |

## Next Phase Entry

What the next phase must read and assume:

1. [project-index.yaml](project-index.yaml) active service entry (primary discovery)
2. Service snapshot at Project Index `snapshot_file`
3. This handover + phase doc (including Discovery exclusions that become next-phase scope)
4. Updated [module-registry.md](../module-registry.md) / manifests
5. Open limitations that become next-phase scope
6. Suggested next phase ID from Project Index `next_phase` / [next-steps.md](../next-steps.md)
7. Enterprise Framework rules — no need to restate in the next prompt

| Field | Value |
| --- | --- |
| Recommended next phase | |
| Blockers for next phase | |
| Entry checklist | |

## Completion Sign-Off

- [ ] Project Index updated ([project-index.yaml](project-index.yaml))
- [ ] Service snapshot regenerated ([service-snapshot-policy.md](service-snapshot-policy.md))
- [ ] Quality gates passed ([quality-gates.md](quality-gates.md))
- [ ] Enterprise Phase Discovery gate passed
- [ ] Tests green
- [ ] Documentation updated ([documentation-template.md](documentation-template.md))
- [ ] Progress / next-steps / registries updated
- [ ] No TODO for claimed deliverables
- [ ] Self audit completed ([development-loop.md](development-loop.md))
- [ ] Enterprise Completeness signed off
- [ ] Definition of Done satisfied

## Related Documents

- [Project Index](project-index.yaml)
- [Service Snapshot Policy](service-snapshot-policy.md)
- [Phase Template](phase-template.md)
- [Enterprise Phase Discovery](enterprise-phase-discovery.md)
- [Development Loop](development-loop.md)
- [Definition of Done](definition-of-done.md)
- [Enterprise Completeness](enterprise-completeness.md)
- [Boundary Rules](boundary-rules.md)
- [Module Registry](../module-registry.md)
- [Progress](../progress.md)
- [Next Steps](../next-steps.md)