Choreography: Backend Services for Item Image Upload

Execution Sequence

Order	Run	Directory	Trigger	Estimated Tasks
1	Run 1: common-module Library	`run-1-common-module/`	Manual	7 (5 implementation + 2 review)
2	Run 2: operations Endpoints + Release	`run-2-operations/`	After Run 1 exit gate passes	11 (5 implementation + 2 review + 4 release/monitoring)

Artifact Dependency Map

Artifact	Produced By	Consumed By	Path	Format
`AssetKeyGenerator` class	Run 1	Run 2 (Module.kt, endpoint)	`common-module: lib/src/.../infra/storage/AssetKeyGenerator.kt`	Kotlin
`CdnUrlResolver` class	Run 1	Run 2 (Module.kt, validator)	`common-module: lib/src/.../infra/storage/CdnUrlResolver.kt`	Kotlin
`S3AssetService` class	Run 1	Run 2 (Module.kt, endpoint, validator, CSV)	`common-module: lib/src/.../infra/storage/S3AssetService.kt`	Kotlin
Passing common-module build	Run 1	Run 2 (entry criterion)	`make clean build` exit code	Build output
Committed common-module code	Run 1	Run 2 (`includeBuild`)	Branch `jmpicnic/item-image-upload-backend`	Git
common-module PR	Run 2	Team reviewers → merge → CI/CD publish	GitHub PR	GitHub
operations PR	Run 2	Team reviewers → merge	GitHub PR	GitHub
Published common-module artifact	Run 2 (post-merge, automated)	operations CI (re-trigger)	GitHub Packages	Maven

Hand-Off Protocol

All hand-offs are filesystem-only — no in-memory state is shared between runs. Each run reads its inputs from the worktree filesystem.

Between Run 1 and Run 2

Run 1 completes all tasks and validate-exit.sh passes.
The coordinator verifies the exit gate output.
Run 2’s entry criteria are checked:
- Run 1 exit gate passed
- common-module builds successfully
- operations worktree exists and is clean
Run 2 is launched.

No deployment gate between runs — Run 2 consumes common-module classes via Gradle includeBuild (local source tree), not a published artifact. The published artifact dependency is only relevant at PR merge time.

After Run 2

After Run 2 completes, the following steps happen outside the agent team:

common-module PR review: Team members review and approve the common-module PR. Agent has addressed initial reviewer comments.
common-module merge: Team member merges the PR. CI/CD automatically tags and publishes to GitHub Packages.
operations CI re-trigger: User re-triggers operations CI after the common-module artifact is available. User notifies the agent (task 2.11).
operations PR review: Team members review and approve the operations PR. Agent addresses reviewer comments after re-trigger.
operations merge: Team member merges the PR.

Worktree Strategy

Three worktrees, all pre-existing (created during project setup):

Worktree	Repository	Branch	Used By
`projects/image-upload-backend-worktrees/common-module`	common-module	`jmpicnic/item-image-upload-backend`	Run 1 (primary), Run 2 (CHANGELOG + PR)
`projects/image-upload-backend-worktrees/operations`	operations	`jmpicnic/item-image-upload-backend`	Run 2 (primary)
`projects/image-upload-backend-worktrees/documentation`	documentation	`jmpicnic/item-image-upload-backend`	Planning documents (this directory)

Base branch (all repos): jmpicnic/claude-prep

No new worktrees need to be created between runs. Both runs use the same worktrees and the same branch names. Run 2 picks up where Run 1 left off in common-module (for CHANGELOG + PR creation).

Cleanup: After both PRs are merged, remove all three worktrees:

git -C /Users/jmp/code/arda/common-module worktree remove \
  /Users/jmp/code/arda/projects/image-upload-backend-worktrees/common-module
git -C /Users/jmp/code/arda/operations worktree remove \
  /Users/jmp/code/arda/projects/image-upload-backend-worktrees/operations
git -C /Users/jmp/code/arda/documentation worktree remove \
  /Users/jmp/code/arda/projects/image-upload-backend-worktrees/documentation
rmdir /Users/jmp/code/arda/projects/image-upload-backend-worktrees

Recovery Procedures

Run 1 fails mid-execution

Diagnosis: Check which tasks completed by reviewing git diff in the common-module worktree. Each task produces independent files (except T-5 which modifies existing code).
Retry: Fix the failing task. If T-5 (CSV refactoring) caused regressions, git checkout the modified file and restart T-5.
Build failure: Run make clean build and review the Gradle output. Common issues: MockAWS configuration, import statements, test assertions.

Run 1 exit gate fails

Test failures: Run individual test classes to isolate:

cd <cm-worktree> && ./gradlew :lib:test --tests "*.AssetKeyGeneratorTest"

Build failure: Check for compilation errors, missing imports, or Gradle dependency issues.
CSV regression: If CsvS3DirectAccessTest or S3BucketAccessTest fail, review the T-5 changes. The factory method signature changed (TD-24) — ensure tests supply an S3AssetService instance.

Run 2 fails mid-execution

Diagnosis: Run make clean build to identify failing tests.
Endpoint errors: Check ImageUploadEndpointTest — common issues: MockAWS service registration, Harness configuration, content negotiation.
Validator errors: Check ItemValidator tests — common issues: ApplicationContext mock setup, BitemporalEntity construction, AppError type matching.
Module wiring: If config loading fails, verify Helm values match the requireExtra() keys in Module.kt.

Run 2 exit gate fails

PR creation failure: Check GitHub authentication (gh auth status). Verify branch is pushed to remote.
CHANGELOG missing: Ensure the CHANGELOG entry follows Keep a Changelog format with the correct version header.
includeBuild not reverted: Check settings.gradle.kts for remaining includeBuild directives.
Version catalog not bumped: Verify gradle/libs.versions.toml has the new arda-common-version.

operations CI fails after re-trigger

common-module artifact not found: Verify the common-module release was published to GitHub Packages. Check the package version matches arda-common-version in the operations version catalog.
Test compilation error: The common-module API may have changed during review. Re-check imports and method signatures.

Launch Commands

Run	Command
1	`/launch-team 2-backend-services/plan/run-1-common-module`
2	`/launch-team 2-backend-services/plan/run-2-operations`

Paths are relative to the project root: projects/image-upload-backend-worktrees/documentation/src/content/docs/roadmap/completed/item-image-upload/