pal-e-docs

Review: Remove plan items from boards + update project page template

review-323-2026-03-24 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Lineage — present (standalone, kanban philosophy alignment)
  • [x] Repo — present (forgejo_admin/pal-e-docs + ~/claude-custom)
  • [x] User Story — present and well-formed
  • [x] Context — present, clear motivation
  • [x] File Targets — present (MCP board operations + template notes)
  • [x] Acceptance Criteria — present, 4 criteria
  • [x] Test Expectations — present, verifiable via list_board_items
  • [x] Constraints — present, 3 constraints clearly stated
  • [x] Checklist — present
  • [x] Related — present
All required sections present. Extra "What Broke" section is acceptable (clarifies this is not a bug).

File Targets

  • [x] template-project-page note — verified exists. Current section order has 9 items including "Plan" at #3 and "Architecture" at #7. Ticket correctly identifies these need reordering.
  • [x] template-ticket note — verified exists. However, arch: label is ALREADY documented in the Label Conventions section (row 2 of the table). The AC "template-ticket mentions arch: label convention" is already satisfied.
  • [x] convention-kanban-over-plans note — verified exists. Contains a "Project Page Template (revised)" section with the proposed 7-item order matching the ticket's intent.
  • [x] Board plan item counts — verified via list_boards. Actual count is 8 plan items across 7 boards, not "~7" as stated:
  • [ ] ~/claude-custom template updates — ISSUE: ticket says "template updates" in claude-custom repo but all template notes (template-project-page, template-ticket) are pal-e-docs notes, not files in claude-custom. No claude-custom file changes are actually needed.

Repo Placement

Mixed. The Forgejo issue is filed on forgejo_admin/pal-e-docs which is correct for the API/template note changes. However, the ticket's Repo field lists ~/claude-custom as a second target — no claude-custom file changes are actually required. The template notes live in pal-e-docs (the database), not in the claude-custom filesystem. This is a minor inaccuracy, not a blocker.

Dependencies

CRITICAL: Undocumented dependency on sync_board endpoint.
The POST /boards/{slug}/sync endpoint (src/pal_e_docs/routes/boards.py:251) explicitly queries plan-type board items to discover child phase notes for syncing:
Removing plan items from boards will cause sync_board to find zero plan items, meaning it will never discover new phases to sync. The /update-docs skill calls sync_board after every merge. This is a functional regression.
Additionally, tests in tests/test_board_sync.py and tests/test_boards.py create plan-type board items for test coverage. These tests would need updating or the sync mechanism needs to be rearchitected to discover phases via plan notes (the notes API) rather than plan board items.
No other board items on board-pal-e-agency block or are blocked by this ticket.

Acceptance Criteria

  • [x] "Zero plan-type items on any board" — verifiable via list_board_items(item_type="plan") per board
  • [x] "template-project-page reflects new section order" — verifiable by reading the note
  • [ ] "template-ticket mentions arch: label convention" — ALREADY TRUE. The arch: label is documented in the Label Conventions table. This AC is pre-satisfied and may cause confusion.
  • [x] "Existing plan notes untouched" — verifiable via list_notes(note_type="plan")
Missing AC: No acceptance criterion addresses the sync_board regression. If plan items are removed, there should be a criterion verifying that phase sync still works (either via a new mechanism or by confirming sync_board is deprecated).

Blast Radius

  • sync_board endpoint — will silently return 0 created / 0 updated / 0 skipped after plan items are removed. No error, just silent no-op. Every /update-docs invocation calls this.
  • MCP sync_board tool (pal-e-docs-mcp/src/pal_e_docs_mcp/tools/boards.py:55) — wraps the same endpoint, same impact.
  • SDK sync_board method (pal-e-docs-sdk/src/pal_e_docs_sdk/boards.py:66) — same.
  • session-start-context.sh — NOT affected. Plans are fetched from the notes API (/notes?tags=plan,active), not from board items.
  • create_board_item MCP tool — still accepts item_type="plan" in its schema. If plan items are being eliminated from boards, should the tool reject them?

Recommendation

Two issues must be resolved before this ticket is READY:
  • Address the sync_board dependency. Either:
  • Remove ~/claude-custom from the Repo field — no files in that repo are affected. All template changes are pal-e-docs note updates.
Minor: update the plan item count from "~7" to "8" and note that the arch: label AC is already satisfied (or reword it to something that isn't already done).