[jacksonsr451]

Summary

Implements the configurable Kanban subsystem for EventFlow's Work Management bounded context.

This PR introduces workspace/project-scoped boards, independently managed columns, customizable workflow mappings, persistent card ordering, WIP limits, movement history, filtering, pagination, RBAC, idempotency, and concurrency protection.

The implementation preserves the existing approval-only WorkItem creation invariant.

Related issue: #8

Status: Ready for review with one architectural reservation.

Changes

Board Management

• Implemented Board creation, listing, retrieval, and updating.
• Added Workspace and Project scoping.
• Added Board versioning and archival support.
• Enforced authorization through existing RBAC policies.

Configurable Columns

• Introduced independently managed Board columns.
• Implemented column creation, listing, updating, and deletion.
• Added persistent column ordering.
• Added configurable canonical WorkItem status mappings.
• Added optional WIP limits.
• Preserved stable column identities.

Card Movement and Ordering

• Implemented persistent movement between columns.
• Added deterministic base-62 fractional ranking.
• Added optimistic concurrency through If-Match.
• Added idempotency for supported mutations.
• Enforced valid WorkItem lifecycle transitions.
• Added explicit RANK_SPACE_EXHAUSTED handling.

WIP Enforcement

• Implemented column-level Work-in-Progress limits.
• Added PostgreSQL row locking for concurrent capacity checks.
• Prevented movements that exceed configured limits.
• Ensured failed movements do not partially update WorkItems or Cards.

Movement History

• Added append-only Card movement history.
• Introduced database triggers protecting historical records.
• Persisted movement history transactionally.
• Added movement history retrieval.

Filtering and Pagination

• Added Board, Card, and WorkItem listing capabilities.
• Implemented supported filters.
• Added cursor-based pagination.
• Preserved deterministic ordering and tenant isolation.

Security

• Integrated board:manage and board:read permissions.
• Enforced Workspace and Project isolation.
• Preserved the approval-only WorkItem creation boundary.
• Prevented unauthorized direct Card creation.

API Operations

Added or completed:

• createBoard
• listBoards
• getBoard
• updateBoard
• createBoardColumn
• listBoardColumns
• updateBoardColumn
• deleteBoardColumn
• listBoardCards
• getBoardCard
• moveBoardCard
• listCardMovements
• listWorkItems
• getWorkItem

Updated contracts:

• contracts/openapi/work-management.yaml
• contracts/schemas/work_management.yaml

Database Migration

Added:

0008_kanban_boards_columns_and_movements

Changes include:

• Board versioning and archival fields.
• board_columns persistence.
• card_movements persistence.
• Append-only history triggers.
• Supporting database functions and constraints.

Migration upgrade and downgrade were verified.

Tests

Executed using jsr-testrunner with PostgreSQL.

Suite	Passed	Failed	Skipped
Work Management	178	0	1
Root contract/security	114	0	0
Total	292	0	1

Validation

• Work Management tests passed.
• Root contract/security tests passed.
• PostgreSQL integration tests passed.
• Contract validation passed.
• Pre-commit hooks passed.
• git diff --check passed.
• Migration upgrade/downgrade verified.
• Remote CI verification pending.

Architecture and Known Limitations

Direct Card Creation

Status: BLOCKED BY ARCHITECTURE

Issue #8 allows optional direct Card creation, but the accepted architecture requires every BoardCard to reference a WorkItem created through an authorized approval workflow.

No direct Card or WorkItem creation endpoint was introduced.

This limitation is documented in ADR-008 Amendment A-03.

An approved ADR and compatible contract amendment are required before implementing this alternative creation path.

Idempotency Response Replay

Repository-level idempotency is supported.

However, replaying an identical request does not necessarily reproduce the original HTTP response body exactly.

This remains a known limitation.

Rank Exhaustion

Card ordering uses variable-length base-62 fractional ranks.

If the available rank space is exhausted, the operation returns:

RANK_SPACE_EXHAUSTED

Automatic rank rebalancing is not implemented.

Column Identifier

target_column_id uses the existing string-based column key rather than a UUID.

This preserves compatibility with the established implementation.

Acceptance Criteria

Requirement	Status
Workspace/Project Boards	PASS
Configurable Columns	PASS
Column Ordering	PASS
Custom Workflow Mapping	PASS
Persistent Card Movement	PASS
Card Ordering	PASS
WIP Limits	PASS
Transition Validation	PASS
Movement History	PASS
Concurrency Protection	PASS
Filtering	PASS
Cursor Pagination	PASS
RBAC	PASS
Tenant Isolation	PASS
Idempotency	PASS
Contract Validation	PASS
Regression Tests	PASS
Direct Card Creation	BLOCKED BY ARCHITECTURE
Remote CI	PENDING

Files Changed

23 files changed, 4,213 insertions, 9 deletions.

Key additions:

• services/work-management/src/eventflow_work_management/api/board_routes.py
• services/work-management/src/eventflow_work_management/repositories/board_column_repository.py
• services/work-management/src/eventflow_work_management/migrations/versions/0008_kanban_boards_columns_and_movements.py

Review Focus

Please review:

1. Board and Column configuration consistency.
2. WorkItem lifecycle mapping.
3. WIP enforcement under concurrent requests.
4. Fractional rank generation and exhaustion.
5. Card movement transaction boundaries.
6. Append-only movement history.
7. Workspace and Project authorization.
8. Idempotency replay behavior.
9. Database migration safety.
10. ADR-008 Amendment A-03 and direct creation restrictions.

Git Information

Branch: feat/8-kanban-boards-custom-workflows

Commit: 4648da8

Commit message:

feat(work-management): implement configurable kanban boards and cards (#8)

Local verification: 292 passed, 0 failed, 1 skipped.

Working state: Committed locally; not pushed or merged.

Final Status

READY FOR PR WITH RESERVATIONS

The configurable Kanban subsystem is implemented and locally verified.

Direct Card/WorkItem creation remains blocked pending architectural approval. Remote CI verification is pending.