Run 4: Integration

Full-flow stories (GEN-MEDIA-0001::0001.UC), grid inline edit (GEN-MEDIA-0001::0007.FS), removal (GEN-MEDIA-0002), REF::ITM integration stories, and remaining MDX descriptions.

Entry Criteria

#	Criterion	Verification Command	Expected Output
1	On branch jmpicnic/uc-stories with Run 3 checkpoint commit	git -C <worktree> log --oneline -1 --grep='Run 3 complete'	Commit hash
2	Branch up-to-date with base	git -C <worktree> fetch origin jmpicnic/item-image-upload-components && git -C <worktree> merge-base --is-ancestor origin/jmpicnic/item-image-upload-components HEAD	Exit 0
3	All GEN-MEDIA-0003 stories exist	find <worktree>/src/use-cases/general-behaviors/entity-media/view-entity-image -name '*.stories.tsx' | wc -l	10
4	All input/validation stories exist (Runs 1–2)	find <worktree>/src/use-cases/general-behaviors/entity-media/set-entity-image -name '*.stories.tsx' | wc -l	16
5	All preview/confirm stories exist (Run 3)	find <worktree>/src/use-cases/general-behaviors/entity-media/set-entity-image/000[56]-* -name '*.stories.tsx' | wc -l	10
6	ImageCellEditor wired to ImageUploadDialog — the cell editor must open the upload dialog on mount, not cancel immediately. If this check fails, stop and notify the user — tasks 4.7–4.10 and 4.16 cannot proceed.	grep -c 'stopEditing.*true' <worktree>/src/components/canary/atoms/grid/image/image-cell-editor.tsx	0 (placeholder stopEditing(true) removed)

Artifact Specifications

Artifact	Path	Format	Description
entity-media description (final)	entity-media/description.mdx	MDX	Section description with cross-cutting concerns (finalize stub from Run 1)
remove-entity-image UC description	remove-entity-image/description.mdx	MDX	Remove use case description
4 scenario descriptions	0001-set-image/description.mdx, 0007-grid-inline-edit/description.mdx, 0001-remove-image/description.mdx, 0010-set-image/description.mdx (+ 0006-change-or-remove-image/description.mdx)	MDX	One per new scenario
3 set-image stories	set-entity-image/0001-set-image/*.stories.tsx	TypeScript	End-to-end framework stories
4 grid-edit stories	set-entity-image/0007-grid-inline-edit/*.stories.tsx	TypeScript	Grid inline edit stories
3 remove stories	remove-entity-image/0001-remove-image/*.stories.tsx	TypeScript	Remove image stories
2 REF::ITM create stories	reference/items/create-item/0010-set-image/*.stories.tsx	TypeScript	Vendored reference + canary
2 REF::ITM edit stories	reference/items/edit-item/0006-change-or-remove-image/*.stories.tsx	TypeScript	Canary grid/detail composition
items.mdx update	reference/items/items.mdx	MDX	Add ITM-0003 and ITM-0004 image entries

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
4.1	Finalize entity-media/description.mdx — section description with cross-cutting concerns (permissions, concurrency) and links to all 3 use case descriptions	fe	—	Pending	MDX renders, links resolve
4.2	Create remove-entity-image/description.mdx — use case description with scenarios table	fe	—	Pending	MDX renders, links to spec
4.3	Create scenario directories: 0001-set-image/, 0007-grid-inline-edit/, 0001-remove-image/, 0010-set-image/, 0006-change-or-remove-image/ with description.mdx in each	fe	—	Pending	5 directories + 5 description.mdx files
4.4	0001-set-image/happy-path.stories.tsx — end-to-end with createUseCaseStories (Interactive/Stepwise/Automated)	fe	4.3	Pending	All 3 variants render, automated play function passes
4.5	0001-set-image/replace-existing.stories.tsx — comparison layout, replacement flow	fe	4.4	Pending	Shows desktop and mobile comparison
4.6	0001-set-image/cancel-and-warn.stories.tsx — Warn state confirmation	fe	4.4	Pending	Play function exercises discard and return paths
4.7	0007-grid-inline-edit/double-click.stories.tsx — double-click opens dialog	fe	4.3	Pending	Play function double-clicks cell, dialog opens, confirm updates row
4.8	0007-grid-inline-edit/enter-key.stories.tsx — Enter key trigger	fe	4.7	Pending	Keyboard accessibility demonstrated
4.9	0007-grid-inline-edit/from-inspector.stories.tsx — inspector→edit transition	fe	4.7	Pending	Play function: eye→inspector→edit→dialog
4.10	0007-grid-inline-edit/cancel.stories.tsx — cancel preserves row	fe	4.7	Pending	Grid row unchanged after cancel
4.11	0001-remove-image/from-form.stories.tsx — trash icon→confirm→placeholder	fe	4.3	Pending	Play function exercises removal
4.12	0001-remove-image/cancel.stories.tsx — cancel preserves image	fe	4.11	Pending	Image unchanged after cancel
4.13	0001-remove-image/playground.stories.tsx — argTypes controls	fe	4.11	Pending	Controls toggle image states
4.14	0010-set-image/during-creation.stories.tsx — vendored reference story	fe	4.3	Pending	Renders vendored ItemFormPanel, existing image handling
4.15	0010-set-image/during-creation-canary.stories.tsx — canary simplified form with createUseCaseStories	fe	4.4	Pending	Interactive/Stepwise/Automated, 10-scene wizard
4.16	0006-change-or-remove-image/change-item-image.stories.tsx — full-app grid, change image	fe	4.7	Pending	Play function: double-click→dialog→confirm→row updates
4.17	0006-change-or-remove-image/remove-item-image.stories.tsx — full-app grid+detail, remove image	fe	4.11	Pending	Play function: hover→trash→confirm→placeholder
4.18	Update items.mdx — add ITM-0003::0010 and ITM-0004::0006 entries	fe	4.14–4.17	Pending	New entries appear in use case table
4.19	Wave gate: lint, tsc, build-storybook, test, full Storybook test runner, VRT	fe	4.1–4.18	Pending	All checks pass
4.20	Quality review of all new files	qr	4.19	Pending	No anti-patterns, consistent style, vendored scoped correctly, description.mdx in every scenario dir

Internal Dependency Graph

4.1 (entity-media.mdx)        4.2 (remove MDX)       4.13 (vendored reference)
      │                              │                        │
      ▼                              ▼                        │
4.3 (happy path) ──────► 4.4 (replace) + 4.5 (cancel/warn)  │
      │                                                       │
      ├──────────────────────────────────────────► 4.14 (canary create)
      │
4.6 (grid dbl-click) ──► 4.7 (enter) + 4.8 (inspector) + 4.9 (cancel)
      │                                                     │
      └──────────────────────────────────────────► 4.15 (change item image)
                                                            │
4.10 (remove form) ──► 4.11 (remove cancel) + 4.12 (playground)
      │                                                     │
      └──────────────────────────────────────────► 4.16 (remove item image)
                                                            │
                                    4.17 (items.mdx update) ◄┘
                                    4.18 (sidebar sort)
                                            │
                                            ▼
                                    4.19 (wave gate)
                                            │
                                            ▼
                                    4.20 (quality review)

Three parallel tracks:

• Track A: End-to-end flow stories (4.3→4.4, 4.5, 4.14)
• Track B: Grid inline edit stories (4.6→4.7, 4.8, 4.9, 4.15)
• Track C: Remove stories (4.10→4.11, 4.12, 4.16)

MDX files (4.1, 4.2, 4.13) can start immediately.

Exit Criteria

#	Criterion	Verification Command	Expected Output
1	entity-media.mdx finalized	test -f <ux-prototype>/src/use-cases/general-behaviors/entity-media/entity-media.mdx	Exit 0
2	remove-entity-image.mdx exists	test -f <ux-prototype>/src/use-cases/general-behaviors/entity-media/remove-entity-image/remove-entity-image.mdx	Exit 0
3	3 set-image stories	find <set-dir> -name 'set-image-*.stories.tsx' | wc -l	3
4	4 grid-edit stories	find <set-dir> -name 'grid-inline-edit-*.stories.tsx' | wc -l	4
5	3 remove stories	find <remove-dir> -name '*.stories.tsx' | wc -l	3
6	2 REF::ITM create stories	find <ux-prototype>/src/use-cases/reference/items/create-item -name '*.stories.tsx' | wc -l	2
7	2 REF::ITM edit stories	ls <ux-prototype>/src/use-cases/reference/items/edit-item/{change,remove}-item-image.stories.tsx 2>/dev/null | wc -l	2
8	Total story count = 47	find <ux-prototype>/src/use-cases/general-behaviors/entity-media -name '*.stories.tsx' | wc -l + REF::ITM count	47
9	Lint passes	npm run lint --prefix <ux-prototype>	Exit 0
10	TypeScript compiles	npx tsc --noEmit --project <ux-prototype>	Exit 0
11	Storybook builds	npm run build-storybook --prefix <ux-prototype>	Exit 0
12	Unit tests pass	npm run test --prefix <ux-prototype>	Exit 0
13	Storybook test runner passes	All play functions pass	Exit 0
14	VRT baselines current	npx playwright test --project=vrt --prefix <ux-prototype>	Exit 0
15	Rebased onto base branch	git -C <worktree> fetch origin jmpicnic/item-image-upload-components && git -C <worktree> rebase origin/jmpicnic/item-image-upload-components	Exit 0, no conflicts
16	Post-rebase checks pass (lint, tsc, build, test, VRT)	Re-run criteria 9–14 after rebase	All pass

Agent Prompt Templates

Front-End Engineer — fe-e2e-stories

Implement end-to-end Storybook use case stories for GEN-MEDIA-0001::0001.UC, GEN-MEDIA-0001::0007.FS, GEN-MEDIA-0002, and REF::ITM integration stories. Working directory: <worktree-path>.

Read the full specification. This is the final run — all prior stories exist as pattern references. Key points:

• 0001.UC stories use createUseCaseStories framework (Interactive/Stepwise/Automated)
• 0007.FS stories need createImageCellEditor wired into story-local column overrides (the shared column defs have editable: false)
• REF::ITM::0003::0010.UC has two stories: vendored reference (wrap ItemFormPanel) and canary (story-local simplified form with ImageFormField)
• REF::ITM::0004::0006.UC is 100% canary — compose from ItemGrid + ItemDetails
• Follow existing full-app patterns from view-items-list.stories.tsx and edit-inline.stories.tsx

Quality Reviewer — qr-integration-stories

Final quality review of all files produced across all 4 runs. Verify:

• Canary-only imports (except vendored reference story)
• Vendored CSS imported ONLY in set-image-during-creation.stories.tsx
• MDX formatting (HTML tables, numeric entities, no bare braces)
• Sidebar title conventions
• Play function coverage for all scenarios
• Framework stories have all 3 variants (Interactive/Stepwise/Automated)

Handoff

Artifacts Consumed (from previous runs)

Artifact	Source Run	Path
Use-case mock data	Run 1	_shared/mock-data.ts
View stories (pattern)	Run 1	view-entity-image/
Input/validation stories (pattern)	Run 2	set-entity-image/input-*, formats-*, url-*
Preview/confirm stories (pattern)	Run 3	set-entity-image/preview-*, confirm-*
Set Entity Image MDX	Run 3	set-entity-image/set-entity-image.mdx

Artifacts Produced (final)

Artifact	Consumer	Path
Complete use case story suite	Stakeholder review, PR	All story and MDX files