134 lines
7.4 KiB
Markdown
134 lines
7.4 KiB
Markdown
# Service Snapshot Policy
|
|
|
|
**Service Snapshot Architecture** — one compact, machine-readable snapshot per service representing current implementation state.
|
|
|
|
Works with [runtime-read-policy.md](runtime-read-policy.md), [context-cache-policy.md](context-cache-policy.md), [`docs/project-status.yaml`](../project-status.yaml), and [project-index.yaml](project-index.yaml). Snapshot file paths are resolved from project-status / Project Index — never discovered by scanning `docs/service-snapshots/`.
|
|
|
|
## Goals
|
|
|
|
1. Eliminate repeated full-project analysis across long-running implementations (with Project Status as the platform dashboard).
|
|
2. Minimize token usage by replacing multi-document state reconstruction with one YAML file per service.
|
|
3. Keep snapshots regenerated automatically after every completed phase.
|
|
4. Keep Project Status regenerated automatically after every completed phase.
|
|
|
|
## Snapshot location
|
|
|
|
Resolved from [project-index.yaml](project-index.yaml) field `snapshot_file` per service:
|
|
|
|
```
|
|
docs/service-snapshots/<service>.yaml
|
|
```
|
|
|
|
Examples (index entries): `hospitality.yaml`, `delivery.yaml`, `experience.yaml`, `crm.yaml`, `accounting.yaml`, `loyalty.yaml`, `communication.yaml`, `sports-center.yaml`.
|
|
|
|
Framework-only workstreams (no owning service) do not require a snapshot file.
|
|
|
|
Template: [docs/service-snapshots/_template.yaml](../service-snapshots/_template.yaml).
|
|
|
|
## Required fields
|
|
|
|
Each snapshot MUST be concise and machine-readable. Required top-level fields:
|
|
|
|
| Field | Description |
|
|
| --- | --- |
|
|
| `service_name` | Canonical service ID (matches [service-manifest.yaml](service-manifest.yaml)) |
|
|
| `commercial_product` | Product / bundle name exposed to tenants |
|
|
| `current_version` | Semver or service version string |
|
|
| `current_phase` | Active phase ID |
|
|
| `last_completed_phase` | Most recent Complete phase ID |
|
|
| `next_phase` | Recommended next phase ID from manifest / next-steps |
|
|
| `completed_phases` | List of Complete phase IDs |
|
|
| `remaining_phases` | List of planned but incomplete phase IDs |
|
|
| `registered_modules` | Module IDs owned by this service |
|
|
| `enabled_capabilities` | Capability keys / feature flags active |
|
|
| `enabled_bundles` | Commercial bundles including this service |
|
|
| `public_apis` | Summary list — method, path, permission (not full OpenAPI) |
|
|
| `published_events` | Summary list — event_type, version |
|
|
| `permission_prefix` | e.g. `accounting.*` |
|
|
| `active_adrs` | ADR IDs governing this service |
|
|
| `integration_contracts` | Cross-service API/event/provider refs |
|
|
| `known_limitations` | Explicit non-goals and temporary constraints |
|
|
| `open_todos` | Open TODOs for in-scope work (empty when phase Complete) |
|
|
| `last_handover_reference` | Path to latest Complete handover |
|
|
| `last_updated` | ISO-8601 date of last regeneration |
|
|
|
|
Optional metadata: `schema_version`, `snapshot_version` (increment on each regeneration).
|
|
|
|
## Execution entry (every phase)
|
|
|
|
Part of the global execution order in [runtime-read-policy.md](runtime-read-policy.md):
|
|
|
|
1. Load [Project Status](../project-status.yaml) (**first**).
|
|
2. Load [Project Index](project-index.yaml) for the active service only.
|
|
3. Load [Runtime Read Policy](runtime-read-policy.md).
|
|
4. Load [Context Cache Policy](context-cache-policy.md).
|
|
5. Load service snapshot — project-status / Project Index `snapshot` for the active service.
|
|
6. Read [phase-manifest.yaml](phase-manifest.yaml).
|
|
7. Read [service-manifest.yaml](service-manifest.yaml).
|
|
8. Read only latest handover — project-status / Project Index.
|
|
9. Additional documents per Runtime Read Policy only.
|
|
|
|
Use project-status + snapshot + index for baseline inventory. Do not re-read completed phase documents when snapshot is valid. Do not inspect unrelated services when project-status exists.
|
|
|
|
## Fallback reconstruction
|
|
|
|
Re-read completed phase documents, registries, or codebase-wide analysis **only** when:
|
|
|
|
| Trigger | Action |
|
|
| --- | --- |
|
|
| Snapshot missing | Build initial snapshot from manifests, latest handover, codebase; then persist |
|
|
| Snapshot invalid | YAML parse error, missing required fields, or manifest/service ID mismatch — rebuild |
|
|
| Snapshot version changed | `snapshot_version` or `last_updated` differs from cache — reload snapshot (not historical phases) |
|
|
| Handover requests additional context | Load only paths explicitly listed in handover |
|
|
| Compatibility validation requires it | Quality gate or validation rule cites specific historical doc |
|
|
|
|
Never bulk-read all completed phase docs when a valid snapshot exists.
|
|
|
|
## Regeneration (mandatory after every completed phase)
|
|
|
|
When a phase marks **Complete** for a service:
|
|
|
|
1. Derive updated field values from handover, manifests, codebase delta, and registries.
|
|
2. Write snapshot to Project Index `snapshot_file` path with all required fields.
|
|
3. Increment `snapshot_version`.
|
|
4. Set `last_updated` to completion date.
|
|
5. Set `last_handover_reference` to the handover just completed.
|
|
6. Update [project-index.yaml](project-index.yaml): `current_version`, `current_phase`, `next_phase`, `latest_handover`, `snapshot_file`.
|
|
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). Never write deprecated `next_recommended_phase` as an active field.
|
|
8. Clear resolved items from `open_todos`; carry forward known limitations.
|
|
9. Pass the **Project Status**, **Service Snapshot**, and **Project Index** quality gates ([quality-gates.md](quality-gates.md)).
|
|
|
|
Framework-only phases: update Project Status + policy docs; snapshot N/A unless they define snapshot schema/policy.
|
|
|
|
## Relationship to other policies
|
|
|
|
| Policy | Role |
|
|
| --- | --- |
|
|
| [project-status.yaml](../project-status.yaml) | Platform execution dashboard — critical_path, execution_priority, deployment_readiness |
|
|
| [project-index.yaml](project-index.yaml) | Path resolver — snapshots, roadmaps, handovers |
|
|
| [runtime-read-policy.md](runtime-read-policy.md) | What may load beyond index + snapshot |
|
|
| [context-cache-policy.md](context-cache-policy.md) | Whether to re-read unchanged docs |
|
|
| [service-snapshot-policy.md](service-snapshot-policy.md) | Snapshot schema and regeneration |
|
|
|
|
Discovery baseline inventory SHOULD come from the snapshot first, then latest handover for delta, then codebase for verification — not from re-reading every completed phase doc.
|
|
|
|
## Backward compatibility
|
|
|
|
- Completed business phases and handovers are unchanged.
|
|
- Services without a snapshot yet: first phase entry builds snapshot per fallback rules; no retrofit of historical phases required.
|
|
- Path `docs/service-snapshots/` is additive; no business service code changes required by this policy alone.
|
|
|
|
- New services: add Project Index entry on registration in same phase as [service-manifest.yaml](service-manifest.yaml).
|
|
|
|
## 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)
|
|
- [Enterprise Phase Discovery](enterprise-phase-discovery.md)
|
|
- [Development Loop](development-loop.md)
|
|
- [Mandatory Phase Artifacts](mandatory-phase-artifacts.md)
|
|
- [Phase Handover](phase-handover.md)
|
|
- [Quality Gates](quality-gates.md)
|