pal-e-docs

Review: Rename BoardItemType 'issue' to 'ticket' for semantic clarity

review-479-2026-03-29 Doc

review ready
Project

Verdict: READY

This is a well-scoped parent/coordination ticket. It does no direct work itself -- all implementation is decomposed into 4 sequenced child tickets across 4 repos. The parent issue serves as the spec and coordination point.

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Standalone, discovered during board item creation workflows
  • [x] Repo -- Cross-repo correctly identified (pal-e-docs, pal-e-docs-sdk, pal-e-mcp, claude-custom)
  • [x] User Story -- Clear persona (platform operator), motivation (eliminate "issue" overloading)
  • [x] Context -- Thorough explanation of the semantic collision and deploy-order rationale
  • [x] File Targets -- Extensive, per-repo, with line numbers and change descriptions
  • [x] Acceptance Criteria -- 10 items, all verifiable
  • [x] Test Expectations -- 4 items with run command
  • [x] Constraints -- 4 constraints including historical migration protection and deploy ordering
  • [x] Checklist -- Present
  • [x] Related -- Present

Traceability

  • [x] story:pm-scope -- present on board item, appropriate for platform operator workflow improvements
  • [x] arch:note-system -- present on board item, correct (BoardItemType is part of the note/board system)
  • [x] Forgejo issue -- forgejo_admin/claude-custom#181, open

File Targets

All file targets verified against current filesystem state:
  • [x] pal-e-docs/src/pal_e_docs/models.py:34-39 -- verified: BoardItemType enum exists with issue = "issue" at line 37
  • [x] pal-e-docs/src/pal_e_docs/schemas.py:225 -- verified: BoardItemTypeType Literal includes "issue"
  • [x] pal-e-docs/src/pal_e_docs/schemas.py:265-268 -- verified: BoardItemCounts has issue: int = 0 at line 268
  • [x] pal-e-docs/src/pal_e_docs/routes/boards.py -- verified: sync endpoint and validation code reference BoardItemType.issue (minor line drift from issue description)
  • [x] pal-e-docs/tests/test_boards.py -- verified: 13 references to item_type.*issue
  • [x] pal-e-docs/tests/test_board_issue_sync.py -- verified: 7 references to item_type.*issue
  • [x] pal-e-docs/tests/test_pagination_activity.py -- verified: 1 reference to item_type.*issue
  • [x] pal-e-docs/alembic/versions/f6a7b8c9d0e1_sprint_schema_expansion.py:30-31 -- verified: historical migration with "issue" in tuples (correctly marked do-not-modify)
  • [x] pal-e-docs-sdk/src/pal_e_sdk/boards.py:110-113 -- verified: docstring says "issue items require"
  • [x] pal-e-docs-sdk/tests/test_boards.py -- verified: 4 references to item_type="issue" at lines 143, 165, 198, 205
  • [x] pal-e-mcp/src/pal_e_mcp/tools/boards.py -- verified: 3 tool descriptions list 'issue' (lines 117, 159, 384), plus "issue-type items" at line 195 and docstring at line 227
  • [x] pal-e-mcp/tests/test_param_alignment.py -- verified: 5 references to item_type="issue" at lines 359, 369, 378, 385, 392
  • [x] claude-custom/hooks/check-board-item.sh -- verified: issue) case branch at line 74 (issue says 52-57, actual is 72-78)
  • [x] claude-custom/skills/review-ticket/SKILL.md:27 -- verified: lists "(phase, issue, incident, repo)"
  • [x] claude-custom/skills/review-ticket/SKILL.md:42 -- verified: "For `issue` items" section
All targets are specific enough for an agent to act on. Line numbers have minor drift from the issue description (expected for issues written before recent merges), but all patterns and files are correctly identified. Child tickets should verify line numbers at execution time.

Repo Placement

OK. Issue is filed on claude-custom (the hooks/config repo) which is correct for cross-repo coordination tickets. Each of the 4 child tickets is filed on its correct repo: pal-e-api#229 (API), pal-e-sdk#40 (SDK), pal-e-mcp#53 (MCP), claude-custom#191 (hooks/skills). No misplacement detected.

Dependencies

  • [x] Deploy ordering (A->B->C->D) -- documented in Decomposition section. Each child blocks the next. This is correct and necessary (SDK must consume new API before MCP can use new SDK).
  • [x] Board item #478 (Spike: Note type system audit) -- in in_progress. This spike targets NoteType (not BoardItemType), so no conflict with this ticket's scope.
  • [x] No other board items on board-pal-e-agency are blocked by or block this ticket.

Acceptance Criteria

All 10 acceptance criteria are verifiable by an agent:
  • Enum presence: grep/read models.py for ticket = "ticket"
  • API acceptance/rejection: pytest integration tests
  • Alembic migration: run migration on test DB, verify row conversion
  • SDK/MCP/hook string changes: grep for old pattern, verify absence
  • "No remaining references" criterion: grep across all 4 repos for item_type.*=.*"issue"
Each child ticket inherits a subset of these criteria. The parent's criteria are the union. No ambiguous "works correctly" language -- all criteria are specific and testable.

Blast Radius

  • MCP tool descriptions are visible to all agents at session start. Changing 'issue' to 'ticket' will change agent behavior when creating board items. The backward-compat transition period in child ticket A mitigates this.
  • Convention/SOP notes that reference item_type="issue" will need updating. Discovered Scope #192 catches the SKILL.md phantom incident type. A content sweep for item_type.*issue in pal-e-docs notes may surface additional convention notes needing updates (not blocking, but worth tracking).
  • Cached MCP sessions may use old value after backward compat removal. Session restart resolves this.
  • Rollback is straightforward: reverse Alembic migration + revert code changes. The backward-compat transition period means rollback is only needed if the new value causes problems after the transition window closes.

Decomposition Assessment

Already decomposed into 4 child tickets with strict deploy ordering:
  • pal-e-api#229 -- Enum + schema + routes + Alembic migration + transition alias (single repo, ~10 files)
  • pal-e-sdk#40 -- Docstrings + test fixtures (single repo, ~2 files)
  • pal-e-mcp#53 -- Tool descriptions + test fixtures + SDK bump (single repo, ~2 files)
  • claude-custom#191 -- Hook case branch + SKILL.md routing (single repo, ~2 files)
Each child ticket targets a single repo and should complete well within the 5-minute rule. Child ticket A is the largest (~10 files including tests and migration) but remains within the 3-file-target-per-repo limit when counting logical changes (enum, schema, routes, migration). The parent ticket itself requires no direct work -- it closes when all 4 children merge. No further decomposition needed.

Recommendation

No action needed. Ticket is well-scoped, fully decomposed, all file targets verified, traceability complete.
Informational observations (not blocking):
  • Line numbers in file targets have minor drift from current file state. Child tickets should verify line numbers at execution time -- this is normal and expected.
  • Consider grepping pal-e-docs note content for item_type.*issue references in SOPs/conventions beyond what Discovered Scope #192 covers. If found, add as discovered scope on the parent.