02 — zero-cost-freshness-gate
Goal
Build the zero-cost freshness primitive: an O(1)-when-fresh check keyed on per-file CONTENT HASH, NOT git. Reuse the embedding pipeline’s embedding_content_hash precedent — a per-file content-hash manifest recorded at index time. Fresh iff every in-scope file’s current content hash matches the stored hash; a file is drift ONLY until re-indexed (self-clearing), so a dirty / uncommitted working tree is never sticky-stale.
Implementation Sketch
Add ensure_fresh.py (intel_repo) owning: (1) read the stored per-file content-hash manifest the sync wrote; (2) cheap mtime pre-filter to pick candidate files (skip unchanged-mtime files); (3) content-hash the candidates and compare to the stored hash — all match -> FRESH (return immediately, zero re-index); (4) else return ONLY the files whose hash diverged as the re-index delta. No git rev-parse, no git diff, no commit-SHA — the signal is content, never VCS state. Indexes current on-disk content (uncommitted included); drift self-clears the moment a file is re-indexed.
Spec References
intel_repo/neo4j/enrich_embeddings.py (embedding_content_hash: SHA over canonicalized text + skip-on-match — the content-hash freshness precedent this section generalizes); :Symbol.content_hash property; intel_repo/CLAUDE.md §Embedding (deterministic content-hash + skip-on-match). This section REPLACES the git/SHA-relative gate signal with content-hash; staleness.py (_cpg_stale_via_changed_files) stays for status display only, not the serve-path gate.
Work Items
-
ensure_fresh.py: per-file content-hash fast path (mtime pre-filter + hash confirm); no Neo4j AND no git when fresh - Re-index delta = ONLY files whose content hash diverged from the stored manifest (self-clearing)
- Per-file content-hash manifest written by the sync on success (reuse
embedding_content_hashpattern); NO cached-HEAD / git marker - Test: unchanged content -> FRESH + zero re-index EVEN with a dirty/uncommitted tree; changed content -> exactly that file in the delta