Choreography: Frontend Implementation for Item Image Upload

Execution Sequence

Order	Run	Directory	Trigger	Repository
1	Run 1: API Proxy Publish	`run-1-api-proxy-publish/`	Manual	api-proxy
2	Run 2: Lifecycle Framework	`run-2-lifecycle-framework/`	After Run 1 exit gate	ux-prototype + documentation
3	Run 3a: Component Updates	`run-3a-component-updates/`	After Run 2 exit gate	ux-prototype
4	Run 3b: CORS Integration	`run-3b-cors-integration/`	After Run 3a exit gate + infrastructure#439 deployed	ux-prototype
5	Run 4: Design System Publish	`run-4-design-system-publish/`	After Run 3b exit gate	ux-prototype
6	Run 5: BFF Routes	`run-5-bff-routes/`	After Run 1 exit gate (api-proxy published) + component-preparation merged	arda-frontend-app
7	Run 6: SPA Integration	`run-6-spa-integration/`	After Run 4 + Run 5 exit gates	arda-frontend-app
8	Run 6b: Backend Strict Validation	—	After Run 6 exit gate + CDN infra deployed	operations
9	Run 7: Release	`run-7-release/`	After Run 6b exit gate	all repos

Parallelization note: Runs 2–4 (ux-prototype track) and Run 5 (arda-frontend-app track) have independent entry criteria once Run 1 completes. If execution schedules require it, these two tracks can run in parallel — Run 5 depends only on Run 1 (api-proxy published), not on Runs 2–4. The current plan documents strictly sequential execution; this note records the parallelization option for reference.

Artifact Dependency Map

Artifact	Produced By	Consumed By	Path	Format
`@arda-cards/api-proxy` package	Run 1	Run 5	GitHub Packages	npm
`RequestContext` + `RequestOptions` types	Run 1	Run 5 (BFF imports api-proxy)	`src/shared/types.ts` in api-proxy	TypeScript
`processUploadJob()` method	Run 1	Run 5 (BFF calls method)	`src/reference/item/proxy.ts` in api-proxy	TypeScript
Lifecycle types (`FieldError`, `ValidationResult`, etc.)	Run 2	Run 3a	`src/types/canary/utilities/edit-lifecycle.ts` in ux-prototype	TypeScript
`setNestedField` utility	Run 2	Run 3a	`src/types/canary/utilities/set-nested-field.ts` in ux-prototype	TypeScript
`useDraft<T>` hook	Run 2	Run 3a	`src/types/canary/utilities/use-draft.ts` in ux-prototype	TypeScript
Edit lifecycle architecture docs	Run 2	All engineers (reference)	`documentation/src/content/docs/current-system/architecture/user-interaction/`	Markdown
Updated `ImageUploadDialog` (indeterminate progress + UploadError)	Run 3a	Run 3b, Run 4	ux-prototype	TypeScript/TSX
Updated `ImageCellEditor` factory	Run 3a	Run 4	ux-prototype	TypeScript/TSX
Updated `ImageFormField`	Run 3a	Run 4	ux-prototype	TypeScript/TSX
Updated `ItemGridColumns`	Run 3a	Run 4	ux-prototype	TypeScript/TSX
`crossOrigin="use-credentials"` support	Run 3b	Run 4	ux-prototype	TypeScript/TSX
`@arda-cards/design-system` package	Run 4	Run 6	GitHub Packages	npm
BFF routes (`/api/items/upload-url`, etc.)	Run 5	Run 6	`src/server/` in arda-frontend-app	TypeScript
SSRF validator, CDN signer, rate limiter utilities	Run 5	Run 6	`src/server/` in arda-frontend-app	TypeScript
Strict CDN validation in `operations`	Run 6b	Run 7	Worktree branch	Git
All committed code (all repos)	Runs 1–6b	Run 7	Worktree branches	Git

Hand-Off Protocol

All hand-offs are filesystem-only — no in-memory state is shared between runs. Runs exchange artifacts via committed code on worktree branches and published npm packages.

Between Run 1 and Runs 2 + 5

Run 1 completes all tasks and exit criteria pass.
The coordinator verifies that @arda-cards/api-proxy is published to GitHub Packages and the new version is installable.
Run 2 (ux-prototype track) and Run 5 (arda-frontend-app track) may both proceed.

Between Runs 2, 3a, 3b, and 4 (ux-prototype track)

Each run in the ux-prototype track produces committed code consumed by the next run in the same worktree. There is no npm publish between these runs — the library build happens only in Run 4. Each run’s exit gate must pass before the next run starts.

Between Run 4 and Run 6

Run 6 requires both:

@arda-cards/design-system published at the new version (produced by Run 4)
BFF routes committed in arda-frontend-app (produced by Run 5)

Verify both conditions before launching Run 6.

Between Run 6 and Run 6b

Run 6b restores strict CDN image URL validation in operations by reverting the backward-compatibility relaxations from PR #163. This is safe to execute once the frontend sends only CDN URLs (Run 6 complete) and CDN infrastructure is deployed to all environments. See operations#164.

After Run 6b

Run 7 (Release) prepares CHANGELOGs, creates PRs, and coordinates merge ordering across all repositories. It requires all prior runs to have their code committed and all CI checks passing on their respective branches.

Worktree Strategy

All worktrees are pre-existing (created during project setup):

Worktree	Repository	Branch	Used By
`projects/image-upload-frontend-worktrees/api-proxy`	api-proxy	`jmpicnic/image-upload-frontend`	Run 1
`projects/image-upload-frontend-worktrees/ux-prototype`	ux-prototype	`jmpicnic/image-upload-frontend`	Runs 2, 3a, 3b, 4
`projects/image-upload-frontend-worktrees/arda-frontend-app`	arda-frontend-app	`jmpicnic/image-upload-frontend`	Runs 5, 6, 7
`projects/image-upload-frontend-worktrees/operations`	operations	`jmpicnic/image-upload-frontend`	Run 6b
`projects/image-upload-frontend-worktrees/documentation`	documentation	`jmpicnic/image-upload-frontend`	All runs (documentation commits)

No new worktrees need to be created between runs. All runs operate on the same branches.

Cleanup: After all PRs are merged, remove all four worktrees:

git -C /Users/jmp/code/arda/api-proxy worktree remove \
  /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/api-proxy
git -C /Users/jmp/code/arda/ux-prototype worktree remove \
  /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/ux-prototype
git -C /Users/jmp/code/arda/arda-frontend-app worktree remove \
  /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/arda-frontend-app
git -C /Users/jmp/code/arda/operations worktree remove \
  /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/operations
git -C /Users/jmp/code/arda/documentation worktree remove \
  /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation
rmdir /Users/jmp/code/arda/projects/image-upload-frontend-worktrees

Recovery Procedures

Run N fails mid-execution

Check which tasks completed by reviewing the git log in the affected worktree.
Fix the failing task. Each task is isolated to specific files, so partial completion does not corrupt prior tasks.
Re-run from the failing task.
Run validate-exit.sh to confirm all exit criteria pass.

Run N exit gate fails

Read the validation output to identify which criteria failed.
Fix the issues in the worktree.
Commit the fixes.
Re-run validate-exit.sh.

Run 3a completes and infrastructure#439 is already deployed

If infrastructure#439 is deployed by the time Run 3a finishes, Runs 3a and 3b may be merged into a single execution. In that case, add the crossOrigin task (Run 3b T-1 through T-3) to the Run 3a session before committing and exit the combined run against the union of both runs’ exit criteria.

npm publish fails (Runs 1 or 4)

Verify the PR is merged to main and CI has completed.
Check GitHub Packages registry for the package: npm view @arda-cards/<package> versions --registry=https://npm.pkg.github.com
If CI publish step failed, re-trigger the publish workflow from the GitHub Actions UI.
Do not proceed to downstream runs until the package is confirmed installable.

Launch Commands

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

Run	Command
1	`/launch-team 3-frontend-implementation/plan/run-1-api-proxy-publish`
2	`/launch-team 3-frontend-implementation/plan/run-2-lifecycle-framework`
3a	`/launch-team 3-frontend-implementation/plan/run-3a-component-updates`
3b	`/launch-team 3-frontend-implementation/plan/run-3b-cors-integration`
4	`/launch-team 3-frontend-implementation/plan/run-4-design-system-publish`
5	`/launch-team 3-frontend-implementation/plan/run-5-bff-routes`
6	`/launch-team 3-frontend-implementation/plan/run-6-spa-integration`
7	`/launch-team 3-frontend-implementation/plan/run-7-release`