pal-e-docs

Plan: Template Enforcement Hooks

plan-2026-02-25-template-enforcement Plan

plan completed
Project

Plan: Template Enforcement Hooks

Vision

pal-e-docs is the development operating system. Templates are enforced at point of action, not suggested. Agents follow PR and issue templates because hooks gate the tool calls.

Projects & Repos Touched

Project/Repo Platform Role in this plan
claude-custom Forgejo PreToolUse hooks for submit_pr and create_issue

Context

Promoted from: Phase 4 of plan-2026-02-24-docs-foundation (redefined — markdown conversion killed).
What we realized: Markdown conversion is overkill. Issues and PRs live on Forgejo (already markdown). Templates live in pal-e-docs. The gap was: nothing enforced that agents follow the templates when creating PRs/issues.
Completed 2026-02-25: PR #27 merged on claude-custom. Both hooks deployed and tested.

Previous Plan

plan-2026-02-24-docs-foundation (still active — this completed its Phase 4)

Depends On

None.

Decisions Made

Decision Rationale
Kill markdown conversion Only PRs and issues need markdown, and they already live on Forgejo. No need to add markdown to pal-e-docs.
PreToolUse hooks, not SessionStart Templates should appear at point of action, not bloat every session.
Fetch templates from pal-e-docs at hook time Single source of truth. Update the note, all agents get the new template.
<code>deny</code> not <code>ask</code> Testing confirmed <code>ask</code> is silently ignored by subagents — they proceed without prompting. <code>deny</code> hard-blocks the tool call, forcing the agent to rebuild with all required sections.
<code>### Plan</code> required on all issues Full traceability chain: project → plan → issue → PR. Every issue traces back to a plan.
Hooks require session restart Hook registrations added to settings.json mid-session don't take effect until session restart.

Phases

Phase 1: PR template enforcement hook — COMPLETE

Completed 2026-02-25: PR #27 merged on claude-custom.
check-pr-template.sh — PreToolUse on mcp__forgejo__submit_pr. Fetches template-pr-body dynamically, extracts ## headings, denies if missing.
Issue: issue-pr-template-hook (resolved)

Phase 2: Forgejo issue template enforcement hook — COMPLETE

Completed 2026-02-25: PR #27 merged on claude-custom.
check-issue-template.sh — PreToolUse on mcp__forgejo__create_issue and mcp__forgejo__create_issue_and_branch. Fetches template-issue dynamically, extracts ### headings, denies if missing.
Issue: issue-issue-template-hook (resolved)

Key Files

Phase File Repo Change
1 ~/.claude/hooks/check-pr-template.sh claude-custom DONE
1 ~/.claude/settings.json claude-custom DONE
2 ~/.claude/hooks/check-issue-template.sh claude-custom DONE
2 ~/.claude/settings.json claude-custom DONE

Verification

  • [x] Create an issue with missing sections → hook denies with missing list
  • [x] Create an issue with all sections → hook allows
  • [x] deny works in subagents, ask does not
  • [x] Hooks require session restart to take effect
  • [x] Hooks fail-open when pal-e-docs unreachable (tested manually)
  • [x] Templates fetched dynamically — updating note changes enforcement

Next Plan Seeds

  • Phase 5 (doc check-in hooks) and Phase 6 (Litestream backup) still pending on parent plan
  • /submit-pr skill that auto-fetches template (future)
  • Test PR template hook end-to-end with a real PR
  • plan-2026-02-24-docs-foundation — parent plan
  • template-pr-body — PR template note
  • template-issue — issue template note
  • enforcement-architecture — the four pillars