Implementation Log

Deviations from plan during implementation, indexed by run and task. Only deviations are recorded here; tasks that followed the plan exactly are omitted.

Last updated: 2026-04-08

Run 1 — Bug Fixes

T-1.4: New `printEventRoute()` helper required

Plan: Add the unmark endpoint following the existing eventRoute() pattern.

Actual: Created a new printEventRoute() helper method alongside the existing eventRoute(), with its own printStateChangeBody response descriptor.

Reason: The existing eventRoute() returns KanbanCardStateChange (operational lifecycle transitions). The unmark endpoint returns KanbanCardPrintStateChange (print lifecycle transitions) — a different type. Reusing eventRoute() would have required a type parameter or generic, which would have been a larger refactor. The new helper follows the same pattern but with the correct return type.

T-1.6: Kanban Cards Module doc had stale enum values

Plan: Update the print lifecycle documentation to add UNMARK.

Actual: Also corrected the KanbanCardPrintStatus enum in the PlantUML class diagram — it was missing DEPRECATED and UNKNOWN values that already existed in the code.

Reason: The documentation was written before the extra-printing-options project added DEPRECATED, and UNKNOWN was always present in code but missing from the doc.

Run 2 — Multi-Template Printing

T-2.5: Synthetic RenderResult for print status tracking

Plan: Construct a RenderResult per successful group to pass to cardPrinted().

Actual: Constructed a single synthetic RenderResult using the CompositeRenderResult header (job, asOF) and the first successful group’s url and templateId. Applied to all cards in successful groups.

Reason: cardPrinted() requires a RenderResult which includes the PDF URL. Since multiple groups produce multiple URLs, the synthetic result uses the first successful URL as a representative value. The job and asOF are shared across all groups. This is adequate for print event tracking — the exact URL per card is not queried later.

T-2.6: replace_all caused double-prefix in import

Plan: Replace RenderResult with CompositeRenderResult in endpoint files.

Actual: Using replace_all on the string RenderResult also matched the already-replaced import line CompositeRenderResult, creating CompositeCompositeRenderResult. Fixed immediately.

Reason: The replace_all operation is not context-aware. The import line was replaced first (changing RenderResult to CompositeRenderResult), then the same replacement ran again on the result. Fixed by correcting the double-prefixed import to CompositeRenderResult.

Run 3 — Pre-Implementation Adjustments

Plan adjustments based on Run 2 results

Plan: Task 3.2 defines a DiagnosticRenderResult wrapper type and extends render() with diagnostic flags.

Actual (pre-implementation): render() is now internal; the primary method is renderGroups(). The DiagnosticRenderResult wrapper is unnecessary — debugPayload: JsonElement? is added directly to GroupRenderResult (as Task 3.4 already specified).

Reason: Run 2 refactored PdfRenderService to use renderGroups() as the primary interface. Diagnostic flags go on renderGroups() and flow through to the internal renderBatch(). Tasks 3.2 and 3.3 are simpler than the spec anticipated because the calling services (ItemPrintingService, PrintLifecycleImpl) now use renderGroups() and just pass the flags through.

Run 4 — API Tests

Bruno query parameters must be in URL string

Plan: Use params:query section in .bru files to pass query parameters.

Actual: Bruno CLI does not send params:query values unless they are also in the URL string. All test files updated to include query parameters directly in the url: field (matching the pattern used by existing tests like PrintOneCard.bru).

Reason: Bruno params:query appears to be metadata for the GUI; the CLI runner only uses the URL string for actual HTTP requests.

Kanban card tests require test data setup

Plan: Test UnmarkPrinted and PrintCardNotesMapping against hardcoded card IDs.

Actual: Card IDs do not exist in the local DB. These 2 tests fail with 404/400. The 5 label/breadcrumb tests pass.

Reason: Card IDs are created by other test workflows and are ephemeral. A proper fix would add a card creation pre-request script or run these tests after the kanban setup workflow.

T-4.1, T-4.2, T-4.3: Deferred to post-deployment

Plan: Update existing disabled tests for composite response (T-4.1), add multi-template tests (T-4.2), add batch limiting tests (T-4.3).

Actual: Deferred. These tests require items with specific size configurations in the test data and validation against a running instance. T-4.4, T-4.5, and T-4.6 were authored first because they use dry-run (no Documint dependency) or test structural endpoints (unmark).

Reason: T-4.2 and T-4.3 need items with different labelSize/ breadcrumbSize/cardSize values. This data may need to be created as part of the test setup or verified against the deployed environment. T-4.1 (existing tests) uses hardcoded IDs — updating assertions without verifying the IDs still work is counterproductive.