morteza/TorbatYar
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
ea5fabaa7c
TorbatYar/docs/ai-framework/service-snapshot-policy.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

7.4 KiB
Raw Blame History

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, docs/project-status.yaml, and 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 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 Status (first).
  2. Load Project Index for the active service only.
  3. Load Runtime Read Policy.
  4. Load Context Cache Policy.
  5. Load service snapshot — project-status / Project Index snapshot for the active service.
  6. Read phase-manifest.yaml.
  7. Read 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: current_version, current_phase, next_phase, latest_handover, snapshot_file.
  7. Update docs/project-status.yaml and docs/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).

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 Platform execution dashboard — critical_path, execution_priority, deployment_readiness
project-index.yaml Path resolver — 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