Run 2: operations Endpoints + Release

Implements the image upload endpoint, entity validation, and infrastructure wiring in operations, then handles release coordination for both repositories. Corresponds to specification.md Phase 2b + Release (tasks T-6 through T-9).

Author: Claude Code for jmpicnic | Date: 2026-03-31 | Status: Planning

User Request

Implement CloudFormation/Helm infrastructure wiring, the image upload presigned credential endpoint (integrated into ItemEndpoint per TD-22), imageUrl validation in ItemValidator (TD-23), and coordinate the multi-repo release with upstream-first PR ordering.

Entry Criteria

#	Criterion	Verification Command	Expected Output
1	Run 1 exit gate passed	bash .../run-1-common-module/validate-exit.sh	ALL CHECKS PASSED
2	common-module build passes	make -C /Users/jmp/code/arda/projects/image-upload-backend-worktrees/common-module clean build	Exit code 0
3	operations worktree exists	git -C /Users/jmp/code/arda/projects/image-upload-backend-worktrees/operations branch --show-current	jmpicnic/item-image-upload-backend
4	No uncommitted changes in operations	git -C /Users/jmp/code/arda/projects/image-upload-backend-worktrees/operations status --porcelain	Empty
5	Worktree based on jmpicnic/claude-prep	git -C /Users/jmp/code/arda/projects/image-upload-backend-worktrees/operations log --oneline -1 origin/jmpicnic/claude-prep	Matches HEAD ancestor

Decomposition

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
2.1	Set up Gradle includeBuild + verify operations baseline	back-end-engineer	—	Pending	includeBuild configured for common-module worktree; make clean build passes; existing Item tests pass (spec T-6 prereq)
2.2	CloudFormation pre-install.cfn.yml + Helm configmap.yaml + build.gradle.kts Helm lint values	back-end-engineer	2.1	Pending	IAM policies added, configmap values added, Helm lint passes (spec T-6a, T-6b)
2.3	Module.kt wiring: image services + ItemService/ItemValidator DI	back-end-engineer	2.2	Pending	Config loads; AssetKeyGenerator, CdnUrlResolver, S3AssetService instantiated; passed to ItemValidator and ItemService (spec T-6c)
2.4	ImageUploadEndpoint + ItemService.generateImageUploadCredentials() + tests	back-end-engineer	2.3	Pending	7 test cases pass: happy path, auth failure, invalid content type, missing fields, policy keys, CDN URL pattern, unique keys. Routes registered in ItemEndpoint.buildRoot() (TD-22) (spec T-7)
2.5	ItemValidator imageUrl validation + tests	back-end-engineer	2.3	Pending	Pre-implementation: verify ScopingValidator DI precedent (TD-25). Convert ItemValidator from object to class. 9 test cases pass: CDN valid, non-CDN, wrong tenant, missing S3, null clear, grandfather, create valid, create non-CDN, create missing S3 (spec T-8)
2.6	Quality review of T-6 through T-8 implementation	quality-reviewer	2.5	Pending	Code review report: no anti-patterns, follows kotlin-coding conventions, endpoint delegation pattern, validator DI pattern
2.7	Address quality review findings (if any)	back-end-engineer	2.6	Pending	All actionable findings resolved. make clean build still passes
2.8	CHANGELOG + PR for common-module	back-end-engineer	2.7	Pending	CHANGELOG.md updated in common-module worktree; PR created via GitHub MCP; branch pushed (spec T-9 steps 9.1–9.2)
2.9	CHANGELOG + version catalog bump + revert includeBuild + PR for operations	back-end-engineer	2.8	Pending	CHANGELOG.md updated; gradle/libs.versions.toml arda-common-version bumped; settings.gradle.kts includeBuild removed; PR created via GitHub MCP; branch pushed. Expected: operations CI will fail until common-module is published (spec T-9 steps 9.7–9.11)
2.10	Monitor common-module PR: checks + comments	coordinator	2.8	Pending	Background: monitor CI checks, diagnose/fix failures. After 30 min: read reviewer comments, present numbered table (Summary + Recommendation) to user. Execute user decisions, reply to comments, resolve threads
2.11	Monitor operations PR: checks + comments (after user re-trigger)	coordinator	2.9	Pending	Wait for user to re-trigger CI after common-module is published. Then: monitor CI checks, diagnose/fix failures. After 30 min from re-trigger: read reviewer comments, present numbered table to user. Execute user decisions, reply to comments, resolve threads

Worktree Strategy

Single directory per repository — no intra-repo worktrees needed.

Primary working directory: /Users/jmp/code/arda/projects/image-upload-backend-worktrees/operations common-module worktree (for CHANGELOG + PR): /Users/jmp/code/arda/projects/image-upload-backend-worktrees/common-module Branch (both repos): jmpicnic/item-image-upload-backend Base branch: jmpicnic/claude-prep

The back-end-engineer works primarily in the operations worktree for tasks 2.1–2.7, then switches to common-module for 2.8, then back to operations for 2.9.

Parallelization

• Sequential chain: 2.1 → 2.2 → 2.3 → 2.4 → 2.5 → 2.6 → 2.7 → 2.8 → 2.9
• Note: T-7 (task 2.4) and T-8 (task 2.5) are independent after T-6 (task 2.3), but both modify Module.kt and share the same repo — running them sequentially avoids merge conflicts.
• Parallel after 2.8: Task 2.10 (common-module PR monitoring) runs in the background while 2.9 (operations PR creation) proceeds.
• Task 2.11 starts only after the user signals that common-module is published and operations CI has been re-triggered.

2.1 → 2.2 → 2.3 → 2.4 → 2.5 → 2.6 → 2.7 → 2.8 ──→ 2.9
                                                  └──→ 2.10 (background: monitor CM PR)
                                                             2.11 (after user re-trigger)

Idle Agent Strategy

Accept idle time — the quality-reviewer is idle during implementation (2.1–2.5) and during release tasks (2.8–2.11). The back-end-engineer is idle during quality review (2.6) and during PR monitoring (2.10–2.11). Phases are short; buffer tasks add no value.

Personas Required

Persona	Agent Name	Tasks Assigned	Working Directory	Spawn Order
back-end-engineer	be-operations	2.1–2.5, 2.7, 2.8, 2.9	/Users/jmp/code/arda/projects/image-upload-backend-worktrees/operations (primary) + /Users/jmp/code/arda/projects/image-upload-backend-worktrees/common-module (for 2.8)	First
quality-reviewer	qr-operations	2.6	/Users/jmp/code/arda/projects/image-upload-backend-worktrees/operations	After 2.5
coordinator	(team-lead)	2.10, 2.11	Both worktrees	After 2.8

Artifact Specifications

Artifact	Path (relative to operations worktree)	Format	Description
CloudFormation update	helm/operations/pre-install.cfn.yml	YAML	IAM policies for image bucket + presign role
Helm configmap update	helm/operations/templates/configmap.yaml	YAML	Image infrastructure values
Helm lint values update	build.gradle.kts	Kotlin/Gradle	Placeholder ARNs for Helm lint
Module wiring	src/main/kotlin/.../reference/item/Module.kt	Kotlin	Image service instantiation + DI
Endpoint	src/main/kotlin/.../reference/item/api/rest/ImageUploadEndpoint.kt	Kotlin	Presigned credential endpoint (or inline in ItemEndpoint)
Request/response models	src/main/kotlin/.../reference/item/api/rest/Model.kt	Kotlin	ImageUploadRequest, ImageUploadResponse
Service method	src/main/kotlin/.../reference/item/business/ItemService.kt	Kotlin	generateImageUploadCredentials()
Validator update	src/main/kotlin/.../reference/item/persistence/ItemValidator.kt	Kotlin	object → class, imageUrl validation (TD-23)
Endpoint test	src/test/kotlin/.../reference/item/api/rest/ImageUploadEndpointTest.kt	Kotlin/Kotest	7 test cases with Harness + MockAWS
Validator test	src/test/kotlin/.../reference/item/persistence/ItemValidatorImageUrlTest.kt	Kotlin/Kotest	9 test cases

Internal Dependency Graph

2.1 (baseline + includeBuild) → 2.2 (CFN + Helm) → 2.3 (Module.kt)
                                                      ├──→ 2.4 (endpoint + tests)
                                                      └──→ 2.5 (validator + tests)
                                                                │
                                                            2.6 (quality review) → 2.7 (fixes)
                                                                                     │
                                                            2.8 (CM CHANGELOG + PR) → 2.10 (monitor CM PR, background)
                                                                │
                                                            2.9 (ops CHANGELOG + PR) → 2.11 (monitor ops PR, after re-trigger)

Exit Criteria

#	Criterion	Verification Command	Expected Output
1	ImageUploadEndpointTest passes	make -C <ops-worktree> clean build 2>&1 | grep -c "ImageUploadEndpointTest"	≥ 1
2	imageUrl validation tests pass	make -C <ops-worktree> clean build 2>&1 | grep -c "ItemValidator"	≥ 1
3	Existing Item tests pass	make -C <ops-worktree> clean build 2>&1 | grep -c "ItemEndpointTest"	≥ 1
4	Full build succeeds	make -C <ops-worktree> clean build	Exit code 0
5	Helm lint passes	Build output includes successful Helm lint	—
6	Quality review completed	Quality review report exists and findings addressed	—
7	common-module PR created	gh pr list --repo Arda-cards/common-module --head jmpicnic/item-image-upload-backend	PR exists
8	operations PR created	gh pr list --repo Arda-cards/operations --head jmpicnic/item-image-upload-backend	PR exists
9	common-module CHANGELOG updated	git -C <cm-worktree> diff --name-only | grep CHANGELOG	CHANGELOG.md
10	operations CHANGELOG updated	git -C <ops-worktree> diff --name-only | grep CHANGELOG	CHANGELOG.md
11	includeBuild reverted	grep -c includeBuild <ops-worktree>/settings.gradle.kts	0 (or no match)
12	Version catalog bumped	grep arda-common-version <ops-worktree>/gradle/libs.versions.toml	New version

Where <ops-worktree> = /Users/jmp/code/arda/projects/image-upload-backend-worktrees/operations, <cm-worktree> = /Users/jmp/code/arda/projects/image-upload-backend-worktrees/common-module.

Agent Prompt Templates

back-end-engineer — be-operations

Primary working directory: /Users/jmp/code/arda/projects/image-upload-backend-worktrees/operations Secondary working directory (for task 2.8): /Users/jmp/code/arda/projects/image-upload-backend-worktrees/common-module Use absolute paths for all tool calls. Prefix Bash commands with cd <worktree-absolute-path> &&.

Implement the image upload endpoint, entity validation, infrastructure wiring, and release coordination. Follow specification.md Phase 2b + Release (tasks T-6 through T-9).

Load skills: kotlin-coding, unit-tests-backend, unit-tests-infra, build-core-modules, release-lifecycle.

Phase 2b source root: src/main/kotlin/cards/arda/operations/reference/item/ Phase 2b test root: src/test/kotlin/cards/arda/operations/reference/item/

Tasks: 2.1 through 2.5, 2.7, 2.8, 2.9 per this plan. Each task produces its tests before the next task starts.

Key decisions: TD-22 (routes in ItemEndpoint), TD-23 (validation in ItemValidator), TD-24 (S3AssetService injected), TD-25 (verify validator DI precedent).

Task 2.1: Configure includeBuild in settings.gradle.kts pointing to /Users/jmp/code/arda/projects/image-upload-backend-worktrees/common-module. Do not commit this change. Run make clean build to verify baseline.

Task 2.5 pre-implementation: Search for ScopingValidator subclasses that are class (not object) to check DI precedent (TD-25). Document findings.

Task 2.8: Switch to common-module worktree. Write CHANGELOG.md entry. Commit and push. Create PR via GitHub MCP tools targeting jmpicnic/claude-prep base. Include attribution block.

Task 2.9: Back in operations worktree. Bump arda-common-version in gradle/libs.versions.toml. Remove includeBuild from settings.gradle.kts. Write CHANGELOG.md entry. Commit and push. Create PR via GitHub MCP tools targeting jmpicnic/claude-prep base. Include attribution block. Expected: CI will fail until common-module is published — this is intentional.

quality-reviewer — qr-operations

Working directory: /Users/jmp/code/arda/projects/image-upload-backend-worktrees/operations Use absolute paths for all tool calls.

Review the new and modified files in the item module:

• helm/operations/pre-install.cfn.yml (IAM policies)
• helm/operations/templates/configmap.yaml (Helm values)
• src/main/kotlin/.../reference/item/Module.kt (DI wiring)
• src/main/kotlin/.../reference/item/api/rest/ (endpoint + models)
• src/main/kotlin/.../reference/item/business/ItemService.kt (service method)
• src/main/kotlin/.../reference/item/persistence/ItemValidator.kt (validation)

And their test files.

Load skills: kotlin-coding, unit-tests-backend.

Evaluate against: Kotlin coding conventions, endpoint delegation pattern (endpoints must not call domain services directly), Result<T> + AppError usage, validator DI pattern, IAM least-privilege, Helm template syntax. Produce a code review report.

PR Monitoring Protocol

Task 2.10: common-module PR

After creating the common-module PR (task 2.8):

1. Background CI monitoring: Poll PR check status. If any check fails, diagnose the failure from CI logs, fix the issue in the common-module worktree, commit, and push.

2. 30-minute comment review: After 30 minutes, read all reviewer comments on the PR. Present to the user as a numbered table:

   #	Reviewer	File	Summary	Recommendation

3. Execute user decisions: For each comment, take the action the user specifies (code change, reply with rationale, create follow-up ticket). Reply to each comment with the action result and resolve the thread.

Task 2.11: operations PR

After the user signals that common-module is published and operations CI has been re-triggered:

1. CI monitoring: Monitor re-triggered checks. If any check fails, diagnose and fix (in operations worktree), commit, push.
2. 30-minute comment review: Same protocol as task 2.10.
3. Execute user decisions: Same protocol as task 2.10.

Handoff

Artifacts Consumed (from Run 1)

Artifact	Source Run	Path
AssetKeyGenerator class	Run 1	common-module: lib/src/main/kotlin/.../infra/storage/AssetKeyGenerator.kt
CdnUrlResolver class	Run 1	common-module: lib/src/main/kotlin/.../infra/storage/CdnUrlResolver.kt
S3AssetService class	Run 1	common-module: lib/src/main/kotlin/.../infra/storage/S3AssetService.kt
Passing common-module build	Run 1	make clean build exit code 0

Artifacts Produced (for subsequent phases)

Artifact	Consumer	Path
common-module PR	Team reviewers → merge → Phase 2c	GitHub PR
operations PR	Team reviewers → merge → Phase 2c	GitHub PR
Published common-module artifact	operations CI	GitHub Packages

Open Questions and Decisions

#	Question	Options	Recommendation	Decision
—	No open questions	—	—	—

All design questions for Run 2 were resolved during specification: TD-22 (routes in ItemEndpoint), TD-23 (validation in ItemValidator), TD-24 (S3AssetService injected), TD-25 (verify validator DI precedent).

Acceptance Criteria

• All endpoint tests pass (7 cases)
• All validator tests pass (9 cases)
• All existing Item tests pass (no regressions)
• make clean build succeeds with exit code 0
• Helm lint passes
• Quality review completed, findings addressed
• common-module PR created, CHANGELOG updated
• operations PR created, CHANGELOG updated, includeBuild reverted, version catalog bumped
• PR reviewer comments addressed (both repos)

Risks and Blockers

Risk / Blocker	Impact	Mitigation
ItemValidator DI conversion breaks existing tests	Medium	TD-25 pre-check; test immediately after conversion
Module.kt wiring errors (missing config values)	Low	Helm lint catches missing required values
operations CI fails after version catalog bump	Expected	User re-triggers after common-module publish
PR reviewer requests significant changes	Medium	Quality review in 2.6 catches issues early
common-module publish delay blocks operations merge	Low	operations PR is created immediately; CI re-triggered later

Project Completion Artifacts

Byproducts (byproducts/)

File	Description
changelog.md	Summary of changes made in Run 2
learnings.md	New knowledge (validator DI pattern, release ordering, PR monitoring)
suggestions.md	Improvement suggestions, tech debt, documentation gaps

Continuous Improvement

Artifact	Produced By	Location
Observation log	CI Observer	session/ci-observations.md
Improvement proposal	Improvement Analyzer	continuous-improvement-proposal.md

Task Tracking Protocol

The team’s TaskList is the single source of truth for task status. Follow the protocol at every phase boundary per the team-lead agent definition.

Progress Log

Date	Event	Notes
2026-03-31	Plan created

---

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