Feature: Remove plan/phase hooks from enforcement layer

forgejo_admin commented

2026-03-26 17:23:40 +00:00

Contributor

Type

Feature

Lineage

standalone — discovered during plan deprecation audit 2026-03-26

Repo

forgejo_admin/claude-custom

User Story

As Betty Sue (PM),
I want the enforcement layer to stop validating plan/phase artifacts,
So that the system reflects the kanban-over-plans convention and doesn't enforce deprecated patterns.

Context

convention-kanban-over-plans (2026-03-24) declared plans deprecated. But 5 hook code points still reference plans/phases. These create confusion: agents see phase validation hooks and assume phases are current. The enforcement pyramid (conventions → SOPs → hooks) must be consistent — if the convention says plans are dead, the hooks must stop enforcing plan patterns.

File Targets

Remove check-phase-template.sh — entire hook orphaned. Validates note_type="phase" structure. No longer needed.
- File: hooks/check-phase-template.sh (delete or rename to .deprecated)
Remove plan routing from check-note-template.sh — lines 53-55 route plan tag to template-plan. Remove this case.
- File: hooks/check-note-template.sh lines 53-55
Remove phase item_type from check-board-item.sh — lines 60-63 validate phase items require note_slug. Remove this case.
- File: hooks/check-board-item.sh lines 60-63
Update remind-update-docs.sh — line 34 mentions "plan notes, phase status." Update to reference board items and project pages instead.
- File: hooks/remind-update-docs.sh line ~34
Update settings.json — remove check-phase-template.sh from PreToolUse hooks on mcp__pal-e-docs__create_note.
- File: settings.json (find the check-phase-template.sh registration)

Files NOT to touch:

check-agent-spawn.sh — no plan dependency (only validates issue reference pattern)
label-on-branch.sh, label-on-pr.sh, label-on-verdict.sh — no plan dependency
board-item-on-merge.sh — matches by forgejo_issue_url, no plan dependency

Acceptance Criteria

check-phase-template.sh removed or disabled
Creating a note with note_type="phase" no longer triggers validation
Creating a note tagged plan no longer routes to template-plan validation
Board items with item_type="issue" still validated (forgejo_issue_url required)
Post-merge reminder no longer references plans/phases
settings.json no longer registers check-phase-template.sh

Test Expectations

Manual test: create note with note_type=phase → no hook fires
Manual test: create board item with item_type=issue → still validates forgejo_issue_url
Verify settings.json is valid JSON after edit

Constraints

Fail-open pattern preserved on all remaining hooks
Don't break existing board items that have item_type=phase (they just won't get validated on future creation)

Checklist

PR opened
Tests pass
No unrelated changes

project-pal-e-agency — project
story:pm-scope — user story
arch:enforcement — architecture component
convention-kanban-over-plans — the convention this implements

### Type Feature ### Lineage standalone — discovered during plan deprecation audit 2026-03-26 ### Repo `forgejo_admin/claude-custom` ### User Story As Betty Sue (PM), I want the enforcement layer to stop validating plan/phase artifacts, So that the system reflects the kanban-over-plans convention and doesn't enforce deprecated patterns. ### Context `convention-kanban-over-plans` (2026-03-24) declared plans deprecated. But 5 hook code points still reference plans/phases. These create confusion: agents see phase validation hooks and assume phases are current. The enforcement pyramid (conventions → SOPs → hooks) must be consistent — if the convention says plans are dead, the hooks must stop enforcing plan patterns. ### File Targets 1. **Remove `check-phase-template.sh`** — entire hook orphaned. Validates `note_type="phase"` structure. No longer needed. - File: `hooks/check-phase-template.sh` (delete or rename to `.deprecated`) 2. **Remove plan routing from `check-note-template.sh`** — lines 53-55 route `plan` tag to `template-plan`. Remove this case. - File: `hooks/check-note-template.sh` lines 53-55 3. **Remove phase item_type from `check-board-item.sh`** — lines 60-63 validate phase items require `note_slug`. Remove this case. - File: `hooks/check-board-item.sh` lines 60-63 4. **Update `remind-update-docs.sh`** — line 34 mentions "plan notes, phase status." Update to reference board items and project pages instead. - File: `hooks/remind-update-docs.sh` line ~34 5. **Update `settings.json`** — remove `check-phase-template.sh` from PreToolUse hooks on `mcp__pal-e-docs__create_note`. - File: `settings.json` (find the check-phase-template.sh registration) Files NOT to touch: - `check-agent-spawn.sh` — no plan dependency (only validates issue reference pattern) - `label-on-branch.sh`, `label-on-pr.sh`, `label-on-verdict.sh` — no plan dependency - `board-item-on-merge.sh` — matches by forgejo_issue_url, no plan dependency ### Acceptance Criteria - [ ] `check-phase-template.sh` removed or disabled - [ ] Creating a note with `note_type="phase"` no longer triggers validation - [ ] Creating a note tagged `plan` no longer routes to template-plan validation - [ ] Board items with `item_type="issue"` still validated (forgejo_issue_url required) - [ ] Post-merge reminder no longer references plans/phases - [ ] settings.json no longer registers check-phase-template.sh ### Test Expectations - Manual test: create note with note_type=phase → no hook fires - Manual test: create board item with item_type=issue → still validates forgejo_issue_url - Verify settings.json is valid JSON after edit ### Constraints - Fail-open pattern preserved on all remaining hooks - Don't break existing board items that have item_type=phase (they just won't get validated on future creation) ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `project-pal-e-agency` — project - `story:pm-scope` — user story - `arch:enforcement` — architecture component - `convention-kanban-over-plans` — the convention this implements

forgejo_admin commented

2026-03-26 17:29:44 +00:00

Author

Contributor

Scope Review: NEEDS_REFINEMENT

Review note: review-396-2026-03-26
Ticket identifies 5 correct file targets but misses the 3 largest plan/phase code points in the hooks directory.

hooks/session-start-context.sh (lines 112-260+) — ~150 lines of active plan-fetching logic (queries notes?tags=plan,active, injects plan TOCs, extracts phase titles for semantic search). Runs every session start. This is the highest-impact omission.
hooks/stop-doc-checkin.sh (lines 9-10) — references "plans advanced" and "plan notes." Runs every session stop.
hooks/inject-subagent-context.sh (line 2) — comment says "plan/SOP context." Minor, comment-only.
Missing acceptance criteria for the above files.

## Scope Review: NEEDS_REFINEMENT Review note: `review-396-2026-03-26` Ticket identifies 5 correct file targets but misses the 3 largest plan/phase code points in the hooks directory. - **`hooks/session-start-context.sh` (lines 112-260+)** — ~150 lines of active plan-fetching logic (queries `notes?tags=plan,active`, injects plan TOCs, extracts phase titles for semantic search). Runs every session start. This is the highest-impact omission. - **`hooks/stop-doc-checkin.sh` (lines 9-10)** — references "plans advanced" and "plan notes." Runs every session stop. - **`hooks/inject-subagent-context.sh` (line 2)** — comment says "plan/SOP context." Minor, comment-only. - Missing acceptance criteria for the above files.

forgejo_admin commented

2026-03-26 17:30:12 +00:00

Author

Contributor

Refinement: 2 missed files (one critical)

Per review review-396-2026-03-26:

Critical Missing File Target

hooks/session-start-context.sh lines 112-260+ — ~150 lines querying pal-e-docs for notes?tags=plan,active, fetching plan details/TOCs, extracting in-progress phase titles for semantic search, injecting into session startup context. This is the LARGEST plan/phase code point in the hook system and runs on every session start. Must be updated to query boards/project pages instead of plans/phases.

Minor Missing File Target

hooks/stop-doc-checkin.sh lines 9-10 — references "plans advanced" and "plan notes in pal-e-docs" in session-end reminder. Update to reference board items and project pages.

Updated Acceptance Criteria (appended)

session-start-context.sh no longer queries plan/phase notes — queries boards and project pages instead
stop-doc-checkin.sh no longer references plans/phases

## Refinement: 2 missed files (one critical) Per review `review-396-2026-03-26`: ### Critical Missing File Target 6. **`hooks/session-start-context.sh` lines 112-260+** — ~150 lines querying pal-e-docs for `notes?tags=plan,active`, fetching plan details/TOCs, extracting in-progress phase titles for semantic search, injecting into session startup context. This is the LARGEST plan/phase code point in the hook system and runs on every session start. Must be updated to query boards/project pages instead of plans/phases. ### Minor Missing File Target 7. **`hooks/stop-doc-checkin.sh` lines 9-10** — references "plans advanced" and "plan notes in pal-e-docs" in session-end reminder. Update to reference board items and project pages. ### Updated Acceptance Criteria (appended) - [ ] `session-start-context.sh` no longer queries plan/phase notes — queries boards and project pages instead - [ ] `stop-doc-checkin.sh` no longer references plans/phases

forgejo_admin commented

2026-03-26 22:21:32 +00:00

Author

Contributor

Scope Review: READY (re-review)

Review note: review-396-2026-03-26-r2
Refinement comment addresses the critical session-start-context.sh gap. All 7 plan/phase-containing hook files now identified with verified line references. 8 acceptance criteria are agent-testable. No blocking dependencies. Scope is complete and ready for execution.

## Scope Review: READY (re-review) Review note: `review-396-2026-03-26-r2` Refinement comment addresses the critical session-start-context.sh gap. All 7 plan/phase-containing hook files now identified with verified line references. 8 acceptance criteria are agent-testable. No blocking dependencies. Scope is complete and ready for execution.