Run 2: Lifecycle Framework

Introduces the minimal lifecycle framework types (FieldError, ValidationResult, Validator<T>, EditPhase, EditLifecycleCallbacks<T>, EditableComponentProps<T>), the setNestedField utility, and the useDraft<T> hook into ux-prototype. Also creates the authoritative Edit Lifecycle architecture documentation in the documentation repository. Corresponds to specification.md.

Author: Claude Code for jmpicnic | Date: 2026-04-07 | Status: Planning

User Request

Implement the minimal lifecycle framework as the foundation for Phase 3.3 component updates. Scope is intentionally minimal per FD-03: only the types and hooks needed by the image upload components. The full framework (useComposedDraft<T>, createCellEditorFactory, EditablePanel<T>) is deferred to ux-prototype#77.

Entry Criteria

#	Criterion	Verification Command	Expected Output
1	Run 1 exit gate passed	npm view @arda-cards/api-proxy versions --registry=https://npm.pkg.github.com	New version present
2	ux-prototype worktree on correct branch	git -C /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/ux-prototype branch --show-current	jmpicnic/image-upload-frontend
3	documentation worktree on correct branch	git -C /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation branch --show-current	jmpicnic/image-upload-frontend
4	Existing ux-prototype checks pass	make -C /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/ux-prototype check	Exit 0
5	Existing ux-prototype tests pass	make -C /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/ux-prototype test	Exit 0
6	Existing ux-prototype build passes	make -C /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/ux-prototype build	Exit 0

Decomposition

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
2.1	Create Edit Lifecycle architecture documentation in documentation worktree	front-end-engineer	—	Pending	edit-lifecycle.md (and splits if > 300 lines) published to current-system/architecture/user-interaction/; state machine, activity, validation model, type catalog, hook reference, composition diagrams present; make pr-checks passes
2.2	Create lifecycle types file src/types/canary/utilities/edit-lifecycle.ts	front-end-engineer	—	Pending	All 6 types (FieldError, ValidationResult, Validator<T>, EditPhase, EditLifecycleCallbacks<T>, EditableComponentProps<T>) defined and exported; type-level unit tests (8+ cases) in edit-lifecycle.test.ts pass
2.3	Create setNestedField utility src/types/canary/utilities/set-nested-field.ts	front-end-engineer	—	Pending	8 unit test cases pass: shallow path, nested path, deep path, creates intermediates, no mutation, preserves siblings, single segment, sibling field preservation
2.4	Implement useDraft<T> hook src/types/canary/utilities/use-draft.ts	front-end-engineer	2.2, 2.3	Pending	15+ unit test cases pass covering: initial state, update(), function updater, updateField(), confirm() valid/invalid, cancel(), reset(), initialValue change, isEqual option, contextErrors merge, errorsFor() filtering, warning severity
2.5	Export types and hook from canary barrel	front-end-engineer	2.2, 2.3, 2.4	Pending	useDraft importable from @arda-cards/design-system/canary; lifecycle types importable from @arda-cards/design-system/types/canary; setNestedField exported from canary barrel
2.6	Full checks (ux-prototype)	front-end-engineer	2.5	Pending	make check, make test, make build all exit 0; new tests included in counts
2.7	Documentation checks and commit	front-end-engineer	2.1, 2.6	Pending	make pr-checks passes in documentation worktree; documentation changes committed referencing Phase 3.2

Worktree Strategy

Two worktrees are active in this run:

Worktree	Purpose
/Users/jmp/code/arda/projects/image-upload-frontend-worktrees/ux-prototype	Implementation (T-2 through T-6)
/Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation	Architecture documentation (T-1) and final commit (T-7)

T-1 (architecture documentation) and T-2/T-3 (types and utility) are independent and could proceed in parallel within a single session. In practice, a single agent handles them sequentially — T-1 before T-2, since the documentation work clarifies the type contracts.

Parallelization

Single agent executes all tasks sequentially. T-2 and T-3 are independent new files but the sequential cost is minimal. T-4 depends on both.

2.1 (architecture docs — documentation worktree)
2.2 (lifecycle types) ─┐
2.3 (setNestedField)  ─┤→ 2.4 (useDraft<T>) → 2.5 (barrel exports) → 2.6 (full checks) → 2.7 (docs commit)

Idle Agent Strategy

Single agent; no idle time.

Personas Required

Persona	Agent Name	Tasks Assigned	Working Directory	Spawn Order
front-end-engineer	fe-lifecycle	2.1 through 2.7	ux-prototype + documentation worktrees	First

Artifact Specifications

Artifact	Path (relative to ux-prototype worktree)	Format	Description
FieldError type	src/types/canary/utilities/edit-lifecycle.ts	TypeScript	field, message, optional code, severity
ValidationResult type	src/types/canary/utilities/edit-lifecycle.ts	TypeScript	valid: boolean, errors: FieldError[]
Validator<T> type	src/types/canary/utilities/edit-lifecycle.ts	TypeScript	(value: T) => ValidationResult
EditPhase type	src/types/canary/utilities/edit-lifecycle.ts	TypeScript	'idle' | 'editing' | 'confirming' | 'error'
EditLifecycleCallbacks<T> interface	src/types/canary/utilities/edit-lifecycle.ts	TypeScript	Optional onChange, onConfirm, onCancel
EditableComponentProps<T> interface	src/types/canary/utilities/edit-lifecycle.ts	TypeScript	Extends EditLifecycleCallbacks<T>; adds initialValue, contextErrors?, disabled?
Lifecycle types unit tests	src/types/canary/utilities/edit-lifecycle.test.ts	TypeScript/Vitest	8+ expectTypeOf structural tests
setNestedField utility	src/types/canary/utilities/set-nested-field.ts	TypeScript	Pure dot-path update, no mutation, shallow copy per level
setNestedField unit tests	src/types/canary/utilities/set-nested-field.test.ts	TypeScript/Vitest	8 test cases
useDraft<T> hook	src/types/canary/utilities/use-draft.ts	TypeScript/React	Full state machine for edit lifecycle
useDraft<T> unit tests	src/types/canary/utilities/use-draft.test.ts	TypeScript/Vitest	15+ test cases using renderHook + act

Artifact	Path (relative to documentation worktree)	Format	Description
Edit Lifecycle doc	src/content/docs/current-system/architecture/user-interaction/edit-lifecycle/index.md	Markdown	Overview, state machine, activity diagram, validation model
Edit Lifecycle types doc	src/content/docs/current-system/architecture/user-interaction/edit-lifecycle/types.md	Markdown	Type catalog, useDraft<T> hook reference
Edit Lifecycle composition doc	src/content/docs/current-system/architecture/user-interaction/edit-lifecycle/composition.md	Markdown	Hierarchical composition, FD-01 relationship

Internal Dependency Graph

2.1 (architecture docs — documentation worktree, independent)

2.2 (lifecycle types) ─┐
                       ├──→ 2.4 (useDraft<T>) → 2.5 (barrel exports) → 2.6 (checks) → 2.7 (docs commit)
2.3 (setNestedField) ──┘

Exit Criteria

#	Criterion	Verification Command	Expected Output
1	Architecture docs present in documentation worktree	ls /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation/src/content/docs/current-system/architecture/user-interaction/	edit-lifecycle.md present (and splits if applicable)
2	ValidationResult, FieldError, and all 6 types exported	npm --prefix <ux-worktree> run typecheck	Exit 0
3	setNestedField unit tests pass	npm --prefix <ux-worktree> run test -- --reporter=verbose 2>&1 | grep "set-nested-field"	8 tests PASS
4	useDraft<T> unit tests pass	npm --prefix <ux-worktree> run test -- --reporter=verbose 2>&1 | grep "use-draft"	15+ tests PASS
5	Lifecycle type tests pass	npm --prefix <ux-worktree> run test -- --reporter=verbose 2>&1 | grep "edit-lifecycle"	8+ tests PASS
6	useDraft importable from canary barrel	npm --prefix <ux-worktree> run typecheck	Exit 0 (import compiles)
7	Full checks pass	make -C <ux-worktree> check && make -C <ux-worktree> test && make -C <ux-worktree> build	All exit 0
8	No existing test regressions	npm --prefix <ux-worktree> run test	Same or greater test count as entry; all existing tests PASS
9	Documentation make pr-checks passes	make -C /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation pr-checks	Exit 0
10	Documentation changes committed	git -C /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation status --porcelain	Empty (committed)

Where <ux-worktree> = /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/ux-prototype.

Agent Prompt Templates

front-end-engineer — fe-lifecycle

Primary working directory: /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/ux-prototype Secondary working directory: /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation Use absolute paths for all tool calls.

Implement Phase 3.2 of the item image upload frontend project: specification.md.

Load skills: ui-component, unit-tests-frontend, document-writing, path-conventions, plantuml-diagrams.

T-1 (architecture documentation): Write authoritative reference docs in the documentation worktree. Use source material from the architectural exploration docs in 3-frontend-implementation/architectural-exploration/ but write for an engineer who hasn’t seen those documents. Split into multiple files if the main file exceeds 300 lines. Use PlantUML for all diagrams (state machine, activity, class, composition).

T-2/T-3: edit-lifecycle.ts and set-nested-field.ts are new files in src/types/canary/utilities/. They are independent of each other.

T-4 (useDraft<T>): Implement the full state machine per the specification interface. Key behaviors: Object.is equality for initialValue by default (callers must memoize); isEqual option for structural equality; errorsFor() prefix matching (not substring).

Key decisions: FD-03 (minimal scope), FD-14 (isEqual parameter). Location of useDraft: src/types/canary/utilities/ (decided: alongside types it depends on). Spread strategy: shallow per level (decided: React best practices, retains referential identity for siblings).

For T-7, run make pr-checks in the documentation worktree and commit any documentation changes including byproducts for Phase 3.2.

Handoff

Artifacts Consumed (from previous runs)

Artifact	Producer Run	Path
Run 1 exit gate passed	Run 1	Implicit (entry criterion)

Artifacts Produced (for subsequent runs)

Artifact	Consumer Run	Path
FieldError, ValidationResult, Validator<T>, EditPhase, EditLifecycleCallbacks<T>, EditableComponentProps<T>	Run 3a	src/types/canary/utilities/edit-lifecycle.ts
setNestedField utility	Run 3a	src/types/canary/utilities/set-nested-field.ts
useDraft<T> hook	Run 3a	src/types/canary/utilities/use-draft.ts
Edit Lifecycle architecture docs	All engineers	documentation/src/content/docs/current-system/architecture/user-interaction/

STOP: Review architecture documentation, lifecycle types, and useDraft<T> implementation before proceeding to Run 3a (component updates).

Open Questions and Decisions

#	Question	Options	Recommendation	Decision
1	Location of useDraft: utilities/ vs. hooks/	A: utilities/ (colocate), B: src/hooks/canary/	A	Decided: A
2	updateField deep clone strategy	A: shallow spread per level, B: structuredClone, C: immer	A	Decided: A — shallow spread; siblings retain referential identity
3	Architecture doc: single file or split?	A: single edit-lifecycle.md, B: split by concern	Split if > 300 lines	Deferred to implementation

Acceptance Criteria

• Edit Lifecycle architecture documentation published with all required sections and diagrams
• All 6 lifecycle types exported from src/types/canary/utilities/edit-lifecycle.ts
• setNestedField utility passes 8 unit test cases
• useDraft<T> hook passes 15+ unit test cases
• useDraft importable from @arda-cards/design-system/canary
• make check, make test, make build all pass in ux-prototype
• No existing test regressions
• Documentation make pr-checks passes; changes committed

Risks and Blockers

Risk / Blocker	Impact	Mitigation
useDraft<T> state machine complexity causes test failures	Medium — rework required	Write tests before implementation (TDD); test each state transition independently
PlantUML diagram syntax errors block documentation build	Low — documentation only	Use plantuml-diagrams skill conventions; validate via make pr-checks
Canary barrel export conflicts with existing exports	Low — typecheck catches	Run make check after T-5 before moving to T-6

Project Completion Artifacts

Byproducts (byproducts/)

File	Description
changelog.md	Summary of types, hook, and documentation changes in Run 2
learnings.md	Observations about React hook testing patterns, Vitest expectTypeOf
suggestions.md	Improvement suggestions, deferred framework items

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-04-07	Plan created

---

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