Run 1: common-module Library

Implements the shared S3 asset management library in common-module and refactors CsvS3BucketDirectAccess to use it. Corresponds to specification.md Phase 0 + Phase 2a (tasks T-1 through T-5).

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

User Request

Implement three new classes (AssetKeyGenerator, CdnUrlResolver, S3AssetService) in common-module’s cards.arda.common.lib.infra.storage package, refactor CsvS3BucketDirectAccess to delegate S3 primitives to S3AssetService (TD-18, TD-24), and verify no regressions in existing CSV functionality.

Entry Criteria

#	Criterion	Verification Command	Expected Output
1	common-module worktree exists	git -C /Users/jmp/code/arda/projects/image-upload-backend-worktrees/common-module branch --show-current	jmpicnic/item-image-upload-backend
2	operations worktree exists (for baseline)	git -C /Users/jmp/code/arda/projects/image-upload-backend-worktrees/operations branch --show-current	jmpicnic/item-image-upload-backend
3	No uncommitted changes in common-module	git -C /Users/jmp/code/arda/projects/image-upload-backend-worktrees/common-module status --porcelain	Empty
4	Worktree based on jmpicnic/claude-prep	git -C /Users/jmp/code/arda/projects/image-upload-backend-worktrees/common-module log --oneline -1 origin/jmpicnic/claude-prep	Matches HEAD ancestor

Decomposition

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
1.1	Baseline verification: make clean build both repos	back-end-engineer	—	Pending	All existing tests pass in both common-module and operations; test counts and coverage recorded
1.2	Implement AssetKeyGenerator + AssetKeyGeneratorTest	back-end-engineer	1.1	Pending	7 test cases pass: namespace validation, key format, tenant prefix, UUID uniqueness, content type mapping, unsupported type failure (spec T-2)
1.3	Implement CdnUrlResolver + CdnUrlResolverTest	back-end-engineer	1.1	Pending	7 test cases pass: URL resolution, valid CDN URL, wrong host, cross-tenant, unexpected path, malformed URL, empty string (spec T-3)
1.4	Implement S3AssetService + S3AssetServiceTest	back-end-engineer	1.2, 1.3	Pending	7 test cases pass with MockAWS: presigned PUT, presigned POST, POST policy conditions, HEAD success, HEAD missing, HEAD metadata match, HEAD metadata mismatch. Pre-implementation: verify AWS SDK presigned POST support (spec T-4)
1.5	Refactor CsvS3BucketDirectAccess to delegate to S3AssetService	back-end-engineer	1.4	Pending	Existing CsvS3DirectAccessTest and S3BucketAccessTest pass. Factory methods accept S3AssetService parameter (TD-24). make clean build succeeds (spec T-5)
1.6	Quality review of T-2 through T-5 implementation	quality-reviewer	1.5	Pending	Code review report: no anti-patterns, follows kotlin-coding conventions, appropriate use of Result<T> and AppError hierarchy
1.7	Address quality review findings (if any)	back-end-engineer	1.6	Pending	All actionable findings resolved. make clean build still passes

Worktree Strategy

Single directory — no intra-repo worktrees needed. One back-end-engineer works sequentially through T-2 → T-3 → T-4 → T-5 in the same worktree.

Working directory: /Users/jmp/code/arda/projects/image-upload-backend-worktrees/common-module Branch: jmpicnic/item-image-upload-backend Base branch: jmpicnic/claude-prep

T-2 and T-3 are independent new files, but parallelism is not worthwhile — each is a single source + test file, and worktree overhead exceeds time savings.

Parallelization

• Sequential chain: 1.1 → 1.2 → 1.4 → 1.5 → 1.6 → 1.7
• Sequential chain: 1.1 → 1.3 → 1.4 (1.3 can start after 1.1, independent of 1.2)
• In practice: Single agent executes 1.1 → 1.2 → 1.3 → 1.4 → 1.5 sequentially. Quality reviewer (1.6) runs after 1.5 completes, then back-end-engineer addresses findings (1.7).

1.1 (baseline) → 1.2 (AssetKeyGenerator) ─┐
                 └→ 1.3 (CdnUrlResolver) ──┤→ 1.4 (S3AssetService) → 1.5 (CSV refactor) → 1.6 (QR) → 1.7 (fixes)

Idle Agent Strategy

Accept idle time — the quality-reviewer is idle during implementation (1.1–1.5) and the back-end-engineer is idle during review (1.6). Phases are short enough that buffer tasks add no value.

Personas Required

Persona	Agent Name	Tasks Assigned	Working Directory	Spawn Order
back-end-engineer	be-common-module	1.1, 1.2, 1.3, 1.4, 1.5, 1.7	/Users/jmp/code/arda/projects/image-upload-backend-worktrees/common-module	First
quality-reviewer	qr-common-module	1.6	/Users/jmp/code/arda/projects/image-upload-backend-worktrees/common-module	After 1.5

Artifact Specifications

Artifact	Path (relative to worktree)	Format	Description
AssetKeyGenerator	lib/src/main/kotlin/cards/arda/common/lib/infra/storage/AssetKeyGenerator.kt	Kotlin	Key generation with configurable namespace (TD-19)
CdnUrlResolver	lib/src/main/kotlin/cards/arda/common/lib/infra/storage/CdnUrlResolver.kt	Kotlin	CDN URL construction and validation (TD-14, TD-20)
S3AssetService	lib/src/main/kotlin/cards/arda/common/lib/infra/storage/S3AssetService.kt	Kotlin	Presigned PUT/POST, HEAD, metadata validation (TD-17)
Refactored CSV service	lib/src/main/kotlin/cards/arda/common/lib/infra/storage/CsvS3ObjectDirectService.kt	Kotlin	Delegates S3 primitives to S3AssetService (TD-18, TD-24)
AssetKeyGeneratorTest	lib/src/test/kotlin/cards/arda/common/lib/infra/storage/AssetKeyGeneratorTest.kt	Kotlin/Kotest	7 test cases
CdnUrlResolverTest	lib/src/test/kotlin/cards/arda/common/lib/infra/storage/CdnUrlResolverTest.kt	Kotlin/Kotest	7 test cases
S3AssetServiceTest	lib/src/test/kotlin/cards/arda/common/lib/infra/storage/S3AssetServiceTest.kt	Kotlin/Kotest	7 test cases with MockAWS

Internal Dependency Graph

1.1 (baseline)
 ├──→ 1.2 (AssetKeyGenerator) ──→ 1.4 (S3AssetService) ──→ 1.5 (CSV refactor)
 └──→ 1.3 (CdnUrlResolver) ────┘                           │
                                                            ↓
                                                         1.6 (quality review) ──→ 1.7 (fixes)

Exit Criteria

#	Criterion	Verification Command	Expected Output
1	AssetKeyGeneratorTest passes	make -C <cm-worktree> clean build 2>&1 | grep -c "AssetKeyGeneratorTest"	≥ 1
2	CdnUrlResolverTest passes	make -C <cm-worktree> clean build 2>&1 | grep -c "CdnUrlResolverTest"	≥ 1
3	S3AssetServiceTest passes	make -C <cm-worktree> clean build 2>&1 | grep -c "S3AssetServiceTest"	≥ 1
4	Existing CSV tests pass	make -C <cm-worktree> clean build 2>&1 | grep -c "CsvS3DirectAccessTest"	≥ 1
5	Full build succeeds	make -C <cm-worktree> clean build	Exit code 0
6	Quality review completed	Quality review report exists and findings addressed	—
7	No uncommitted changes outside scope	git -C <cm-worktree> diff --stat	Only expected files

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

Agent Prompt Templates

back-end-engineer — be-common-module

Working directory: /Users/jmp/code/arda/projects/image-upload-backend-worktrees/common-module Use absolute paths for all tool calls. Prefix Bash commands with cd /Users/jmp/code/arda/projects/image-upload-backend-worktrees/common-module &&.

Implement the shared S3 asset management library in common-module. Follow specification.md Phase 0 + Phase 2a (tasks T-1 through T-5).

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

Package: cards.arda.common.lib.infra.storage Source root: lib/src/main/kotlin/cards/arda/common/lib/infra/storage/ Test root: lib/src/test/kotlin/cards/arda/common/lib/infra/storage/

Tasks: 1.1 through 1.5 per this plan. Each task produces its tests before the next task starts. Record any design decisions in the project decision log continuing from TD-25.

Key decisions: TD-17 (PUT+POST), TD-18 (CSV delegation), TD-19 (configurable namespace), TD-20 (ApplicationContext for tenant), TD-24 (S3AssetService injected into CSV factory).

T-4 pre-implementation check: Verify AWS SDK presigned POST support in version pinned by gradle/libs.versions.toml before coding.

After completing all tasks, run make clean build and report the full test count and any coverage changes.

quality-reviewer — qr-common-module

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

Review the new and modified files in lib/src/main/kotlin/cards/arda/common/lib/infra/storage/:

• AssetKeyGenerator.kt
• CdnUrlResolver.kt
• S3AssetService.kt
• CsvS3ObjectDirectService.kt (refactored)

And their test files in lib/src/test/kotlin/cards/arda/common/lib/infra/storage/.

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

Evaluate against: Kotlin coding conventions, Result<T> + AppError usage, suspend function patterns, Exposed ORM conventions (if any), DRY principle, type safety. Produce a code review report.

Handoff

Artifacts Consumed (from previous runs)

None — this is the first run.

Artifacts Produced (for subsequent runs)

Artifact	Consumer Run	Path
AssetKeyGenerator class	Run 2	lib/src/main/kotlin/.../infra/storage/AssetKeyGenerator.kt
CdnUrlResolver class	Run 2	lib/src/main/kotlin/.../infra/storage/CdnUrlResolver.kt
S3AssetService class	Run 2	lib/src/main/kotlin/.../infra/storage/S3AssetService.kt
Passing build baseline	Run 2	make clean build exit code 0
Committed code	Run 2	Branch jmpicnic/item-image-upload-backend

Open Questions and Decisions

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

All design questions for Run 1 were resolved during specification: TD-17 (PUT+POST), TD-18 (CSV delegation), TD-19 (configurable namespace), TD-20 (ApplicationContext), TD-24 (S3AssetService injected into CSV).

Acceptance Criteria

• All 3 new test suites pass (AssetKeyGenerator, CdnUrlResolver, S3AssetService)
• Existing CSV tests pass without modification
• make clean build succeeds with exit code 0
• Quality review completed, findings addressed
• Code committed on jmpicnic/item-image-upload-backend branch

Risks and Blockers

Risk / Blocker	Impact	Mitigation
AWS SDK v2.34.3 lacks presigned POST API	High — T-4 design changes	T-4 pre-implementation check; construct policy manually if needed
CSV refactoring breaks existing tests	High — regression	T-5 constraint: existing tests must pass without modification
S3AssetService factory signature change breaks CSV callers	Medium — test updates needed	TD-24 decided: factory accepts S3AssetService; tests updated to supply MockAWS instance
MockAWS/LocalStack doesn’t support presigned POST	Medium — test coverage gap	Test form field presence only; defer full policy validation to Phase 2c

Project Completion Artifacts

Byproducts (byproducts/)

File	Description
changelog.md	Summary of changes made in Run 1
learnings.md	New knowledge about AWS SDK, MockAWS capabilities
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