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](runtime-read-policy.md) and [service-snapshot-policy.md](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](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](project-index.yaml) |
| Phase manifest | [phase-manifest.yaml](phase-manifest.yaml) |
| Service manifest | [service-manifest.yaml](service-manifest.yaml) |
| Service snapshot | From Project Index `snapshot_file` for active service |
| Next steps | [next-steps.md](../next-steps.md) |
| Progress | [progress.md](../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](../README.md) |
| Module registry | [module-registry.md](../module-registry.md) |
| Glossary | [glossary.md](../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](master-prompt.md)
- [development-loop.md](development-loop.md)
- [enterprise-phase-discovery.md](enterprise-phase-discovery.md)
- [runtime-read-policy.md](runtime-read-policy.md)
- [context-cache-policy.md](context-cache-policy.md)
- [service-snapshot-policy.md](service-snapshot-policy.md)
- [definition-of-done.md](definition-of-done.md)
- [quality-gates.md](quality-gates.md)
- [mandatory-phase-artifacts.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](runtime-read-policy.md) execution entry — **Project Index first**.
2. **Always reload** the [Always reload](#always-reload-every-new-phase) 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](enterprise-phase-discovery.md) 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](project-index.yaml) | Single discovery entry — services, snapshots, roadmaps, handovers |
| [service-snapshot-policy.md](service-snapshot-policy.md) | Compact service state — always reload via index path |
| [runtime-read-policy.md](runtime-read-policy.md) | Tiers, triggers, NEVER AUTO READ — what may load |
| [context-cache-policy.md](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](project-index.yaml)
- [Service Snapshot Policy](service-snapshot-policy.md)
- [Runtime Read Policy](runtime-read-policy.md)
- [Master Prompt](master-prompt.md)
- [Development Loop](development-loop.md)
- [Enterprise Phase Discovery](enterprise-phase-discovery.md)
- [Quality Gates](quality-gates.md)