TorbatYar/docs/ai-framework/context-cache-policy.md

Context Cache Policy

Incremental Context Loading for TorbatYar AI-assisted phases.

Works with runtime-read-policy.md and service-snapshot-policy.md. The read policy decides which documents may load; this policy decides whether to re-read a document or reuse cached context. project-index.yaml is always reloaded first — never scan folders to resolve paths.

Goals

1. Prevent re-reading unchanged documentation between phases.
2. Keep phase entry context fresh where milestones and manifests change every phase.
3. Never skip loading a document the read policy requires — cache reuse applies only when content is unchanged.

Cache model

Maintain a session context cache keyed by file path (or stable doc ID). For each cached entry store at minimum:

Field	Purpose
Path	Canonical doc path
Content hash or mtime	Change detection
Loaded at	Last full read timestamp
Phase ID	Phase that last verified the entry

Between phases in the same agent track (same service or framework workstream), prefer cache hits over disk reads.

Always reload (every new phase)

These files MUST be read from disk at the start of every phase — never served from cache without a fresh read:

Document	Path
Project Index	project-index.yaml
Phase manifest	phase-manifest.yaml
Service manifest	service-manifest.yaml
Service snapshot	From Project Index snapshot_file for active service
Next steps	next-steps.md
Progress	progress.md
Latest phase handover	From Project Index latest_handover for active service

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

Cache-eligible (reload only if changed)

On phase entry, load these only when the file changed since last cache entry (hash/mtime/git diff) or the cache has no entry:

Category	Paths
Docs index	docs/README.md
Module registry	module-registry.md
Glossary	glossary.md
Roadmap	From Project Index roadmap_file for active service
Architecture references	Individual files under docs/architecture/* already loaded
ADR references	Individual files under docs/architecture/adr/* already loaded
Service README	backend/services/<name>/README.md for the owning service
Completed handovers (superseded)	Older Complete handovers when snapshot + latest handover suffice
Framework documents	All normative docs under docs/ai-framework/ except manifests listed in Always reload
Reference / development / deployment	Individual triggered files under docs/reference/*, docs/development/*, docs/deployment/*

If unchanged: reuse cached content — do not re-read.

Never re-read unchanged framework documents

After the first load in a workstream, treat unchanged framework docs as cache hits, including:

• master-prompt.md
• development-loop.md
• enterprise-phase-discovery.md
• runtime-read-policy.md
• context-cache-policy.md
• service-snapshot-policy.md
• definition-of-done.md
• quality-gates.md
• mandatory-phase-artifacts.md
• Templates and companions loaded per read-policy triggers

Exception: If a framework doc was edited during the current or prior phase (handover notes a framework upgrade, or mtime/hash changed), invalidate cache and reload that file only.

Phase entry procedure

1. Follow runtime-read-policy.md execution entry — Project Index first.
2. Always reload the Always reload set.
3. Apply read policy to determine additional in-scope paths (never folder scans).
4. For each in-scope path not in Always reload: check cache → reload only if changed.
5. Run Enterprise Phase Discovery from index + snapshot + reloaded inputs.
6. After phase completion: update Project Index; regenerate snapshot; invalidate cache for modified docs.

Cache invalidation

Invalidate (force reload on next access) when:

Event	Action
Phase completes	Update Project Index; regenerate snapshot; invalidate progress, next-steps, manifests, handover
New service registered	Add Project Index entry; add service-manifest entry
Doc edited in phase	Invalidate that path
Framework upgrade phase	Invalidate changed framework docs only
New ADR accepted	Invalidate that ADR path and any dependent cached architecture refs
Service switch	Clear service-scoped cache (roadmap, service README, service handovers); retain platform/framework cache if unchanged

Do not invalidate the full cache on every phase — only changed paths and always-reload set.

Relationship to Runtime Read Policy

Policy	Responsibility
project-index.yaml	Single discovery entry — services, snapshots, roadmaps, handovers
service-snapshot-policy.md	Compact service state — always reload via index path
runtime-read-policy.md	Tiers, triggers, NEVER AUTO READ — what may load
context-cache-policy.md	Incremental loading — whether to re-read or reuse

Read policy ALWAYS READ tier splits as:

• Always reload every phase: manifests, progress, next-steps, current phase handover
• Cache-eligible after first load: module-registry, glossary, framework docs, and other stable entries per tables above

READ ONCE PER SERVICE aligns with cache: first read populates cache; subsequent phases reuse until changed.

READ ONLY IF REFERENCED: load on first trigger; cache thereafter until changed.

Backward compatibility

• Completed business phases unchanged.
• Agents without explicit cache state should still follow read policy; cache is an optimization, not a skip of required synthesis.
• Discovery remains mandatory — snapshot + cached docs count as reviewed inputs when unchanged.
• Path docs/ai-framework/ and docs/service-snapshots/ remain canonical.

Related Documents

• Project Index
• Service Snapshot Policy
• Runtime Read Policy
• Master Prompt
• Development Loop
• Enterprise Phase Discovery
• Quality Gates