5c6a2e78cf
Register all active platform services and base features in core DB so admin can manage them, add delivery/hospitality/sports-center backend phases, update apps catalog and production deploy tooling. Co-authored-by: Cursor <cursoragent@cursor.com>
164 lines
9.1 KiB
Markdown
164 lines
9.1 KiB
Markdown
# Development Loop
|
||
|
||
Permanent implementation lifecycle for every TorbatYar phase.
|
||
|
||
Agents and humans follow these stages in order. After Quality Gates or Enterprise Completeness fail, enter the Automatic Repair Loop until all gates pass **and** missing required artifacts are implemented, then complete.
|
||
|
||
Canonical mandates: [enterprise-phase-discovery.md](enterprise-phase-discovery.md) · [definition-of-done.md](definition-of-done.md) · [mandatory-phase-artifacts.md](mandatory-phase-artifacts.md) · [boundary-rules.md](boundary-rules.md) · [ADR-018](../architecture/adr/ADR-018.md) · [ADR-019](../architecture/adr/ADR-019.md).
|
||
|
||
## 1. Enterprise Phase Discovery
|
||
|
||
**Mandatory before Implementation.** Full procedure: [enterprise-phase-discovery.md](enterprise-phase-discovery.md).
|
||
|
||
1. Read [docs/README.md](../README.md), [AI Framework README](README.md), [master-prompt.md](master-prompt.md).
|
||
2. Inspect **all** Discovery Inputs: Current Roadmap, Current Architecture, Service Boundaries, Previous Phase Handover, Existing Codebase, Existing APIs, Existing Domain Model, Existing Events, Existing Permissions, Existing Aggregates, Existing Tests, Existing Documentation.
|
||
3. Confirm Objective, Scope, Out of Scope, Dependencies, and Required Services from [phase-manifest.yaml](phase-manifest.yaml) and the phase brief.
|
||
4. Inventory baseline vs target responsibility for **this phase only**.
|
||
5. Run the Missing Capability Checklist; never assume CRUD is sufficient.
|
||
6. Promote every Missing→Implement gap into Scope; exclude future-phase and other-service items.
|
||
7. Publish the **Enterprise Phase Discovery** record in the phase doc.
|
||
8. Stop if Discovery reveals ADR/boundary conflicts — resolve via ADR/docs first.
|
||
|
||
**Exit:** Complete Discovery Record with gap analysis and promoted implementation scope.
|
||
|
||
## 2. Business Analysis
|
||
|
||
1. Refine actors, business capabilities, success metrics, and non-goals from Discovery.
|
||
2. Align Business Analysis section with Discovery’s Target Responsibility and Promoted Scope.
|
||
3. Confirm derived [mandatory-phase-artifacts.md](mandatory-phase-artifacts.md) for this phase (do not pull future-phase features).
|
||
|
||
**Exit:** Written Business Analysis consistent with the Discovery Record.
|
||
|
||
## 3. Architecture Validation
|
||
|
||
1. Validate against [module-boundaries.md](../architecture/module-boundaries.md), [boundary-rules.md](boundary-rules.md), [database-architecture.md](../architecture/database-architecture.md), [multi-tenant-architecture.md](../architecture/multi-tenant-architecture.md).
|
||
2. Confirm Database-per-Service, tenancy, eventing, and FE/BE separation.
|
||
3. Confirm service vs module decision ([service-template.md](service-template.md) vs [module-template.md](module-template.md)).
|
||
4. Identify required ADRs; create Proposed/Accepted ADR if a new decision is introduced.
|
||
5. Confirm Discovery exclusions: no ownership theft, no future-phase pull-forward, no service duplication.
|
||
6. Confirm integration approach is API / Events / Providers only.
|
||
|
||
**Exit:** Architecture checklist green or ADR/docs updated to resolve conflicts.
|
||
|
||
## 4. Domain Modeling
|
||
|
||
1. Model bounded context slice for Discovery-promoted scope only.
|
||
2. Aggregate Design — consistency boundaries and invariants.
|
||
3. Entity / Value Object Design per [entity-template.md](entity-template.md) (tenant, soft delete, audit, indexes, optimistic locking where needed).
|
||
4. DTO Design per [api-template.md](api-template.md).
|
||
5. Identify Specifications, Policies, Commands, and Queries needed.
|
||
6. Identify Provider Interfaces if external systems are involved.
|
||
|
||
**Exit:** Domain model section in the phase doc ready to implement.
|
||
|
||
## 5. Implementation
|
||
|
||
1. Follow [cursor-guidelines.md](cursor-guidelines.md) implementation order.
|
||
2. Implement **every** Discovery gap marked Missing→Implement.
|
||
3. Models / entities / migrations (owning DB only).
|
||
4. Repositories per [repository-template.md](repository-template.md) (pagination, filter, sort, search, soft delete, tenant filters).
|
||
5. Specifications, Policies, Validators.
|
||
6. Commands and Queries (packages or equivalent explicit methods).
|
||
7. Services per [service-layer-template.md](service-layer-template.md).
|
||
8. Events / outbox per [event-template.md](event-template.md).
|
||
9. APIs / DTOs / OpenAPI per [api-template.md](api-template.md) — including Health, Capabilities, Metrics, Permission surfaces as required.
|
||
10. Configuration, feature flags, seed data, background jobs when required.
|
||
11. Dependency injection wiring.
|
||
12. Do **not** implement Out of Scope, future-phase, or other-service responsibilities.
|
||
13. Do **not** stop at CRUD — deliver domain rules and mandatory artifacts.
|
||
|
||
**Exit:** Code matches Discovery-promoted scope and mandatory artifacts; no unrelated service edits.
|
||
|
||
## 6. Automated Testing
|
||
|
||
1. Apply [testing-template.md](testing-template.md) and [testing-strategy.md](../development/testing-strategy.md).
|
||
2. Run the service’s pytest (and relevant sibling suites if contracts changed).
|
||
3. Include unit, integration, architecture, security, permission, migration, tenant isolation, and docs validation as required.
|
||
4. Include performance validation for hot paths (or justified N/A).
|
||
5. Cover Discovery-promoted capabilities — not only happy-path CRUD.
|
||
|
||
**Exit:** All required tests pass locally (or in CI for the phase).
|
||
|
||
## 7. Self Audit
|
||
|
||
1. Re-read Discovery Record, Scope / Out of Scope — reject scope creep and future-phase leakage.
|
||
2. Verify every Missing→Implement gap was implemented.
|
||
3. Walk [definition-of-done.md](definition-of-done.md) and [mandatory-phase-artifacts.md](mandatory-phase-artifacts.md).
|
||
4. Search for TODO/FIXME in touched paths related to claimed deliverables.
|
||
5. Verify layering (no business logic in routers/repos).
|
||
6. Verify no cross-DB access or foreign model imports ([boundary-rules.md](boundary-rules.md)).
|
||
7. Verify secrets/brand not hardcoded.
|
||
8. Verify audit/events for state-changing business actions.
|
||
9. Verify OpenAPI, permissions, health/capabilities/metrics as applicable.
|
||
|
||
**Exit:** Self-audit notes with no open blockers.
|
||
|
||
## 8. Documentation Update
|
||
|
||
1. Follow [documentation-template.md](documentation-template.md).
|
||
2. Ensure Discovery Record remains in the phase doc.
|
||
3. Update phase doc, progress, next-steps, module registry, provider registry (if needed), reference contracts/events/APIs as applicable.
|
||
4. Update [phase-manifest.yaml](phase-manifest.yaml) / [service-manifest.yaml](service-manifest.yaml) status and versions.
|
||
5. Fill [phase-handover.md](phase-handover.md) including Discovery summary and Enterprise Completeness Sign-Off.
|
||
|
||
**Exit:** Docs consistent with code; cross-links valid.
|
||
|
||
## 9. Enterprise Completeness Verification
|
||
|
||
1. Run the procedure in [enterprise-completeness.md](enterprise-completeness.md).
|
||
2. Confirm Discovery gaps are closed.
|
||
3. For every failed required dimension: treat as a defect to implement (not a waiver).
|
||
4. Re-run after fixes.
|
||
|
||
**Exit:** All applicable completeness dimensions Pass.
|
||
|
||
## 10. Quality Gates
|
||
|
||
Run every gate in [quality-gates.md](quality-gates.md), including **Enterprise Phase Discovery**.
|
||
|
||
**Exit:** All gates Pass, or Fail with a concrete defect list.
|
||
|
||
## 11. Automatic Repair Loop
|
||
|
||
While any gate or completeness dimension fails:
|
||
|
||
1. Classify defect (discovery gap, business, architecture, security, test, docs, link, tenancy, migration, compatibility, missing artifact, boundary violation).
|
||
2. Fix by **implementing the missing required work** or correcting docs/ADR — smallest correct change.
|
||
3. Prefer docs/ADR first when rules conflict with code intent.
|
||
4. Re-run the failed gate and dependent gates.
|
||
5. Do not mark the phase complete while any gate fails.
|
||
6. Do not weaken gates to force completion.
|
||
7. Do not reclassify current-phase Discovery gaps as “future work” to escape DoD.
|
||
|
||
**Exit:** All gates Pass and DoD satisfied.
|
||
|
||
## 12. Completion Rules
|
||
|
||
A phase may be marked complete only when:
|
||
|
||
1. Enterprise Phase Discovery Record is complete and all Missing→Implement gaps are closed.
|
||
2. [Definition of Done](definition-of-done.md) checklist is satisfied for the phase boundary.
|
||
3. Code and tests for in-scope work are done and green.
|
||
4. Documentation and registries are updated.
|
||
5. ADR updated/created if required.
|
||
6. Enterprise Completeness signed off.
|
||
7. Quality gates all Pass.
|
||
8. Handover package is complete ([phase-handover.md](phase-handover.md)).
|
||
9. [progress.md](../progress.md) records completion; [next-steps.md](../next-steps.md) points to the next milestone.
|
||
10. No TODO remains for claimed deliverables.
|
||
11. Final verification checklist in [docs/README.md](../README.md) Phase Completion Gate is satisfied.
|
||
12. Boundary rules respected throughout.
|
||
|
||
After completion: stop. Do not start the next phase unless explicitly requested.
|
||
|
||
## Related Documents
|
||
|
||
- [Enterprise Phase Discovery](enterprise-phase-discovery.md)
|
||
- [Master Prompt](master-prompt.md)
|
||
- [Definition of Done](definition-of-done.md)
|
||
- [Enterprise Completeness](enterprise-completeness.md)
|
||
- [Quality Gates](quality-gates.md)
|
||
- [Phase Handover](phase-handover.md)
|
||
- [Cursor Guidelines](cursor-guidelines.md)
|
||
- [Project Principles](../development/project-principles.md)
|