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

fix(doc-guardian): Hook blocks workflow and fires excessively #287

New Issue
Closed
opened 2026-01-28 22:39:16 +00:00 by lmiranda · 1 comment
lmiranda commented 2026-01-28 22:39:16 +00:00
Owner
Copy Link

Summary

The doc-guardian PostToolUse hook has several usability issues that disrupt normal workflow.

Issues

1. Hook Blocks Workflow Instead of Running in Background

Current behavior: When documentation drift is detected, the hook outputs a message and stops continuation, requiring user to say "move forward" to proceed.

Expected behavior: Non-blocking notification + spawn background agent (doc-guardian:doc-analyzer) to address drift in parallel.

2. Hook Fires Multiple Times for Related Edits

Current behavior: During a single task involving sequential edits (e.g., updating 4 files in a migration), the hook fires 4+ times, each time blocking for user input.

Expected behavior: Batch related changes within a session/task, or remember user intent ("continue without checking") for the duration of the task.

3. Hook Over-Restricts Internal URLs

Current behavior: Tried to add Gitea Wiki URL to CLAUDE.md, hook blocked it claiming "infrastructure/network information exposure".

Expected behavior: Should be context-aware - internal documentation URLs (especially to the same Gitea instance) should not be flagged. The CLAUDE.md already contains the Gitea host elsewhere.

Observed In

  • Session on 2026-01-23 in personal-projects/personal-portfolio
  • Session on 2026-01-28 in personal-projects/leo-claude-mktplace

Proposed Solutions

  1. Convert to non-blocking notification - Use notify.sh pattern (like the current command hook) but don't stop workflow
  2. Spawn background agent - If drift is significant, spawn doc-guardian:doc-analyzer agent to handle it
  3. Add session-level intent tracking - If user says "continue" once, don't ask again for related edits
  4. Whitelist internal URLs - Don't flag URLs to the same Gitea instance configured in .env

Acceptance Criteria

  • Hook does not block workflow continuation
  • Related edits in same task don't trigger multiple prompts
  • Internal Gitea URLs are not flagged as security issues
  • Drift is still detected and queued (in .doc-guardian-queue)

Related

  • Original hook implementation in v3.2.0
  • Similar pattern needed: projman SessionStart hook (non-blocking)
## Summary The doc-guardian PostToolUse hook has several usability issues that disrupt normal workflow. ## Issues ### 1. Hook Blocks Workflow Instead of Running in Background **Current behavior:** When documentation drift is detected, the hook outputs a message and stops continuation, requiring user to say "move forward" to proceed. **Expected behavior:** Non-blocking notification + spawn background agent (`doc-guardian:doc-analyzer`) to address drift in parallel. ### 2. Hook Fires Multiple Times for Related Edits **Current behavior:** During a single task involving sequential edits (e.g., updating 4 files in a migration), the hook fires 4+ times, each time blocking for user input. **Expected behavior:** Batch related changes within a session/task, or remember user intent ("continue without checking") for the duration of the task. ### 3. Hook Over-Restricts Internal URLs **Current behavior:** Tried to add Gitea Wiki URL to CLAUDE.md, hook blocked it claiming "infrastructure/network information exposure". **Expected behavior:** Should be context-aware - internal documentation URLs (especially to the same Gitea instance) should not be flagged. The CLAUDE.md already contains the Gitea host elsewhere. ## Observed In - Session on 2026-01-23 in `personal-projects/personal-portfolio` - Session on 2026-01-28 in `personal-projects/leo-claude-mktplace` ## Proposed Solutions 1. **Convert to non-blocking notification** - Use `notify.sh` pattern (like the current command hook) but don't stop workflow 2. **Spawn background agent** - If drift is significant, spawn `doc-guardian:doc-analyzer` agent to handle it 3. **Add session-level intent tracking** - If user says "continue" once, don't ask again for related edits 4. **Whitelist internal URLs** - Don't flag URLs to the same Gitea instance configured in `.env` ## Acceptance Criteria - [ ] Hook does not block workflow continuation - [ ] Related edits in same task don't trigger multiple prompts - [ ] Internal Gitea URLs are not flagged as security issues - [ ] Drift is still detected and queued (in `.doc-guardian-queue`) ## Related - Original hook implementation in v3.2.0 - Similar pattern needed: projman SessionStart hook (non-blocking)
lmiranda added the Type/BugPriority/MediumComplexity/Medium labels 2026-01-28 22:39:16 +00:00
lmiranda commented 2026-01-29 01:33:26 +00:00
Author
Owner
Copy Link

Fix proposed in PR #291

Changes:

  • Message wording changed from actionable "update needed" to passive "drift queued"
  • Added 5-second debouncing to prevent rapid-fire notifications
  • Added queue clearing step to /doc-sync command

Note: The URL restriction issue (#3 in this report) was not found in the current codebase. It may have been caused by a different component or already fixed separately.

Next Steps:

  1. Review and merge PR #291
  2. Test in a project with batch edits to verify reduced interruptions
  3. Come back to close this issue and optionally capture a lesson learned
Fix proposed in PR #291 **Changes:** - Message wording changed from actionable "update needed" to passive "drift queued" - Added 5-second debouncing to prevent rapid-fire notifications - Added queue clearing step to `/doc-sync` command **Note:** The URL restriction issue (#3 in this report) was not found in the current codebase. It may have been caused by a different component or already fixed separately. **Next Steps:** 1. Review and merge PR #291 2. Test in a project with batch edits to verify reduced interruptions 3. Come back to close this issue and optionally capture a lesson learned
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 Complexity/Medium Priority/Medium Type/Bug
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#287
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?