2026-02-04 00:59:04 +00:00
11 changed files with 241 additions and 228 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -40,8 +40,76 @@ Run `./scripts/verify-hooks.sh`. If changes affect MCP servers or hooks, inform

 **Valid hook events:** `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`

+### ⛔ MANDATORY: Before Any Code Change
+
+**Claude MUST show this checklist BEFORE editing any file:**
+
+#### 1. Impact Search Results
+Run and show output of:
+```bash
+grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git"
+```
+
+#### 2. Files That Will Be Affected
+Numbered list of every file to be modified, with the specific change for each.
+
+#### 3. Files Searched But Not Changed (and why)
+Proof that related files were checked and determined unchanged.
+
+#### 4. Documentation That References This
+List of docs that mention this feature/script/function.
+
+**User verifies this list before Claude proceeds. If Claude skips this, STOP IMMEDIATELY.**
+
+#### After Changes
+Run the same grep and show results proving no references remain unaddressed.
+
 ---

+## ⚠️ Development Context: We Build AND Use These Plugins
+
+**This is a self-referential project.** We are:
+1. **BUILDING** a plugin marketplace (source code in `plugins/`)
+2. **USING** the installed marketplace to build it (dogfooding)
+
+### Plugins ACTIVELY USED in This Project
+
+These plugins are installed and should be used during development:
+
+| Plugin | Used For |
+|--------|----------|
+| **projman** | Sprint planning, issue management, lessons learned |
+| **git-flow** | Commits, branch management |
+| **pr-review** | Pull request reviews |
+| **doc-guardian** | Documentation drift detection |
+| **code-sentinel** | Security scanning, refactoring |
+| **clarity-assist** | Prompt clarification |
+| **claude-config-maintainer** | CLAUDE.md optimization |
+| **contract-validator** | Cross-plugin compatibility |
+
+### Plugins NOT Used Here (Development Only)
+
+These plugins exist in source but are **NOT relevant** to this project's workflow:
+
+| Plugin | Why Not Used |
+|--------|--------------|
+| **data-platform** | For data engineering projects (pandas, PostgreSQL, dbt) |
+| **viz-platform** | For dashboard projects (Dash, Plotly) |
+| **cmdb-assistant** | For infrastructure projects (NetBox) |
+
+**Do NOT suggest** `/ingest`, `/profile`, `/chart`, `/cmdb-*` commands - they don't apply here.
+
+### Key Distinction
+
+| Context | Path | What To Do |
+|---------|------|------------|
+| **Editing plugin source** | `~/claude-plugins-work/plugins/` | Modify code, add features |
+| **Using installed plugins** | `~/.claude/plugins/marketplaces/` | Run commands like `/sprint-plan` |
+
+When user says "run /sprint-plan", use the INSTALLED plugin.
+When user says "fix the sprint-plan command", edit the SOURCE code.
+
+---

 ## Project Overview

@@ -76,7 +144,7 @@ A plugin marketplace for Claude Code containing:
 ./scripts/post-update.sh   # Rebuild venvs, verify symlinks
 ```

-### Plugin Commands by Category
+### Plugin Commands - USE THESE in This Project

 | Category | Commands |
 |----------|----------|
@@ -88,12 +156,19 @@ A plugin marketplace for Claude Code containing:
 | **Docs** | `/doc-audit`, `/doc-sync`, `/changelog-gen`, `/doc-coverage`, `/stale-docs` |
 | **Security** | `/security-scan`, `/refactor`, `/refactor-dry` |
 | **Config** | `/config-analyze`, `/config-optimize`, `/config-diff`, `/config-lint` |
-| **Data** | `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/lineage-viz`, `/run`, `/dbt-test`, `/data-quality` |
-| **Visualization** | `/component`, `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/accessibility-check`, `/breakpoints` |
 | **Validation** | `/validate-contracts`, `/check-agent`, `/list-interfaces`, `/dependency-graph` |
-| **CMDB** | `/cmdb-search`, `/cmdb-device`, `/cmdb-ip`, `/cmdb-site`, `/cmdb-audit`, `/cmdb-register`, `/cmdb-sync`, `/cmdb-topology`, `/change-audit`, `/ip-conflicts` |
 | **Debug** | `/debug-report`, `/debug-review` |

+### Plugin Commands - NOT RELEVANT to This Project
+
+These commands are being developed but don't apply to this project's workflow:
+
+| Category | Commands | For Projects Using |
+|----------|----------|-------------------|
+| **Data** | `/ingest`, `/profile`, `/schema`, `/lineage`, `/dbt-test` | pandas, PostgreSQL, dbt |
+| **Visualization** | `/component`, `/chart`, `/dashboard`, `/theme` | Dash, Plotly dashboards |
+| **CMDB** | `/cmdb-search`, `/cmdb-device`, `/cmdb-sync` | NetBox infrastructure |
+
 ## Repository Structure

 ```
@@ -354,4 +429,4 @@ The script will:

 ---

-**Last Updated:** 2026-01-28
+**Last Updated:** 2026-01-30
--- a/docs/CANONICAL-PATHS.md
+++ b/docs/CANONICAL-PATHS.md
@@ -163,12 +163,11 @@ leo-claude-mktplace/
 │       └── claude-md-integration.md
 ├── scripts/                    # Setup and maintenance scripts
 │   ├── setup.sh                # Initial setup (create venvs, config templates)
-│   ├── post-update.sh          # Post-update (rebuild venvs, verify symlinks)
-│   ├── check-venv.sh           # Check if venvs exist (for hooks)
+│   ├── post-update.sh          # Post-update (clear cache, show changelog)
+│   ├── check-venv.sh           # Check if venvs exist (read-only)
 │   ├── validate-marketplace.sh # Marketplace compliance validation
 │   ├── verify-hooks.sh         # Verify all hooks use correct event types
-│   ├── setup-venvs.sh          # Setup/repair MCP server venvs
-│   ├── venv-repair.sh          # Repair broken venv symlinks
+│   ├── setup-venvs.sh          # Setup MCP server venvs (create only, never delete)
 │   └── release.sh              # Release automation with version bumping
 ├── CLAUDE.md
 ├── README.md
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -501,9 +501,8 @@ If you get 401, regenerate your token in Gitea.
 # Check venv exists
 ls /path/to/mcp-servers/gitea/.venv

-# Reinstall if missing
+# If missing, create venv (do NOT delete existing venvs)
 cd /path/to/mcp-servers/gitea
-rm -rf .venv
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
--- a/docs/UPDATING.md
+++ b/docs/UPDATING.md
@@ -132,10 +132,8 @@ When updating, review if changes affect the setup workflow:
 ### Dependencies fail to install

 ```bash
-# Rebuild virtual environment
+# Install missing dependencies (do NOT delete .venv)
 cd mcp-servers/gitea
-rm -rf .venv
-python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
 deactivate
--- a/plugins/claude-config-maintainer/agents/maintainer.md
+++ b/plugins/claude-config-maintainer/agents/maintainer.md
@@ -277,6 +277,39 @@ Every CLAUDE.md should have:
 1. **Project Overview** - What is this?
 2. **Quick Start** - How do I build/test/run?
 3. **Important Rules** - What must I NOT do?
+4. **Pre-Change Protocol** - Mandatory dependency check before code changes
+
+### Pre-Change Protocol Section (MANDATORY)
+
+**This section is REQUIRED in every CLAUDE.md.** It ensures Claude performs comprehensive dependency analysis before making any code changes.
+
+```markdown
+## ⛔ MANDATORY: Before Any Code Change
+
+**Claude MUST show this checklist BEFORE editing any file:**
+
+### 1. Impact Search Results
+Run and show output of:
+```bash
+grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git"
+```
+
+### 2. Files That Will Be Affected
+Numbered list of every file to be modified, with the specific change for each.
+
+### 3. Files Searched But Not Changed (and why)
+Proof that related files were checked and determined unchanged.
+
+### 4. Documentation That References This
+List of docs that mention this feature/script/function.
+
+**User verifies this list before Claude proceeds. If Claude skips this, stop immediately.**
+
+### After Changes
+Run the same grep and show results proving no references remain unaddressed.
+```
+
+**When analyzing a CLAUDE.md, flag as HIGH priority issue if this section is missing.**

 ### Optional Sections (as needed)

--- a/plugins/claude-config-maintainer/commands/analyze.md
+++ b/plugins/claude-config-maintainer/commands/analyze.md
@@ -59,6 +59,7 @@ Analyze the CLAUDE.md file in this project
 - Quick start commands documented
 - Critical rules highlighted
 - Key workflows covered
+- **Pre-Change Protocol section present** (MANDATORY - see below)

 ### Conciseness (25 points)
 - No unnecessary repetition
@@ -66,6 +67,42 @@ Analyze the CLAUDE.md file in this project
 - Appropriate length for project size
 - No generic filler content

+## Pre-Change Protocol Check (MANDATORY)
+
+**This check is CRITICAL.** The Pre-Change Protocol section ensures Claude performs comprehensive dependency analysis before making any code changes, preventing missed references and incomplete updates.
+
+### What to Check
+
+Search CLAUDE.md for:
+- Section header containing "Pre-Change" or "Before Any Code Change"
+- References to `grep -rn` or impact search
+- Checklist with "Files That Will Be Affected"
+- Requirement for user verification before proceeding
+
+### If Missing
+
+**Flag as HIGH PRIORITY issue:**
+
+```
+1. [HIGH] Missing Pre-Change Protocol section
+   CLAUDE.md lacks mandatory dependency-check protocol.
+   Impact: Claude may miss file references when making changes,
+   leading to broken dependencies and incomplete updates.
+
+   Recommendation: Add Pre-Change Protocol section immediately.
+   This is the #1 cause of cascading bugs from incomplete changes.
+```
+
+### Required Section Content
+
+The Pre-Change Protocol section must include:
+1. Requirement to run grep search and show results
+2. List of files that will be affected
+3. List of files searched but not changed (with reasoning)
+4. Documentation that references the change target
+5. User verification checkpoint before proceeding
+6. Post-change verification step
+
 ## Plugin Integration Analysis

 After the content analysis, the command detects and analyzes marketplace plugin integration:
--- a/plugins/claude-config-maintainer/commands/init.md
+++ b/plugins/claude-config-maintainer/commands/init.md
@@ -139,6 +139,7 @@ For small projects or when starting fresh:
 - Project Overview (required)
 - Quick Start (required)
 - Critical Rules (required)
+- **Pre-Change Protocol (required)**

 ### Standard Template (default)
 For typical projects:
@@ -146,6 +147,7 @@ For typical projects:
 - Quick Start
 - Architecture
 - Critical Rules
+- **Pre-Change Protocol**
 - Common Operations
 - File Structure

@@ -153,11 +155,44 @@ For typical projects:
 For large or complex projects:
 - All standard sections plus:
 - Detailed Architecture
+- **Pre-Change Protocol**
 - Troubleshooting
 - Integration Points
 - Development Workflow
 - Deployment Notes

+### Pre-Change Protocol Section (MANDATORY in ALL templates)
+
+**This section MUST be included in every generated CLAUDE.md:**
+
+```markdown
+## ⛔ MANDATORY: Before Any Code Change
+
+**Claude MUST show this checklist BEFORE editing any file:**
+
+### 1. Impact Search Results
+Run and show output of:
+\`\`\`bash
+grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git"
+\`\`\`
+
+### 2. Files That Will Be Affected
+Numbered list of every file to be modified, with the specific change for each.
+
+### 3. Files Searched But Not Changed (and why)
+Proof that related files were checked and determined unchanged.
+
+### 4. Documentation That References This
+List of docs that mention this feature/script/function.
+
+**User verifies this list before Claude proceeds. If Claude skips this, stop immediately.**
+
+### After Changes
+Run the same grep and show results proving no references remain unaddressed.
+```
+
+**Rationale:** This protocol prevents incomplete changes where Claude modifies some files but misses others that reference the same code, causing cascading bugs.
+
 ## Auto-Detection

 The command automatically detects:
--- a/plugins/claude-config-maintainer/commands/optimize.md
+++ b/plugins/claude-config-maintainer/commands/optimize.md
@@ -56,6 +56,7 @@ Or specify specific optimizations:

 ### Enhance
 - Add missing essential sections
+- **Add Pre-Change Protocol if missing (HIGH PRIORITY)**
 - Improve unclear instructions
 - Add helpful examples
 - Highlight critical rules
@@ -158,6 +159,49 @@ Backup saved to: .claude/backups/CLAUDE.md.2025-01-18
 | `--preserve-comments` | Keep all existing comments |
 | `--section=NAME` | Optimize specific section only |

+## Pre-Change Protocol (Mandatory Addition)
+
+**If CLAUDE.md is missing the Pre-Change Protocol section, optimization MUST add it.**
+
+This is the highest priority enhancement because it prevents cascading bugs from incomplete code changes.
+
+### Detection
+
+Search CLAUDE.md for:
+- "Pre-Change" or "Before Any Code Change" in headers
+- References to impact search or grep verification
+- User verification checkpoint
+
+### If Missing
+
+Add this section (position: after Critical Rules, before Common Operations):
+
+```markdown
+## ⛔ MANDATORY: Before Any Code Change
+
+**Claude MUST show this checklist BEFORE editing any file:**
+
+### 1. Impact Search Results
+Run and show output of:
+\`\`\`bash
+grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git"
+\`\`\`
+
+### 2. Files That Will Be Affected
+Numbered list of every file to be modified, with the specific change for each.
+
+### 3. Files Searched But Not Changed (and why)
+Proof that related files were checked and determined unchanged.
+
+### 4. Documentation That References This
+List of docs that mention this feature/script/function.
+
+**User verifies this list before Claude proceeds. If Claude skips this, stop immediately.**
+
+### After Changes
+Run the same grep and show results proving no references remain unaddressed.
+```
+
 ## When to Use

 Run `/config-optimize` when:
--- a/plugins/projman/hooks/startup-check.sh
+++ b/plugins/projman/hooks/startup-check.sh
@@ -7,29 +7,6 @@ PREFIX="[projman]"

 # Calculate paths
 PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "$(realpath "$0")")")}"
-# Marketplace root is 2 levels up from plugin root (plugins/projman -> .)
-MARKETPLACE_ROOT="$(dirname "$(dirname "$PLUGIN_ROOT")")"
-VENV_REPAIR_SCRIPT="$MARKETPLACE_ROOT/scripts/venv-repair.sh"
-
-# ============================================================================
-# Auto-repair MCP venvs (runs before other checks)
-# ============================================================================
-
-if [[ -x "$VENV_REPAIR_SCRIPT" ]]; then
-    # Run venv repair - this creates symlinks to cached venvs
-    # Only outputs messages if something needed fixing
-    "$VENV_REPAIR_SCRIPT" 2>/dev/null || {
-        echo "$PREFIX MCP venv setup failed - run: cd $MARKETPLACE_ROOT && ./scripts/setup-venvs.sh"
-        exit 0
-    }
-else
-    # Fallback: just check if venv exists
-    VENV_PATH="$PLUGIN_ROOT/mcp-servers/gitea/.venv/bin/python"
-    if [[ ! -f "$VENV_PATH" ]]; then
-        echo "$PREFIX MCP venvs missing - run setup.sh from installed marketplace"
-        exit 0
-    fi
-fi

 # Check git remote vs .env config (only if .env exists)
 if [[ -f ".env" ]]; then
--- a/scripts/post-update.sh
+++ b/scripts/post-update.sh
@@ -6,9 +6,10 @@
 #
 # This script:
 # 1. Clears Claude plugin cache (forces fresh .mcp.json reads)
-# 2. Restores MCP venv symlinks (instant if cache exists)
-# 3. Creates venvs in external cache if missing (first run only)
-# 4. Shows recent changelog updates
+# 2. Shows recent changelog updates
+#
+# NOTE: This script does NOT touch .venv directories.
+# If venvs are missing, run ./scripts/setup.sh manually.
 #

 set -euo pipefail
@@ -22,13 +23,11 @@ REPO_ROOT="$(dirname "$SCRIPT_DIR")"
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
-RED='\033[0;31m'
 NC='\033[0m'

 log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
 log_success() { echo -e "${GREEN}[OK]${NC} $1"; }
 log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
-log_error() { echo -e "${RED}[ERROR]${NC} $1"; }

 check_changelog() {
    if [[ -f "$REPO_ROOT/CHANGELOG.md" ]]; then
@@ -52,35 +51,21 @@ main() {

    # Clear Claude plugin cache to force fresh .mcp.json reads
    # This cache holds versioned copies that become stale after updates
+    # NOTE: This does NOT touch .venv directories
    if [[ -d "$CLAUDE_PLUGIN_CACHE" ]]; then
        log_info "Clearing Claude plugin cache..."
        rm -rf "$CLAUDE_PLUGIN_CACHE"
        log_success "Plugin cache cleared"
    fi

-    # Run venv-repair.sh to restore symlinks to external cache
-    # This is instant if cache exists, or does full setup on first run
-    if [[ -x "$SCRIPT_DIR/venv-repair.sh" ]]; then
-        log_info "Restoring MCP venv symlinks..."
-        if "$SCRIPT_DIR/venv-repair.sh"; then
-            log_success "MCP venvs ready"
-        else
-            log_error "MCP venv setup failed"
-            log_warn "Run: $SCRIPT_DIR/setup-venvs.sh for full setup"
-            exit 1
-        fi
-    else
-        log_error "venv-repair.sh not found at $SCRIPT_DIR"
-        exit 1
-    fi
-
    check_changelog

    echo ""
    log_success "Post-update complete!"
    echo ""
    echo "IMPORTANT: Restart Claude Code for changes to take effect."
-    echo "MCP servers will work immediately on next session start."
+    echo ""
+    echo "If MCP servers are not working, run: ./scripts/setup.sh"
 }

 main "$@"
--- a/scripts/venv-repair.sh
+++ b/scripts/venv-repair.sh
@@ -1,169 +0,0 @@
-#!/usr/bin/env bash
-#
-# venv-repair.sh - Fast MCP venv auto-repair for SessionStart hooks
-#
-# This script is designed to run at session start. It:
-# 1. Checks if venvs exist in external cache (~/.cache/claude-mcp-venvs/)
-# 2. Creates symlinks from marketplace to cache (instant operation)
-# 3. Only runs pip install if cache is missing (first install)
-#
-# Output format: All messages prefixed with [mcp-venv] for hook display
-#
-# Usage:
-#   ./scripts/venv-repair.sh           # Auto-repair (default)
-#   ./scripts/venv-repair.sh --silent  # Silent mode (no output unless error)
-#
-
-set -euo pipefail
-
-# ============================================================================
-# Configuration
-# ============================================================================
-
-PREFIX="[mcp-venv]"
-VENV_CACHE_DIR="${HOME}/.cache/claude-mcp-venvs/leo-claude-mktplace"
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-REPO_ROOT="$(dirname "$SCRIPT_DIR")"
-
-# MCP servers
-MCP_SERVERS=(gitea netbox data-platform viz-platform contract-validator)
-
-# Parse args
-SILENT=false
-[[ "${1:-}" == "--silent" ]] && SILENT=true
-
-log() {
-    [[ "$SILENT" == true ]] && return
-    echo "$PREFIX $1"
-}
-
-log_error() {
-    echo "$PREFIX ERROR: $1" >&2
-}
-
-# ============================================================================
-# Check if all venvs exist in cache
-# ============================================================================
-
-cache_complete() {
-    for server in "${MCP_SERVERS[@]}"; do
-        local venv_python="$VENV_CACHE_DIR/$server/.venv/bin/python"
-        [[ ! -f "$venv_python" ]] && return 1
-    done
-    return 0
-}
-
-# ============================================================================
-# Create symlinks from marketplace to cache
-# ============================================================================
-
-create_symlink() {
-    local server_name="$1"
-    local server_path="$REPO_ROOT/mcp-servers/$server_name"
-    local venv_cache="$VENV_CACHE_DIR/$server_name/.venv"
-    local venv_link="$server_path/.venv"
-
-    # Skip if server doesn't exist
-    [[ ! -d "$server_path" ]] && return 0
-
-    # Skip if cache doesn't exist
-    [[ ! -d "$venv_cache" ]] && return 1
-
-    # Already correct symlink?
-    if [[ -L "$venv_link" ]]; then
-        local target
-        target=$(readlink "$venv_link")
-        [[ "$target" == "$venv_cache" ]] && return 0
-        rm "$venv_link"
-    elif [[ -d "$venv_link" ]]; then
-        # Old venv directory exists - back it up or remove
-        rm -rf "$venv_link"
-    fi
-
-    # Create symlink
-    ln -s "$venv_cache" "$venv_link"
-    return 0
-}
-
-create_all_symlinks() {
-    local created=0
-    for server in "${MCP_SERVERS[@]}"; do
-        if create_symlink "$server"; then
-            ((created++)) || true
-        fi
-    done
-    [[ $created -gt 0 ]] && log "Restored $created venv symlinks"
-}
-
-# ============================================================================
-# Full setup (only if cache missing)
-# ============================================================================
-
-setup_server() {
-    local server_name="$1"
-    local server_path="$REPO_ROOT/mcp-servers/$server_name"
-    local venv_path="$VENV_CACHE_DIR/$server_name/.venv"
-
-    [[ ! -d "$server_path" ]] && return 0
-
-    mkdir -p "$VENV_CACHE_DIR/$server_name"
-
-    # Create venv
-    if [[ ! -d "$venv_path" ]]; then
-        python3 -m venv "$venv_path"
-    fi
-
-    # Install dependencies
-    # shellcheck disable=SC1091
-    source "$venv_path/bin/activate"
-    pip install -q --upgrade pip
-
-    if [[ -f "$server_path/requirements.txt" ]]; then
-        pip install -q -r "$server_path/requirements.txt"
-    fi
-
-    if [[ -f "$server_path/pyproject.toml" ]]; then
-        pip install -q -e "$server_path"
-    fi
-
-    deactivate
-
-    # Save hash for future quick checks
-    local hash_file="$VENV_CACHE_DIR/$server_name/.requirements_hash"
-    {
-        if [[ -f "$server_path/requirements.txt" ]]; then
-            cat "$server_path/requirements.txt"
-        fi
-        if [[ -f "$server_path/pyproject.toml" ]]; then
-            cat "$server_path/pyproject.toml"
-        fi
-        echo ""  # Ensure non-empty input for sha256sum
-    } | sha256sum | cut -d' ' -f1 > "$hash_file"
-}
-
-full_setup() {
-    log "First run - setting up MCP venvs (this only happens once)..."
-    for server in "${MCP_SERVERS[@]}"; do
-        log "  Setting up $server..."
-        setup_server "$server"
-    done
-    log "Setup complete. Future sessions will be instant."
-}
-
-# ============================================================================
-# Main
-# ============================================================================
-
-main() {
-    # Fast path: cache exists, just ensure symlinks
-    if cache_complete; then
-        create_all_symlinks
-        exit 0
-    fi
-
-    # Slow path: need to create venvs (first install)
-    full_setup
-    create_all_symlinks
-}
-
-main "$@"