Run 2: Multi-Template Printing

Implement composite response type, PdfRenderService.renderGroups() with parallel rendering and batch splitting, simplify calling services, and update frontend to handle multiple PDF URLs.

Specification: Phase 2 Specification Requirements: Phase 2 Requirements Verification: Phase 2 Verification

Entry Criteria

#	Criterion	Verification Command	Expected Output
1	Run 1 exit gate passes	`bash .../run-1-bug-fixes/validate-exit.sh`	`ALL CHECKS PASSED`
2	Run 1 changes committed to all worktrees	`git -C .../operations log --oneline -1`	Contains Run 1 commit
3	Operations builds clean	`make -C .../operations build`	`BUILD SUCCESSFUL`

Artifact Specifications

Artifact	Path	Format	Description
CompositeRenderResult	`operations/src/.../pdfrender/business/RenderResult.kt`	Kotlin	New composite response types
PdfRenderService.renderGroups()	`operations/src/.../pdfrender/service/PdfRenderService.kt`	Kotlin	Multi-group rendering with batching and parallelism
Printing config	`operations/src/main/resources/shop-access/pdf-render/application.conf`	HOCON	`maxItemsPerDocumintRequest`, `maxParallelRenders`
Per-request config	`operations/src/main/resources/reference/item/application.conf`	HOCON	`maxItemsPerRequest`
Simplified ItemPrintingService	`operations/src/.../item/service/ItemPrintingService.kt`	Kotlin	Groups and delegates to renderGroups()
Simplified PrintLifecycleImpl	`operations/src/.../kanban/service/PrintLifecycleImpl.kt`	Kotlin	Groups, delegates, scoped status updates
Updated endpoints	`operations/src/.../item/api/rest/ItemEndpoint.kt`	Kotlin	Response type changed to CompositeRenderResult
Frontend handlers	`arda-frontend-app/src/app/items/page.tsx`	TSX	Handles results array, opens multiple tabs
Updated PDF Render Module doc	`documentation/src/.../shop-access/pdf-render-module.md`	Markdown	renderGroups(), composite types, sequence diagram
Updated Item Module doc	`documentation/src/.../reference-data/item/index.md`	Markdown	Simplified printing sequence diagram
CHANGELOG entries	`operations/CHANGELOG.md`, `arda-frontend-app/CHANGELOG.md`	Markdown	Version entries for multi-template feature

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
2.1	Define CompositeRenderResult + GroupRenderResult in pdfRender module	back-end-engineer	—	Pending	Types compile. T-P2-006, T-P2-007.
2.2	Add printing config to pdfRender and item/kanban modules	back-end-engineer	—	Pending	Config loads with defaults. T-P2-013.
2.3	Implement PdfRenderService.renderGroups()	back-end-engineer	2.1, 2.2	Pending	Grouping, batch splitting, Semaphore-limited parallelism. T-P2-001 through T-P2-005, T-P2-009 through T-P2-012.
2.4	Simplify ItemPrintingService	back-end-engineer	2.3	Pending	Groups by template, delegates to renderGroups(). Single-template enforcement removed. T-P2-001, T-P2-002, T-P2-011, T-P2-012.
2.5	Simplify PrintLifecycleImpl for cards	back-end-engineer	2.3	Pending	Groups, delegates, scoped print status updates. T-P2-003, T-P2-016.
2.6	Update API endpoint response types	back-end-engineer	2.4, 2.5	Pending	All print endpoints return CompositeRenderResult. T-P2-008.
2.7	Frontend composite response handling	front-end-engineer	2.1 (response shape)	Pending	Opens multiple tabs, shows per-group errors. Remove card grouping logic. T-P2-014, T-P2-015.
2.8	Update design documentation	back-end-engineer	2.3, 2.4, 2.5	Pending	PDF Render Module + Item Module docs updated. T-P2-019, T-P2-020.
2.9	Regression tests and CHANGELOG	back-end-engineer	2.1-2.8	Pending	All builds pass. CHANGELOG entries with `[X.Y.Z-jmpicnic-0408]` format. T-P2-017, T-P2-018.

Internal Dependency Graph

2.1 (types) ──┬──→ 2.3 (renderGroups) ──┬──→ 2.4 (ItemPrintingService) ──┐
2.2 (config) ─┘                         └──→ 2.5 (PrintLifecycleImpl) ───┤
                                                                         ├──→ 2.6 (endpoints) ──→ 2.8 (docs) ──→ 2.9 (regression)
2.1 (types) ──────────────────────────────→ 2.7 (frontend) ──────────────┘

Tasks 2.1 and 2.2 can run in parallel. Task 2.3 is the critical path. Tasks 2.4 and 2.5 can run in parallel after 2.3. Task 2.7 (frontend) can start as soon as 2.1 defines the response shape.

Agent assignment: A single back-end-engineer handles 2.1-2.6, 2.8-2.9 (sequential dependency chain). A front-end-engineer handles 2.7 (can work in parallel once response shape is defined).

Exit Criteria

#	Criterion	Verification Command	Expected Output
1	Operations builds with all tests passing	`make -C .../operations build`	`BUILD SUCCESSFUL`
2	Frontend builds	`cd .../arda-frontend-app && npm run build`	Exit 0
3	Frontend Jest tests pass	`cd .../arda-frontend-app && npx jest ...`	All pass
4	Documentation builds	`cd .../documentation && make build`	`Complete!`
5	CHANGELOG updated in operations	`head -20 .../operations/CHANGELOG.md`	Contains `jmpicnic` version entry
6	All worktrees clean	`git -C .../operations status --short`	Clean

PR creation and deployment to dev are gated on explicit user prompt. The dev environment is a shared resource. Do not push, create PRs, or deploy without user authorization.

Agent Prompt Templates

Back-End Engineer — `be-multi-template`

You are implementing multi-template printing in the operations repository at /Users/jmp/code/arda/projects/multi-pdf-print-and-bugs-worktrees/operations.

Read the specification at .../../phase-2-multi-template/specification.md and implement Tasks 2.1 through 2.6, 2.8, 2.9. Use mode: "bypassPermissions".

Key architecture decision: PdfRenderService owns column packing, batch splitting, parallel execution, and result composition. Calling services (ItemPrintingService, PrintLifecycleImpl) only transform domain types to JsonElement, group by template, validate per-request limit, and delegate to renderGroups().

Config field names: maxItemsPerDocumintRequest, maxItemsPerRequest, maxParallelRenders. CHANGELOG format: [X.Y.Z-jmpicnic-0408].

Front-End Engineer — `fe-multi-template`

You are implementing composite print response handling in arda-frontend-app at /Users/jmp/code/arda/projects/multi-pdf-print-and-bugs-worktrees/arda-frontend-app.

Read the specification at .../../phase-2-multi-template/specification.md and implement Task 2.7.

Key decisions:

All print responses use composite shape (even single-item)
Parse data.data.results array; window.open() per successful URL; toast.error() per failed group
Remove frontend card grouping logic (cardsByTemplate map)
Remove label/breadcrumb same-template error check

Handoff

Artifacts Consumed (from previous runs)

Artifact	Source Run	Path
Fixed notes mapping	Run 1	`operations/src/.../kanban/business/KanbanCardPrinter.kt`
UNMARK event (stable print status)	Run 1	`operations/src/.../kanban/business/KanbanCard.kt`

Artifacts Produced (for subsequent runs)

Artifact	Consumer Run	Path
CompositeRenderResult type	Run 3, Run 4	`operations/src/.../pdfrender/business/RenderResult.kt`
PdfRenderService.renderGroups()	Run 3	`operations/src/.../pdfrender/service/PdfRenderService.kt`
Printing config pattern	Run 3	`operations/src/main/resources/.../application.conf`
CHANGELOG entry	Run 3 (appends)	`operations/CHANGELOG.md`