# Development Loop

Permanent implementation lifecycle for every TorbatYar phase.

Agents and humans follow these stages in order. After Quality Gates fail, enter the Automatic Repair Loop until all gates pass, then complete.

## 1. Requirements Analysis

1. Read [docs/README.md](../README.md), [AI Framework README](README.md), [master-prompt.md](master-prompt.md).
2. Read architecture (`docs/architecture/*`, `docs/architecture/adr/*`), development standards, registries, glossary.
3. Read the phase brief (or create from [phase-template.md](phase-template.md)).
4. Confirm Objective, Scope, Out of Scope, Dependencies, and Required Services from [phase-manifest.yaml](phase-manifest.yaml).
5. List aggregates, APIs, events, permissions, and docs that must change.
6. Stop if requirements conflict with ADRs or module boundaries — resolve via ADR/docs first.

**Exit:** Written understanding of in-scope deliverables and explicit non-goals.

## 2. Architecture Validation

1. Validate against [module-boundaries.md](../architecture/module-boundaries.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 no ownership theft (e.g. CRM must not own Loyalty or Communication).

**Exit:** Architecture checklist green or ADR/docs updated to resolve conflicts.

## 3. Implementation

1. Follow [cursor-guidelines.md](cursor-guidelines.md) implementation order.
2. Models / entities per [entity-template.md](entity-template.md).
3. Repositories per [repository-template.md](repository-template.md).
4. Services per [service-layer-template.md](service-layer-template.md).
5. Validators, permissions, events per [event-template.md](event-template.md).
6. APIs / DTOs per [api-template.md](api-template.md).
7. Migrations owned by the service database only.
8. Do not implement out-of-scope features.

**Exit:** Code matches phase scope; no unrelated service edits.

## 4. 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 tenant isolation negatives for new tenant-scoped APIs.
4. Include permission, migration, architecture/boundary, and docs validation tests when the service pattern requires them.

**Exit:** All required tests pass locally (or in CI for the phase).

## 5. Self Audit

1. Re-read Scope / Out of Scope — reject scope creep.
2. Search for TODO/FIXME in touched paths related to claimed deliverables.
3. Verify layering (no business logic in routers/repos).
4. Verify no cross-DB access or foreign model imports.
5. Verify secrets/brand not hardcoded.
6. Verify audit/events for state-changing business actions.

**Exit:** Self-audit notes with no open blockers.

## 6. Documentation Update

1. Follow [documentation-template.md](documentation-template.md).
2. Update phase doc, progress, next-steps, module registry, provider registry (if needed), reference contracts/events/APIs as applicable.
3. Update [phase-manifest.yaml](phase-manifest.yaml) / [service-manifest.yaml](service-manifest.yaml) status and versions.
4. Fill [phase-handover.md](phase-handover.md) sections for the phase (or phase-specific handover section in the phase doc).

**Exit:** Docs consistent with code; cross-links valid.

## 7. Quality Gates

Run every gate in [quality-gates.md](quality-gates.md):

- Architecture · Security · Performance · Testing · Documentation · Migration · Backward Compatibility · Tenant Isolation

**Exit:** All gates Pass, or Fail with a concrete defect list.

## 8. Automatic Repair Loop

While any gate fails:

1. Classify defect (architecture, security, test, docs, link, tenancy, migration, compatibility).
2. Fix the smallest correct change (prefer docs/ADR first when rules conflict).
3. Re-run the failed gate and dependent gates.
4. Do not mark the phase complete while any gate fails.
5. Do not weaken gates to force completion.

**Exit:** All gates Pass.

## 9. Completion Rules

A phase may be marked complete only when:

1. Code and tests for in-scope work are done and green.
2. Documentation and registries are updated.
3. ADR updated/created if required.
4. Quality gates all Pass.
5. Handover package is complete ([phase-handover.md](phase-handover.md)).
6. [progress.md](../progress.md) records completion; [next-steps.md](../next-steps.md) points to the next milestone.
7. No TODO remains for claimed deliverables.
8. Final verification checklist in [docs/README.md](../README.md) Phase Completion Gate is satisfied.

After completion: stop. Do not start the next phase unless explicitly requested.

## Related Documents

- [Master Prompt](master-prompt.md)
- [Quality Gates](quality-gates.md)
- [Phase Handover](phase-handover.md)
- [Cursor Guidelines](cursor-guidelines.md)
- [Project Principles](../development/project-principles.md)
