TorbatYar/docs/ai-framework/runtime-read-policy.md

# Runtime Read Policy

**Authoritative source for document loading** during every AI-assisted phase on TorbatYar.

All framework stages ([development-loop.md](development-loop.md), [enterprise-phase-discovery.md](enterprise-phase-discovery.md), [master-prompt.md](master-prompt.md)) defer to this policy. When any other document says “read all …”, “read framework + architecture …”, or lists unconditional doc paths, **this policy wins**.

**Incremental loading:** [context-cache-policy.md](context-cache-policy.md) governs whether to re-read or reuse cached context between phases. This policy still defines *what* may load; the cache policy defines *when to re-read* unchanged files.

**Execution dashboard:** [`docs/project-status.yaml`](../project-status.yaml) is the **first** document every phase reads. Use `execution_priority` + `critical_path` + `deployment_readiness` (not deprecated `next_recommended_phase`). When present, do **not** inspect unrelated services or full-scan the project.

**Service state:** [service-snapshot-policy.md](service-snapshot-policy.md) provides compact per-service state. **[project-index.yaml](project-index.yaml)** resolves service, snapshot, roadmap, and handover paths for the **active** service only; never scan repository folders.

## Execution entry (every phase)

At phase start, in **exact** order:

1. Load [`docs/project-status.yaml`](../project-status.yaml) (**first** — authoritative execution dashboard).
2. If project-status exists: determine remaining work from `execution_priority`, `critical_path`, `remaining_phases`, and `deployment_readiness` — **do not** inspect unrelated services or reconstruct platform state by scanning. Never use deprecated `next_recommended_phase`.
3. Load [Project Index](project-index.yaml) for path resolution of the **active service only**.
4. Load [Runtime Read Policy](runtime-read-policy.md) (this document).
5. Load [Context Cache Policy](context-cache-policy.md).
6. Load the current **service snapshot** — path from Project Index `snapshot_file` (or project-status `snapshot`) for the active service.
7. Read [phase-manifest.yaml](phase-manifest.yaml).
8. Read [service-manifest.yaml](service-manifest.yaml).
9. Read **only** the latest handover — path from Project Index / project-status for the active service.
10. Read additional documents only when this policy requires them.

**Fallback:** If `project-status.yaml` is missing or invalid YAML, reconstruct once from Project Index + manifests + snapshots, persist project-status, then continue. Never require a full project scan again once the file is valid.

**Never scan** folders to discover services, handovers, roadmaps, snapshots, ADRs, or architecture documents — resolve through project-status + Project Index.

## Loading tiers

Agents MUST load documents only from the tiers below. Do not bulk-read directories or unrelated services.

### ALWAYS READ

Required context at phase start. Split by [context-cache-policy.md](context-cache-policy.md):

**Always reload from disk (every new phase):**

| Document | Path |
| --- | --- |
| Project Status | [project-status.yaml](../project-status.yaml) |
| Project Index | [project-index.yaml](project-index.yaml) |
| Service snapshot | From project-status / Project Index for **active service only** |
| Phase manifest | [phase-manifest.yaml](phase-manifest.yaml) |
| Service manifest | [service-manifest.yaml](service-manifest.yaml) |
| Progress | [progress.md](../progress.md) |
| Next steps | [next-steps.md](../next-steps.md) |
| Latest phase handover | From project-status / Project Index for active service |

Also load the **current phase brief** (phase doc or prompt) when assigned — new each phase.

**Required but cache-eligible (reload only if changed):**

| Document | Path |
| --- | --- |
| Module registry | [module-registry.md](../module-registry.md) |
| Glossary | [glossary.md](../glossary.md) |
| Docs index | [docs/README.md](../README.md) |
| Definition of Done | [definition-of-done.md](definition-of-done.md) |
| Quality gates | [quality-gates.md](quality-gates.md) |
| Development loop | [development-loop.md](development-loop.md) |
| Enterprise Phase Discovery | [enterprise-phase-discovery.md](enterprise-phase-discovery.md) |
| Runtime Read Policy | [runtime-read-policy.md](runtime-read-policy.md) |
| Context Cache Policy | [context-cache-policy.md](context-cache-policy.md) |
| Service Snapshot Policy | [service-snapshot-policy.md](service-snapshot-policy.md) |

Do **not** auto-read latest completed handover or completed phase documents when a valid service snapshot exists — use snapshot + latest handover only per [service-snapshot-policy.md](service-snapshot-policy.md).

### READ ONCE PER SERVICE

Load once per service when entering that service’s work; cache per [context-cache-policy.md](context-cache-policy.md) — do not re-read on every sub-step or subsequent phase unless content changed:

| Document | Path |
| --- | --- |
| Service roadmap | From Project Index `roadmap_file` for active service |
| Service README | `backend/services/<name>/README.md` |

Do **not** load latest completed phase documents when snapshot is valid — snapshot supersedes historical phase doc reconstruction.

### READ ONLY IF REFERENCED

Load individual files from these areas **only** when required by one of the [Additional load triggers](#additional-load-triggers) below — never as bulk directory reads:

| Area | Path |
| --- | --- |
| Architecture | `docs/architecture/*` |
| ADRs | `docs/architecture/adr/*` |
| Published Resource | [published-resource-architecture.md](../architecture/published-resource-architecture.md), [ADR-022](../architecture/adr/ADR-022.md), [published-resource-contracts.md](../reference/published-resource-contracts.md) — load when designing public surfaces or Payment/Communication/Link/QR/Analytics attachments |
| Reference contracts | `docs/reference/*` |
| Development standards | `docs/development/*` |
| Deployment | `docs/deployment/*` |

Examples: load [ADR-001](../architecture/adr/ADR-001.md) when tenancy or DB-per-service is in scope; load [testing-strategy.md](../development/testing-strategy.md) when running the Testing stage; load [event-catalog.md](../reference/event-catalog.md) when validating events. After first load, **cache** individual architecture, ADR, reference, development, and deployment files until changed.

### NEVER AUTO READ

Do not load unless an [Additional load trigger](#additional-load-triggers) explicitly requires a specific file:

| Category | Examples |
| --- | --- |
| Other services | Roadmaps, phase docs, handovers, snapshots of services not in current scope |
| Completed phase history | Completed phase documents when a valid service snapshot exists |
| Frontend | `frontend/` documentation (unless the phase scopes frontend work) |
| Historical / audit | Old audit reports, superseded handovers, archived docs |
| Bulk paths | `architecture/*`, `reference/*`, `development/*`, `deployment/*`, `phase-handover/*`, `service-snapshots/*` as directory scans |
| Repository tree scan | Any folder walk to discover services, docs, or paths not listed in Project Index |

## Additional load triggers

Beyond the tiers above, load a document **only** when:

1. **Required by the current phase** — listed in the phase brief, phase doc, or promoted Discovery scope.
2. **Required by the current service** — owning service README, templates, or in-service docs for work in progress.
3. **Referenced by [phase-manifest.yaml](phase-manifest.yaml)** — `required_docs`, deliverables, or phase metadata for this phase ID.
4. **Referenced by [service-manifest.yaml](service-manifest.yaml)** — service entry, dependencies, or required docs for the owning service.
5. **Referenced by [project-status.yaml](../project-status.yaml) or [project-index.yaml](project-index.yaml)** — snapshot, roadmap, handover, or ADR path for the active service.
6. **Referenced by the latest handover** — explicit paths beyond index entries.
7. **Required by a compatibility or validation rule** — e.g. [quality-gates.md](quality-gates.md) gate, [boundary-rules.md](boundary-rules.md), or a cited ADR during Architecture Validation.
8. **Public-surface / publish integration design** — load [ADR-022](../architecture/adr/ADR-022.md) and [published-resource-architecture.md](../architecture/published-resource-architecture.md) when work attaches Payment, Communication, Short Link, QR, Analytics, or future products to a public surface via `publish_id`. Also load [published-action-registry.md](../reference/published-action-registry.md), [public-access-contract.md](../reference/public-access-contract.md), and/or [embed-contract.md](../reference/embed-contract.md) when designing actions, access policies, or embeds.

When a trigger applies, load **only the referenced files**, not sibling or parent directories.

## Discovery inputs (policy mapping)

[Enterprise Phase Discovery](enterprise-phase-discovery.md) synthesizes inputs below. Use this mapping instead of reading every path unconditionally:

| Discovery input | Load via |
| --- | --- |
| Service baseline state | **Project Status** + **Project Index** + **service snapshot** ([service-snapshot-policy.md](service-snapshot-policy.md)) |
| Current Roadmap | Project Index `roadmap_file` + snapshot + manifests |
| Current Architecture | READ ONLY IF REFERENCED (manifest, handover, phase, gate, ADR, or snapshot `active_adrs`) |
| Service Boundaries | Snapshot + ALWAYS READ registries/manifests; boundary docs when referenced |
| Previous Phase Handover | Project Index `latest_handover` (always reload) |
| Existing Codebase | Inspect `backend/services/<name>/` for delta verification (not full reconstruction) |
| Existing APIs | Snapshot `public_apis` summary; codebase/OpenAPI for current-phase changes |
| Existing Domain Model | Snapshot + codebase + current phase doc |
| Existing Events | Snapshot `published_events`; codebase for current-phase changes |
| Existing Permissions | Snapshot `permission_prefix` + codebase |
| Existing Aggregates | Codebase models; snapshot modules — not completed phase docs |
| Existing Tests | Codebase `app/tests/` |
| Existing Documentation | Snapshot + ALWAYS READ tier + current phase doc + triggered reference files |

## Framework and template docs

Load framework templates ([cursor-guidelines.md](cursor-guidelines.md), [testing-template.md](testing-template.md), [api-template.md](api-template.md), etc.) **when the active development-loop stage or quality gate requires them**, not preemptively.

[master-prompt.md](master-prompt.md) summarizes permanent rules; ALWAYS READ tier already includes loop, gates, DoD, and Discovery.

## Backward compatibility

- Completed business phases and their handovers are unchanged.
- Legacy prompts or docs that instruct unconditional reads are **superseded** by this policy; agents follow tiers and triggers above.
- Path `docs/ai-framework/` remains canonical; no relocation required.
- Enterprise Phase Discovery remains mandatory; Discovery uses snapshot + targeted loading, not full-tree or historical phase doc reads.
- Cache reuse is an optimization; if change detection is unavailable, follow read tiers normally.
- Services without a snapshot: path from Project Index; build per [service-snapshot-policy.md](service-snapshot-policy.md) fallback rules.
- New services: add Project Index entry on registration; never discover by scanning.

## Related Documents

- [Project Status](../project-status.yaml) · [project-status.md](../project-status.md)
- [Project Index](project-index.yaml)
- [Service Snapshot Policy](service-snapshot-policy.md)
- [Context Cache Policy](context-cache-policy.md)
- [Master Prompt](master-prompt.md)
- [Development Loop](development-loop.md)
- [Enterprise Phase Discovery](enterprise-phase-discovery.md)
- [Quality Gates](quality-gates.md)
- [Phase Handover](phase-handover.md)