Review: Update MCP tools, SDK, and hooks for board-as-note

Verdict: NEEDS_REFINEMENT

Re-Review Summary (2026-03-24)

• Fix 1 (session-start-context.sh) — VERIFIED. File exists at ~/.claude/hooks/session-start-context.sh (576 lines). Reads board API at lines 157 (GET /boards/{slug}/items?column=in_progress), 398 (GET /boards/{slug}/items), 446 (GET /boards/{slug}/items). Consumes .column, .title, .item_type fields from response JSON. Correctly proposed as verify-only target.
• Fix 2 (method count) — VERIFIED. SDK BoardsMixin has 12 methods: list_boards, create_board, get_board, update_board, delete_board, sync_board, get_backlog, list_board_items, add_board_item, update_board_item, delete_board_item, bulk_move_items. Docstring on line 12 says "11 endpoints" — needs correction. Refinement correctly identifies the fix.
• Fix 3 (#316 board state) — NOT RESOLVED. Refinement comment says "Already resolved — board item #316 is in done column. Reviewer saw stale state." However, board item #316 is currently in todo (position 2). Forgejo issue #197 is closed. The board-item-on-merge hook either did not fire or failed silently. Board item must be moved to done before this ticket starts.

Template Completeness

• [x] Type
• [x] Lineage (variant of Plan — acceptable)
• [x] Repo (3 repos correctly listed)
• [x] User Story
• [x] Context
• [x] File Targets (6 files + 1 verify-only from refinement = 7)
• [x] Acceptance Criteria (5 items)
• [x] Test Expectations (3 items with real commands)
• [x] Constraints
• [x] Checklist
• [x] Related

File Targets

• [x] pal-e-docs-mcp/src/pal_e_docs_mcp/tools/boards.py — verified: 12 MCP tools present
• [x] pal-e-docs-sdk/src/pal_e_docs_sdk/boards.py — verified: 12 methods (docstring says 11, needs fix)
• [x] ~/.claude/hooks/boards-config.sh — verified: 6 board slugs, 21 lines
• [x] ~/.claude/hooks/board-item-on-merge.sh — verified: sources boards-config.sh, searches boards via REST API
• [x] ~/.claude/hooks/check-board-item.sh — verified: validates create_board_item tool calls
• [x] ~/.claude/hooks/session-start-board-sync.sh — verified: syncs all boards via POST /boards/{slug}/sync
• [x] ~/.claude/hooks/session-start-context.sh — verified (from refinement): verify-only target, reads .column/.title/.item_type at 3 locations

Repo Placement

Dependencies

• #195 (Add "board" to NoteType) — board item #314 in done. Forgejo issue closed. OK.
• #196 (Add board_note_id FK + data migration) — board item #315 in done. Forgejo issue closed. OK.
• #197 (Update board API for board notes) — board item #316 still in todo despite Forgejo issue being closed. Stale board state persists. Must be moved to done.
• #199 (Drop legacy boards table) — board item #318 in backlog. Downstream. Correctly sequenced.
• #208 (Refactor sync_board) — board item #327 in backlog. Related but independent.

Acceptance Criteria

• pytest tests/test_param_alignment.py -v — file exists in pal-e-docs-mcp
• pytest tests/ -v — SDK has test_boards.py and integration/test_boards.py
• Manual merge-and-verify appropriate for hook testing

Blast Radius

• session-start-context.sh — now in scope as verify-only target (from refinement). Risk is mitigated if response fields are additive (they are).
• pal-e-app — SvelteKit frontend consumes same REST API. Not in scope (correct). Contract stabilized by prerequisite #197.
• Hook count — Context section says "4 hooks" but there are 4 hooks + 1 config file, plus the newly-scoped session-start-context.sh = 5 hooks + 1 config. Minor editorial inaccuracy in Context section.

Recommendation

• Move board item #316 to done — Forgejo issue #197 is closed but the board item is still in todo. The refinement claimed this was resolved, but current board state shows otherwise. Run: update_board_item(board-pal-e-docs, 316, column="done").