diff --git a/CACHE_MANAGEMENT_ENFORCEMENT.md b/CACHE_MANAGEMENT_ENFORCEMENT.md new file mode 100644 index 00000000..0b3496ca --- /dev/null +++ b/CACHE_MANAGEMENT_ENFORCEMENT.md @@ -0,0 +1,336 @@ +# 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**: +```bash +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**: +```bash +# 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` +```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` +```javascript +const CACHE_VERSION = '0.1.1'; // Auto-updated by script +``` + +### 3. All HTML files +```html + + + + + +``` + +### 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 + +```bash +# 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) + +```bash +# 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: + +```bash +# 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: + +```bash +# 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**: + +```json +{ + "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 diff --git a/public/about.html b/public/about.html index 29477824..52eee20e 100644 --- a/public/about.html +++ b/public/about.html @@ -5,9 +5,9 @@ About | Tractatus AI Safety Framework - - - + + +