283 lines
13 KiB
Markdown
283 lines
13 KiB
Markdown
# 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-status.yaml](../project-status.yaml) · [project-index.yaml](project-index.yaml) · [ADR-018](../architecture/adr/ADR-018.md) · [ADR-019](../architecture/adr/ADR-019.md).
|
|
|
|
## Project Status
|
|
|
|
| Check | Pass criteria |
|
|
| --- | --- |
|
|
| Exists | [`docs/project-status.yaml`](../project-status.yaml) and [`docs/project-status.md`](../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](../project-status.yaml) · [runtime-read-policy.md](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](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 |
|
|
| Project Status | [project-status.yaml](../project-status.yaml) + [project-status.md](../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
|
|
|
|
- [Project Status](../project-status.yaml)
|
|
- [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)
|