BACK-494 - Backlog-Guard: PreToolUse hook to enforce MCP/CLI access to backlog directories by lenucksi · Pull Request #649 · MrLesk/Backlog.md

lenucksi · 2026-05-13T11:21:34Z

Summary

Adds hooks/backlog-guard/ — a Claude Code PreToolUse hook that hard-blocks direct Read/Edit/Write/Bash access to configured backlog directories and redirects agents to the correct MCP tool or CLI command with pre-filled parameters (task ID extracted from filename, document name, etc.)
Config via .backlog-guard YAML file at git root, auto-discovered via git rev-parse --show-toplevel; falls back to detecting backlog/config.yml in the directory tree (no configuration needed for standard single-backlog projects)
Modelled after serena-guard — same hard-blocking pattern, same hook output format; difference is path-prefix detection instead of file-extension detection
Adds .codex/skills/backlog-guard-setup/SKILL.md — a one-command setup skill that auto-detects the backlog directory, creates .backlog-guard, writes the hook entry into the appropriate settings file, and optionally adds mcp__backlog__* tool permissions to the allowlist
Adds __pycache__/ and *.pyc to .gitignore

Test plan

python -m pytest hooks/backlog-guard/test_check.py -v — 8 tests pass
Manual: Read on backlog/tasks/back-1-...md → denied, BACK-1 in reason, MCP + CLI suggestion in context
Manual: Read on src/cli.ts → allowed (not in backlog dir)
Manual: Bash(cat backlog/tasks/back-1-...md) → denied
Manual: grep pattern file.txt | grep back-123 → allowed (pipeline stdin, not file arg)
Manual: no .backlog-guard, backlog/config.yml present → auto-detect still blocks
Manual: /backlog-guard-setup skill → .backlog-guard created, settings hook entry written

Block message example

When an agent tries Read(backlog/tasks/back-494 - Backlog-Guard-....md):

⛔ BACKLOG GUARD — Read on task file (BACK-494) is forbidden.
All backlog data access must go through MCP tools or the backlog CLI.
Target: /path/to/backlog/tasks/back-494 - Backlog-Guard-....md

USE ONE OF THESE INSTEAD:
MCP:  mcp__backlog__task_view(id="BACK-494")
CLI:  backlog task BACK-494

Protected directory: /path/to/backlog
Config: /path/to/.backlog-guard

🤖 Generated with Claude Code

- Add terminalStatuses?: string[] to BacklogConfig interface - Parse terminal_statuses key in config loader (same pattern as statuses) - Extend getTerminalStatus/isTerminalStatus with optional terminalStatuses param - Falls back to last-element convention when not provided (backward-compatible) - isTerminalStatus returns true for any entry in terminalStatuses array - getTerminalStatus returns terminalStatuses[0] as primary terminal status - Add 5 new test cases covering multi-terminal, fallback, empty-array, and non-last-element override scenarios Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

BACK-465 - Config-Schema: terminalStatuses-Key einführen

…atistics, milestones, handlers Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…uences and board filters Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…x serializeConfig Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Added 4 tests to src/web/lib/lanes.test.ts covering the sortTasksForStatus refactoring from BACK-467: custom terminal status gets done-sort even when not last in statuses array, empty terminalStatuses falls back to last-element convention, and active statuses are unaffected when terminalStatuses is set. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…tyling - Add blockedStatuses?: string[] to BacklogConfig type - Parse/serialize blocked_statuses in parseConfig/serializeConfig (same pattern as terminalStatuses) - Extend getStatusStyle(), getStatusColor(), getStatusIcon(), formatStatusWithIcon() to accept optional blockedStatuses param - Config-aware check runs first; falls back to exact-match statusMap ("Blocked") and substring heuristic (includes("blocked")) - Thread blockedStatuses prop through App.tsx -> BoardPage -> Board -> TaskColumn - Update getStatusBadgeClass() in TaskColumn: config array checked first, then fallback includes("blocked")/includes("stuck") - Add 3 new tests (RED confirmed before implementation) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…HEAD Replace git rev-list --all --count with git rev-list --count HEAD in getCommitCountInTest. The --all flag includes refs/notes/ai commits created asynchronously by the global git-ai trace2 tool, inflating counts non-deterministically. HEAD-scoped counting matches the approach in cli.test.ts and correctly measures commits on the current branch. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Commit all untracked backlog task files (back-465 through back-482) and update modified task files (back-200 through back-438) to establish a safe baseline before upstream PR rebase operations. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Upstream version-bump CI commit used 2-space indent; reformat to tabs to match the project Biome config and unblock `bun run check .`. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Renamed back-466/back-467 task files from German to English names. Translated implementation notes in back-469 to English. BACK-480 marked Done with full notes and final summary. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Exclude package.json from Biome's formatter via overrides to prevent tabs-vs-spaces conflicts on every pull from upstream, which uses spaces. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

style.css is rebuilt by build:css before every build/cli invocation; committing it caused noisy 200KB single-line diffs on any CSS change. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

New tasks: - BACK-486: Colored Labels (WebUI/TUI/CLI/MCP/REST) - BACK-487: Labels for Documents and Decisions - BACK-488: Label Management — central CRUD + autocomplete - BACK-489: Archive Documents and Decisions + superseded ADRs - BACK-490: REST API OpenAPI self-documentation - BACK-491: Cross-Modality CI — enforce feature parity - BACK-492: Tech Debt Research — codebase audit Updated: - BACK-474: recycled from German stub → Sequence/Dependency Visualizer Research (audits BACK-217/218 cluster, library eval, no code) - BACK-484: fleshed out assignee autocomplete stub with description + AC (scraping-based, no central config) All tickets include upstream-master constraint block and explicit 5-modality AC. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- BACK-466/467: translate implementation notes and titles to English (BACK-480 follow-up) - BACK-479/481/482: mark Done, check off all ACs, add Final Summary sections - BACK-478: remove task (superseded by BACK-479–482) - BACK-483: add new task (subtasks / Epic-level tracking question) - .gitignore: ignore archive/ directory Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>