# 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)