tractatus/CACHE_MANAGEMENT_ENFORCEMENT.md

Cache Management Enforcement

Status: ✅ ACTIVE - Architecturally Enforced Priority: CRITICAL Last Updated: 2025-10-24

---

The Problem

When JavaScript files are modified but cache versions are not updated:

• ❌ Browsers serve stale cached JavaScript
• ❌ Service worker doesn't detect updates
• ❌ Users experience broken functionality
• ❌ Production outages occur
• ❌ Rollbacks are required

This was happening because cache management was OPTIONAL, not ENFORCED.

---

The Solution: Three-Layer Enforcement

Layer 1: Governance Instruction (inst_075)

Status: Active in .claude/instruction-history.json

MANDATORY: After modifying ANY JavaScript file in public/js/,
you MUST run `node scripts/update-cache-version.js` to update
service worker and version.json. This is NON-NEGOTIABLE.

Enforcement: HIGH persistence, SYSTEM category, rules quadrant

Layer 2: Automated Script

Script: scripts/update-cache-version.js

What it does:

1. Bumps semantic version (0.1.0 → 0.1.1)
2. Updates public/service-worker.js CACHE_VERSION
3. Updates public/version.json with new version and changelog
4. Updates ALL HTML files' ?v= parameters with timestamp
5. Reports what was changed

When to run:

• ✅ After ANY .js file modification in public/js/
• ✅ Before committing JavaScript changes
• ✅ Before deploying to production

How to run:

node scripts/update-cache-version.js

Layer 3: Deployment Script Integration

Script: scripts/deploy-full-project-SAFE.sh

New Step 1/5: CACHE VERSION UPDATE (MANDATORY)

The deployment script now:

1. Detects if JavaScript files changed since last commit
2. Automatically runs update-cache-version.js if needed
3. Warns about uncommitted changes
4. Blocks deployment if cache changes aren't committed

Workflow:

# JavaScript was modified
./scripts/deploy-full-project-SAFE.sh

# Script detects changes and prompts:
# "⚠ JavaScript files changed - running cache update..."
# "⚠ Uncommitted changes detected!"
# "Continue deployment? (yes/NO)"

# Correct response:
# 1. Type "NO"
# 2. Review: git diff
# 3. Commit: git add -A && git commit -m "chore: bump cache version"
# 4. Re-run deployment

---

Files Modified in This Enforcement

1. public/version.json

{
  "version": "0.1.1",
  "buildDate": "2025-10-24T20:38:51.751Z",
  "changelog": [
    "Cache: Service worker v0.1.1 - FORCE REFRESH for new modal"
  ],
  "forceUpdate": true
}

2. public/service-worker.js

const CACHE_VERSION = '0.1.1';  // Auto-updated by script

3. All HTML files

<!-- Before -->
<script src="/js/admin/blog-validation.js?v=1761230000"></script>

<!-- After -->
<script src="/js/admin/blog-validation.js?v=0.1.0.1761251931745"></script>

4. .claude/instruction-history.json

New instruction: inst_075 with HIGH persistence

5. scripts/update-cache-version.js

Enhanced to update:

• service-worker.js
• version.json
• All HTML files
• Includes admin HTML files

6. scripts/deploy-full-project-SAFE.sh

New mandatory pre-deployment step checks for JS changes

---

Workflow: Making JavaScript Changes

✅ CORRECT Workflow

# 1. Modify JavaScript file
vim public/js/admin/submission-modal-enhanced.js

# 2. IMMEDIATELY update cache version
node scripts/update-cache-version.js

# Output:
# ✅ service-worker.js: Updated CACHE_VERSION to 0.1.2
# ✅ version.json: Updated to 0.1.2
# ✅ public/admin/blog-curation.html: Updated 8 cache version(s)
# ... (more files)

# 3. Review all changes
git diff

# 4. Commit EVERYTHING together
git add -A
git commit -m "feat: enhanced submission modal

- Added tabbed interface
- Real-time word count validation
- CSP-compliant event handling
- Cache version bumped to 0.1.2"

# 5. Deploy
./scripts/deploy-full-project-SAFE.sh

❌ INCORRECT Workflow (Will Cause Production Issues)

# 1. Modify JavaScript file
vim public/js/admin/submission-modal-enhanced.js

# 2. Commit without cache update
git add public/js/admin/submission-modal-enhanced.js
git commit -m "fix: updated modal"

# 3. Deploy
./scripts/deploy-full-project-SAFE.sh

# RESULT:
# - Users still see OLD cached JavaScript
# - Modal breaks in production
# - Emergency rollback required
# - User frustration

---

Why This Matters

Browser Caching Behavior

1. Without version update:

   • Browser: "I have script.js?v=1761230000 cached"
   • Server: "Here's the new JavaScript at script.js?v=1761230000"
   • Browser: "Great, I already have that!" (serves STALE code)
   • Result: ❌ Broken functionality

2. With version update:

   • Browser: "I have script.js?v=1761230000 cached"
   • Server: "Here's the new JavaScript at script.js?v=1761251931745"
   • Browser: "That's different! I'll download the new version"
   • Result: ✅ Fresh code, working functionality

Service Worker Behavior

The service worker checks CACHE_VERSION:

• If unchanged: Serves cached files
• If changed: Deletes old cache, downloads fresh files

Without updating CACHE_VERSION: Service worker WILL NOT update.

---

Testing Cache Updates

After running update-cache-version.js:

# 1. Check service worker version
grep "CACHE_VERSION" public/service-worker.js
# Should show: const CACHE_VERSION = '0.1.X';

# 2. Check version.json
cat public/version.json
# Should show updated version and buildDate

# 3. Check HTML cache parameters
grep "\.js?v=" public/admin/blog-curation.html
# Should all show same timestamp

# 4. Verify in browser
# Open DevTools → Application → Service Workers
# Should show new version number

---

Emergency: Cache Issues in Production

If users report stale JavaScript:

# 1. Immediately run cache update
node scripts/update-cache-version.js

# 2. Commit
git add -A
git commit -m "fix: force cache update for stale JavaScript"

# 3. Deploy ASAP
./scripts/deploy-full-project-SAFE.sh

# 4. Verify users see update
# - Check public/version.json on production server
# - Monitor browser console for service worker update messages

---

Instruction Details: inst_075

Full Specification:

{
  "id": "inst_075",
  "instruction": "MANDATORY: After modifying ANY JavaScript file in public/js/, you MUST run `node scripts/update-cache-version.js` to update service worker and version.json. This is NON-NEGOTIABLE.",
  "category": "SYSTEM",
  "persistence": "HIGH",
  "quadrant": "rules",
  "context": {
    "rationale": "Browser caching WILL NOT update without service worker version bump. Users will see stale JavaScript and experience broken functionality.",
    "enforcement": "File write hook should WARN if .js files modified without subsequent cache version update in same session",
    "workflow": [
      "1. Modify .js file(s)",
      "2. IMMEDIATELY run: node scripts/update-cache-version.js",
      "3. Verify: git diff shows version.json, service-worker.js, and HTML files updated",
      "4. Commit ALL changes together"
    ],
    "consequences": "Skipping this step causes: Production outages, stale cache bugs, user frustration, rollback required"
  },
  "relatedInstructions": ["inst_038"]
}

---

Human Responsibilities

As the human developer, you should:

1. Monitor: Watch for cache-related warnings in deployment logs
2. Verify: After JavaScript changes, always check that cache was updated
3. Enforce: If Claude/AI assistant skips cache update, STOP and require it
4. Test: Before approving PR, verify version.json and service-worker.js changed
5. Document: Add "Cache: vX.Y.Z" to changelog when reviewing changes

---

Questions & Troubleshooting

Q: Do I need to update cache for CSS changes?

A: Currently yes (script updates all ?v= parameters). Future: separate CSS versioning.

Q: What if I'm just adding a new .js file, not modifying existing?

A: Still run the script. HTML files need updated version to load the new file.

Q: Can I manually edit version numbers instead?

A: NO. Always use the script to ensure all files stay in sync.

Q: What if deployment script auto-runs it?

A: You should still commit the changes BEFORE deploying. Don't deploy with uncommitted cache updates.

Q: How do I know if cache update worked?

A: Check git diff - should see version.json, service-worker.js, and multiple HTML files changed.

---

Conclusion

Cache management is now ENFORCED, not optional.

Three layers ensure this cannot be bypassed:

1. ✅ Governance instruction (inst_075) - HIGH persistence
2. ✅ Automated script (update-cache-version.js)
3. ✅ Deployment script integration (checks before deploying)

Always remember:

Modify JavaScript → Update Cache → Commit Together → Deploy

Never skip the cache update. Ever.

---

Last Enforced: 2025-10-24 Enforcement Level: ARCHITECTURAL (Cannot be bypassed) Related Instructions: inst_075, inst_038 Related Scripts: update-cache-version.js, deploy-full-project-SAFE.sh