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 per 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-index.yaml · runtime-read-policy.md · context-cache-policy.md · service-snapshot-policy.md · enterprise-phase-discovery.md · definition-of-done.md · mandatory-phase-artifacts.md · boundary-rules.md · ADR-018 · ADR-019.

1. Enterprise Phase Discovery

Mandatory before Implementation. Full procedure: enterprise-phase-discovery.md.

1. Load docs/project-status.yaml first; resolve next work from execution_priority (critical→future) and critical_path; then load project-index.yaml and follow 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.
3. Confirm Objective, Scope, Out of Scope, Dependencies, and Required Services from 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 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 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 vs 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 (tenant, soft delete, audit, indexes, optimistic locking where needed).
4. DTO Design per 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 implementation order.
2. Implement every Discovery gap marked Missing→Implement.
3. Models / entities / migrations (owning DB only).
4. Repositories per 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.
8. Events / outbox per event-template.md.
9. APIs / DTOs / OpenAPI per 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; apply 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 and 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).
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.
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 / service-manifest.yaml status and versions.
5. Fill phase-handover.md including Discovery summary and Enterprise Completeness Sign-Off.
6. Update project-index.yaml for the owning service (version, phase, next phase, handover, snapshot path).
7. Update docs/project-status.yaml and docs/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.
9. Invalidate 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.
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, 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 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).
9. Service snapshot regenerated; Project Index updated; Project Status updated (service-snapshot-policy.md, project-index.yaml, project-status.yaml).
10. progress.md records completion; next-steps.md points to the next milestone.
11. No TODO remains for claimed deliverables.
12. Final verification checklist in docs/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 Index
• Runtime Read Policy
• Context Cache Policy
• Service Snapshot Policy
• Enterprise Phase Discovery
• Master Prompt
• Definition of Done
• Enterprise Completeness
• Quality Gates
• Phase Handover
• Cursor Guidelines
• Project Principles