From 6c24bcbb9130dbb516a35cc82389ea372d6be044 Mon Sep 17 00:00:00 2001
From: lmiranda <leobmiranda@gmail.com>
Date: Fri, 23 Jan 2026 11:48:54 -0500
Subject: [PATCH] fix(doc-guardian): replace prompt hook with command hook

Prompt hooks are unreliable - Claude ignores instructions and generates
verbose analysis despite explicit FORBIDDEN rules. Command hooks guarantee
the exact output we want.

- Add notify.sh script that only outputs for config file changes
- Change hooks.json from prompt type to command type
- Script exits silently for non-config files (no blocking)

Fixes #110

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 plugins/doc-guardian/hooks/hooks.json |  4 ++--
 plugins/doc-guardian/hooks/notify.sh  | 23 +++++++++++++++++++++++
 2 files changed, 25 insertions(+), 2 deletions(-)
 create mode 100755 plugins/doc-guardian/hooks/notify.sh

diff --git a/plugins/doc-guardian/hooks/hooks.json b/plugins/doc-guardian/hooks/hooks.json
index d76de92..2a58ee4 100644
--- a/plugins/doc-guardian/hooks/hooks.json
+++ b/plugins/doc-guardian/hooks/hooks.json
@@ -5,8 +5,8 @@
         "matcher": "Write|Edit|MultiEdit",
         "hooks": [
           {
-            "type": "prompt",
-            "prompt": "STRICT OUTPUT RULES - FOLLOW EXACTLY:\n\n1. Your output MUST start with '[doc-guardian]' - NO EXCEPTIONS\n2. Output ONLY ONE of these two responses:\n   - If file is in commands/, agents/, skills/, or hooks/ directories: '[doc-guardian] Config file modified. Run /doc-sync when ready.'\n   - Otherwise: say absolutely nothing (empty response)\n\n3. FORBIDDEN - You must NEVER:\n   - Analyze file contents\n   - Report specific issues or errors\n   - Use words like 'drift', 'inconsistent', 'error', 'warning', 'problem'\n   - Output more than 15 words\n   - Stop or block the workflow\n\n4. After your single-line output (or silence), IMMEDIATELY continue with the user's task\n\nThis is a passive notification only. Never analyze. Never block. Never elaborate."
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/notify.sh"
           }
         ]
       }
diff --git a/plugins/doc-guardian/hooks/notify.sh b/plugins/doc-guardian/hooks/notify.sh
new file mode 100755
index 0000000..f7c1bbc
--- /dev/null
+++ b/plugins/doc-guardian/hooks/notify.sh
@@ -0,0 +1,23 @@
+#!/bin/bash
+# doc-guardian notification hook
+# Outputs a single notification for config file changes, nothing otherwise
+# This is a command hook - guaranteed not to block workflow
+
+# Read tool input from stdin (JSON with file_path)
+INPUT=$(cat)
+
+# Extract file_path from JSON input
+FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+
+# If no file_path found, exit silently
+if [ -z "$FILE_PATH" ]; then
+    exit 0
+fi
+
+# Check if file is in a config directory (commands/, agents/, skills/, hooks/)
+if echo "$FILE_PATH" | grep -qE '/(commands|agents|skills|hooks)/'; then
+    echo "[doc-guardian] Config file modified. Run /doc-sync when ready."
+fi
+
+# Exit silently for all other files (no output = no blocking)
+exit 0