personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[Bug] doc-guardian hooks block workflow and lack session awareness #113

New Issue
Closed
opened 2026-01-23 16:57:57 +00:00 by lmiranda · 0 comments
lmiranda commented 2026-01-23 16:57:57 +00:00
Owner
Copy Link

Diagnostic Report

Generated: 2026-01-23T11:45:00Z
Command Tested: Lesson migration from local files to Gitea Wiki
Reporter: Claude Code via /debug-report

Project Context

Field Value
Repository personal-projects/personal-portfolio
Git Remote ssh://git@hotserv.tailc9b278.ts.net:2222/personal-projects/personal-portfolio.git
Working Directory /home/lmiranda/Repositories/personal/personal-portfolio
Current Branch development

MCP Diagnostic Results

All 5 MCP diagnostic tests PASSED:

  • validate_repo_org: PASS
  • get_labels: PASS (18 labels)
  • list_issues: PASS
  • list_milestones: PASS
  • suggest_labels: PASS

The issues encountered are NOT MCP-related. They are doc-guardian hook behavior issues.

Hook Issues Encountered

Issue 1: Hook stops workflow instead of continuing

Symptom: After every Edit to documentation files (CLAUDE.md, README.md, INDEX.md), the hook emitted:

PostToolUse:Edit hook stopped continuation: Documentation drift detected...

Impact: Blocked Claude's ability to continue working. User had to say "move forward" after every edit.

Expected Behavior: Hook should emit a notification but NOT stop continuation.

Issue 2: Hook should spawn agent, not block

Current Behavior: When documentation drift is detected, hook blocks execution with a system-reminder message.

Expected Behavior:

  • Emit a non-blocking notification
  • Optionally spawn a background agent (e.g., doc-guardian:doc-analyzer) to track/address the drift
  • Allow the current operation to continue

Issue 3: Hook lacks session/task awareness

Symptom: During a single task (removing references to a deleted folder), the hook fired 4+ times for sequential related edits:

  1. Edit CLAUDE.md - hook fired
  2. Edit CLAUDE.md again - hook fired
  3. Edit INDEX.md - hook fired
  4. Edit README.md - hook fired

Impact: User had to say "move forward" 4 times for what was clearly one logical operation.

Expected Behavior:

  • Recognize related changes within a task/session
  • Batch notifications OR remember user's "move forward" intent
  • Only fire once per logical operation

Issue 4: Overly restrictive URL blocking

Symptom: Tried to add Gitea Wiki URL to CLAUDE.md, hook blocked with:

PreToolUse:Edit hook error: Hardcoded URL containing potential infrastructure/network information

Context:

  • The same file already contains the Gitea host (gitea.hotserv.cloud)
  • It's internal documentation meant to help developers find resources
  • The URL was for the project's own wiki

Expected Behavior: Should be configurable or context-aware. Internal documentation URLs should be allowed, especially when the host is already documented in the same file.

Summary

  • Total Hook Interruptions: 5+ during a 15-minute session
  • MCP Tools: All working correctly
  • Affected Plugin: doc-guardian (hooks)
  • Severity: Medium - disrupts workflow but workaround exists (user says "move forward")

Suggested Investigation

  1. doc-guardian/hooks/ - PostToolUse:Edit hook logic
  2. doc-guardian/hooks/ - PreToolUse:Edit URL validation logic
  3. Consider adding session state to track user intent
  4. Consider making URL restrictions configurable

Reproduction Steps

  1. Navigate to any project with doc-guardian enabled
  2. Make 3+ sequential edits to documentation files (CLAUDE.md, README.md)
  3. Observe hook stopping continuation after each edit
  4. Try adding an internal URL to CLAUDE.md
  5. Observe URL blocked even when host already exists in file

Generated by /debug-report - Labels: Type: Bug, Priority: Medium, Component: doc-guardian

## Diagnostic Report **Generated**: 2026-01-23T11:45:00Z **Command Tested**: Lesson migration from local files to Gitea Wiki **Reporter**: Claude Code via /debug-report ## Project Context | Field | Value | |-------|-------| | Repository | `personal-projects/personal-portfolio` | | Git Remote | `ssh://git@hotserv.tailc9b278.ts.net:2222/personal-projects/personal-portfolio.git` | | Working Directory | `/home/lmiranda/Repositories/personal/personal-portfolio` | | Current Branch | `development` | ## MCP Diagnostic Results All 5 MCP diagnostic tests **PASSED**: - validate_repo_org: PASS - get_labels: PASS (18 labels) - list_issues: PASS - list_milestones: PASS - suggest_labels: PASS **The issues encountered are NOT MCP-related. They are doc-guardian hook behavior issues.** ## Hook Issues Encountered ### Issue 1: Hook stops workflow instead of continuing **Symptom**: After every Edit to documentation files (CLAUDE.md, README.md, INDEX.md), the hook emitted: ``` PostToolUse:Edit hook stopped continuation: Documentation drift detected... ``` **Impact**: Blocked Claude's ability to continue working. User had to say "move forward" after every edit. **Expected Behavior**: Hook should emit a notification but NOT stop continuation. --- ### Issue 2: Hook should spawn agent, not block **Current Behavior**: When documentation drift is detected, hook blocks execution with a system-reminder message. **Expected Behavior**: - Emit a non-blocking notification - Optionally spawn a background agent (e.g., `doc-guardian:doc-analyzer`) to track/address the drift - Allow the current operation to continue --- ### Issue 3: Hook lacks session/task awareness **Symptom**: During a single task (removing references to a deleted folder), the hook fired 4+ times for sequential related edits: 1. Edit CLAUDE.md - hook fired 2. Edit CLAUDE.md again - hook fired 3. Edit INDEX.md - hook fired 4. Edit README.md - hook fired **Impact**: User had to say "move forward" 4 times for what was clearly one logical operation. **Expected Behavior**: - Recognize related changes within a task/session - Batch notifications OR remember user's "move forward" intent - Only fire once per logical operation --- ### Issue 4: Overly restrictive URL blocking **Symptom**: Tried to add Gitea Wiki URL to CLAUDE.md, hook blocked with: ``` PreToolUse:Edit hook error: Hardcoded URL containing potential infrastructure/network information ``` **Context**: - The same file already contains the Gitea host (`gitea.hotserv.cloud`) - It's internal documentation meant to help developers find resources - The URL was for the project's own wiki **Expected Behavior**: Should be configurable or context-aware. Internal documentation URLs should be allowed, especially when the host is already documented in the same file. --- ## Summary - **Total Hook Interruptions**: 5+ during a 15-minute session - **MCP Tools**: All working correctly - **Affected Plugin**: doc-guardian (hooks) - **Severity**: Medium - disrupts workflow but workaround exists (user says "move forward") ## Suggested Investigation 1. `doc-guardian/hooks/` - PostToolUse:Edit hook logic 2. `doc-guardian/hooks/` - PreToolUse:Edit URL validation logic 3. Consider adding session state to track user intent 4. Consider making URL restrictions configurable ## Reproduction Steps 1. Navigate to any project with doc-guardian enabled 2. Make 3+ sequential edits to documentation files (CLAUDE.md, README.md) 3. Observe hook stopping continuation after each edit 4. Try adding an internal URL to CLAUDE.md 5. Observe URL blocked even when host already exists in file --- *Generated by /debug-report - Labels: Type: Bug, Priority: Medium, Component: doc-guardian*
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Component/API
API endpoints, contracts, and integration
 Component/Auth
Authentication and authorization
 Component/Backend
Backend service code and business logic
 Component/Database
Database schemas, migrations, queries
 Component/Deploy
Deployment, infrastructure, DevOps
 Component/Docs
Documentation and guides
 Component/Frontend
User interface and client-side code
 Component/Infra
Infrastructure and system configuration
 Component/Testing
Test infrastructure and frameworks
 Tech/Docker
Docker containers and compose
 Tech/FastAPI
FastAPI backend framework
 Tech/JavaScript
JavaScript/Node.js code
 Tech/PostgreSQL
PostgreSQL database
 Tech/Python
Python language and libraries
 Tech/Redis
Redis cache and pub/sub
 Tech/Vue
Vue.js frontend framework
Complexity/Complex
High uncertainty or many dependencies
 Complexity/Medium
Some unknowns or dependencies
 Complexity/Simple
Straightforward, well-understood
 Effort/L
3-5 days
 Effort/M
1-2 days
 Effort/S
2-4 hours
 Effort/XL
> 1 week
 Effort/XS
< 2 hours
 Priority/Critical
Immediate attention required
 Priority/High
Important, needs attention soon
 Priority/Low
Nice to have, can wait
 Priority/Medium
Normal priority
 Type/Bug
Something isn't working
 Type/Chore
Maintenance tasks
 Type/Documentation
Documentation improvements
 Type/Feature
New feature or request
 Type/Refactor
Code refactoring without changing behavior
 Type/Test
Testing related
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
lmiranda
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: personal-projects/leo-claude-mktplace#113
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?