Run 3: Print Diagnostics

Add debug, dry-run, and live-print diagnostic parameters to all print endpoints. Extend PdfRenderService for diagnostic passthrough. Update OpenAPI descriptions.

Specification: Phase 3 Specification Requirements: Phase 3 Requirements Verification: Phase 3 Verification

Entry Criteria

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

Artifact Specifications

Artifact	Path	Format	Description
DiagnosticRenderResult	`operations/src/.../pdfrender/business/RenderResult.kt`	Kotlin	Optional debugPayload field in GroupRenderResult
Extended PdfRenderService	`operations/src/.../pdfrender/service/PdfRenderService.kt`	Kotlin	debug/dryRun parameters on render and renderGroups
Updated endpoints	`operations/src/.../item/api/rest/ItemEndpoint.kt`	Kotlin	debug, dry-run query params with OpenAPI descriptions
Unit tests	`operations/src/test/`	Kotlin	Tests for debug, dry-run, parameter combinations
Updated PDF Render Module doc	`documentation/src/.../shop-access/pdf-render-module.md`	Markdown	Diagnostic parameters, dry-run sequence diagram
Updated Item Module doc	`documentation/src/.../reference-data/item/index.md`	Markdown	Diagnostic parameters on endpoint table
CHANGELOG entry	`operations/CHANGELOG.md`	Markdown	Version entry for diagnostics

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
3.1	Add debug/dry-run params to print endpoints with OpenAPI descriptions	back-end-engineer	—	Pending	Params parsed from query string. OpenAPI spec shows descriptions.
3.2	Extend PdfRenderService for diagnostic modes	back-end-engineer	3.1	Pending	render/renderGroups accept debug/dryRun. Dry-run skips Documint. Debug includes payload. T-P3-004 through T-P3-008.
3.3	Wire diagnostic params through ItemPrintingService and PrintLifecycleImpl	back-end-engineer	3.2	Pending	Dry-run skips print status updates for cards. T-P3-005.
3.4	Add debugPayload to GroupRenderResult	back-end-engineer	3.2	Pending	Field omitted when null (not serialized). T-P3-001 through T-P3-003, T-P3-006.
3.5	Update design documentation	back-end-engineer	3.1-3.4	Pending	PDF Render Module + Item Module docs updated. T-P3-012, T-P3-013.
3.6	Regression tests and CHANGELOG	back-end-engineer	3.1-3.5	Pending	All builds pass. Default params (debug=false, dryRun=false) don’t change behavior. T-P3-010, T-P3-011. CHANGELOG entry.

Internal Dependency Graph

3.1 (endpoint params) ──→ 3.2 (PdfRenderService) ──→ 3.3 (wire through) ──→ 3.5 (docs) ──→ 3.6 (regression)
                                                  └──→ 3.4 (debugPayload)  ──┘

Sequential chain. Single back-end-engineer agent. No frontend changes in this run.

Exit Criteria

#	Criterion	Verification Command	Expected Output
1	Operations builds with all tests passing	`make -C .../operations build`	`BUILD SUCCESSFUL`
2	Documentation builds	`cd .../documentation && make build`	`Complete!`
3	CHANGELOG updated	`head -20 .../operations/CHANGELOG.md`	Contains `jmpicnic` version entry
4	Operations worktree clean	`git -C .../operations status --short`	Clean

PR creation and deployment to dev are gated on explicit user prompt.

Agent Prompt Templates

Back-End Engineer — `be-diagnostics`

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

Read the specification at .../../phase-3-diagnostics/specification.md and implement Tasks 3.1 through 3.6. Use mode: "bypassPermissions".

Key decisions:

Diagnostic params available to all authenticated users (no role check)
debugPayload field omitted from JSON when null (@EncodeDefault(NEVER))
Endpoint route descriptions must include parameter behavior details for OpenAPI spec
CHANGELOG format: [X.Y.Z-jmpicnic-0408]

Handoff

Artifacts Consumed (from previous runs)

Artifact	Source Run	Path
CompositeRenderResult / GroupRenderResult	Run 2	`operations/src/.../pdfrender/business/RenderResult.kt`
PdfRenderService.renderGroups()	Run 2	`operations/src/.../pdfrender/service/PdfRenderService.kt`

Artifacts Produced (for subsequent runs)

Artifact	Consumer Run	Path
Diagnostic endpoints (debug, dry-run)	Run 4	`operations/src/.../item/api/rest/ItemEndpoint.kt`
debugPayload in GroupRenderResult	Run 4	`operations/src/.../pdfrender/business/RenderResult.kt`