Rename BoardItemType 'issue' to 'ticket' for semantic clarity #181
Labels
No labels
domain:backend
domain:devops
domain:frontend
status:approved
status:in-progress
status:needs-fix
status:qa
type:bug
type:devops
type:feature
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
ldraney/claude-custom#181
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Type
Feature
Lineage
Standalone -- discovered during board item creation workflows where
item_type="issue"causes semantic confusion with Forgejo issues.Repo
Cross-repo:
forgejo_admin/pal-e-docs,forgejo_admin/pal-e-docs-sdk,forgejo_admin/pal-e-mcp,forgejo_admin/claude-customUser Story
As a platform operator managing board items via MCP tools and hooks
I want the board item type for Forgejo-linked kanban cards to be called
ticketinstead ofissueSo that "issue" unambiguously means "Forgejo issue" (the spec) and "ticket" means "board item" (the kanban card) throughout the pal-e-agency system
Context
The
BoardItemTypeenum usesissuefor board items that represent Forgejo issues. But "issue" is overloaded in the pal-e-agency system:The established convention is: "issues" are Forgejo issues, "tickets" are board items. Using
item_type="issue"for the board item type creates confusion in hooks, skills, agent prompts, and SOPs. The rename aligns the API with the established vocabulary.This is a breaking change for all MCP consumers. Every hook, skill, agent prompt, and test that passes
item_type="issue"must be updated. The database stores the string value, so existing rows need a data migration. Deploy order: API first (with backward compat accepting both), SDK second, MCP third, hooks/skills fourth, then remove backward compat.File Targets
Files the agent should modify or create:
pal-e-docs (API server) --
~/pal-e-docssrc/pal_e_docs/models.py:33-39--BoardItemTypeenum: renameissue = "issue"toticket = "ticket"src/pal_e_docs/schemas.py:228--BoardItemTypeTypeLiteral: replace"issue"with"ticket"src/pal_e_docs/schemas.py:262-268--BoardItemCountsmodel: renameissue: int = 0field toticket: int = 0src/pal_e_docs/routes/boards.py:395-- Comment:item_type=issuein sync docstringsrc/pal_e_docs/routes/boards.py:488--item_type=BoardItemType.issuein sync endpointsrc/pal_e_docs/routes/boards.py:602-605-- Validation:body.item_type == "issue"and error messagetests/test_boards.py-- ~20 references to"item_type": "issue"and?item_type=issuein query stringstests/test_board_issue_sync.py-- ~8 references toitem_type=issueanditem["item_type"] == "issue"tests/test_pagination_activity.py:49--"item_type": "issue"test fixturealembic/versions/xxxx_rename_issue_to_ticket.py-- data migration:UPDATE board_items SET item_type = 'ticket' WHERE item_type = 'issue'pal-e-docs (Alembic -- existing migrations, reference only)
alembic/versions/f6a7b8c9d0e1_sprint_schema_expansion.py:30-31--OLD_ITEM_TYPESandNEW_ITEM_TYPEStuples contain"issue"(historical, do not modify -- add forward migration instead)pal-e-docs-sdk --
~/pal-e-docs-sdksrc/pal_e_sdk/boards.py:101-116--add_board_item()docstring: "issue items require" -> "ticket items require"tests/test_boards.py:140-145--item_type="issue"intest_get_backlog_with_item_typetests/test_boards.py:165-167--item_type="issue"in list_board_items testtests/test_boards.py:198-205--item_type="issue"in add_board_item testpal-e-mcp (MCP server) --
~/pal-e-mcpsrc/pal_e_mcp/tools/boards.py:104--list_board_itemstool: item_type description lists'issue'src/pal_e_mcp/tools/boards.py:138--create_board_itemtool: item_type field description lists'issue'src/pal_e_mcp/tools/boards.py:160--forgejo_issue_urlfield description references "issue-type items"src/pal_e_mcp/tools/boards.py:180-181--create_board_itemdocstring: categorises withissue, "For issue items"src/pal_e_mcp/tools/boards.py:302--get_backlogtool: item_type description lists'issue'tests/test_param_alignment.py:349,357,365,372,379-- 5 test fixtures useitem_type="issue"claude-custom --
~/claude-customhooks/check-board-item.sh:52-57--casestatement:issue)branch rename toticket)skills/review-ticket/SKILL.md:27-- item_type list:(phase, issue, incident, repo)->(phase, ticket, incident, repo)skills/review-ticket/SKILL.md:40-42-- "Forissueitems" section rename to "Forticketitems"Files the agent should NOT touch:
alembic/versions/f6a7b8c9d0e1_sprint_schema_expansion.py-- historical migration, do not rewritealembic/versions/n4i5j6k7l8m9_replace_sprints_with_boards.py-- historical migration, do not rewritealembic/versions/e5f6a7b8c9d0_add_sprint_tables.py-- historical migration, do not rewriteAcceptance Criteria
BoardItemTypeenum hasticketinstead ofissueitem_type="ticket"and rejectitem_type="issue"(after transition period)"issue"rows to"ticket"inboard_itemstableadd_board_item()docstring and tests referenceticketnotissuecreate_board_itemtool description showsticketin the valid values listlist_board_itemsandget_backlogtool descriptions showticketin valid valuestest_param_alignment.pyuseitem_type="ticket"check-board-item.shhook validatesticket)case instead ofissue)review-ticketskill referencesticketitem typeitem_type="issue"(as a BoardItemType value) in any of the four reposTest Expectations
pal-e-docs/tests/test_boards.pypass with"ticket"replacing"issue"test_board_issue_sync.pypasses withitem_type=ticketfor Forgejo-synced itemspal-e-docs-sdk/tests/test_boards.pypasses withitem_type="ticket"pal-e-mcp/tests/test_param_alignment.pypasses withitem_type="ticket"pytest tests/test_boards.py tests/test_board_issue_sync.py tests/test_board_sync.py tests/test_pagination_activity.py -vConstraints
"issue"and"ticket"during rollout, logging a deprecation warning for"issue"item_typecolumn isString(20)--"ticket"fits within the constraintDecomposition
This parent ticket is decomposed into 4 child tickets with strict deploy order (see comment #9353):
pal-e-api#229pal-e-sdk#40pal-e-mcp#53claude-custom#191Deploy order:
A -> B -> C -> D. No direct work on this parent ticket.Discovered Scope
claude-custom#192-- Bug:review-ticket/SKILL.mdlists phantomincidentitem_type that does not exist in the enum.Checklist
"issue"rowsRelated
pal-e-agency-- project this affects (board system is part of the agency platform)convention-todo-lifecycle-- references board item typestemplate-ticket-- ticket template that creates board itemsboard-pal-e-agency-- board that will contain this itemDecomposition (2026-03-27)
Review
review-181-2026-03-27found this ticket violates the 5-minute and 3-thing rules: 4 repos, 27+ files. Decomposed into 4 child tickets with strict deploy order.Child Tickets
forgejo_admin/pal-e-api#229forgejo_admin/pal-e-sdk#40forgejo_admin/pal-e-mcp#53forgejo_admin/claude-custom#191Deploy Order
A ships first with a transition alias (API accepts both
"issue"and"ticket"). Each downstream ticket updates to the new canonical value. D is last.Discovered Scope
forgejo_admin/claude-custom#192-- Bug:review-ticket/SKILL.mdlists phantomincidentitem_type that does not exist in the enum. Also missingplan,project,todofrom the valid values list.Resolution
This parent ticket (#181) should be closed once all 4 child tickets merge. No direct work on this ticket.
Scope Review: NEEDS_REFINEMENT
Review note:
review-479-2026-03-27Template is complete and traceability labels are solid. Two issues found:
pal-e-mcp-- The MCP server tool description (pal-e-mcp/src/pal_e_mcp/tools/boards.py:180-181) and 5 tests (tests/test_param_alignment.py) referenceitem_type="issue". This is where AC #5 ("MCP create_board_item tool description") actually lives. Add as fourth repo.docs/superpowers/specs/2026-03-18-review-ticket-design.md:41references the field nameitem_type, not the value"issue". No change needed; remove from targets.template-boardsplit: (A) API enum+migration, (B) SDK+MCP, (C) hooks/skills, (D) backward compat removal.Body Refinement (2026-03-27)
Responding to
review-479-2026-03-27. Three changes applied to issue body:1. Added
pal-e-mcpto repo scopeforgejo_admin/pal-e-mcpboards.py(lines 104, 138, 160, 180-181, 302) + 5 test fixtures intest_param_alignment.py2. Removed inaccurate file target
docs/superpowers/specs/2026-03-18-review-ticket-design.md:41-- that line references the field nameitem_typein a fetch call, not the enum value"issue". No rename needed there.3. Added decomposition to body
incidenttype).Decomposition Verification
All 4 child issues from the decomposition plan already exist and are confirmed open:
pal-e-api#229pal-e-sdk#40pal-e-mcp#53claude-custom#191Discovered scope issue also exists:
claude-custom#192(phantomincidentitem_type).No new issues needed — decomposition was already executed.
Scope Review: READY
Review note:
review-479-2026-03-29Ticket is well-scoped. All 15+ file targets verified against filesystem. Template complete, traceability triangle satisfied (story:pm-scope, arch:note-system, Forgejo issue open). Already decomposed into 4 child tickets (pal-e-api#229 -> pal-e-sdk#40 -> pal-e-mcp#53 -> claude-custom#191) with correct deploy ordering. No blockers, no refinement needed. Ready for execution via child tickets.