TorbatYar/docs/ai-framework/service-snapshot-policy.md

Service Snapshot Policy

Service Snapshot Architecture — one compact, machine-readable snapshot per service representing current implementation state.

Works with runtime-read-policy.md, context-cache-policy.md, and project-index.yaml. Snapshot file paths are resolved from Project Index — never discovered by scanning docs/service-snapshots/.

Goals

1. Eliminate repeated full-project analysis across long-running implementations.
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.

Snapshot location

Resolved from 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.

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

1. Load Project Index.
2. Load Runtime Read Policy.
3. Load Context Cache Policy.
4. Load service snapshot — Project Index snapshot_file for the active service.
5. Read phase-manifest.yaml.
6. Read service-manifest.yaml.
7. Read only latest handover — Project Index latest_handover.
8. Additional documents per Runtime Read Policy only.

Use snapshot + index for baseline inventory. Do not re-read completed phase documents when snapshot is valid.

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: current_version, current_phase, next_phase, latest_handover, snapshot_file.
7. Clear resolved items from open_todos; carry forward known limitations.
8. Pass the Service Snapshot and Project Index quality gates (quality-gates.md).

Framework-only phases: N/A unless they define snapshot schema/policy (update policy docs only).

Relationship to other policies

Policy	Role
project-index.yaml	Discovery entry — paths to snapshots, roadmaps, handovers
runtime-read-policy.md	What may load beyond index + snapshot
context-cache-policy.md	Whether to re-read unchanged docs
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.

Related Documents

• Project Index
• Runtime Read Policy
• Context Cache Policy
• Enterprise Phase Discovery
• Development Loop
• Mandatory Phase Artifacts
• Phase Handover
• Quality Gates