TorbatYar/docs/ai-framework/development-loop.md

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

**Document loading:** Start from [`docs/project-status.yaml`](../project-status.yaml) per [runtime-read-policy.md](runtime-read-policy.md) execution entry. When project-status exists, do not inspect unrelated services. Never scan repository folders.

Canonical mandates: [project-status.yaml](../project-status.yaml) · [project-index.yaml](project-index.yaml) · [runtime-read-policy.md](runtime-read-policy.md) · [context-cache-policy.md](context-cache-policy.md) · [service-snapshot-policy.md](service-snapshot-policy.md) · [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. Load [`docs/project-status.yaml`](../project-status.yaml) first; resolve next work from `execution_priority` (critical→future) and `critical_path`; then load [project-index.yaml](project-index.yaml) and follow [runtime-read-policy.md](runtime-read-policy.md) execution entry for the **active service only**.
2. Synthesize **Discovery Inputs** from Project Status + Project Index + snapshot + policy mapping per [enterprise-phase-discovery.md](enterprise-phase-discovery.md).
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. Follow [Runtime Read Policy](runtime-read-policy.md) for boundary and architecture docs required by this stage.
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. Follow [Runtime Read Policy](runtime-read-policy.md); apply [testing-template.md](testing-template.md) when the Testing stage or gate requires it.
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.
6. Update [project-index.yaml](project-index.yaml) for the owning service (version, phase, next phase, handover, snapshot path).
7. Update [`docs/project-status.yaml`](../project-status.yaml) and [`docs/project-status.md`](../project-status.md) per `automatic_update_rules`: completed/remaining phases, deployment_readiness, percentages, critical_path, execution_priority, service completion, timestamps. **Do not** set deprecated `next_recommended_phase`.
8. Regenerate service snapshot per [service-snapshot-policy.md](service-snapshot-policy.md).
9. Invalidate [context-cache-policy.md](context-cache-policy.md) entries for every doc modified in this phase.

**Exit:** Docs consistent with code; Project Status, Project Index, and snapshot updated; cache invalidated for changed paths.

## 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. Service snapshot regenerated; Project Index updated; **Project Status updated** ([service-snapshot-policy.md](service-snapshot-policy.md), [project-index.yaml](project-index.yaml), [project-status.yaml](../project-status.yaml)).
10. [progress.md](../progress.md) records completion; [next-steps.md](../next-steps.md) points to the next milestone.
11. No TODO remains for claimed deliverables.
12. Final verification checklist in [docs/README.md](../README.md) Phase Completion Gate is satisfied.
13. Boundary rules respected throughout.

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

## Related Documents

- [Project Status](../project-status.yaml)
- [Project Index](project-index.yaml)
- [Runtime Read Policy](runtime-read-policy.md)
- [Context Cache Policy](context-cache-policy.md)
- [Service Snapshot Policy](service-snapshot-policy.md)
- [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)