pal-e-docs

Review: Remove plan/phase hooks from enforcement layer

review-396-2026-03-26-r2 Review

review ready
Project

Verdict: READY

Template Completeness

  • [x] Type
  • [x] Lineage
  • [x] Repo
  • [x] User Story
  • [x] Context
  • [x] File Targets (5 original + 2 from refinement comment = 7 total, covering all 7 plan/phase-containing hooks)
  • [x] Acceptance Criteria (6 original + 2 from refinement = 8 total)
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related

File Targets

  • [x] hooks/check-phase-template.sh (96 lines) — verified: entire file is phase-only validation. Delete target is correct.
  • [x] hooks/check-note-template.sh lines 53-55 — verified: if echo "$TAGS" | grep -qw "plan" routes to template-plan. Remove this case block.
  • [x] hooks/check-board-item.sh lines 60-63 — verified: phase) case requires note_slug. Remove this case block.
  • [x] hooks/remind-update-docs.sh line 34 — verified: additionalContext string references "plan notes, phase status." Update text.
  • [x] settings.json lines 177-180 — verified: check-phase-template.sh registered under mcp__pal-e-docs__create_note PreToolUse matcher. Remove entry.
  • [x] hooks/session-start-context.sh lines 112-260 — verified: ~150 lines querying notes?tags=plan,active, fetching plan details/TOCs, extracting in-progress phase titles for semantic search, building plans_table and plans_read_lines. Also lines 262-272 build "Active Plan TOCs" block, and lines 539-542 inject plans_table. 74 total occurrences of plan/phase in this file. This is the highest-impact target.
  • [x] hooks/stop-doc-checkin.sh lines 9-10 — verified: "plans advanced" and "plan notes in pal-e-docs." Update text to reference board items and project pages.
Not in scope (correctly excluded):
  • hooks/inject-subagent-context.sh line 2 — comment-only ("inject plan/SOP context"). No functional plan logic in code. Minor, not worth a file target.
  • hooks/check-agent-spawn.sh — no plan dependency (verified).
  • hooks/board-item-on-merge.sh — matches by forgejo_issue_url, no plan dependency (verified).

Repo Placement

OK. All 7 file targets are in forgejo_admin/claude-custom. Issue is filed on the same repo. Single-repo scope.

Dependencies

  • Board item #98 (in_progress): "Context intelligence — behavioral memory + vector-powered startup" (note_slug: phase-pal-e-docs-f13-context-intelligence). This phase built the session-start-context.sh semantic search (F13b). However, that is a pal-e-docs phase, not a claude-custom issue, and the feature is already deployed. No conflict — this ticket cleans the plan-fetching logic that F13b added, which is exactly what kanban-over-plans requires.
  • Board item #397 (todo): "Update 11 SOPs/conventions for kanban-over-plans." Sibling work, same story. No blocking dependency. Could be done in either order.
  • Board item #395 (todo): "Upgrade story: label to hard-block." Same arch:enforcement label. No dependency.
  • No blockers identified. This ticket can proceed independently.

Acceptance Criteria

All 8 criteria are testable by an agent:
  • AC1: check-phase-template.sh removed — verify file absent or renamed to .deprecated
  • AC2: note_type="phase" no longer triggers validation — verify settings.json and hook absence
  • AC3: plan tag no longer routes to template-plan — verify check-note-template.sh updated
  • AC4: item_type="issue" still validates — verify check-board-item.sh still has issue case
  • AC5: Post-merge reminder no longer references plans — grep remind-update-docs.sh
  • AC6: settings.json no longer registers check-phase-template.sh — grep settings.json
  • AC7 (refinement): session-start-context.sh no longer queries plan/phase notes — grep for plan,active query
  • AC8 (refinement): stop-doc-checkin.sh no longer references plans/phases — grep output
All verifiable via grep + file existence checks. Test expectations (manual tests) are realistic.

Blast Radius

  • session-start-context.sh runs on every session start. Removing ~150 lines of plan-fetching logic will change the injected context for all agents. The replacement strategy (query boards/project pages instead) must preserve the dynamic briefing feature (semantic search from in-progress item titles). The ticket's refinement comment correctly calls this out.
  • check-note-template.sh still validates project-page and issue tags after removing plan. No collateral damage.
  • check-board-item.sh still validates issue type after removing phase. No collateral damage.
  • Existing phase board items (14 on this board, all in done/backlog) will stop getting creation-time validation. Ticket's constraints section correctly notes this is acceptable.
  • No downstream services affected. This is hooks-only, no API changes.

Recommendation

No action needed. The original issue body + refinement comment together form a complete, agent-executable spec. All 7 plan/phase-containing hook files are identified with accurate line references. The session-start-context.sh gap (the critical missing file from the first review) is fully addressed in the refinement comment. Scope is ready for execution.