Cache Policy — 4-Layer Hierarchy¶
Last Updated: 2026-07-11 Version: v0.2.0
**Last Updated: 2026-06-22
Owner:
cache-management-agent(canonical) — supportingworkflow-optimization-agent. Status: Specification (Phase 5; YAML rollout in Phase 5b). Branch authored:copilot/analyze-test-coverage-and-documentationADA citation: ../../.codex/CODEBASE_AGENCY_POLICY.md
Why¶
User directive: "we must improve workflow functions where we do not want to continue scans on files that have been retouched by more recent commits… save on bandwidth and leverage cache" (recorded in repository memory workflow optimization). The current estate includes 285 workflow files under .github/workflows/ (active workflows plus dispatch-only stubs) and can run duplicate scans on superseded SHAs, wasting CI minutes and Actions cache quota.
The four layers¶
| Layer | Scope | Cache key | Expected retention* | Owner agent |
|---|---|---|---|---|
| L1: Toolchain | Python interpreters, ruff, mypy, pre-commit binaries, actionlint | runner.os + py-version + pyproject.toml hash |
30 d | cache-management-agent |
| L2: Dependencies | pip/uv site-packages, npm node_modules, Cargo target/ (rlib only) |
runner.os + requirements*.txt + uv.lock + package-lock.json + Cargo.lock hash |
14 d | cache-management-agent |
| L3: Tool-state | .mypy_cache/, .ruff_cache/, .pytest_cache/, .hypothesis/ |
runner.os + branch + paths-changed-since-base |
7 d | cache-management-agent |
| L4: Data/models | DVC remote, HuggingFace model cache, datasets | dvc.lock hash + models/manifest.json hash |
30 d | cache-management-agent + DVC |
GitHub Actions cache eviction is GitHub-managed (typically inactivity-based). Values above are target retention windows, not guaranteed TTLs.
Skip-rescan policy¶
Every scanning workflow (lint, security, coverage, doc-link-check, markdown-link-check, mypy) must:
- Declare
concurrencywithgroup: ${{ github.workflow }}-${{ github.ref }}andcancel-in-progress: truefor PR events. - Use a paths-filter step (e.g.
dorny/paths-filter@v3ortj-actions/changed-files@v45) to short-circuit when the changed file set contains zero files in the workflow's scope. - On
pushto a superseded SHA (same ref, newer SHA exists): cancel via the concurrency group — no manual diff needed. - Never key caches on
${{ github.sha }}directly; always on lockfile hashes plus a workflow-version segment (v1,v2, …) bumped only when the workflow's input contract changes.
Workflow Execution Gate (single entry point)¶
To cut duplicate fan-out, a single front-gate workflow (workflow-execution-gate.yml, already present) must:
- Resolve the changed-files set once (cached as an artifact).
- Pre-check
workflow-compliance-guardian(concurrency + timeout rules) andci-pattern-guardian(forbid known anti-patterns). - Emit per-workflow
should-run: true|falseoutputs; downstream workflows read this output instead of re-computing.
Verification¶
actionlintafter each workflow YAML edit.- A scheduled
cache-management-agentjob audits hit/miss rates weekly and reports todocs/workflows/MONITORING_LOG.md.
Phase 5b rollout sequence (deferred to follow-up PR)¶
- Add
concurrency+cancel-in-progressto the 70+ workflows that lack it. - Add
paths-filterto lint/security/doc/coverage workflows. - Migrate cache keys to lockfile-hash + version segment.
- Wire downstream workflows to read
workflow-execution-gate.ymloutputs. - Bump cache-key version segment when contract changes (no purge needed; old keys are evicted by GitHub cache policy over time).
This file is the contract; the YAML diff lands in Phase 5b under workflow-management-agent.