Intelligence Cache Invalidation and Refresh Policy

[github-actions]

Strategic Improvement

Intelligence cache exists but has no invalidation policy beyond TTL. Stale cache = bad decisions = wasted cost. Build smart invalidation: when hotspot files change, when test coverage shifts, when architecture.json updates. Add selective refresh (don't recompute everything, just affected sections). Improves cost efficiency and decision quality.

Acceptance Criteria

• Add cache fingerprinting: hash of git HEAD, test coverage %, architecture.json mtime
• Implement sw-intelligence.sh check-cache that compares fingerprints and invalidates on mismatch
• Add selective refresh: if only test coverage changed, refresh only coverage section
• Log cache hit/miss/invalidation rates to cost tracking
• Measure: cache invalidation accuracy (% of invalidations that led to different recommendations)

Context

• Priority: P3
• Complexity: fast
• Generated by: Strategic Intelligence Agent
• Strategy alignment: P3: Cost Efficiency

[github-actions]

⚓ Shipwright Pipeline Starting

Field	Value
Template	standard
Complexity	standard
Max Iterations	20
Triage	Well-scoped intelligence cache improvement with clear acceptance criteria; adds fingerprinting and selective refresh to reduce stale decisions and cost waste; moderate complexity in selective invalidation logic, touches 2-3 files.
Runner	ubuntu-latest
Risk Level	unknown
Workflow	25289732111

The autonomous pipeline is processing this issue. Updates will be posted as stages complete.

[github-actions]

[github-actions]

[github-actions]

📋 Implementation Plan

Click to expand full plan (233 lines)

Implementation Plan: Intelligence Cache Invalidation and Refresh Policy

Goal Summary

Augment sw-intelligence.sh's existing TTL-based cache with fingerprint-based invalidation and selective section refresh. Stale entries are evicted when underlying inputs change (git HEAD, test coverage %, architecture.json mtime). Track invalidation accuracy as a new cost-tracking metric.

Files to Modify

File	Action	Purpose
scripts/sw-intelligence.sh	modify	Fingerprint helpers, check-cache subcommand, selective refresh, telemetry
scripts/sw-intelligence-test.sh	modify	New unit tests for fingerprint, invalidation, selective refresh
scripts/sw-cost.sh	modify (small)	Surface cache hit/invalidation rates from cache-events.jsonl
.claude/CLAUDE.md	modify	Document check-cache subcommand under Intelligence Layer

No new files. Changes are localized to existing intelligence module.

Cache Schema Extension (backwards-compatible)

Current entry shape (preserved):

{ "result": ..., "timestamp": 1775336504, "ttl": 1800 }

New optional fields:

{
  "result": ...,
  "timestamp": 1775336504,
  "ttl": 1800,
  "fingerprint": {
    "git_head": "57195d5",
    "coverage_pct": 78,
    "arch_mtime": 1775332100
  },
  "section": "analysis"
}

Sections: analysis, coverage, architecture, composition, prediction.

New top-level cache_meta counter:

{ "entries": {...}, "cache_meta": { "hits": 0, "misses": 0, "invalidations": 0 } }

Legacy entries lacking fingerprint are treated as a one-time miss (lazy migration), then re-populated with the new shape.

Implementation Steps

✅ Task Checklist

• Write 12 unit tests in sw-intelligence-test.sh (RED)
• Add fingerprint helpers (_intelligence_fp_git_head, _fp_coverage, _fp_arch_mtime, _compute_fingerprint)
• Add _intelligence_section_deps dependency map
• Extend _intelligence_cache_get with fingerprint comparison + counter
• Extend _intelligence_cache_set to persist fingerprint and section
• Plumb section parameter through _intelligence_call_claude and 6 call sites
• Implement cmd_check_cache with --evict and --section flags
• Register check-cache in CLI dispatch and show_help
• Append cache events to ~/.shipwright/cache-events.jsonl
• Implement invalidation-accuracy ring buffer + metric in cmd_cache_stats
• Add intelligence.fingerprint_enabled feature flag
• Update sw-cost.sh daily roll-up to surface hit/invalidation rates
• Update .claude/CLAUDE.md Intelligence Layer section
• Bump VERSION; run shipwright version check
• Run npm test — full suite must pass
• All 5 acceptance criteria from the issue met (fingerprint, check-cache, selective refresh, hit/miss/invalidation logging, accuracy metric)
• npm test green (102 suites)
• No regression in existing sw-intelligence-test.sh
• shipwright version check passes
• shipwright docs check passes (CLAUDE.md AUTO sections still in sync)

---

Generated by shipwright pipeline at 2026-05-03T20:27:48Z

[github-actions]

[github-actions]

[github-actions]

📐 Architecture Decision Record

Click to expand ADR (226 lines)

Design: Intelligence Cache Invalidation and Refresh Policy

Context

scripts/sw-intelligence.sh caches Claude analysis results in .claude/intelligence-cache.json with TTL-only invalidation (30 min – 1 h, adaptively tuned). TTL alone produces two failure modes:

1. Stale-but-fresh: an entry within TTL is served even though git HEAD, test coverage, or architecture.json have changed — downstream pipeline composition decisions made on outdated context.
2. Fresh-but-wasteful: TTL expires forcing re-analysis even when no underlying input has changed.

Constraints:

• Bash 3.2 (no declare -A, readarray, ${var,,})
• Concurrent daemon workers write the same cache file — atomic writes (tmp+mv) and serialization required
• Backwards compatibility: existing intelligence-cache.json entries (~10 in .claude/intelligence-cache.json) must not crash a new binary, and old binaries must tolerate new fields
• set -euo pipefail — fingerprint helpers must never abort the caller
• Cost discipline: over-invalidation increases Claude calls; under-invalidation degrades decisions

Decision

Layer fingerprint-based invalidation on top of the existing TTL check inside _intelligence_cache_get/_intelligence_cache_set. Each cache entry is tagged with (a) a section label and (b) a fingerprint of the inputs that section depends on. A new check-cache subcommand walks the cache, recomputes fingerprints, and reports/evicts stale entries. Telemetry flows through an append-only ~/.shipwright/cache-events.jsonl and is rolled up by sw-cost.sh.

Section → dependency map (deliberately narrow to avoid cascading invalidation):

Section	git_head	coverage_pct	arch_mtime
analysis	✓	✓	✓
coverage		✓
architecture			✓
composition	✓		✓
prediction	✓	✓

Data flow on _intelligence_cache_get(key, section):

read entry → TTL check (existing) → fp_stored = entry.fingerprint
  → fp_now = compute(section_deps[section])
  → compare only keys in section_deps
  → mismatch ⇒ emit invalidation event, miss
  → match    ⇒ emit hit event, return cached

Failure containment: every fingerprint helper wraps its command in || true and falls back to a sentinel (unknown / -1 / 0). A sentinel is a deterministic fingerprint, so cache treats it as "stable but unknown" — degraded correctness, never a pipefail abort.

Concurrency: existing tmp+mv pattern preserved for _cache_set. cmd_check_cache --evict takes a flock-with-mkdir-fallback on $INTELLIGENCE_CACHE.lock so check-then-rewrite is serialized. Single-line JSONL appends to cache-events.jsonl rely on POSIX O_APPEND ≤ PIPE_BUF atomicity.

Kill switch: intelligence.fingerprint_enabled (default true). When false, code path collapses to today's TTL-only behavior — no redeploy needed.

Accuracy metric: on each invalidation, store md5 of prior result; on next repopulation, compute new md5; ratio of different mds → "did invalidation matter?" Surfaced in cache-stats and cost show.

Component Diagram

┌──────────────────────────────────────────────────────────┐
│ sw-intelligence.sh (orchestrator)                        │
│                                                          │
│  ┌─────────────────────┐    ┌────────────────────────┐   │
│  │ Fingerprint Module  │───▶│ Cache I/O Module       │   │
│  │  _fp_git_head       │    │  _cache_get / _set     │   │
│  │  _fp_coverage       │    │  (atomic tmp+mv,flock) │   │
│  │  _fp_arch_mtime     │    └──────────┬─────────────┘   │
│  │  _section_deps      │               │                 │
│  └─────────────────────┘               ▼                 │

</details>

---
_Generated by `shipwright pipeline` design stage at 2026-05-03T20:30:28Z_

[github-actions]

[github-actions]

🔨 Build started — shipwright loop with 20 max iterations, 1 agent(s), model: opus

[github-actions]

❌ Pipeline failed at stage build after 4m 11s.

No log available

[github-actions]