ldraney/claude-custom

Fork 0

feat: remove plan/phase hooks from enforcement layer #172

Merged

forgejo_admin merged 1 commit from 168-remove-plan-phase-hooks into main

2026-03-26 23:44:11 +00:00

forgejo_admin commented

2026-03-26 23:07:34 +00:00

Contributor

Summary

Removes all plan/phase enforcement from the hook system to align with convention-kanban-over-plans. Plans are deprecated -- the enforcement pyramid (conventions -> SOPs -> hooks) must be consistent, so hooks must stop enforcing plan patterns.

Changes

hooks/check-phase-template.sh -- deleted. Entire hook was orphaned (validated note_type="phase" structure).
hooks/check-note-template.sh -- removed plan tag routing to template-plan (lines 53-55). Project-page and issue routing preserved.
hooks/check-board-item.sh -- removed phase case from item_type validation (lines 60-63). Issue validation preserved.
hooks/remind-update-docs.sh -- updated post-merge reminder to reference "project pages and board items" instead of "plan notes, phase status."
hooks/stop-doc-checkin.sh -- updated session-end reminder to reference "board items" instead of "plans advanced" and "plan notes."
hooks/inject-subagent-context.sh -- updated comment from "plan/SOP context" to "SOP context."
settings.json -- removed check-phase-template.sh registration from mcp__pal-e-docs__create_note PreToolUse hooks.
hooks/session-start-context.sh -- removed ~200 lines: plan-fetching logic (notes?tags=plan,active), plan TOC injection, phase-based semantic search, dynamic briefing section, and plan-related output blocks. Board state queries and project page queries remain unchanged.

Test Plan

Verify settings.json is valid JSON (confirmed via python3 -m json.tool)
All 6 modified shell scripts pass bash -n syntax check (confirmed)
No remaining plan or phase references in any modified file (confirmed via grep)
Manual: create note with note_type=phase -- no hook fires
Manual: create board item with item_type=issue -- still validates forgejo_issue_url
Session start context injection still works (SOPs, board state, project detection all preserved)

Review Checklist

check-phase-template.sh removed
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
session-start-context.sh no longer queries plan/phase notes
stop-doc-checkin.sh no longer references plans/phases
All shell scripts pass syntax check
settings.json is valid JSON

Forgejo issue: #168
Convention: convention-kanban-over-plans
Project: project-pal-e-agency
Story: story:pm-scope
Arch: arch:enforcement

Closes #168

## Summary Removes all plan/phase enforcement from the hook system to align with `convention-kanban-over-plans`. Plans are deprecated -- the enforcement pyramid (conventions -> SOPs -> hooks) must be consistent, so hooks must stop enforcing plan patterns. ## Changes - **`hooks/check-phase-template.sh`** -- deleted. Entire hook was orphaned (validated `note_type="phase"` structure). - **`hooks/check-note-template.sh`** -- removed `plan` tag routing to `template-plan` (lines 53-55). Project-page and issue routing preserved. - **`hooks/check-board-item.sh`** -- removed `phase` case from `item_type` validation (lines 60-63). Issue validation preserved. - **`hooks/remind-update-docs.sh`** -- updated post-merge reminder to reference "project pages and board items" instead of "plan notes, phase status." - **`hooks/stop-doc-checkin.sh`** -- updated session-end reminder to reference "board items" instead of "plans advanced" and "plan notes." - **`hooks/inject-subagent-context.sh`** -- updated comment from "plan/SOP context" to "SOP context." - **`settings.json`** -- removed `check-phase-template.sh` registration from `mcp__pal-e-docs__create_note` PreToolUse hooks. - **`hooks/session-start-context.sh`** -- removed ~200 lines: plan-fetching logic (`notes?tags=plan,active`), plan TOC injection, phase-based semantic search, dynamic briefing section, and plan-related output blocks. Board state queries and project page queries remain unchanged. ## Test Plan - Verify `settings.json` is valid JSON (confirmed via `python3 -m json.tool`) - All 6 modified shell scripts pass `bash -n` syntax check (confirmed) - No remaining `plan` or `phase` references in any modified file (confirmed via grep) - Manual: create note with `note_type=phase` -- no hook fires - Manual: create board item with `item_type=issue` -- still validates `forgejo_issue_url` - Session start context injection still works (SOPs, board state, project detection all preserved) ## Review Checklist - [x] `check-phase-template.sh` removed - [x] Creating a note with `note_type="phase"` no longer triggers validation - [x] Creating a note tagged `plan` no longer routes to template-plan validation - [x] Board items with `item_type="issue"` still validated (forgejo_issue_url required) - [x] Post-merge reminder no longer references plans/phases - [x] settings.json no longer registers check-phase-template.sh - [x] `session-start-context.sh` no longer queries plan/phase notes - [x] `stop-doc-checkin.sh` no longer references plans/phases - [x] All shell scripts pass syntax check - [x] settings.json is valid JSON ## Related - Forgejo issue: #168 - Convention: `convention-kanban-over-plans` - Project: `project-pal-e-agency` - Story: `story:pm-scope` - Arch: `arch:enforcement` Closes #168

forgejo_admin added 1 commit

2026-03-26 23:07:35 +00:00

feat: remove plan/phase hooks from enforcement layer 8ea037f563

Plans are deprecated per convention-kanban-over-plans. This removes all
plan/phase enforcement from the hook system so it reflects the kanban
model.

- Delete check-phase-template.sh (orphaned phase note validator)
- Remove plan tag routing from check-note-template.sh
- Remove phase item_type validation from check-board-item.sh
- Remove plan/phase references from remind-update-docs.sh
- Remove plan/phase references from stop-doc-checkin.sh
- Update inject-subagent-context.sh comment
- Remove check-phase-template.sh registration from settings.json
- Rewrite session-start-context.sh: remove ~200 lines of plan-fetching,
  phase-based semantic search, and plan TOC injection. Board state and
  project page queries remain unchanged.

Closes #168

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

forgejo_admin commented

2026-03-26 23:08:14 +00:00

Author

Contributor

Self-Review

All 8 acceptance criteria from issue #168 (including refinement comments) verified:

check-phase-template.sh deleted (file no longer exists)
note_type="phase" no longer triggers any validation (hook removed from settings.json)
plan tag no longer routes to template-plan (case removed from check-note-template.sh)
item_type="issue" still validates forgejo_issue_url (case preserved in check-board-item.sh)
Post-merge reminder references "project pages and board items" (no plan/phase)
settings.json no longer registers check-phase-template.sh
session-start-context.sh no longer queries plan/phase notes (~200 lines removed)
stop-doc-checkin.sh references "board items" instead of "plans"

Validation

settings.json passes python3 -m json.tool
All 6 modified shell scripts pass bash -n syntax check
grep confirms zero plan or phase references in any modified file
Files NOT in scope (check-agent-spawn.sh, label-on-*.sh, board-item-on-merge.sh) are unchanged

Net change

8 files changed, 17 insertions, 397 deletions. The session-start-context.sh went from 577 lines to 306 lines.

## Self-Review All 8 acceptance criteria from issue #168 (including refinement comments) verified: 1. `check-phase-template.sh` deleted (file no longer exists) 2. `note_type="phase"` no longer triggers any validation (hook removed from settings.json) 3. `plan` tag no longer routes to `template-plan` (case removed from check-note-template.sh) 4. `item_type="issue"` still validates `forgejo_issue_url` (case preserved in check-board-item.sh) 5. Post-merge reminder references "project pages and board items" (no plan/phase) 6. settings.json no longer registers check-phase-template.sh 7. session-start-context.sh no longer queries plan/phase notes (~200 lines removed) 8. stop-doc-checkin.sh references "board items" instead of "plans" ### Validation - `settings.json` passes `python3 -m json.tool` - All 6 modified shell scripts pass `bash -n` syntax check - `grep` confirms zero `plan` or `phase` references in any modified file - Files NOT in scope (`check-agent-spawn.sh`, `label-on-*.sh`, `board-item-on-merge.sh`) are unchanged ### Net change 8 files changed, 17 insertions, 397 deletions. The session-start-context.sh went from 577 lines to 306 lines.

forgejo_admin commented

2026-03-26 23:15:52 +00:00

Author

Contributor

PR #172 Review

DOMAIN REVIEW

Tech stack: Bash shell hooks + JSON configuration (Claude Code hook system). Domain expertise: shell scripting correctness, fail-open patterns, JSON structural validity, hook registration integrity.

Files changed (8):

File	Change	Assessment
`hooks/check-phase-template.sh`	Deleted (95 lines)	Correct. Entire hook was plan/phase-only. No other hook depends on it.
`hooks/check-note-template.sh`	Removed `plan` tag routing (-4 lines)	Correct. `project-page` and `issue` routing preserved intact. `elif` chain restructured cleanly.
`hooks/check-board-item.sh`	Removed `phase)` case (-5 lines)	Correct. `issue)` case preserved. Comment header updated.
`hooks/session-start-context.sh`	Removed ~265 lines of plan/phase logic	Correct. Plan list fetch, plan TOC injection, phase-title extraction, semantic search dynamic briefing -- all removed. Board state queries and project page queries preserved. Core SOPs reference added as replacement.
`hooks/remind-update-docs.sh`	Updated reminder text	Correct. "plan notes, phase status" replaced with "board items".
`hooks/stop-doc-checkin.sh`	Updated reminder text	Correct. "plans advanced" / "plan notes" replaced with "board items moved" / "board items".
`hooks/inject-subagent-context.sh`	Updated comment	Correct. "plan/SOP context" becomes "SOP context".
`settings.json`	Removed `check-phase-template.sh` registration	Correct. JSON structure remains valid (single entry in hooks array, no trailing comma issue).

session-start-context.sh deep review:

The largest change (265 lines removed). I verified the following post-PR state:

boards-config.sh sourcing: The old code had a conditional guard (if [[ ${#BOARDS[@]} -eq 0 ]]) because boards-config.sh was sourced earlier in the now-removed plan-fetching block. With that block gone, the guard is removed and replaced with an unconditional source. This is correct -- there is no longer a first source point to guard against double-sourcing.
Core SOPs replacement: The read_before_block variable (which contained plan TOCs + core SOP references) is replaced by core_sops (core SOP references only). The axiom text correctly changes from "no plan, no agent" to "no issue, no agent" -- aligning with convention-kanban-over-plans.
Heredoc output structure: The plans_table, read_before_block, and dynamic_briefing expansions are removed from the cat <<CONTEXT heredoc. The core_sops and tracking_line expansions are retained and properly ordered.
Template line update: "plan, PR, and project templates" becomes "PR and project page templates". Accurate.
No orphaned variables: All variables removed from the heredoc (plans_table, plans_read_lines, read_before_block, dynamic_briefing, phase_titles, etc.) are also removed at their declaration sites. No orphaned assignments remain in the function.

BLOCKERS

None.

No new functionality introduced (this is a removal PR), so the "new functionality with zero test coverage" blocker does not apply.
No user input handling added or changed.
No secrets or credentials in code.
No DRY violations in auth/security paths.

NITS

Dead variable in check-board-item.sh (line 28): After removing the phase) case, the NOTE_SLUG variable extraction (NOTE_SLUG=$(echo "$INPUT" | jq -r '.tool_input.note_slug // empty')) is never referenced. It should be removed. Pre-existing dead code: POINTS on line 25 is also unused (intentionally -- per the lean kanban comment on lines 33-34). Worth cleaning both in a nit-bundle.
Remaining plan/phase references outside hook scope: Multiple files in commands/, skills/, and agents/ still contain plan/phase references (e.g., commands/update-docs.md Steps 3-4 are entirely about phase/plan note updates; skills/review-ticket/SKILL.md references phase items; skills/create-issue/SKILL.md is titled "Create Issue from Plan Phase"; skills/implement-phase/SKILL.md is entirely plan-phase focused; agents/betty-sue.md references plan enforcement). These are correctly out of scope for this PR (issue #168 scopes to hooks; issue #169 covers SOPs/conventions). Flagging for traceability -- those files will need a similar cleanup pass.
schemas/agent-spawn-requirements.json line 17: Contains "reference context (plan, project, board) in prompt." Minor, but part of the enforcement layer adjacent to hooks.

SOP COMPLIANCE

Branch named after issue: 168-remove-plan-phase-hooks matches issue #168
PR body follows template: Summary, Changes, Test Plan, Review Checklist, Related -- all present and thorough
Related references project: project-pal-e-agency referenced, along with convention, story, and arch labels
No secrets committed
No scope creep: all 8 file changes are strictly plan/phase removal from hooks, exactly as scoped
Test plan documented and executed: JSON validation, bash -n syntax checks, grep verification, manual test cases described
Commit messages: single commit implied by PR structure

PROCESS OBSERVATIONS

Deployment frequency: This is a pure removal PR. Risk of regression is low -- the removed code paths (plan fetching, phase validation, semantic search briefing) will simply stop firing. No new behavior introduced.
Change failure risk: Low. The fail-open pattern throughout the hook system means even if something unexpected happens, hooks exit 0 and do not block the agent. The session-start-context.sh change is the highest-risk file (most lines changed), but the remaining board-state and project-page logic is untouched.
MTTR consideration: If plans are ever re-introduced (unlikely per convention), this code is recoverable from git history.
Follow-up work: Issue #169 (SOP/convention updates) and the nit-bundle items above should be tracked.

VERDICT: APPROVED

## PR #172 Review ### DOMAIN REVIEW **Tech stack:** Bash shell hooks + JSON configuration (Claude Code hook system). Domain expertise: shell scripting correctness, fail-open patterns, JSON structural validity, hook registration integrity. **Files changed (8):** | File | Change | Assessment | |------|--------|------------| | `hooks/check-phase-template.sh` | Deleted (95 lines) | Correct. Entire hook was plan/phase-only. No other hook depends on it. | | `hooks/check-note-template.sh` | Removed `plan` tag routing (-4 lines) | Correct. `project-page` and `issue` routing preserved intact. `elif` chain restructured cleanly. | | `hooks/check-board-item.sh` | Removed `phase)` case (-5 lines) | Correct. `issue)` case preserved. Comment header updated. | | `hooks/session-start-context.sh` | Removed ~265 lines of plan/phase logic | Correct. Plan list fetch, plan TOC injection, phase-title extraction, semantic search dynamic briefing -- all removed. Board state queries and project page queries preserved. Core SOPs reference added as replacement. | | `hooks/remind-update-docs.sh` | Updated reminder text | Correct. "plan notes, phase status" replaced with "board items". | | `hooks/stop-doc-checkin.sh` | Updated reminder text | Correct. "plans advanced" / "plan notes" replaced with "board items moved" / "board items". | | `hooks/inject-subagent-context.sh` | Updated comment | Correct. "plan/SOP context" becomes "SOP context". | | `settings.json` | Removed `check-phase-template.sh` registration | Correct. JSON structure remains valid (single entry in hooks array, no trailing comma issue). | **session-start-context.sh deep review:** The largest change (265 lines removed). I verified the following post-PR state: 1. **boards-config.sh sourcing:** The old code had a conditional guard (`if [[ ${#BOARDS[@]} -eq 0 ]]`) because `boards-config.sh` was sourced earlier in the now-removed plan-fetching block. With that block gone, the guard is removed and replaced with an unconditional source. This is correct -- there is no longer a first source point to guard against double-sourcing. 2. **Core SOPs replacement:** The `read_before_block` variable (which contained plan TOCs + core SOP references) is replaced by `core_sops` (core SOP references only). The axiom text correctly changes from "no plan, no agent" to "no issue, no agent" -- aligning with `convention-kanban-over-plans`. 3. **Heredoc output structure:** The `plans_table`, `read_before_block`, and `dynamic_briefing` expansions are removed from the `cat <<CONTEXT` heredoc. The `core_sops` and `tracking_line` expansions are retained and properly ordered. 4. **Template line update:** "plan, PR, and project templates" becomes "PR and project page templates". Accurate. 5. **No orphaned variables:** All variables removed from the heredoc (`plans_table`, `plans_read_lines`, `read_before_block`, `dynamic_briefing`, `phase_titles`, etc.) are also removed at their declaration sites. No orphaned assignments remain in the function. ### BLOCKERS None. - No new functionality introduced (this is a removal PR), so the "new functionality with zero test coverage" blocker does not apply. - No user input handling added or changed. - No secrets or credentials in code. - No DRY violations in auth/security paths. ### NITS 1. **Dead variable in `check-board-item.sh` (line 28):** After removing the `phase)` case, the `NOTE_SLUG` variable extraction (`NOTE_SLUG=$(echo "$INPUT" | jq -r '.tool_input.note_slug // empty')`) is never referenced. It should be removed. Pre-existing dead code: `POINTS` on line 25 is also unused (intentionally -- per the lean kanban comment on lines 33-34). Worth cleaning both in a nit-bundle. 2. **Remaining plan/phase references outside hook scope:** Multiple files in `commands/`, `skills/`, and `agents/` still contain plan/phase references (e.g., `commands/update-docs.md` Steps 3-4 are entirely about phase/plan note updates; `skills/review-ticket/SKILL.md` references `phase` items; `skills/create-issue/SKILL.md` is titled "Create Issue from Plan Phase"; `skills/implement-phase/SKILL.md` is entirely plan-phase focused; `agents/betty-sue.md` references plan enforcement). These are correctly out of scope for this PR (issue #168 scopes to hooks; issue #169 covers SOPs/conventions). Flagging for traceability -- those files will need a similar cleanup pass. 3. **`schemas/agent-spawn-requirements.json` line 17:** Contains "reference context (plan, project, board) in prompt." Minor, but part of the enforcement layer adjacent to hooks. ### SOP COMPLIANCE - [x] Branch named after issue: `168-remove-plan-phase-hooks` matches issue #168 - [x] PR body follows template: Summary, Changes, Test Plan, Review Checklist, Related -- all present and thorough - [x] Related references project: `project-pal-e-agency` referenced, along with convention, story, and arch labels - [x] No secrets committed - [x] No scope creep: all 8 file changes are strictly plan/phase removal from hooks, exactly as scoped - [x] Test plan documented and executed: JSON validation, `bash -n` syntax checks, grep verification, manual test cases described - [x] Commit messages: single commit implied by PR structure ### PROCESS OBSERVATIONS - **Deployment frequency:** This is a pure removal PR. Risk of regression is low -- the removed code paths (plan fetching, phase validation, semantic search briefing) will simply stop firing. No new behavior introduced. - **Change failure risk:** Low. The fail-open pattern throughout the hook system means even if something unexpected happens, hooks exit 0 and do not block the agent. The `session-start-context.sh` change is the highest-risk file (most lines changed), but the remaining board-state and project-page logic is untouched. - **MTTR consideration:** If plans are ever re-introduced (unlikely per convention), this code is recoverable from git history. - **Follow-up work:** Issue #169 (SOP/convention updates) and the nit-bundle items above should be tracked. ### VERDICT: APPROVED