Expand check-note-template.sh to enforce new type templates

forgejo_admin commented

2026-03-28 01:54:53 +00:00

Contributor

Type

Feature

Lineage

Related to forgejo_admin/claude-custom #180 (spike: note type system audit).
Part of Wave 4: enforcement hooks.

Repo

forgejo_admin/claude-custom

User Story

As a PM (Betty Sue)
I want every note type to have template enforcement via hooks
So that agents can't create non-compliant notes

Context

The audit found that check-note-template.sh only validates 2 of 17 types (project-page and issue). After the type system refactor, we need enforcement for 6 additional types. All 5 new template notes now exist in pal-e-docs.

File Targets

Files to modify:

hooks/check-note-template.sh -- add case branches routing on .tool_input.note_type field (not just tags)

Files NOT to touch:

hooks/check-issue-template.sh -- validates Forgejo issues, not notes
hooks/check-board-item.sh -- board items are separate

Required Headings Per Type

The hook must enforce these required h3 headings (extracted from template notes):

Type	Required Headings
`review`	Template Completeness, Traceability, File Targets, Repo Placement, Dependencies, Acceptance Criteria, Blast Radius, Decomposition Assessment, Recommendation
`architecture`	Diagram, Components, Key Decisions, Related
`user-story`	Role, Key, Want, So That, Acceptance Criteria, Success Metric, Related Architecture, Related
`sop`	Purpose, Steps, Rules, Related
`convention`	Rule, Rationale, Examples, Enforcement, Related
`validation`	Ticket, Environment, Checks, Verdict, Discovered Issues

Routing Mechanism

Current hook routes on tags (grep for tag name). New types must route on the note_type field from .tool_input.note_type. Implementation should:

Extract note_type from tool input JSON
Case-match on type name
For matched types, extract headings from note content and validate against required list
For doc type: pass through (intentionally unguarded)

Heading Format

Templates use HTML <h3> tags in their code blocks. The hook must grep for <h3> patterns OR markdown ### patterns (some notes use HTML, some use markdown). Recommend: check for both formats with grep -iE '(<h3[^>]*>|^### )' .

Acceptance Criteria

Creating a review note without required headings is blocked
Creating an architecture note without required headings is blocked
Creating a user-story note without required headings is blocked
Creating a sop note without required headings is blocked
Creating a convention note without required headings is blocked
Creating a validation note without required headings is blocked
Creating a doc note is NOT blocked (intentionally unguarded)
Existing validated types (project-page) still work

Test Expectations

Manual test: create note with each type missing required headings, verify blocked
Manual test: create note with correct headings, verify allowed
Run command: manual hook testing via Claude Code session

Constraints

All 6 template notes exist: template-review, template-architecture, template-user-story, template-sop, template-convention, template-validation
Hook runs as PreToolUse on create_note only (settings.json matcher: mcp__pal-e-docs__create_note)
Must handle both HTML and markdown heading formats

Checklist

PR opened
Tests pass
No unrelated changes

project-pal-e-agency
forgejo_admin/claude-custom #180 -- parent spike

Review History

review-183-2026-03-27: NEEDS_REFINEMENT — Missing required headings table, routing mechanism not specified, HTML/markdown format mismatch, template-validation missing from scope. All 4 gaps fixed in this update.
review-483-2026-03-27-r2: NEEDS_REFINEMENT — 2 nits: (1) validation heading list missing "Discovered Issues", (2) Constraints claimed hook wires both create_note and update_note but settings.json only wires create_note. Both fixed.

### Type Feature ### Lineage Related to `forgejo_admin/claude-custom #180` (spike: note type system audit). Part of Wave 4: enforcement hooks. ### Repo `forgejo_admin/claude-custom` ### User Story As a PM (Betty Sue) I want every note type to have template enforcement via hooks So that agents can't create non-compliant notes ### Context The audit found that `check-note-template.sh` only validates 2 of 17 types (project-page and issue). After the type system refactor, we need enforcement for 6 additional types. All 5 new template notes now exist in pal-e-docs. ### File Targets Files to modify: - `hooks/check-note-template.sh` -- add case branches routing on `.tool_input.note_type` field (not just tags) Files NOT to touch: - `hooks/check-issue-template.sh` -- validates Forgejo issues, not notes - `hooks/check-board-item.sh` -- board items are separate ### Required Headings Per Type The hook must enforce these required h3 headings (extracted from template notes): | Type | Required Headings | |------|-------------------| | `review` | Template Completeness, Traceability, File Targets, Repo Placement, Dependencies, Acceptance Criteria, Blast Radius, Decomposition Assessment, Recommendation | | `architecture` | Diagram, Components, Key Decisions, Related | | `user-story` | Role, Key, Want, So That, Acceptance Criteria, Success Metric, Related Architecture, Related | | `sop` | Purpose, Steps, Rules, Related | | `convention` | Rule, Rationale, Examples, Enforcement, Related | | `validation` | Ticket, Environment, Checks, Verdict, Discovered Issues | ### Routing Mechanism Current hook routes on `tags` (grep for tag name). New types must route on the `note_type` field from `.tool_input.note_type`. Implementation should: 1. Extract `note_type` from tool input JSON 2. Case-match on type name 3. For matched types, extract headings from note content and validate against required list 4. For `doc` type: pass through (intentionally unguarded) ### Heading Format Templates use HTML `<h3>` tags in their code blocks. The hook must grep for `<h3>` patterns OR markdown `### ` patterns (some notes use HTML, some use markdown). Recommend: check for both formats with `grep -iE '(<h3[^>]*>|^### )' `. ### Acceptance Criteria - [ ] Creating a `review` note without required headings is blocked - [ ] Creating an `architecture` note without required headings is blocked - [ ] Creating a `user-story` note without required headings is blocked - [ ] Creating a `sop` note without required headings is blocked - [ ] Creating a `convention` note without required headings is blocked - [ ] Creating a `validation` note without required headings is blocked - [ ] Creating a `doc` note is NOT blocked (intentionally unguarded) - [ ] Existing validated types (project-page) still work ### Test Expectations - [ ] Manual test: create note with each type missing required headings, verify blocked - [ ] Manual test: create note with correct headings, verify allowed - Run command: manual hook testing via Claude Code session ### Constraints - All 6 template notes exist: template-review, template-architecture, template-user-story, template-sop, template-convention, template-validation - Hook runs as PreToolUse on create_note only (settings.json matcher: `mcp__pal-e-docs__create_note`) - Must handle both HTML and markdown heading formats ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `project-pal-e-agency` - `forgejo_admin/claude-custom #180` -- parent spike ### Review History - review-183-2026-03-27: NEEDS_REFINEMENT — Missing required headings table, routing mechanism not specified, HTML/markdown format mismatch, template-validation missing from scope. All 4 gaps fixed in this update. - review-483-2026-03-27-r2: NEEDS_REFINEMENT — 2 nits: (1) validation heading list missing "Discovered Issues", (2) Constraints claimed hook wires both create_note and update_note but settings.json only wires create_note. Both fixed.

forgejo_admin commented

2026-03-28 05:45:38 +00:00

Author

Contributor

Scope Review: NEEDS_REFINEMENT

Review note: review-483-2026-03-27-r2

Issue is well-structured after R1 refinements. Two remaining gaps found:

Validation type heading list incomplete: The ### Required Headings Per Type table lists 4 headings for validation (Ticket, Environment, Checks, Verdict) but the actual template-validation code block has a 5th required heading: "Discovered Issues". Add it to the table.
Constraints claim inaccurate re: update_note: Constraints say "Hook runs as PreToolUse on create_note and update_note" but settings.json only wires mcp__pal-e-docs__create_note. Either clarify that wiring update_note is out of scope, or expand scope to include it (adding a 9th AC).

## Scope Review: NEEDS_REFINEMENT Review note: `review-483-2026-03-27-r2` Issue is well-structured after R1 refinements. Two remaining gaps found: - **Validation type heading list incomplete**: The `### Required Headings Per Type` table lists 4 headings for `validation` (Ticket, Environment, Checks, Verdict) but the actual `template-validation` code block has a 5th required heading: "Discovered Issues". Add it to the table. - **Constraints claim inaccurate re: update_note**: Constraints say "Hook runs as PreToolUse on create_note and update_note" but `settings.json` only wires `mcp__pal-e-docs__create_note`. Either clarify that wiring `update_note` is out of scope, or expand scope to include it (adding a 9th AC).

forgejo_admin commented

2026-03-28 05:51:34 +00:00

Author

Contributor

Scope Review: READY

Review note: review-483-2026-03-27-r3
All prior refinement nits resolved. Heading tables verified against all 6 template notes. Constraints correctly state create_note only (confirmed in settings.json). Validation type includes "Discovered Issues." Dependencies satisfied (all 6 templates exist, NoteType enum updated). Single file, single repo, <5 min agent scope. Ready for execution.

## Scope Review: READY Review note: `review-483-2026-03-27-r3` All prior refinement nits resolved. Heading tables verified against all 6 template notes. Constraints correctly state create_note only (confirmed in settings.json). Validation type includes "Discovered Issues." Dependencies satisfied (all 6 templates exist, NoteType enum updated). Single file, single repo, <5 min agent scope. Ready for execution.