TorbatYar/docs/phase-handover/phase-af-enterprise.md

Phase Handover — AF-Enterprise (Enterprise Development Framework Upgrade)

Field	Value
Phase ID	ai-framework-enterprise
Title	Enterprise Development Framework Upgrade
Status	Complete
Service(s)	N/A (documentation / process only)
Version	Framework enterprise-1.0 (extends ADR-013 baseline)
Date	2026-07-25
ADR(s)	ADR-018 (extends ADR-013)

Business Analysis Summary

Item	Detail
Capabilities delivered	Permanent enterprise execution rules so every future phase ships production-ready by default
Explicit non-goals honored	No Delivery/Restaurant/CRM/business feature implementation; no retrofit of completed business phases/code

Enhancement Catalog

New normative documents

Document	Purpose
definition-of-done.md	Mandatory phase DoD; CRUD never sufficient; derive missing technical components inside phase
mandatory-phase-artifacts.md	Full artifact matrix (Business Analysis → Self Audit) applied automatically
enterprise-completeness.md	Pre-close verification dimensions + sign-off block
boundary-rules.md	No foreign ownership, no logic duplication, no cross-DB, API/Events/Providers only, no future-phase pull-forward

Core execution upgrades

Document	Enhancement
README.md	Rebranded as Enterprise / AI Framework; single source of truth; expanded index & lifecycle
master-prompt.md	Enterprise Completeness Rules; DoD; boundary summary; auto production artifacts
development-loop.md	Business Analysis → Domain Modeling → Implementation → Completeness → Gates → Repair (implement missing work)
quality-gates.md	Expanded gates: Business/API/Permission/Event/Repository/Validation/Provider/Integration/Ops/DX/DoD
prompt-rules.md	Enterprise quality automatic; CRUD forbidden as DoD; thin phase prompts
cursor-guidelines.md	Reading/implementation/validation order includes DoD, artifacts, completeness

Template upgrades

Template	Enhancement
phase-template.md	Business Analysis, Domain Model, Specs/Policies/Commands/Queries, operational APIs, artifact trace, DoD criteria
phase-handover.md	Boundary compliance, Enterprise Completeness Sign-Off, Definition of Done
testing-template.md	Commands/Queries, architecture, OpenAPI, list UX, DoD-aware rules
documentation-template.md	OpenAPI, completeness, forbid “limitations” for missing current-phase artifacts
service-template.md	commands/queries/policies/specifications layout; health/capabilities/metrics
module-template.md	Full layer stack + boundary/DoD discipline
entity-template.md	Soft delete mandatory default; optimistic locking section
repository-template.md	Page/filter/sort/search + specs
service-layer-template.md	Commands, Queries, Specifications, Policies, DI
api-template.md	OpenAPI, capabilities/metrics, list UX mandatory
event-template.md	Event completeness gate linkage

Supporting documentation

Document	Change
project-principles.md	Principles 21–24 (DoD, artifacts, boundaries, completeness)
testing-strategy.md	Expanded layers + CRUD insufficiency rule
docs/README.md	Framework index + Phase Completion Gate expanded
architecture.md	Framework reading entry updated
Root README.md	Framework row updated
glossary.md	Enterprise Framework / DoD / artifacts / completeness / boundary terms
roadmap.md · next-steps.md · progress.md · module-registry.md	Cross-links; progress records AF-Enterprise complete
phase-manifest.yaml	Phase ai-framework-enterprise registered Complete
ADR index	ADR-018 listed; duplicate ADR-016 row cleaned

Architecture decision

ADR	Decision
ADR-018	Enterprise Completeness Mandate — extends ADR-013; framework is single source of truth for production-ready phases by default

Reusable Components

Component	Location	Reuse notes
Definition of Done	docs/ai-framework/definition-of-done.md	Every future phase
Mandatory Artifacts matrix	docs/ai-framework/mandatory-phase-artifacts.md	Auto-include checklist
Completeness sign-off	docs/ai-framework/enterprise-completeness.md	Copy into every handover
Boundary rules	docs/ai-framework/boundary-rules.md	Architecture + integration enforcement
Expanded quality gates	docs/ai-framework/quality-gates.md	Reviewer checklist

Public APIs

N/A — documentation/process only.

Events

N/A.

Permissions

N/A.

Extension Points

Extension point	How to extend	Forbidden uses
New permanent process rule	Update docs/ai-framework/ + ADR if architectural	Burying rules in a single phase prompt
New mandatory artifact	Add to mandatory-phase-artifacts + DoD + gates	Retrofitting completed business code without an explicit phase
Service package conventions	Prefer commands/queries/policies/specs layout for new work	Forcing unrelated refactors of completed services

Known Limitations

• Does not retrofit completed business phases or existing service codebases to the new package layout.
• Equivalent patterns (command methods on services, inline specs) remain acceptable when responsibilities are equally covered.
• Does not replace short forms under docs/templates/.
• Does not implement product AI Assistant features.

Migration Notes

Item	Detail
Alembic revision(s)	N/A
Upgrade steps	Agents/humans read upgraded framework before next business phase
Downgrade support	N/A
Data backfill / seeds	N/A
Breaking changes	None for runtime; process bar is higher for future phases (intentional)

Dependencies

Dependency	Type	Required for
ADR-013 / Phase AF	Docs	Baseline framework
docs architecture (Phase D)	Docs	Documentation structure

Boundary Compliance

• No foreign service ownership implemented
• No business logic duplication
• No cross-DB access
• Integrations only via API / Events / Providers (N/A — no runtime integrations)
• No future-phase business functionality pulled forward

Enterprise Completeness Sign-Off

• Business completeness (framework process capabilities)
• Architectural completeness (ADR-018 + links)
• API completeness (N/A — docs)
• Permission completeness (N/A — docs)
• Capability completeness (framework capabilities documented)
• Event completeness (N/A — docs)
• Migration completeness (N/A — docs)
• Repository completeness (N/A — docs)
• Validation completeness (framework validation suites described)
• Security completeness (security gates retained/expanded)
• Performance completeness (performance gates retained)
• Documentation completeness
• Testing completeness (testing template/strategy updated; docs-phase validation)
• Tenant isolation (rules retained/emphasized)
• Provider abstraction (rules retained/emphasized)
• Integration completeness (boundary rules)
• Operational readiness (health/metrics/config in mandatory artifacts)
• Developer experience (README, prompt rules, cursor guidelines)
• Maintainability (single source of truth; thin phase prompts)
• Self Audit

Definition of Done

• Framework upgrade DoD satisfied for this docs-only phase boundary
• CRUD-only delivery N/A (no business CRUD)
• Applicable mandatory artifacts for a docs phase delivered (analysis, architecture validation, documentation, self audit, gates)

Next Phase Entry

1. This handover + ai-framework/README.md
2. ADR-018
3. Resume business milestones per next-steps.md — using the upgraded framework without restating enterprise rules in the phase prompt
4. Do not start a business phase from this handover unless explicitly requested

Field	Value
Recommended next phase	Per next-steps.md (business track) — not started by this phase
Blockers for next phase	None from this upgrade
Entry checklist	Read DoD + mandatory artifacts + completeness + boundary rules once; follow loop/gates

Completion Sign-Off

• Quality gates passed (documentation / architecture / cross-reference / template / manifest validation for framework phase)
• Tests N/A for runtime; docs validation performed via review
• Documentation updated
• Progress / next-steps / registries / manifests updated
• No TODO for claimed deliverables
• Self audit completed
• Enterprise Completeness signed off
• Definition of Done satisfied

Related Documents

• AI / Enterprise Framework README
• ADR-013
• ADR-018
• Progress
• Next Steps