morteza/TorbatYar
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
208a9c2661
TorbatYar/docs/ai-framework/quality-gates.md
Mortezakoohjani 091b33a638 feat(platform): finalize commercial runtime, platform shell and hospitality production frontend 
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-28 20:39:10 +03:30

13 KiB
Raw Blame History

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) and implement missing required artifacts — do not waive enterprise requirements.

Companions: enterprise-phase-discovery.md · definition-of-done.md · enterprise-completeness.md · boundary-rules.md · service-snapshot-policy.md · project-status.yaml · project-index.yaml · ADR-018 · ADR-019.

Project Status

Check Pass criteria
Exists docs/project-status.yaml and docs/project-status.md present
Fields schema v2: project_version, last_updated, last_completed_phase, critical_path, execution_priority, resume_rules, automatic_update_rules, per-service deployment_readiness, depends_on/required_by, completion percents, global_statistics
Freshness Updated on this phase Complete for affected service + global stats + critical_path + priorities
Scope discipline Agents used project-status first; no unrelated-service scan when file valid; no use of deprecated next_recommended_phase
Align project-status.yaml · runtime-read-policy.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

Project Index

Check Pass criteria
Exists project-index.yaml present and valid YAML
Coverage Every registered service in 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 · 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 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

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 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 and boundary-rules.md
DB isolation No cross-DB queries/FKs (ADR-001)
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)
ADR New architectural decisions recorded; conflicts resolved
Events Outbox-ready; naming per 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 / 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

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 exist and pass
Strategy Aligns with 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 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)
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 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 satisfied
Completeness enterprise-completeness.md sign-off complete
Artifacts Applicable mandatory-phase-artifacts.md delivered or justified N/A
Discovery enterprise-phase-discovery.md Record complete; gaps closed
Snapshot service-snapshot-policy.md regenerated when service-scoped
Project Index project-index.yaml updated when service-scoped
Project Status project-status.yaml + project-status.md updated

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, Project Status, 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.
  9. Project Status Validation — YAML parses; schema v2 fields present; critical_path + execution_priority present; no active next_recommended_phase; run node docs/ai-framework/scripts/validate-project-status.mjs.

Sign-Off

  • Enterprise Phase Discovery
  • Project Status
  • 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