TorbatYar/docs/phase-handover/phase-af-context-cache-policy.md

# Phase Handover — AF-Context-Cache-Policy (Incremental Context Loading)

| Field | Value |
| --- | --- |
| Phase ID | `ai-framework-context-cache-policy` |
| Title | Context Cache Policy — Incremental Context Loading |
| Status | Complete |
| Service(s) | N/A (documentation / process only) |
| Version | Framework context-cache-1.0 |
| Date | 2026-07-26 |
| ADR(s) | Extends [ADR-018](../architecture/adr/ADR-018.md), [ADR-019](../architecture/adr/ADR-019.md) (process; no new ADR) |

## Business Analysis Summary

| Item | Detail |
| --- | --- |
| Capabilities delivered | Incremental Context Loading via context cache; prevents re-reading unchanged docs between phases while keeping manifests and milestone docs fresh |
| Explicit non-goals honored | No business service changes; no completed business phase retrofits; no relocation of `docs/ai-framework/` |

## Enterprise Phase Discovery Summary (this docs phase)

| Item | Detail |
| --- | --- |
| Discovery Record location | This handover + [context-cache-policy.md](../ai-framework/context-cache-policy.md) |
| Gaps promoted & closed | Unconditional re-reads between phases → cache-eligible vs always-reload split |
| Exclusions | All business phases and services |
| CRUD-only rejected | N/A (process rule) |

## Enhancement Catalog

### New normative document

| Document | Purpose |
| --- | --- |
| [context-cache-policy.md](../ai-framework/context-cache-policy.md) | Cache model, always-reload set, cache-eligible set, framework doc reuse, invalidation, phase entry procedure |

### Core execution upgrades

| Document | Enhancement |
| --- | --- |
| [runtime-read-policy.md](../ai-framework/runtime-read-policy.md) | ALWAYS READ split into always-reload vs cache-eligible; READ ONCE PER SERVICE includes service README; architecture/ADR caching |
| [master-prompt.md](../ai-framework/master-prompt.md) | Document loading references cache policy; AI rules use incremental loading |
| [development-loop.md](../ai-framework/development-loop.md) | Stage 1 cache-aware loading; Documentation Update invalidates changed cache entries |
| [enterprise-phase-discovery.md](../ai-framework/enterprise-phase-discovery.md) | Discovery load step uses cache policy; inputs synthesized from reloaded + cached docs |

## Reusable Components

| Component | Location | Reuse notes |
| --- | --- | --- |
| Context Cache Policy | `docs/ai-framework/context-cache-policy.md` | Every future phase in same workstream |
| Always reload set | Same | Manifests, progress, next-steps, current handover |
| Cache-eligible set | Same + runtime-read-policy | README, registries, glossary, roadmap, architecture/ADR refs, service README, completed handovers, framework docs |

## Public APIs

N/A — documentation/process only.

## Events

N/A.

## Permissions

N/A.

## Extension Points

| Extension point | How to extend | Forbidden uses |
| --- | --- | --- |
| New always-reload doc | Add to context-cache-policy + runtime-read-policy always-reload table | Skipping required synthesis because doc is cached |
| New cache-eligible category | Add to cache-eligible table with invalidation rules | Full cache flush every phase |

## Known Limitations

- Cache is an agent-session optimization; change detection depends on mtime/hash/git diff when available.
- Does not retrofit completed business phase prompts.
- Active current handover always reloads; completed handovers are cache-eligible.

## Migration Notes

| Item | Detail |
| --- | --- |
| Alembic revision(s) | N/A |
| Upgrade steps | On next phase entry: always reload manifests/progress/next-steps/current handover; reuse unchanged cached docs |
| Breaking changes | None for runtime; reduced doc fan-out between phases |

## Dependencies

| Dependency | Type | Required for |
| --- | --- | --- |
| AF-Runtime-Read-Policy | Docs | Tiered loading baseline |
| AF-Discovery / ADR-019 | Docs | Enterprise Phase Discovery |
| AF-Enterprise / ADR-018 | Docs | Enterprise framework baseline |

## Boundary Compliance

- [x] No foreign service ownership implemented
- [x] No business logic duplication
- [x] No cross-DB access
- [x] No future-phase business functionality pulled forward
- [x] No business service code modified

## Enterprise Completeness Sign-Off

- [x] Discovery completeness (cache-aware Discovery load)
- [x] Business completeness (framework process)
- [x] Documentation completeness
- [x] Self Audit

## Definition of Done

- [x] context-cache-policy.md published
- [x] master-prompt.md, development-loop.md, enterprise-phase-discovery.md, runtime-read-policy.md updated
- [x] Framework handover complete
- [x] No business code changes

## Next Phase Entry

1. [context-cache-policy.md](../ai-framework/context-cache-policy.md) — phase entry procedure
2. [runtime-read-policy.md](../ai-framework/runtime-read-policy.md) — what may load
3. Always reload: phase-manifest.yaml, service-manifest.yaml, next-steps.md, progress.md, current phase handover
4. Resume business milestones per [next-steps.md](../next-steps.md) when explicitly requested

| Field | Value |
| --- | --- |
| Recommended next phase | Per [next-steps.md](../next-steps.md) (business track) — not started by this phase |
| Blockers for next phase | None from this upgrade |
| Entry checklist | Always reload set → cache check remaining in-scope docs → Discovery → implement promoted gaps only |

## Completion Sign-Off

- [x] Context Cache Policy integrated into framework
- [x] Incremental Context Loading defined
- [x] Framework handover complete
- [x] No TODO for claimed deliverables
- [x] No business service modifications

## Related Documents

- [Context Cache Policy](../ai-framework/context-cache-policy.md)
- [Runtime Read Policy](../ai-framework/runtime-read-policy.md)
- [Master Prompt](../ai-framework/master-prompt.md)
- [Development Loop](../ai-framework/development-loop.md)
- [Enterprise Phase Discovery](../ai-framework/enterprise-phase-discovery.md)
- [Phase Handover AF-Runtime-Read-Policy](phase-af-runtime-read-policy.md)
- [Phase Handover AF-Discovery](phase-af-discovery.md)