Add Anti-Cache Lying constraint and content-addressed storage implementation

[klappy]

Summary

This PR establishes a foundational constraint against TTL-based caching of derived or mutable content, documents a critical incident where OddKit violated this constraint, and provides an implementation plan to replace TTL caching with content-addressed storage.

Key Changes

• New Constraint: Anti-Cache Lying (odd/constraint/anti-cache-lying.md)

  • Establishes that derived/mutable content MUST NOT be cached with TTL-based expiration
  • Defines content-addressed storage (SHA-keyed) as the only acceptable caching strategy
  • Articulates the Total Cost of Ownership problem: caching optimizes for request latency while hiding debugging hours, staleness incidents, and trust erosion
  • Includes the OddKit stale-cache incident as a case study of the constraint violation

• Incident Documentation (docs/incidents/oddkit-stale-cache-2026-02.md)

  • Records that OddKit served stale canon documents for days without detection
  • Documents that the invalidate_cache flush mechanism was incomplete (only cleared .zip files)
  • Identifies violations of Axioms 1, 3, and 4 (Reality Is Sovereign, Integrity Is Non-Negotiable Efficiency, Verification Requires Observation)
  • Demonstrates the irony: the tool built to enforce epistemic discipline was itself asserting without verification

• Implementation Plan (docs/oddkit/IMPL-content-addressed-caching.md)

  • Specifies replacement of TTL-based caching with commit-SHA-keyed immutable storage
  • Redefines invalidate_cache as orphan cleanup (storage hygiene, not correctness)
  • Requires ALL cached artifacts to be SHA-keyed (not just .zip files)
  • Includes acceptance criteria and decision record comparing TTL vs. content-addressed approaches

• Decision Rule Addition (canon/constraints/decision-rules.md)

  • Adds Decision Rule Add Methods category and four canon constraints (C1-C4) #15: "Measure Total Cost Before Optimizing"
  • Requires TCO evidence before accepting caching or optimization claims
  • Names "Local Maxima Optimization (The Cache Trap)" as a documented anti-pattern
  • Cross-references the Anti-Cache Lying constraint

Notable Implementation Details

• The constraint is grounded in the foundational axioms (Reality Is Sovereign, Axiom 2 on debt, Integrity Is Non-Negotiable Efficiency)
• The incident serves as proof that the constraint was necessary — OddKit itself violated it
• The implementation plan is specific and measurable, with explicit non-goals to prevent workarounds
• The decision rule ties optimization decisions to evidence, preventing pre-optimization without measurement
• All three documents cross-reference each other, creating a coherent narrative from axiom → constraint → incident → implementation

https://claude.ai/code/session_018r5zV6zfjtH53A6ZdAQaqm

---

Note

Low Risk
Documentation-only additions/edits that don’t modify runtime code paths. Main risk is governance/process impact if teams treat the new caching constraint as universally applicable without nuance.

Overview
Introduces a new canonical constraint, odd/constraint/anti-cache-lying.md, that prohibits TTL-based caching for derived/mutable content and mandates content-addressed (e.g., commit-SHA) storage; it reframes cache invalidation as hygiene rather than a correctness mechanism.

Updates canon/constraints/decision-rules.md with a new Decision Rule #15 (Measure Total Cost Before Optimizing) and a related failure mode (Local Maxima Optimization / Cache Trap), explicitly requiring TCO evidence before accepting “it will be faster” optimizations.

Adds supporting documentation: an incident report on OddKit serving stale canon for days (docs/incidents/oddkit-stale-cache-2026-02.md) and an implementation instruction set to replace TTL caching with SHA-keyed immutable storage and rename/repurpose invalidate_cache into orphan cleanup (docs/oddkit/IMPL-content-addressed-caching.md).

^{Written by Cursor Bugbot for commit 46e1e27. This will update automatically on new commits. Configure here.}