Plan: SOP Enforcement via Hooks, MCP, and pal-e-docs
Vision
CLAUDE.md is unreliable enforcement — it's advisory, agents can ignore it. What works: hooks (they block), MCP tools (queryable data), skills (concrete workflows). This plan built the enforcement stack.
Architecture
- Hooks enforce: SessionStart injects SOPs, PreToolUse blocks bad actions (main commits, unauthorized merges), PostToolUse reminds review loop
- MCP provides data: pal-e-docs for SOPs/conventions, forgejo-mcp for API operations
- CLAUDE.md is thin: ~45 lines — identity, principles, pointers to pal-e-docs
- pal-e-docs notes: worktree-workflow, branch-protection, solo-dev-pr-workflow, pr-review-loop, ci-rules (project: claude-config)
What Was Built
- SessionStart hook — queries pal-e-docs for active SOPs, injects platform detection + SOP list + bug/TODO counts into session context
- forgejo-sdk — 304 endpoints, 10 mixin modules, published to PyPI as ldraney-forgejo-sdk v0.1.0
- forgejo-mcp — 12 SOP-aware compound tools, registered in ~/.mcp.json
- Global CLAUDE.md thinned — 170→45 lines, verbose SOPs moved to pal-e-docs
- 5 SOP notes migrated — worktree-workflow, branch-protection, solo-dev-pr-workflow, pr-review-loop, ci-rules
- Bug/TODO tracking — SessionStart hook queries bug,open and todo,open tags, agents instructed to create/resolve notes
Key Insight
The three enforcement layers: hooks block (can't bypass), MCP informs (queryable on demand), CLAUDE.md guides (advisory). The thin CLAUDE.md + hook injection pattern means SOPs update in pal-e-docs without touching config files.
Status
Executed. Validation pending (Phase 5 of follow-up plan).