pal-e-docs

Review: Add validation column to board schema and API

review-241-2026-03-28 Review

review block
Project

Verdict: BLOCK

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — board, story, arch, enables
  • [x] Repo — forgejo_admin/pal-e-api
  • [x] User Story — PM wants validation column between needs_approval and done
  • [x] Context — explains gap between SOP and API
  • [x] File Targets — 3 targets listed
  • [x] Acceptance Criteria — 5 criteria
  • [x] Test Expectations — 4 test items + run command
  • [x] Constraints — 3 constraints listed
  • [x] Checklist — 6 items
  • [x] Related — sop-board-workflow, convention-validation-checkpoints
All template sections present and well-formed.

Traceability

  • [x] story:superuser-maintain — present on board item
  • [x] arch:board-api — present on board item
  • [x] Forgejo issue — forgejo_admin/pal-e-api#241, open

File Targets

  • [x] src/pal_e_docs/schemas.py — ALREADY DONE: BoardColumnType Literal at line 226 already includes "validation" (line 233)
  • [x] src/pal_e_docs/routes/boards.py — ALREADY DONE: All board routes already handle the validation column via the existing BoardColumn enum
  • [x] alembic/ — ALREADY DONE: Migration r8m9n0o1p2q3_add_validation_board_column.py exists
  • [x] src/pal_e_docs/models.py (not listed in issue but relevant) — ALREADY DONE: BoardColumn enum includes validation = "validation" at line 30
All file targets verified — but the work has already been completed.

Repo Placement

Correct repo (pal-e-api). However, the Constraints section notes the MCP SDK docstring needs updating — that lives in pal-e-mcp (separate repo). The MCP docstrings are stale: list_board_items (line 127-129), create_board_item (line 170-171), and update_board_item (line 268-269) enumerate columns without validation. This is a separate ticket for pal-e-mcp.

Dependencies

  • [x] Board item #522 (Validate: alembic upgrade head — NoteTypes + validation column, pal-e-api#232) — satisfied, in done
  • [x] Board item #524 (Fix 12 failing board_sync tests blocking CI, pal-e-api#233) — satisfied, in done
Both prior items completed the exact work this ticket describes.

Acceptance Criteria

All 5 acceptance criteria are already satisfied in the current codebase:
  • update_board_item(column="validation") — works, tested in test_board_item_validation_column
  • create_board_item(column="validation") — works, BoardColumnType Literal accepts it
  • list_board_items(column="validation") — works, tested in test_board_item_filter_validation_column
  • sync_board handles new column — works, BoardColumn enum used throughout
  • Existing board items unaffected — confirmed, migration is no-op on VARCHAR

Blast Radius

MCP tool docstrings in pal-e-mcp are stale — three tool descriptions (list_board_items, create_board_item, update_board_item) enumerate column values without validation. Agents relying on MCP tool descriptions may not discover the column exists. This is real discovered scope for a separate ticket.

Decomposition Assessment

N/A — the work is already complete. No implementation needed. The ticket should be closed as duplicate rather than executed.
  • Discrete changes: 0 (already done)
  • Estimated agent time: 0 minutes
  • Independent subtasks: none

Recommendation

  • [SCOPE] Close pal-e-api#241 as duplicate. The validation column already exists in the model enum (models.py:30), schema Literal (schemas.py:233), alembic migration (r8m9n0o1p2q3), and has passing tests (test_note_type_enum.py). This work was completed as part of #232/#233.
  • [BODY] Create a new Forgejo issue on forgejo_admin/pal-e-mcp for the stale MCP docstrings — 3 tool descriptions missing "validation" in their column value lists (list_board_items line 127, create_board_item line 170, update_board_item line 268).