Implementation Plan

Author: Claude Code for jmpicnic Date: 2026-03-30 Status: Draft Related Issue: Arda-cards/management#820

Summary

Implement additional printing format options (X_SMALL and SPECIAL_01–SPECIAL_10) across the Documint configuration spreadsheet, the operations backend, and deliver a frontend specification ticket. This plan covers a single-agent, three-phase execution with two STOP gates.

Context

• Goal and Requirements — analysis, requirements (REQ-EPO-001–016), and acceptance criteria (24 items)
• Specification — detailed task breakdown, per-task code examples, alias tables, and phase instructions
• Verification — bidirectional traceability matrix (requirements → acceptance criteria → verification methods)
• Printing Configuration Spreadsheet — source of truth for template IDs, display names, and active flags
• Project type: Modification — extending existing enums, protobuf definitions, configuration, and CSV upload logic

Scope

In Scope

1. Spreadsheet — New versioned sheet Documint Template Mapping (20260330) with 45 data rows, Active and Notes columns.
2. Backend (operations) — Domain enums, protobuf enums, mapping functions, PrintingTemplateConfiguration data class, pdf-templates.json, CSV alias support, tests, CHANGELOG.
3. Frontend ticket — GitHub issue in Arda-cards/management assigned to danmerb with full specification for arda-frontend-app.

Out of Scope

• Direct modifications to arda-frontend-app (ticket only).
• Changes to common-module (reference dependency only).
• Rendering logic or Documint template design.
• API endpoint signatures.

Design

Persistence Changes

None. Existing enumerationByName columns store enum names as strings. Adding new enum values (X_SMALL, SPECIAL_01–SPECIAL_10) is additive — no schema migration or Flyway script needed. Verify at implementation time (T-8).

Service Layer Changes

PrintingTemplateConfiguration (RenderJob.kt): Add active: Boolean = true field. Default ensures backwards compatibility with existing JSON entries that lack the field.

PrintTemplates (Printing.kt): No change to resolution logic. Fallback to MEDIUM for missing sizes is preserved. The active flag is stored but not used for backend resolution.

ItemCsvUploadService (ItemCsvUploadService.kt):

• Extend CardSizeMessage.domain(), LabelSizeMessage.domain(), BreadcrumbSizeMessage.domain() with mappings for all new protobuf values.
• Add alias resolution: CSV values matching the Size of Template display name (e.g., “Quarter-Index”) resolve to the corresponding enum value. Alias tables are defined in the specification.

API Changes

None. Existing print endpoints (/v1/kanban/kanban-card/print-card, /v1/item/item/print-label, /v1/item/item/print-breadcrumb) accept the size from the item’s persisted value. New enum values flow through the existing path.

Frontend Changes

Delivered as a GitHub ticket (T-12), not implemented in this plan. See specification Phase 3 for the ticket contents.

Task Breakdown

#	Task	Persona	Depends On	Acceptance Criteria
T-1	Create new spreadsheet sheet via Google Workspace MCP	Implementer	—	45 data rows (15 per category), Active/Notes columns, no LARGE+QR row
				STOP — Review checkpoint
T-2	Extend domain enums in Printing.kt	Back End Engineer	T-1	15 values per enum, correct ordering
T-3	Extend protobuf enums in item_row.proto	Back End Engineer	T-1	Sequential field numbers 5–15 appended
T-4	Update protobuf → domain mapping in ItemCsvUploadService.kt	Back End Engineer	T-2, T-3	All new values mapped; UNSPECIFIED → MEDIUM preserved
T-5	Add CSV alias resolution for display names	Back End Engineer	T-4	Aliases from specification accepted in CSV upload
T-6	Add active field to PrintingTemplateConfiguration	Back End Engineer	—	active: Boolean = true in data class
T-7	Update pdf-templates.json from spreadsheet	Back End Engineer	T-1, T-6	45 entries with template, columns, description, default, active
T-8	Verify existing data deserialization	Back End Engineer	T-2, T-7	SMALL/MEDIUM/LARGE/X_LARGE items load without error
T-9	Update and add tests	Back End Engineer	T-2–T-7	All tests pass, new enum values and aliases covered
T-10	make clean build and verify coverage	Back End Engineer	T-2–T-9	Zero errors, coverage meets Gradle targets
T-11	Update CHANGELOG.md	Back End Engineer	T-10	[2.20.0-jmpicnic-820] entry with Added section
				STOP — Review checkpoint
T-12	Write frontend spec and create GitHub ticket	Implementer	T-1, T-10	Ticket in Arda-cards/management, assigned to danmerb

Execution Sequence

Within Phase 2, tasks can be grouped into two parallel streams that converge at T-8/T-9:

• Stream A: T-2 → T-3 → T-4 → T-5 (enum + protobuf + mapping + aliases)
• Stream B: T-6 → T-7 (data class + JSON config)
• Convergence: T-8, T-9 → T-10 → T-11

Since this is a single-agent project, streams execute sequentially in practice but the dependency graph allows flexibility in ordering.

Worktree Strategy

Single agent, two repositories — no additional worktrees needed.

Worktree directory	Branch	Repository	Tasks
extra-printing-options-worktrees/operations	jmpicnic/extra-printing-options-management-820	operations	T-2 through T-11
extra-printing-options-worktrees/documentation	jmpicnic/extra-printing-options-management-820	documentation	Project docs, T-12

Spreadsheet task (T-1) uses Google Workspace MCP — no worktree needed.

Merge workflow: Each worktree pushes its branch directly. One PR per repository targeting main.

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
enumerationByName fails on new enum values for existing DB rows	Low	High	Additive change; existing string names unchanged. Verify at T-8.
Protobuf wire compatibility broken by new field numbers	Low	High	New values appended after existing; UNSPECIFIED = 0 unchanged.
Spreadsheet MCP write fails mid-update	Low	Medium	New sheet created (existing untouched); can retry from scratch.
Frontend misinterprets active flag semantics	Low	Medium	Ticket specifies exact behavior; backend stores but does not filter.
Test coverage drops below threshold due to new enum branches	Medium	Medium	Add explicit tests for new values and aliases in T-9.

Open Questions and Decisions

All questions resolved during planning — see specification for the full decision log.

#	Question	Decision
1	Breadcrumb X_SMALL/SMALL alias collision	Differentiate display names: “3 x 1 (xs Label Printer)” vs “3 x 1 (Label Printer)“
2	active default in data class	true (backwards-compatible)
3	CHANGELOG version	2.20.0 (minor — additive feature)

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved