7.3 KiB
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. docs/project-status.yaml is always reloaded first, then project-index.yaml — never scan folders to resolve paths.
Goals
- Prevent re-reading unchanged documentation between phases.
- Keep phase entry context fresh where milestones and manifests change every phase.
- 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 Status | project-status.yaml |
| Project Index | project-index.yaml |
| Phase manifest | phase-manifest.yaml |
| Service manifest | service-manifest.yaml |
| Service snapshot | From project-status / Project Index for active service |
| Next steps | next-steps.md |
| Progress | progress.md |
| Latest phase handover | From project-status / Project Index 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
- Follow runtime-read-policy.md execution entry — Project Status first, then Project Index.
- Always reload the Always reload set.
- Apply read policy to determine additional in-scope paths (never folder scans; never unrelated services when project-status exists).
- For each in-scope path not in Always reload: check cache → reload only if changed.
- Run Enterprise Phase Discovery from project-status + index + snapshot + reloaded inputs.
- After phase completion: update Project Status; 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 Status; update Project Index; regenerate snapshot; invalidate progress, next-steps, manifests, handover |
| New service registered | Add Project Status row; 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 | Path resolver for active service (after Project Status) |
| service-snapshot-policy.md | Compact service state — always reload via status/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 |
| project-status.yaml | Platform execution dashboard — always reload first |
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/anddocs/service-snapshots/remain canonical.