Add "lessons/patterns/plugin-version-mismatch-causes-silent-load-failure"

lessons%2Fpatterns%2Fplugin-version-mismatch-causes-silent-load-failure.-.md

@@ -0,0 +1,109 @@
+# Plugin Version Mismatch Causes Silent Load Failure
+
+## Context
+- **Date:** 2026-02-02
+- **Time Wasted:** 5+ hours debugging across 3 devices
+- **Severity:** CRITICAL - plugins fail silently with NO error message
+- **Impact:** User sees "failed to load · 1 error" but NO details
+
+## Problem
+
+Plugins failed to load with this unhelpful message:
+```
+contract-validator Plugin · leo-claude-mktplace · ✘ failed to load · 1 error
+```
+
+**Claude Code provides NO error details.** The user has to guess what's wrong.
+
+## Root Cause
+
+**Version mismatch between marketplace.json and plugin.json:**
+
+| Plugin | marketplace.json | plugin.json | Status |
+|--------|-----------------|-------------|--------|
+| contract-validator | 1.2.0 | 1.1.0 | FAILED |
+| git-flow | 1.2.0 | 1.0.0 | FAILED |
+| projman | 3.4.0 | 3.3.0 | FAILED |
+| clarity-assist | 1.2.0 | 1.0.0 | FAILED |
+| doc-guardian | 1.1.0 | 1.0.0 | FAILED |
+
+When Claude Code loads a plugin, it checks the version in marketplace.json and expects the same version in plugin.json. If they don't match, it **silently fails**.
+
+## How This Happened
+
+1. Version was bumped in marketplace.json during releases
+2. Individual plugin.json files were NOT updated
+3. No validation caught the mismatch
+4. Claude Code loaded plugins but failed silently
+
+## Solution
+
+1. Fix all version mismatches:
+```bash
+# Check mismatches
+python3 << 'EOF'
+import json, os
+with open('.claude-plugin/marketplace.json') as f:
+    mkt = json.load(f)
+mkt_ver = {p['name']: p['version'] for p in mkt['plugins']}
+for p in os.listdir('plugins'):
+    if os.path.exists(f'plugins/{p}/.claude-plugin/plugin.json'):
+        with open(f'plugins/{p}/.claude-plugin/plugin.json') as f:
+            pv = json.load(f)['version']
+        if mkt_ver.get(p) != pv:
+            print(f"MISMATCH: {p} mkt={mkt_ver[p]} plugin={pv}")
+EOF
+```
+
+2. Clear corrupted cache:
+```bash
+rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/{plugin-name}/
+```
+
+3. Restart Claude Code
+
+## Prevention
+
+### 1. Add Version Sync Validation to Pre-Commit Hook
+
+Add to `scripts/validate-marketplace.sh`:
+```bash
+# Validate version consistency
+for plugin in plugins/*/; do
+    name=$(basename "$plugin")
+    mkt_ver=$(grep -A1 "\"$name\"" .claude-plugin/marketplace.json | grep version | grep -oE '[0-9.]+')
+    plugin_ver=$(grep version "$plugin/.claude-plugin/plugin.json" | grep -oE '[0-9.]+')
+    if [[ "$mkt_ver" != "$plugin_ver" ]]; then
+        echo "ERROR: Version mismatch for $name"
+        exit 1
+    fi
+done
+```
+
+### 2. Single Version Source
+
+Consider using a script to update ALL version locations atomically.
+
+### 3. Release Checklist
+
+- [ ] Update marketplace.json version
+- [ ] Update plugin.json version (MUST MATCH)
+- [ ] Run version consistency check
+- [ ] Clear plugin cache after update
+
+## Warning Signs
+
+If you see this, check version consistency:
+- "✘ failed to load · 1 error" with no details
+- Plugin worked before, suddenly doesn't
+- After version bump, plugins stop loading
+
+## Related Issues
+
+- Claude Code provides no error details for plugin load failures
+- Cache can hold stale/orphaned versions
+- No built-in version consistency validation
+
+
+---
+**Tags:** version, plugin, silent-failure, cache, critical, marketplace, debugging