Hook Catalog — Complete Enforcement Surface
Hook Catalog — Complete Enforcement Surface
Complete map of every hook script in
claude-custom/hooks/ to its event, matcher, SOP/convention, and enforcement layer. This is the single source of truth for the enforcement surface. 34 scripts total: 30 settings hooks, 3 frontmatter hooks, 1 utility.Last audited: 2026-03-14. Repo:
forgejo_admin/claude-custom.Layer 1: Block (PreToolUse — hard stops)
Hard enforcement — rejects non-compliant actions before they execute. Exit 2 = blocked.
| Script | Matcher | What it blocks | Backs SOP/Convention |
|---|---|---|---|
| <code>block-upstream.sh</code> | Bash | <code>git push upstream</code> — prevents pushing to upstream remotes | Branch protection convention |
| <code>block-main-commits.sh</code> | Bash | <code>git commit</code> on main branch — forces branch workflow | <code>branch-protection</code> |
| <code>block-pr-merge.sh</code> | Bash | <code>gh pr merge</code> / <code>git merge</code> — prevents CLI merges (use MCP) | <code>solo-dev-pr-workflow</code> |
| <code>block-claude-custom-main-edit.sh</code> | Write|Edit|NotebookEdit | Direct edits to claude-custom files on main branch | <code>sop-claude-config-development</code> |
| <code>block-mcp-merge.sh</code> | mcp__forgejo__merge_approved_pr | Merge without explicit user approval | <code>pr-lifecycle</code> |
| <code>check-issue.sh</code> | Write|Edit|NotebookEdit | File writes without Forgejo issue tracking | <code>agent-workflow</code> |
| <code>check-agent-spawn.sh</code> | Task (Agent tool) | Agent spawn without plan/issue/project slug in prompt | <code>agent-spawn-conventions</code> |
| <code>check-pr-template.sh</code> | mcp__forgejo__submit_pr | PR without required template sections | <code>template-pr-body</code> |
| <code>check-issue-template.sh</code> | mcp__forgejo__create_issue* | Issue without required template sections | <code>template-issue</code> |
| <code>check-note-template.sh</code> | mcp__pal-e-docs__create_note | Note creation without proper structure | Various templates |
| <code>check-phase-template.sh</code> | mcp__pal-e-docs__create_note | Phase creation without Lineage/template compliance | <code>template-phase</code> |
| <code>warn-delete-note.sh</code> | mcp__pal-e-docs__delete_note | Note deletion without backup (warning, not hard block) | <code>sop-note-deletion</code> |
| <code>check-ruff-before-commit.sh</code> | Bash | <code>git commit</code> in Python repos with ruff violations | Code quality convention |
Layer 2: Auto-format (PreToolUse — fix compliance automatically)
Automatically fixes compliance issues — no human intervention needed.
| Script | Matcher | What it does | Backs SOP/Convention |
|---|---|---|---|
| <code>auto-ruff-format.sh</code> | Bash | Runs <code>ruff format</code> on staged .py files before <code>git commit</code> | Code quality convention |
| <code>pypi-pr-checklist.sh</code> | Bash | Adds PyPI publishing checklist to PR body for SDK repos | PyPI publishing convention |
Layer 3: Auto-label (PostToolUse — state machine advancement)
Automatically advances the Forgejo issue lifecycle state machine via label changes.
| Script | Matcher | What it does | Backs SOP/Convention |
|---|---|---|---|
| <code>label-on-branch.sh</code> | mcp__forgejo__create_issue_and_branch | Sets <code>status:in-progress</code> label when branch created | <code>pr-lifecycle</code> |
| <code>label-on-pr.sh</code> | mcp__forgejo__submit_pr | Sets <code>status:qa</code> label when PR submitted | <code>pr-lifecycle</code> |
| <code>label-on-verdict.sh</code> | mcp__forgejo__comment_on_pr | Sets <code>status:approved</code> or <code>status:needs-fix</code> based on verdict | <code>pr-lifecycle</code> |
Layer 4: Remind (PostToolUse — nudge downstream obligations)
Non-blocking reminders that nudge the next step in the workflow.
| Script | Matcher | What it reminds | Backs SOP/Convention |
|---|---|---|---|
| <code>remind-review-loop.sh</code> | Bash (git push) | Run <code>/review-pr</code> after pushing a branch | <code>pr-review-loop</code> |
| <code>remind-mcp-review-loop.sh</code> | mcp__forgejo__submit_pr | Same, for MCP-submitted PRs | <code>pr-review-loop</code> |
| <code>remind-update-docs.sh</code> | mcp__forgejo__merge_approved_pr | Run <code>/update-docs</code> after merging | <code>sop-post-merge-docs</code> |
| <code>remind-sprint-update.sh</code> | mcp__forgejo__merge_approved_pr | Move board item to done after merging | Board management convention |
| <code>post-merge-rebase.sh</code> | Bash (git push) | Rebase other branches after merge to main | <code>worktree-workflow</code> |
| <code>post-mcp-merge-rebase.sh</code> | mcp__forgejo__merge_approved_pr | Same, for MCP merges | <code>worktree-workflow</code> |
Layer 5: Context inject (SessionStart + SubagentStart)
Inject personality, SOPs, plan context at session/agent startup.
| Script | Event | What it injects | Backs SOP/Convention |
|---|---|---|---|
| <code>session-start-context.sh</code> | SessionStart | Personality, active SOPs, plan TOCs, open bugs/TODOs | <code>agent-workflow</code> |
| <code>check-claude-custom-clean.sh</code> | SessionStart | Warns if claude-custom not on main (stale hooks risk) | <code>sop-claude-config-development</code> |
| <code>cleanup-worktrees.sh</code> | SessionStart | Cleans stale worktrees on session start | <code>worktree-workflow</code> |
| <code>check-mcp-servers.sh</code> | SessionStart | Detects missing MCP servers, warns (fail-open) | <code>sop-mcp-server-recovery</code> |
| <code>inject-subagent-context.sh</code> | SubagentStart (qa|dev|general-purpose|dottie) | Injects plan context + personality into spawned agents | <code>agent-spawn-conventions</code> |
Layer 6: Agent containment (frontmatter + Stop)
Defense-in-depth inside agent contexts. Frontmatter hooks fire only inside the agent.
| Script | Location | What it enforces | Backs SOP/Convention |
|---|---|---|---|
| <code>block-docs-writes.sh</code> | Frontmatter: dev.md, qa.md | Blocks all pal-e-docs write MCP tools (17 ops) | <code>agent-spawn-conventions</code> |
| <code>block-write-tools.sh</code> | Frontmatter: qa.md | Blocks Write/Edit/Bash inside QA agent | <code>agent-spawn-conventions</code> |
| <code>block-dottie-code-writes.sh</code> | Frontmatter: dottie.md | Blocks code writes (Write/Edit/Bash on repos) inside Dottie | <code>agent-spawn-conventions</code> |
| <code>stop-doc-checkin.sh</code> | Stop event (settings) | Prompts doc check-in at session end | <code>sop-post-merge-docs</code> |
Utility (not a hook)
| Script | Purpose |
|---|---|
| <code>forgejo-helper.sh</code> | Shared helper sourced by label-on-*.sh scripts. Provides Forgejo API auth and label functions. |
Coverage Gaps
SOPs/conventions that exist but have NO hook enforcement:
| SOP/Convention | Gap | Suggested Hook | Phase |
|---|---|---|---|
| <code>sop-platform-tf-changes</code> | <code>tofu plan</code> without <code>-lock=false</code> from worktrees | PreToolUse:Bash — block <code>tofu plan</code> missing <code>-lock=false</code> | — |
| <code>sop-platform-tf-changes</code> | Infra PRs merged without pre-merge validation evidence (tofu plan output, kubectl kustomize output) | PreToolUse:<code>mcp__forgejo__merge_approved_pr</code> — check PR body/comments for validation evidence on infra repos | Phase 17a |
| <code>sop-incident-response</code> | Incident board tracking is in the SOP (Step 4) but not hook-enforced — manual process | PostToolUse:incident note creation — prompt for board item creation | — |
| <code>sop-note-deletion</code> | <code>warn-delete-note.sh</code> warns but doesn't enforce backup | PreToolUse — require backup confirmation before delete | — |
| <code>convention-arch-sop-pairing</code> | No hook ensures new arch notes link to SOPs | PostToolUse:create_note — check if note_type=reference, prompt for SOP link | — |
| <code>ci-rules</code> | CI conventions are documented but not hook-enforced | PreToolUse:Bash — block skip-ci patterns | — |
Statistics
| Category | Count |
|---|---|
| Total scripts | 34 |
| Settings hooks | 30 |
| Frontmatter hooks | 3 |
| Utility scripts | 1 |
| Events used | 5 of 17 (SessionStart, PreToolUse, PostToolUse, Stop, SubagentStart) |
| Events unused | 12 (SessionEnd, PreCompact, UserPromptSubmit, PostToolUseFailure, PermissionRequest, SubagentStop, TeammateIdle, TaskCompleted, ConfigChange, Notification, WorktreeCreate, WorktreeRemove) |
| SOPs backed by hooks | 12 |
| Coverage gaps identified | 4 |
Related
hook-events-reference— event types, inputs/outputs, matchersenforcement-architecture— enforcement layer model (4 layers within Agency)sop-index— SOP → agent → enforcement mappingsop-hook-block-recovery— what to do when a hook blocks unexpectedlysop-claude-config-development— how to safely develop hooks- Procedures:
sop-hook-block-recovery— recovery when hooks block unexpectedly