Merge pull request 'development' (#289) from development into main

Reviewed-on: #289

CLAUDE.md

@@ -1,44 +1,48 @@
 # CLAUDE.md
 
 This file provides guidance to Claude Code when working with code in this repository.
+## ⛔ MANDATORY BEHAVIOR RULES - READ FIRST
 
-## ⛔ RULES - READ FIRST
+**These rules are NON-NEGOTIABLE. Violating them wastes the user's time and money.**
 
-### Behavioral Rules
+### 1. WHEN USER ASKS YOU TO CHECK SOMETHING - CHECK EVERYTHING
+- Search ALL locations, not just where you think it is
+- Check cache directories: `~/.claude/plugins/cache/`
+- Check installed: `~/.claude/plugins/marketplaces/`
+- Check source: `~/claude-plugins-work/`
+- **NEVER say "no" or "that's not the issue" without exhaustive verification**
 
-| Rule | Summary |
+### 2. WHEN USER SAYS SOMETHING IS WRONG - BELIEVE THEM
-|------|---------|
+- The user knows their system better than you
-| **Check everything** | Search cache (`~/.claude/plugins/cache/`), installed (`~/.claude/plugins/marketplaces/`), and source (`~/claude-plugins-work/`) |
+- Investigate thoroughly before disagreeing
-| **Believe the user** | User knows their system. Investigate before disagreeing. |
+- If user suspects cache, CHECK THE CACHE
-| **Verify before "done"** | Run commands, show output, check all locations. "Done" = verified working. |
+- If user suspects a file, READ THE FILE
-| **Show what's asked** | Don't interpret or summarize unless asked. |
+- **Your confidence is often wrong. User's instincts are often right.**
 
-### After Plugin Updates
+### 3. NEVER SAY "DONE" WITHOUT VERIFICATION
+- Run the actual command/script to verify
+- Show the output to the user
+- Check ALL affected locations
+- **"Done" means VERIFIED WORKING, not "I made changes"**
 
-Run `./scripts/verify-hooks.sh`. If changes affect MCP servers or hooks, inform user to restart session.
+### 4. SHOW EXACTLY WHAT USER ASKS FOR
-**DO NOT clear cache mid-session** - breaks loaded MCP tools.
+- If user asks for messages, show the MESSAGES
+- If user asks for code, show the CODE
+- If user asks for output, show the OUTPUT
+- **Don't interpret or summarize unless asked**
 
-### NEVER USE CLI TOOLS FOR EXTERNAL SERVICES
+### 5. AFTER PLUGIN UPDATES - VERIFY AND RESTART
-- **FORBIDDEN:** `gh`, `tea`, `curl` to APIs, any CLI that talks to Gitea/GitHub/external services
-- **REQUIRED:** Use MCP tools exclusively (`mcp__plugin_projman_gitea__*`, `mcp__plugin_pr-review_gitea__*`)
-- **NO EXCEPTIONS.** Don't try CLI first. Don't fall back to CLI. MCP ONLY.
 
-### NEVER PUSH DIRECTLY TO PROTECTED BRANCHES
+**⚠️ DO NOT clear cache mid-session** - this breaks MCP tools that are already loaded.
-- **FORBIDDEN:** `git push origin development`, `git push origin main`, `git push origin master`
-- **REQUIRED:** Create feature branch → push feature branch → create PR via MCP
-- If you accidentally commit to a protected branch locally: `git checkout -b fix/branch-name` then reset the protected branch
 
-### Repository Rules
+1. Run `./scripts/verify-hooks.sh` to check hook types
+2. If changes affect MCP servers or hooks, inform the user:
+   > "Plugin changes require a session restart to take effect. Please restart Claude Code."
+3. Cache clearing is ONLY safe **before** starting a new session (not during)
 
-| Rule | Details |
+See `docs/DEBUGGING-CHECKLIST.md` for details on cache timing.
-|------|---------|
-| **File creation** | Only in allowed paths. Use `.scratch/` for temp work. Verify against `docs/CANONICAL-PATHS.md` |
-| **plugin.json location** | Must be in `.claude-plugin/` directory |
-| **Hooks** | Use `hooks/hooks.json` (auto-discovered). Never inline in plugin.json |
-| **MCP servers** | Shared at root with symlinks. Use MCP tools, never CLI (`tea`, `gh`) |
-| **Allowed root files** | `CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example` |
 
-**Valid hook events:** `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
+**FAILURE TO FOLLOW THESE RULES = WASTED USER TIME = UNACCEPTABLE**
 
 ---
 
@@ -158,6 +162,40 @@ leo-claude-mktplace/
     └── CONFIGURATION.md          # Centralized configuration guide
 ```
 
+## CRITICAL: Rules You MUST Follow
+
+### File Operations
+- **NEVER** create files in repository root unless listed in "Allowed Root Files"
+- **NEVER** modify `.gitignore` without explicit permission
+- **ALWAYS** use `.scratch/` for temporary/exploratory work
+- **ALWAYS** verify paths against `docs/CANONICAL-PATHS.md` before creating files
+
+### Plugin Development
+- **plugin.json MUST be in `.claude-plugin/` directory** (not plugin root)
+- **Every plugin MUST be listed in marketplace.json**
+- **MCP servers are SHARED at root** with symlinks from plugins
+- **MCP server venv path**: `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{name}/.venv/bin/python`
+- **CLI tools forbidden** - Use MCP tools exclusively (never `tea`, `gh`, etc.)
+
+#### ⚠️ plugin.json Format Rules (CRITICAL)
+- **Hooks in separate file** - Use `hooks/hooks.json` (auto-discovered), NOT inline in plugin.json
+- **NEVER reference hooks** - Don't add `"hooks": "..."` field to plugin.json at all
+- **Agents auto-discover** - NEVER add `"agents": ["./agents/"]` - .md files found automatically
+- **Always validate** - Run `./scripts/validate-marketplace.sh` before committing
+- **Working examples:** projman, pr-review, claude-config-maintainer all use `hooks/hooks.json`
+- See lesson: `lessons/patterns/plugin-manifest-validation---hooks-and-agents-format-requirements`
+
+### Hooks (Valid Events Only)
+`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
+
+**INVALID:** `task-completed`, `file-changed`, `git-commit-msg-needed`
+
+### Allowed Root Files
+`CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example`
+
+### Allowed Root Directories
+`.claude/`, `.claude-plugin/`, `.claude-plugins/`, `.scratch/`, `docs/`, `hooks/`, `mcp-servers/`, `plugins/`, `scripts/`
+
 ## Architecture
 
 ### Four-Agent Model (projman)

plugins/doc-guardian/commands/doc-sync.md

@@ -52,13 +52,7 @@ Then proceed with the sync.
    - Single commit: `docs: sync documentation with code changes`
    - Include summary of what was updated in commit body
 
-5. **Clear Queue**
+5. **Output**
-   After successful sync, clear the queue file:
-   ```bash
-   echo "# Doc Guardian Queue - cleared after sync on $(date +%Y-%m-%d)" > .doc-guardian-queue
-   ```
-
-6. **Output**
 ```
 ## Documentation Sync Complete
 

plugins/doc-guardian/hooks/notify.sh

@@ -2,10 +2,6 @@
 # doc-guardian notification hook
 # Tracks documentation dependencies and queues updates
 # This is a command hook - guaranteed not to block workflow
-#
-# IMPORTANT: Output is purely informational - uses passive language
-# to avoid triggering Claude to seek user confirmation.
-# Run /doc-sync to process the queue when ready.
 
 # Read tool input from stdin (JSON with file_path)
 INPUT=$(cat)
@@ -48,30 +44,6 @@ DEPENDENT_DOCS="${DOC_DEPS[$MODIFIED_TYPE]}"
 # Queue file for tracking pending updates
 QUEUE_FILE="${CLAUDE_PROJECT_ROOT:-.}/.doc-guardian-queue"
 
-# Debounce: skip notification if same type was logged in last 5 seconds
-# This prevents 4+ rapid notifications during batch edits
-DEBOUNCE_SECONDS=5
-if [ -f "$QUEUE_FILE" ]; then
-    LAST_ENTRY=$(tail -1 "$QUEUE_FILE" 2>/dev/null || true)
-    LAST_TYPE=$(echo "$LAST_ENTRY" | cut -d'|' -f2 | tr -d ' ')
-    LAST_TIME=$(echo "$LAST_ENTRY" | cut -d'|' -f1 | tr -d ' ')
-
-    if [ "$LAST_TYPE" = "$MODIFIED_TYPE" ] && [ -n "$LAST_TIME" ]; then
-        # Convert timestamps to seconds for comparison
-        LAST_EPOCH=$(date -d "$LAST_TIME" +%s 2>/dev/null || echo "0")
-        NOW_EPOCH=$(date +%s)
-        DIFF=$((NOW_EPOCH - LAST_EPOCH))
-
-        if [ "$DIFF" -lt "$DEBOUNCE_SECONDS" ]; then
-            # Still add to queue, but skip notification
-            {
-                echo "$(date +%Y-%m-%dT%H:%M:%S) | $MODIFIED_TYPE | $FILE_PATH | $DEPENDENT_DOCS"
-            } >> "$QUEUE_FILE" 2>/dev/null || true
-            exit 0
-        fi
-    fi
-fi
-
 # Add to queue (create if doesn't exist, append if does)
 {
     echo "$(date +%Y-%m-%dT%H:%M:%S) | $MODIFIED_TYPE | $FILE_PATH | $DEPENDENT_DOCS"
@@ -80,8 +52,7 @@ fi
 # Count pending updates
 PENDING_COUNT=$(wc -l < "$QUEUE_FILE" 2>/dev/null | tr -d ' ' || echo "1")
 
-# Output passive notification (no action implied)
+# Output notification with specific docs that need updating
-# Uses "queued" instead of "update needed" to avoid triggering Claude to ask about it
+echo "[doc-guardian] $MODIFIED_TYPE changed → update needed: $DEPENDENT_DOCS (${PENDING_COUNT} pending)"
-echo "[doc-guardian] drift queued: $MODIFIED_TYPE → $DEPENDENT_DOCS ($PENDING_COUNT total)"
 
 exit 0

plugins/git-flow/hooks/hooks.json

@@ -1,16 +1,19 @@
 {
-  "hooks": [
+  "hooks": {
-    {
+    "PreToolUse": [
-      "event": "PreToolUse",
+      {
-      "matcher": "Bash",
+        "matcher": "Bash",
-      "type": "command",
+        "hooks": [
-      "command": "${CLAUDE_PLUGIN_ROOT}/hooks/branch-check.sh"
+          {
-    },
+            "type": "command",
-    {
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/branch-check.sh"
-      "event": "PreToolUse",
+          },
-      "matcher": "Bash",
+          {
-      "type": "command",
+            "type": "command",
-      "command": "${CLAUDE_PLUGIN_ROOT}/hooks/commit-msg-check.sh"
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/commit-msg-check.sh"
-    }
+          }
-  ]
+        ]
+      }
+    ]
+  }
 }

plugins/projman/commands/debug-review.md

@@ -385,13 +385,6 @@ git push -u origin fix/issue-[NUMBER]-[brief-description]
 git checkout development
 ```
 
-**⚠️ IMPORTANT: Issue will NOT auto-close**
-
-PRs merged to `development` do NOT trigger Gitea's auto-close feature.
-Auto-close only works when merging to the default branch (`main`).
-
-You MUST manually close the issue in Step 15 after the PR is merged.
-
 5. Add comment to original issue:
 ```
 mcp__plugin_projman_gitea__add_comment(
@@ -424,14 +417,9 @@ Next Steps:
 
 **This step runs AFTER the user has verified the fix works.**
 
-**⚠️ MANDATORY: You MUST manually close the issue.**
-
-PRs merged to `development` do NOT auto-close issues (Gitea only auto-closes
-on merges to the default branch `main`). Always close manually after merge.
-
 When user returns and confirms the fix is working:
 
-**1. Close the issue (REQUIRED - won't auto-close):**
+**1. Close the issue:**
 
 ```
 mcp__plugin_projman_gitea__update_issue(

plugins/projman/hooks/startup-check.sh

@@ -81,29 +81,6 @@ if [[ -f ".env" ]]; then
     fi
 fi
 
-# ============================================================================
-# Check version consistency across files (early drift detection)
-# ============================================================================
-# Versions must stay in sync across: README.md, marketplace.json, CHANGELOG.md
-# Drift here causes confusion and release issues
-
-if [[ -f "README.md" && -f ".claude-plugin/marketplace.json" && -f "CHANGELOG.md" ]]; then
-    VERSION_README=$(grep -oE "^# .* - v[0-9]+\.[0-9]+\.[0-9]+" README.md 2>/dev/null | grep -oE "[0-9]+\.[0-9]+\.[0-9]+" || echo "")
-    # Extract metadata.version specifically (appears after "metadata" in marketplace.json)
-    VERSION_MARKETPLACE=$(sed -n '/"metadata"/,/}/p' .claude-plugin/marketplace.json 2>/dev/null | grep -oE '"version"[[:space:]]*:[[:space:]]*"[0-9]+\.[0-9]+\.[0-9]+"' | head -1 | grep -oE "[0-9]+\.[0-9]+\.[0-9]+" || echo "")
-    VERSION_CHANGELOG=$(grep -oE "^## \[[0-9]+\.[0-9]+\.[0-9]+\]" CHANGELOG.md 2>/dev/null | head -1 | grep -oE "[0-9]+\.[0-9]+\.[0-9]+" || echo "")
-
-    if [[ -n "$VERSION_README" && -n "$VERSION_MARKETPLACE" && -n "$VERSION_CHANGELOG" ]]; then
-        if [[ "$VERSION_README" != "$VERSION_MARKETPLACE" ]] || [[ "$VERSION_README" != "$VERSION_CHANGELOG" ]]; then
-            echo "$PREFIX Version mismatch detected:"
-            echo "$PREFIX   README.md:        v$VERSION_README"
-            echo "$PREFIX   marketplace.json: v$VERSION_MARKETPLACE"
-            echo "$PREFIX   CHANGELOG.md:     v$VERSION_CHANGELOG"
-            echo "$PREFIX Run /suggest-version to analyze and fix"
-        fi
-    fi
-fi
-
 # Check for CHANGELOG.md [Unreleased] content (version management)
 if [[ -f "CHANGELOG.md" ]]; then
     # Check if there's content under [Unreleased] that hasn't been released