TorbatYar/docs/ai-framework/quality-gates.md

# Quality Gates

Mandatory gates before any implementation phase may be marked complete.

All gates must **Pass**. On failure, enter the Automatic Repair Loop ([development-loop.md](development-loop.md)) and **implement missing required artifacts** — do not waive enterprise requirements.

Companions: [enterprise-phase-discovery.md](enterprise-phase-discovery.md) · [definition-of-done.md](definition-of-done.md) · [enterprise-completeness.md](enterprise-completeness.md) · [boundary-rules.md](boundary-rules.md) · [service-snapshot-policy.md](service-snapshot-policy.md) · [project-index.yaml](project-index.yaml) · [ADR-018](../architecture/adr/ADR-018.md) · [ADR-019](../architecture/adr/ADR-019.md).

## Enterprise Phase Discovery

| Check | Pass criteria |
| --- | --- |
| Record | Discovery Record present in phase doc before Implementation claimed |
| Inputs | Roadmap, Architecture, Boundaries, Prior handover, Codebase, APIs, Domain, Events, Permissions, Aggregates, Tests, Docs reviewed (or N/A justified for docs-only) |
| Gap analysis | Missing Capability Checklist completed; CRUD-only rejected |
| Promotion | Every Missing→Implement gap implemented before Complete |
| Boundaries | No future-phase pull-forward; no foreign ownership; no service duplication |
| Align | [enterprise-phase-discovery.md](enterprise-phase-discovery.md) |

## Project Index

| Check | Pass criteria |
| --- | --- |
| Exists | [project-index.yaml](project-index.yaml) present and valid YAML |
| Coverage | Every registered service in [service-manifest.yaml](service-manifest.yaml) has an index entry |
| Fields | All required fields per service (name, product, identifier, status, version, phases, snapshot, roadmap, handover, manifests, registry, permission, DB, API port, prefixes, endpoints) |
| Consistency | Index agrees with service-manifest, latest handover, and snapshot for owning service |
| Freshness | Updated on service registration and phase Complete (`current_version`, `current_phase`, `next_phase`, `latest_handover`, `snapshot_file`) |
| Discovery | Agents resolve paths from index — no repository folder scans |
| Align | [project-index.yaml](project-index.yaml) · [runtime-read-policy.md](runtime-read-policy.md) |

## Service Snapshot

| Check | Pass criteria |
| --- | --- |
| Exists | Project Index `snapshot_file` present for service-scoped Complete phases (or initial snapshot built on first entry) |
| Fields | All required fields from [service-snapshot-policy.md](service-snapshot-policy.md) populated |
| Freshness | Regenerated after this phase; `last_updated` and `last_handover_reference` match completion |
| Consistency | Snapshot agrees with handover, manifests, and in-scope codebase |
| Usage | Next phase may use snapshot as primary state — no required re-read of completed phase docs |
| Align | [service-snapshot-policy.md](service-snapshot-policy.md) |

## Business Completeness

| Check | Pass criteria |
| --- | --- |
| Capabilities | Every in-scope / Discovery-promoted business capability delivered end-to-end |
| Not CRUD-only | Domain rules, validators, policies/specs as needed beyond CRUD |
| DoD | [definition-of-done.md](definition-of-done.md) checklist complete for phase boundary |
| No future pull-forward | Out of Scope / future phases untouched |

## Architecture

| Check | Pass criteria |
| --- | --- |
| Boundaries | No ownership theft per [module-boundaries.md](../architecture/module-boundaries.md) and [boundary-rules.md](boundary-rules.md) |
| DB isolation | No cross-DB queries/FKs ([ADR-001](../architecture/adr/ADR-001.md)) |
| Layering | Business logic in services/commands; thin API; persistence-only repos |
| FE/BE | No backend imports in frontend; no UI rules in backend ([ADR-002](../architecture/adr/ADR-002.md)) |
| ADR | New architectural decisions recorded; conflicts resolved |
| Events | Outbox-ready; naming per [event-template.md](event-template.md) |
| Domain model | Aggregates/entities/DTOs designed for in-scope work |

## API Completeness

| Check | Pass criteria |
| --- | --- |
| REST | In-scope resources exposed with correct methods and DTOs |
| Health | `/health` present for runnable services |
| Capabilities | `/capabilities` (or equivalent) when discoverable features exist |
| Metrics | `/metrics` or justified N/A with operational alternative |
| OpenAPI | Generated/updated and accurate for new/changed routes |
| List UX | Pagination, filtering, sorting, searching on collection endpoints |
| Permission APIs | Permission tree registered; permission listing routes when service pattern requires |

## Permission Completeness

| Check | Pass criteria |
| --- | --- |
| Mapping | Every privileged route has a permission check |
| Naming | `{service}.{resource}.{action}` / `{service}.*` trees documented |
| Tests | Denial cases covered |

## Event Completeness

| Check | Pass criteria |
| --- | --- |
| Emission | Cross-service-relevant state changes write outbox events |
| Catalog | [event-catalog.md](../reference/event-catalog.md) / registry updated |
| Envelope | Stable envelope fields; additive payloads |

## Repository Completeness

| Check | Pass criteria |
| --- | --- |
| Tenant filter | All tenant-owned queries scoped |
| Soft delete | Defaults exclude soft-deleted rows where policy requires |
| List support | Pagination/filter/sort/search supported as API requires |
| No domain logic | Business branching stays in services |

## Validation Completeness

| Check | Pass criteria |
| --- | --- |
| Edge | Pydantic request/query validation |
| Domain | Validators / specifications / policies enforce invariants |
| Codes | Stable error codes for illegal transitions |

## Security

| Check | Pass criteria |
| --- | --- |
| Auth | Protected routes deny anonymous access |
| Secrets | No hardcoded credentials/brand tokens |
| Errors | No stack/secret leakage |
| Providers | Credentials only in owning service config |
| Align | [security-architecture.md](../architecture/security-architecture.md) |

## Performance

| Check | Pass criteria |
| --- | --- |
| Queries | Tenant-scoped lists use sensible indexes; no obvious N+1 in new hot paths |
| Hot paths | Covered or explicitly N/A in phase doc |
| Async | Long-running provider I/O not blocking business transactions when architecture requires async |

## Testing

| Check | Pass criteria |
| --- | --- |
| Suite | Required tests from [testing-template.md](testing-template.md) exist and pass |
| Strategy | Aligns with [testing-strategy.md](../development/testing-strategy.md) |
| Claims | Every claimed deliverable has coverage |
| Categories | Unit · Integration · Architecture · Security · Tenant · Permission · Migration · Docs as applicable |

## Documentation

| Check | Pass criteria |
| --- | --- |
| Updates | [documentation-template.md](documentation-template.md) checklist done |
| Links | No broken relative links in touched docs |
| Registries | Module/provider/manifests consistent with code |
| Glossary | New terms defined when introduced |
| No TODO | No TODO for claimed deliverables |
| OpenAPI | Documented as part of API surface |

## Migration

| Check | Pass criteria |
| --- | --- |
| Alembic | Revision exists for schema changes in owning service |
| Apply | Upgrade smoke succeeds |
| Ownership | Only owning DB migrated |
| Seed | Seed data present when phase requires it |
| Notes | Handover includes migration notes |

## Backward Compatibility

| Check | Pass criteria |
| --- | --- |
| APIs | Additive within version unless phase documents breaking change + consumer plan |
| Events | No silent meaning change of existing `event_type` |
| Data | Existing rows remain valid or backfill documented |

## Tenant Isolation

| Check | Pass criteria |
| --- | --- |
| Schema | Business tables have `tenant_id` ([ADR-003](../architecture/adr/ADR-003.md)) |
| Queries | Filters applied |
| Tests | Cross-tenant denial covered |
| Admin exceptions | Explicit and audited |

## Provider Abstraction

| Check | Pass criteria |
| --- | --- |
| Protocols | External systems behind interfaces in owning service |
| Registry | [provider-registry.md](../provider-registry.md) updated when providers change |
| No leakage | Foreign platforms not implemented inside non-owning modules |

## Integration Completeness

| Check | Pass criteria |
| --- | --- |
| Channels | Only API / Events / Providers used cross-service |
| No duplication | Business logic not copied from owning services |
| No foreign DB | Zero cross-DB access |

## Operational Readiness

| Check | Pass criteria |
| --- | --- |
| Health | Liveness endpoint green |
| Observability | Logging + metrics (or justified N/A) |
| Config | Env/settings documented; no secrets in code |
| Jobs | Background jobs present when phase requires async/scheduled work |
| Feature flags | Present when gated capabilities are in scope |

## Maintainability & DX

| Check | Pass criteria |
| --- | --- |
| Patterns | Matches sibling service conventions or documents intentional deviation |
| DI | Explicit dependency injection |
| README | Service README updated for new run/config surfaces |
| Scope hygiene | No unrelated drive-by refactors |

## Definition of Done Gate

| Check | Pass criteria |
| --- | --- |
| DoD | Full [definition-of-done.md](definition-of-done.md) satisfied |
| Completeness | [enterprise-completeness.md](enterprise-completeness.md) sign-off complete |
| Artifacts | Applicable [mandatory-phase-artifacts.md](mandatory-phase-artifacts.md) delivered or justified N/A |
| Discovery | [enterprise-phase-discovery.md](enterprise-phase-discovery.md) Record complete; gaps closed |
| Snapshot | [service-snapshot-policy.md](service-snapshot-policy.md) regenerated when service-scoped |
| Project Index | [project-index.yaml](project-index.yaml) updated when service-scoped |

## Validation Suites (Framework Phases)

When changing `docs/ai-framework/` or docs structure, also verify:

1. **Architecture Validation** — framework links to architecture/ADR correctly; no conflicting rules vs principles.
2. **Documentation Validation** — all listed framework docs exist; index complete.
3. **Cross Reference Validation** — manifests ↔ registries ↔ phase areas agree on names/status where claimed.
4. **Broken Link Validation** — relative Markdown links resolve.
5. **Template Validation** — every template referenced from README exists and has Related Documents.
6. **Manifest Validation** — YAML parses; required fields present; phase/service IDs unique.
7. **Enterprise Rule Validation** — DoD, Discovery, mandatory artifacts, completeness, boundary docs, and Project Index cross-linked from master-prompt, loop, gates, and phase template.
8. **Project Index Validation** — YAML parses; every service-manifest entry indexed; paths resolve; no orphan snapshot references.

## Sign-Off

- [ ] Enterprise Phase Discovery
- [ ] Project Index
- [ ] Service Snapshot
- [ ] Business Completeness
- [ ] Architecture
- [ ] API Completeness
- [ ] Permission Completeness
- [ ] Event Completeness
- [ ] Repository Completeness
- [ ] Validation Completeness
- [ ] Security
- [ ] Performance
- [ ] Testing
- [ ] Documentation
- [ ] Migration
- [ ] Backward Compatibility
- [ ] Tenant Isolation
- [ ] Provider Abstraction
- [ ] Integration Completeness
- [ ] Operational Readiness
- [ ] Maintainability & DX
- [ ] Definition of Done / Enterprise Completeness

## Related Documents

- [Project Index](project-index.yaml)
- [Service Snapshot Policy](service-snapshot-policy.md)
- [Development Loop](development-loop.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)
- [docs/README.md](../README.md) Phase Completion Gate
- [Project Principles](../development/project-principles.md)