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, enterprise-phase-discovery.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 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 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 provides compact per-service state. 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 (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 for path resolution of the active service only.
4. Load Runtime Read Policy (this document).
5. Load Context Cache Policy.
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.
8. Read 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:

Always reload from disk (every new phase):

Document	Path
Project Status	project-status.yaml
Project Index	project-index.yaml
Service snapshot	From project-status / Project Index for active service only
Phase manifest	phase-manifest.yaml
Service manifest	service-manifest.yaml
Progress	progress.md
Next steps	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
Glossary	glossary.md
Docs index	docs/README.md
Definition of Done	definition-of-done.md
Quality gates	quality-gates.md
Development loop	development-loop.md
Enterprise Phase Discovery	enterprise-phase-discovery.md
Runtime Read Policy	runtime-read-policy.md
Context Cache Policy	context-cache-policy.md
Service Snapshot Policy	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.

READ ONCE PER SERVICE

Load once per service when entering that service’s work; cache per 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 below — never as bulk directory reads:

Area	Path
Architecture	docs/architecture/*
ADRs	docs/architecture/adr/*
Published Resource	published-resource-architecture.md, ADR-022, 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 when tenancy or DB-per-service is in scope; load testing-strategy.md when running the Testing stage; load 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 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 — required_docs, deliverables, or phase metadata for this phase ID.
4. Referenced by service-manifest.yaml — service entry, dependencies, or required docs for the owning service.
5. Referenced by project-status.yaml or 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 gate, boundary-rules.md, or a cited ADR during Architecture Validation.
8. Public-surface / publish integration design — load ADR-022 and 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, public-access-contract.md, and/or 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 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)
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, testing-template.md, api-template.md, etc.) when the active development-loop stage or quality gate requires them, not preemptively.

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 fallback rules.
• New services: add Project Index entry on registration; never discover by scanning.

Related Documents

• Project Status · project-status.md
• Project Index
• Service Snapshot Policy
• Context Cache Policy
• Master Prompt
• Development Loop
• Enterprise Phase Discovery
• Quality Gates
• Phase Handover