fix(doc-guardian): Hook blocking behavior and multiple firing issues #312

New Issue

lmiranda · 2026-01-29T03:05:08Z

lmiranda commented

2026-01-29 03:05:08 +00:00

Issues from 2026-01-23 personal-portfolio session

1. doc-guardian hook incorrectly stops workflow

The PostToolUse:Edit hook for doc-guardian stopped continuation after detecting documentation drift
It should NOT stop the workflow - blocking is disruptive to user tasks

2. doc-guardian hook should spawn agent instead of blocking

When documentation drift is detected, the hook should activate another agent (e.g., doc-guardian:doc-analyzer) to address the drift in parallel
Current behavior: blocks with a system-reminder message
Expected behavior: non-blocking notification + spawn background agent

During lesson migration cleanup, the hook fired 4+ times for sequential edits
Each time user had to say "move forward" to continue
Hooks should be smarter about batching related changes or remembering user intent within a session

4. Hook blocked edit with hardcoded URL warning

Tried to add Gitea Wiki URL to CLAUDE.md, hook blocked it claiming "infrastructure/network information exposure"
This is overly restrictive for internal documentation that already contains the Gitea host elsewhere
Should be configurable or context-aware

5. CLAUDE.md had outdated Wiki.js references

Project CLAUDE.md still referenced Wiki.js for lessons learned storage when the plugin was changed to use Gitea Wiki
This caused confusion during lesson migration workflow
Status: Fixed in that project's CLAUDE.md, but may exist in other projects

Acceptance Criteria

Hook does not block workflow on drift detection
Hook batches related changes within a session
Hook spawns background agent for drift resolution (or queues for later)
URL/hostname detection is context-aware (allows internal docs references)
Consider session-level "acknowledged" state to prevent repeat notifications

## Issues from 2026-01-23 personal-portfolio session ### 1. doc-guardian hook incorrectly stops workflow - The `PostToolUse:Edit` hook for doc-guardian stopped continuation after detecting documentation drift - It should NOT stop the workflow - blocking is disruptive to user tasks ### 2. doc-guardian hook should spawn agent instead of blocking - When documentation drift is detected, the hook should activate another agent (e.g., `doc-guardian:doc-analyzer`) to address the drift in parallel - **Current behavior:** blocks with a system-reminder message - **Expected behavior:** non-blocking notification + spawn background agent ### 3. Hook fired multiple times for related edits in same task - During lesson migration cleanup, the hook fired 4+ times for sequential edits - Each time user had to say "move forward" to continue - Hooks should be smarter about batching related changes or remembering user intent within a session ### 4. Hook blocked edit with hardcoded URL warning - Tried to add Gitea Wiki URL to CLAUDE.md, hook blocked it claiming "infrastructure/network information exposure" - This is overly restrictive for internal documentation that already contains the Gitea host elsewhere - Should be configurable or context-aware ### 5. CLAUDE.md had outdated Wiki.js references - Project CLAUDE.md still referenced Wiki.js for lessons learned storage when the plugin was changed to use Gitea Wiki - This caused confusion during lesson migration workflow - **Status:** Fixed in that project's CLAUDE.md, but may exist in other projects ## Acceptance Criteria - [ ] Hook does not block workflow on drift detection - [ ] Hook batches related changes within a session - [ ] Hook spawns background agent for drift resolution (or queues for later) - [ ] URL/hostname detection is context-aware (allows internal docs references) - [ ] Consider session-level "acknowledged" state to prevent repeat notifications

lmiranda referenced this issue from a commit

2026-01-29 03:09:52 +00:00

fix(doc-guardian): make hook silent by default

lmiranda referenced a pull request that will close this issue

2026-01-29 03:10:00 +00:00

fix(doc-guardian): make hook silent by default #313

lmiranda referenced this issue from a commit

2026-01-29 03:12:11 +00:00

fix(doc-guardian): make hook silent by default

lmiranda closed this issue

2026-01-29 03:12:40 +00:00

Sign in to join this conversation.