diff --git a/.claude/instruction-history.json b/.claude/instruction-history.json index c81331df..65a93b05 100644 --- a/.claude/instruction-history.json +++ b/.claude/instruction-history.json @@ -2470,7 +2470,7 @@ "id": "inst_075", "text": "AFTER each response, check for current token count. IF token count > next_checkpoint value in .claude/token-checkpoints.json, MUST run: node scripts/check-token-checkpoint.js --tokens [current]/[budget]. This generates pressure report and marks checkpoint as completed. Checkpoints are at 25% (50k), 50% (100k), 75% (150k). Checking checkpoints is MANDATORY, not optional. Token budget awareness prevents context window exhaustion and maintains quality.", "timestamp": "2025-10-22T23:43:14.646Z", - "quadrant": "SYSTEM", + "quadrant": "rules", "persistence": "HIGH", "temporal_scope": "PERMANENT", "verification_required": "MANDATORY", @@ -2490,7 +2490,33 @@ "active": true, "notes": "Created in response to token checkpoint enforcement failure (session passed 96k tokens without reporting at 50k and 100k thresholds). Makes checkpoint monitoring architecturally enforced through HIGH persistence instruction. Prevents context window exhaustion and session quality degradation.", "created_date": "2025-10-23", - "incident_response": "token_checkpoint_enforcement_failure_2025_10_22" + "incident_response": "token_checkpoint_enforcement_failure_2025_10_22", + "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", + "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" + }, + "examples": [ + { + "scenario": "Modified submission-modal-enhanced.js", + "correct": "Edit file → Run update-cache-version.js → Commit all changes", + "incorrect": "Edit file → Commit only .js file → Deploy (USERS GET STALE CACHE)" + } + ], + "relatedInstructions": [ + "inst_038" + ], + "createdAt": "2025-10-23T20:39:40.016Z", + "createdBy": "cache-enforcement-setup", + "lastValidated": "2025-10-23T20:39:40.016Z" }, { "id": "inst_024_CONSOLIDATED", diff --git a/.claude/session-state.json b/.claude/session-state.json index f4a65b01..1518924e 100644 --- a/.claude/session-state.json +++ b/.claude/session-state.json @@ -43,13 +43,13 @@ "last_deliberation": null }, "FileEditHook": { - "timestamp": "2025-10-23T13:24:58.371Z", - "file": "/home/theflow/projects/tractatus/public/js/admin/blog-validation.js", + "timestamp": "2025-10-23T20:40:13.114Z", + "file": "/home/theflow/projects/tractatus/scripts/deploy-full-project-SAFE.sh", "result": "passed" }, "FileWriteHook": { - "timestamp": "2025-10-23T12:07:43.867Z", - "file": "/home/theflow/projects/tractatus/scripts/record-auto-compact.js", + "timestamp": "2025-10-23T20:41:13.338Z", + "file": "/home/theflow/projects/tractatus/CACHE_MANAGEMENT_ENFORCEMENT.md", "result": "passed" } }, @@ -58,25 +58,25 @@ "tokens": 30000 }, "alerts": [], - "last_updated": "2025-10-23T13:24:58.371Z", + "last_updated": "2025-10-23T20:41:13.338Z", "initialized": true, "framework_components": { "CrossReferenceValidator": { "message": 0, "tokens": 0, - "timestamp": "2025-10-23T19:47:26.784Z", - "last_validation": "2025-10-23T19:47:26.783Z", - "validations_performed": 592 + "timestamp": "2025-10-23T20:43:13.295Z", + "last_validation": "2025-10-23T20:43:13.294Z", + "validations_performed": 627 }, "BashCommandValidator": { "message": 0, "tokens": 0, "timestamp": null, - "last_validation": "2025-10-23T19:47:26.785Z", - "validations_performed": 292, + "last_validation": "2025-10-23T20:43:13.296Z", + "validations_performed": 301, "blocks_issued": 37 } }, - "action_count": 292, + "action_count": 301, "auto_compact_events": [] } \ No newline at end of file diff --git a/.claude/token-checkpoints.json b/.claude/token-checkpoints.json index 594012e4..3f83ba01 100644 --- a/.claude/token-checkpoints.json +++ b/.claude/token-checkpoints.json @@ -23,5 +23,5 @@ ], "next_checkpoint": 50000, "overdue": false, - "last_check": "2025-10-23T12:40:13.502Z" + "last_check": "2025-10-23T20:04:43.651Z" } \ No newline at end of file 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 - - - + + +