# 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)