Skip to content
Arda Platform Documentation

Specification: Phase 3.7 — Release

Final release activities: project closing documents, CHANGELOG updates, PR creation, merge ordering. Worktree cleanup is performed separately at the user’s request.

Entry Criteria

Section titled “Entry Criteria”
  • Phase 3.6b complete: backend strict validation reviewed and approved
  • All phases 3.1–3.6b committed and passing checks
  • api-proxy already merged (Phase 3.1)
  • ux-prototype already merged (Phase 3.4)

Tasks

Section titled “Tasks”

T-1: Project closing documents

Section titled “T-1: Project closing documents”

Produce the standard project byproducts per the implementation-task skill (byproduct generation phase) in the documentation worktree under the project directory (3-frontend-implementation/byproducts/):

  • changelog.md — consolidated log of all commits across all repos, organized by phase. Include commit hashes, dates, and brief descriptions.
  • learnings.md — key insights discovered during implementation: patterns that worked well, surprises, technical debt identified, performance observations. At minimum document:
    • TanStack Query integration patterns that worked/didn’t
    • Design system typed provider pattern (FD-01) practical experience
    • useDraft<T> hook usage patterns
    • BFF route structure (FD-02) practical experience
    • Any deviations from specification and why
  • suggestions.md — improvement recommendations for future projects: things to do differently, tools to adopt, patterns to standardize.
  • alternatives.md — design alternatives that were considered and rejected during implementation (beyond what’s already in the architectural exploration documents).
  • skipped.md — items that were in scope but skipped or deferred, with rationale and ticket references.
  • specification-post.md — post-implementation specification recording any deviations from the original specification. For each deviation: what was specified, what was implemented, and why.

T-2: arda-frontend-app CHANGELOG

Section titled “T-2: arda-frontend-app CHANGELOG”

Update CHANGELOG.md per the release-lifecycle skill conventions:

  • Added: @tanstack/react-query integration, @aws-sdk/client-secrets-manager, image upload BFF routes (/api/image-upload, /api/storage/check-url, /api/storage/fetch-url, /api/storage/cdn-cookies), CDN cookie lifecycle manager, TanStack Query hooks (useImageUpload, useCheckReachability, useFetchExternalImage, useCdnCookies), image components wired in item grid and forms, ITEM_IMAGE_CONFIG, src/server/ and src/api/ directory structure (FD-02), src/server/lib/aws-naming.ts (AWS naming convention utility), src/server/lib/secrets.ts (generic secrets utility with configurable cache TTL), useImageWithCdnRecovery shared CDN image recovery hook (src/hooks/cdn/), NEXT_PUBLIC_INFRASTRUCTURE, NEXT_PUBLIC_PARTITION, and NEXT_PUBLIC_CDN_COOKIE_TTL_MS environment variables.
  • Changed: Item grid column definitions include image cell display/editor. ItemFormPanel includes optional image field.

T-3: arda-frontend-app PR

Section titled “T-3: arda-frontend-app PR”
  • Create PR from jmpicnic/image-upload-frontend to dev
  • Include attribution block
  • PR description summarizes all phases
  • Run /pr-steward <pr-url> to monitor CI checks, surface reviewer comments, implement fixes, reply to threads, and resolve conversations

T-4: operations CHANGELOG

Section titled “T-4: operations CHANGELOG”

Update CHANGELOG.md per the release-lifecycle skill conventions:

  • Changed: Restore strict CDN image URL validation — reject non-CDN external URLs with 400. Infrastructure config values (imageAssetBucketName, imagePresignRoleArn, imageCdnDomain) are now required (module fails to start if missing). Helm deploy fails if CloudFormation exports are missing.

Note: The operations CHANGELOG has already been updated by the user. Verify the entry exists and is accurate.

T-5: operations PR

Section titled “T-5: operations PR”
  • Create PR from jmpicnic/image-upload-frontend to jmpicnic/multi-pdf-print-and-bugs (the parent branch)
  • Include attribution block
  • Run /pr-steward <pr-url> to monitor CI checks

T-6: documentation CHANGELOG

Section titled “T-6: documentation CHANGELOG”

Update CHANGELOG.md per the release-lifecycle skill conventions:

  • Added: Frontend implementation planning documents (goal, analysis, requirements, verification, 7 phase specifications), architectural exploration documents (TanStack adoption, component binding, lifecycle framework, code organization, architectural review), edit lifecycle architecture documentation (current-system/architecture/user-interaction/), project byproducts.

T-7: documentation PR

Section titled “T-7: documentation PR”
  • Create PR from jmpicnic/image-upload-frontend to main
  • Run make pr-checks before pushing
  • Run /pr-steward <pr-url> to monitor CI checks, surface reviewer comments, implement fixes, reply to threads, and resolve conversations

T-7b: File legacy ItemCard removal ticket

Section titled “T-7b: File legacy ItemCard removal ticket”

Create a GitHub issue tracking the removal of the legacy src/components/items/itemCard.tsx component and its associated rollback scaffolding in ItemFormPanel.tsx, to be addressed in a follow-up project after this one closes.

Rationale (per Phase 3.6c audit in ../36c-discovery-remediation/analysis.md, Issue 3):

  • Originally-claimed parity gaps (three size selectors, inline validation) do not exist — they were misattributed. The size selectors are rendered by ItemFormPanel itself, and neither legacy ItemCard nor ItemCardEditor supports per-field inline validation.
  • No technical blocker remains to removing legacy ItemCard, but the removal is out of scope for this project to keep scope contained.

Ticket fields (recommended):

  • Title: Remove legacy ItemCard after image-upload-frontend project
  • Repo: Arda-cards/arda-frontend-app
  • Body:
    • Link to this analysis: .../36c-discovery-remediation/analysis.md
    • Files to touch: src/components/items/itemCard.tsx (delete), ItemFormPanel.tsx (remove handleItemCardChange, @deprecated imports, cardEditorFields legacy mapping, and the commented rollback instructions around line 1278)
    • Tests to remove: itemCard.test.tsx and any ItemCard-specific mocks
    • Acceptance criteria:
      • No references to itemCard remain in src/
      • npm run lint, npm run typecheck, npx jest, and make test-e2e-safari all pass
      • CHANGELOG updated with a Removed entry (major bump)
  • Label / project: tie to whatever tracker is used for arda-frontend-app technical debt items.

Also: re-assess Arda-cards/management#861 in light of the audit — update its scope or close it with a reference to the new removal ticket.

T-8: Move project docs to completed/

Section titled “T-8: Move project docs to completed/”

After all PRs are merged, move the project documentation from roadmap/completed/item-image-upload/3-frontend-implementation/ to roadmap/completed/item-image-upload/3-frontend-implementation/.

Commit and push as a follow-up to the documentation PR (or amend if not yet merged).

T-9: Merge ordering

Section titled “T-9: Merge ordering”

Per release-lifecycle skill conventions for multi-repository projects:

  1. documentation PR — merge first (no code dependencies)
  2. operations PR — merge after documentation (backend must enforce strict validation before frontend PR lands on main)
  3. arda-frontend-app PR — merge last

(api-proxy and ux-prototype PRs already merged in Phases 3.1 and 3.4.)

T-10: Worktree cleanup (user-initiated)

Section titled “T-10: Worktree cleanup (user-initiated)”

Do NOT execute automatically. Present the following commands to the user and wait for explicit confirmation before running:

Terminal window
# Remove 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


# Remove worktree parent directory
rmdir /Users/jmp/code/arda/projects/image-upload-frontend-worktrees


# Clean up local branches
git -C /Users/jmp/code/arda/api-proxy branch -d jmpicnic/image-upload-frontend
git -C /Users/jmp/code/arda/ux-prototype branch -d jmpicnic/image-upload-frontend
git -C /Users/jmp/code/arda/arda-frontend-app branch -d jmpicnic/image-upload-frontend
git -C /Users/jmp/code/arda/operations branch -d jmpicnic/image-upload-frontend
git -C /Users/jmp/code/arda/documentation branch -d jmpicnic/image-upload-frontend

The user must explicitly request cleanup. Do not run these commands as part of an automated phase execution.

Exit Criteria

Section titled “Exit Criteria”
  • Project byproducts produced (learnings, suggestions, alternatives, skipped, specification-post, changelog)
  • All CHANGELOGs updated
  • All PRs created, reviewed, and merged
  • Merge ordering followed (documentation first, then arda-frontend-app)
  • Project documentation moved to completed/
  • Worktree cleanup commands presented to user (not executed automatically)

Open Questions and Decisions

Section titled “Open Questions and Decisions”
#QuestionOptionsRecommendationDecision
—None———

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

Copyright: © Arda Systems 2025-2026, All rights reserved