ldraney/claude-custom
1
0
Fork 0
Code Issues 32 Pull requests Projects Releases Packages Wiki Activity Actions

Phase 4: check-phase-template.sh enforcement hook #63

New issue
Closed
opened 2026-03-07 23:06:01 +00:00 by forgejo_admin · 0 comments
forgejo_admin commented 2026-03-07 23:06:01 +00:00
Contributor
Copy link

Lineage

plan-2026-03-07-note-hierarchy-conventions → Phase 4 (Enforcement Hook)

Repo

forgejo_admin/claude-custom

User Story

As Betty Sue (main session)
I want phase notes to be validated against template-phase when created
So that every phase and subphase follows the standard structure and I don't drift into ad-hoc formats

Context

We just created template-phase in pal-e-docs, which defines required sections for phase notes. The existing check-issue-template.sh hook already validates Forgejo issues against template-issue by fetching the template live from the pal-e-docs API and extracting required headings. This hook follows the exact same pattern but for mcp__pal-e-docs__create_note calls with note_type=phase.

The hook is template-driven (not hardcoded) — it fetches template-phase at runtime and extracts validation rules from the content. This means template changes don't require hook changes.

Key difference from issue template hook: Phase notes use HTML content (not markdown), and the required fields are a mix of bold-text header fields (Goal:, Owner:, Repo:, Depends on:) and HTML headings (<h3>Scope</h3> or <h3>Problem</h3>+<h3>Fix</h3>, plus <h3>Related</h3>).

File Targets

Files the agent should create:

  • hooks/check-phase-template.sh — PreToolUse hook that validates phase note content

Files the agent should modify:

  • settings.json — register the new hook under PreToolUse with matcher mcp__pal-e-docs__create_note

Files the agent should reference (read-only):

  • hooks/check-issue-template.sh — the pattern to follow (same fetch-from-API, fail-open approach)
  • hooks/check-note-template.sh — may already exist and handle plan notes; if so, extend it rather than creating a new file

Files the agent should NOT touch:

  • Any other hook files
  • Any agent profile .md files

Acceptance Criteria

  • Creating a phase note with note_type=phase that is missing required fields gets blocked with a helpful error message
  • Required fields checked: Goal:, Owner:, Repo:, Depends on: (bold-text in <strong> tags or plain text)
  • At least one of: <h3>Scope</h3> OR (<h3>Problem</h3> AND <h3>Fix</h3>) — the two shapes from template-phase
  • <h3>Related</h3> section required
  • Creating a note with note_type other than phase is NOT affected (fail-open for non-phase notes)
  • Network errors / API unreachable → fail-open (allow the create, don't block on infra issues)
  • Empty content → deny with message pointing to template-phase
  • Existing create_note calls for plans, SOPs, etc. are unaffected

Test Expectations

  • Manual test: create a phase note missing Goal → blocked
  • Manual test: create a phase note with all required fields → allowed
  • Manual test: create a phase note with Problem+Fix (no Scope) → allowed (subphase variant)
  • Manual test: create a non-phase note → allowed (not affected)
  • Run command: manual testing via Claude Code session (hooks are live via symlink)

Constraints

  • Follow check-issue-template.sh pattern exactly: fail-open on all errors, use jq for JSON parsing, curl for API fetch
  • Hook must check tool_input.note_type == "phase" first — bail early for non-phase notes
  • The validation logic should work with HTML content (the content field), not markdown
  • Check for <strong>Goal:</strong> pattern (or just Goal: in content) for header fields
  • Use grep -qi for case-insensitive matching where appropriate
  • set -eo pipefail with trap 'exit 0' ERR for fail-open

Checklist

  • PR opened
  • Hook works (manual test)
  • No unrelated changes

Related

  • template-phase — the template this hook enforces
  • convention-subphase — documents the two-shape pattern (full phase vs subphase)
  • plan-2026-03-07-note-hierarchy-conventions — parent plan
  • ai-agency — project
### Lineage `plan-2026-03-07-note-hierarchy-conventions` → Phase 4 (Enforcement Hook) ### Repo `forgejo_admin/claude-custom` ### User Story As Betty Sue (main session) I want phase notes to be validated against `template-phase` when created So that every phase and subphase follows the standard structure and I don't drift into ad-hoc formats ### Context We just created `template-phase` in pal-e-docs, which defines required sections for phase notes. The existing `check-issue-template.sh` hook already validates Forgejo issues against `template-issue` by fetching the template live from the pal-e-docs API and extracting required headings. This hook follows the exact same pattern but for `mcp__pal-e-docs__create_note` calls with `note_type=phase`. The hook is template-driven (not hardcoded) — it fetches `template-phase` at runtime and extracts validation rules from the content. This means template changes don't require hook changes. **Key difference from issue template hook:** Phase notes use HTML content (not markdown), and the required fields are a mix of bold-text header fields (`Goal:`, `Owner:`, `Repo:`, `Depends on:`) and HTML headings (`<h3>Scope</h3>` or `<h3>Problem</h3>`+`<h3>Fix</h3>`, plus `<h3>Related</h3>`). ### File Targets Files the agent should create: - `hooks/check-phase-template.sh` — PreToolUse hook that validates phase note content Files the agent should modify: - `settings.json` — register the new hook under PreToolUse with matcher `mcp__pal-e-docs__create_note` Files the agent should reference (read-only): - `hooks/check-issue-template.sh` — the pattern to follow (same fetch-from-API, fail-open approach) - `hooks/check-note-template.sh` — may already exist and handle plan notes; if so, extend it rather than creating a new file Files the agent should NOT touch: - Any other hook files - Any agent profile `.md` files ### Acceptance Criteria - [ ] Creating a phase note with `note_type=phase` that is missing required fields gets blocked with a helpful error message - [ ] Required fields checked: `Goal:`, `Owner:`, `Repo:`, `Depends on:` (bold-text in `<strong>` tags or plain text) - [ ] At least one of: `<h3>Scope</h3>` OR (`<h3>Problem</h3>` AND `<h3>Fix</h3>`) — the two shapes from template-phase - [ ] `<h3>Related</h3>` section required - [ ] Creating a note with `note_type` other than `phase` is NOT affected (fail-open for non-phase notes) - [ ] Network errors / API unreachable → fail-open (allow the create, don't block on infra issues) - [ ] Empty content → deny with message pointing to `template-phase` - [ ] Existing `create_note` calls for plans, SOPs, etc. are unaffected ### Test Expectations - [ ] Manual test: create a phase note missing Goal → blocked - [ ] Manual test: create a phase note with all required fields → allowed - [ ] Manual test: create a phase note with Problem+Fix (no Scope) → allowed (subphase variant) - [ ] Manual test: create a non-phase note → allowed (not affected) - Run command: manual testing via Claude Code session (hooks are live via symlink) ### Constraints - Follow `check-issue-template.sh` pattern exactly: fail-open on all errors, use `jq` for JSON parsing, `curl` for API fetch - Hook must check `tool_input.note_type == "phase"` first — bail early for non-phase notes - The validation logic should work with HTML content (the `content` field), not markdown - Check for `<strong>Goal:</strong>` pattern (or just `Goal:` in content) for header fields - Use `grep -qi` for case-insensitive matching where appropriate - `set -eo pipefail` with `trap 'exit 0' ERR` for fail-open ### Checklist - [ ] PR opened - [ ] Hook works (manual test) - [ ] No unrelated changes ### Related - `template-phase` — the template this hook enforces - `convention-subphase` — documents the two-shape pattern (full phase vs subphase) - `plan-2026-03-07-note-hierarchy-conventions` — parent plan - `ai-agency` — project
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
217-enhance-skill-review-ticket-verify-arch
86-epilogue-nits-hook-updates-dottie-config
76-add-sessionstart-hook-to-detect-missing
69-fix-block-docs-writes-sh-security-gap-ad
51-phase-3-agent-label-behavior-posttooluse
No results found.
Labels
Clear labels   
domain:backend

   
domain:devops

   
domain:frontend

   
status:approved

QA passed, awaiting merge approval

  
status:in-progress

Dev agent is actively working

  
status:needs-fix

QA found issues, back to dev

  
status:qa

PR submitted, awaiting QA review

  
type:bug

Bug fix

  
type:devops

Infrastructure/CI/config work

  
type:feature

New functionality

No labels
domain:backend
domain:devops
domain:frontend
status:approved
status:in-progress
status:needs-fix
status:qa
type:bug
type:devops
type:feature
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
ldraney/claude-custom#63
No description provided.