pal-e-docs

Review: Board API: update_board_item should support title field

review-281-2026-03-22 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Lineage
  • [x] Repo
  • [x] User Story
  • [x] Context
  • [x] File Targets
  • [x] Acceptance Criteria
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related
All required template sections present. Well-structured issue.

File Targets

  • [x] src/pal_e_docs/routes/boards.py — verified exists. However, update_board_item (line 611) and BoardItemUpdate schema (line 295 in schemas.py) already support title. AC #1 is already satisfied at the API layer.
  • [ ] src/pal_e_docs/services/board_sync.py — ISSUE: file does not exist. Sync logic lives in src/pal_e_docs/routes/boards.py (function sync_board at line 251). File target is wrong.
  • [x] src/pal_e_docs/routes/notes.py — verified exists; correctly marked as do-not-touch.

Missing File Target: MCP Layer

The actual gap is in pal-e-docs-mcp, not pal-e-docs. The MCP tool update_board_item in pal-e-docs-mcp/src/pal_e_docs_mcp/tools/boards.py (line 209) does not expose a title parameter, even though both the SDK (pal-e-docs-sdk/src/pal_e_docs_sdk/boards.py line 136) and the API already support it. This is the root cause of the reported inability to update titles programmatically.

Repo Placement

MISMATCH. The Forgejo issue is filed on forgejo_admin/pal-e-docs. The fix has two parts:
  • sync_board title drift — correct repo (pal-e-docs, in routes/boards.py)
  • MCP title param — wrong repo. Fix belongs in forgejo_admin/pal-e-docs-mcp
This means the issue either needs to be split into two Forgejo issues (one per repo), or scoped down to only the sync_board fix (since the API already works). The MCP gap needs its own issue on pal-e-docs-mcp.

Dependencies

  • No blocking dependencies found on the board.
  • Item #48 (MCP sprint tools cannot clear points/labels) is tangentially related to board API but not a blocker.
  • The SDK already supports title — no SDK change needed.

Acceptance Criteria

  • AC #1 (PUT /boards/{slug}/items/{id} accepts optional title): Already implemented. The endpoint is PATCH, not PUT — minor inaccuracy. Verified: BoardItemUpdate.title exists at schemas.py:295, handler at boards.py:611.
  • AC #2 (sync_board detects title drift on phase items): Valid gap. sync_board lines 298-303 only check column drift. Note: sync_issues already handles title drift for issue-type items (lines 394-399), so the pattern exists and can be followed.
  • AC #3 (existing items without title changes are unaffected): Testable, valid criterion.
AC #1 should be rewritten to target the MCP layer, or removed if that becomes a separate issue.

Test Expectations

  • Test command pytest tests/ -k board is valid.
  • Existing test test_sync_sets_title_from_phase_note covers initial title population but not title drift on re-sync.
  • A test for title drift detection on phase re-sync is the correct test to add.
  • MCP-layer tests would need to live in pal-e-docs-mcp repo, not here.

Blast Radius

  • sync_issues already handles title drift for issue-type items — no blast radius there.
  • sync_board only affects phase-type items linked to plan notes. Low blast radius.
  • The MCP gap affects all MCP consumers (Claude agents). Until the MCP tool exposes title, no agent can programmatically update board item titles despite the API supporting it.

Recommendation

Three specific actions before this ticket is READY:
  • Fix file target: Replace src/pal_e_docs/services/board_sync.py with src/pal_e_docs/routes/boards.py (function sync_board at line 251).
  • Split or rescope: AC #1 is already done at the API/SDK layer. The real gap is the MCP tool in pal-e-docs-mcp. Either (a) remove AC #1 and scope this issue to only the sync_board title drift fix, or (b) split into two issues — one for sync_board (pal-e-docs) and one for MCP title param (pal-e-docs-mcp).
  • Minor fix: AC #1 says "PUT" but the endpoint is PATCH. Correct the HTTP method.