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**:
```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
<!-- 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

```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