Implementation Log

Deviations from plan during implementation, indexed by phase and task. Only deviations are recorded here; tasks that followed the plan exactly are omitted.

Last updated: 2026-04-09 (Phase 3.6b added)

Phase 3.2 — Lifecycle Framework

Task ordering (T-1 vs T-2/T-3)

Plan: Execute T-1 (architecture documentation) first, since “the documentation work clarifies the type contracts.”

Actual: Executed T-2/T-3/T-4 (code) first, then T-1 (documentation) after the code was complete.

Reason: The Phase 3.2 specification already fully defined all type interfaces, hook signatures, and test cases. The documentation task was writing authoritative reference docs, not design exploration. Writing the code first allowed the documentation to reference the actual implementation and produced more accurate API examples.

Architecture documentation split (T-1)

Plan: “Split if > 300 lines” — deferred to implementation.

Actual: Split into 3 files: index.md (overview, state machine, activity flow, validation model), types.md (type catalog, hook reference), composition.md (hierarchical composition, FD-01 relationship). Total: 647 lines.

Reason: The content naturally divided along these seams. A single file would have been too long to navigate effectively.

Activity flow diagrams (T-1, post-review)

Plan: Single activity diagram showing the edit cycle.

Actual: Two activity diagrams with swimlanes: one for immediate contextual errors (parent injects errors into child on each change), one for delayed contextual errors (parent shows warning during editing, promotes to error on confirm). A comparison table was also added.

Reason: User review identified that contextual error propagation has two distinct forms that warrant separate documentation. The delayed pattern (e.g., “February 30” from independent day/month fields) was not captured in the original exploration documents.

Phase 3.3 — Component Updates

Run 3b executed without infrastructure#439 (T-1 change 7)

Plan: Run 3b entry criterion #2 required infrastructure#439 (CloudFront CORS Response Headers Policy) to be deployed.

Actual: Run 3b was executed before the infrastructure PR merged.

Reason: The crossOrigin code is testable in Storybook without the infrastructure (Storybook uses local blobs, not CDN URLs). Implementing it alongside Run 3a meant the published package (@arda-cards/design-system@4.8.0) ships ready for production when the infrastructure deploys, avoiding a second publish cycle. The user later confirmed the CORS policy is live in the dev environment, which is sufficient for development.

Phase 3.4 — Design System Publish

CHANGELOG category reclassification (T-2)

Plan: Changed entries for “progress indicator changed from simulated percentage to indeterminate” and “upload triggered directly instead of after timer.”

Actual: Reclassified as Fixed entries.

Reason: The clq CHANGELOG validator enforces the changemap strictly: Changed triggers a major version bump (5.0.0). These are internal behavioral improvements (not breaking API changes) — the simulated progress was misleading, and the timer was unnecessary. A major bump would be disproportionate. Reclassifying as Fixed keeps the appropriate minor bump (4.8.0).

Version bump is CI-managed (T-3)

Plan: “Bump version in package.json per changelog category rules.”

Actual: No manual version bump. The publish.yml CI workflow extracts the version from the CHANGELOG via clq-action and sets it with npm version before publishing.

Reason: The package.json version on main is always 0.1.0 (a placeholder). The CI pipeline is the source of truth for the published version. Manual bumping would be overwritten by CI and could cause merge conflicts if multiple PRs touch package.json.

Starlight slug overrides for dotted directory names

Plan: Not anticipated — the 3.1-api-proxy-publish/, 3.5-bff-routes/, and 3.6-spa-integration/ directories were expected to generate correct URLs.

Actual: Added slug: frontmatter overrides to 3 phase specification files.

Reason: Starlight strips dots from directory names in generated URL slugs (e.g., 3.1-api-proxy-publish becomes 31-api-proxy-publish). The remark-resolve-md-links plugin resolves .md links to filesystem paths (with dots), creating a mismatch. Explicit slug: frontmatter forces Starlight to use the dotted path, matching what the link resolver produces.

Cross-Phase

Documentation file reorganization (post-Run 4)

Plan: Architecture docs at user-interaction/edit-lifecycle.md, user-interaction/edit-lifecycle-types.md, user-interaction/edit-lifecycle-composition.md.

Actual: Moved to user-interaction/edit-lifecycle/index.md, types.md, composition.md.

Reason: User review — the edit-lifecycle- prefix was redundant once the files lived in their own subdirectory. The subdirectory grouping is cleaner for navigation.

Run 1 exit validation script bug

Plan: validate-exit.sh scripts use ((PASS++)) for counting.

Actual: The script fails on the first check under set -euo pipefail because ((PASS++)) evaluates to 0 (post-increment of 0 is falsy in bash arithmetic), which causes an exit code 1.

Reason: Known bash pitfall. All Run 1 checks were verified manually and passed. The bug affects all validate-exit.sh scripts in the project (Runs 1-7) but does not affect correctness — the scripts are convenience tools, not gates.

Phase 3.5 — BFF Routes

`aws-naming.ts` location: `src/lib/shared/` instead of `src/server/lib/` (T-1b)

Plan: Place resolveAwsNaming() in src/server/lib/aws-naming.ts.

Actual: Placed in src/lib/shared/aws-naming.ts.

Reason: The spec requires Phase 3.6 SPA code (useCdnCookies, useImageWithCdnRecovery) to import resolveAwsNaming() for CDN host detection and cookie refresh intervals. But src/server/ has import 'server-only' which blocks client-side imports. Since resolveAwsNaming() reads only NEXT_PUBLIC_* env vars (non-sensitive deployment identifiers), there is no security reason to restrict it to server-only. The src/lib/shared/ directory was created to mark clearly that these utilities are importable by both BFF and SPA. Long-term, existing src/lib/ contents should migrate into client/, server/, or shared/ subdirectories.

Cookie timing extracted from `AwsNaming` to `cdn-config.ts` (T-1b)

Plan: AwsNaming interface included cookieTtlMs and cookieRefreshIntervalMs fields.

Actual: Cookie timing moved to src/lib/shared/cdn-config.ts. AwsNaming retains only naming concerns (fqn, subdomain, cdnHost, signingKeySecretName).

Reason: Design review identified location coupling — cookie TTL has no relationship to AWS resource naming. Co-locating them in the naming utility created a false dependency. The separate cdn-config module follows the Single Responsibility Principle and is independently importable by the signer (server) and the cookie hook (SPA).

Singleton pattern in `secrets.ts` documented as tech debt (T-1c)

Plan: Module-level singleton (global client and cache).

Actual: Same implementation, with tech debt comment added.

Reason: Design review noted that a class-based DI pattern would be more testable and modular. The singleton was retained for consistency with the existing codebase (env.ts, jwt.ts) — introducing DI in one module while the rest uses singletons would be inconsistent. The comment records the migration path: refactor alongside the planned src/lib/ → client/server/shared reorganization.

Route handlers refactored to single return point (T-5 through T-8)

Plan: Original implementations had 4-6 return points per handler.

Actual: Refactored to single return via helper function pipelines: handleX() → checkPreflight() → processX() → buildResponse().

Reason: Design review applied the single-return-point standard (added to TypeScript coding standards as part of this review). Multiple early returns made control flow hard to maintain. The pipeline pattern decomposes each handler into named steps with clear responsibilities.

TypeScript coding standards updated (cross-phase)

Plan: No control flow guidance in the TypeScript coding skill.

Actual: Added “Single Return Point” and “Next.js Route Handlers” sections to process/craft/implementation/typescript-coding.md, mirroring the existing Kotlin standard.

Reason: Design review identified the gap. The Kotlin skill explicitly mandates single return point; the TypeScript skill had no equivalent. The addition ensures consistency across backend and frontend coding standards.

Phase 3.6 — SPA Integration

T-9: Form integration deferred (ItemCard complexity)

Plan: Replace the disabled image dropzone placeholder in ItemFormPanel with ImageFormField from the design system, wired to the upload dialog via useItemImageUploadDialog.

Actual: Replaced the entire legacy ItemCard component with ItemCardEditor from the design system (@arda-cards/design-system/canary). Upload hooks wired via Option B bridge (forwarding props). Legacy ItemCard marked @deprecated but retained for rollback.

Reason: ItemCardEditor is the design system’s WYSIWYG card editor that already integrates ImageUploadDialog and ImageDropZone. Using it replaces ~1,400 lines of legacy code (itemCard.tsx + test + mappings) with ~40 lines of field mapping. Feature parity gap (unit typeahead, size selectors, validation display) tracked in management#861. Upload hook injection will migrate from Option B (prop forwarding) to Option C (ImageUploadContext) per management#860 when ux-prototype#77 lands.

Cookie timing uses `cdn-config` instead of `AwsNaming` (T-4)

Plan: Spec references resolveAwsNaming().cookieRefreshIntervalMs.

Actual: Uses cookieRefreshIntervalMs from @/lib/shared/cdn-config.

Reason: Run 5 design review separated cookie timing from AWS naming.

Type name correction in api-proxy re-exports (T-2)

Plan: Spec references ImageUploadUrlRequest / ImageUploadUrlResponse.

Actual: The actual exported names from @arda-cards/api-proxy are ImageUploadRequest / ImageUploadResponse (without Url).

Reason: Spec used aspirational names; corrected to match the actual published package exports.

Scope Addition — Phase 3.6b (2026-04-09)

Backend strict validation added to project scope

Plan: Original specification covered 4 repositories (api-proxy, ux-prototype, arda-frontend-app, documentation) across 8 phases (3.1–3.7).

Actual: Added Phase 3.6b (operations repository) and an operations worktree, expanding the project to 5 repositories and 9 phases.

Reason: operations#164 — the backend relaxed strict CDN URL validation for backward compatibility during Phase 2 (commit 9ad1c03). Now that the frontend sends only CDN URLs (Phase 3.6 complete), the strict validation can be restored. Including this in the image upload frontend project keeps the full-stack feature delivery coordinated and ensures merge ordering is correct (backend strict validation must land before or alongside the frontend PR).