Run 5: Sidebar Clean-Up

Reorganize the Storybook sidebar to follow the hierarchical convention established by this project: scenario-level grouping within use cases, and a corrected top-level section order.

Entry Criteria

#	Criterion	Verification Command	Expected Output
1	On branch jmpicnic/uc-stories with Run 4 checkpoint commit	git -C <worktree> log --oneline -1 --grep='Run 4 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 47 story files exist	find <worktree>/src/use-cases -name '*.stories.tsx' | wc -l	47+ (includes pre-existing stories)

Artifact Specifications

Artifact	Path	Format	Description
Updated preview.ts	.storybook/preview.ts	TypeScript	Corrected storySort.order configuration
Updated story titles	Various *.stories.tsx	TypeScript	Hierarchical title paths with scenario grouping
Updated MDX titles	Various *.mdx	MDX	<Meta title="..." /> updated to match hierarchy

Context

Current Top-Level Sidebar Order (preview.ts)

1. Docs
2. Components
3. Visual Elements
4. Dev Witness
5. Canary Refactor
6. Use Cases
7. Archive

Target Top-Level Sidebar Order

1. Docs
2. Visual Elements
3. Components
4. Use Cases
5. Canary Refactor
6. Dev Witness
7. Archive

Current Use Cases Sidebar Structure (flat)

Use Cases/General Behaviors/Entity Media/GEN-MEDIA-0001 Set Entity Image/Happy Path

Target Use Cases Sidebar Structure (hierarchical)

Use Cases/General Behaviors/Entity Media/GEN-MEDIA-0001 Set Entity Image/0001 Set Image/Happy Path

Adding a scenario grouping level between the use case and the individual stories so each scenario can be folded/expanded independently.

Task List

Note: The hierarchical story title paths and scenario-level directory structure are baked in from Runs 1–4. This run only handles preview.ts configuration.

#	Task	Persona	Depends On	Status	Acceptance Criteria
5.1	Update preview.ts storySort.order — reorder top-level sections to: Docs, Visual Elements, Components, Use Cases, Canary Refactor, Dev Witness, Archive	fe	—	Pending	Top-level sidebar matches target order
5.2	Update preview.ts storySort.order — add Entity Media section with scenario-level ordering under Use Cases	fe	5.1	Pending	Entity Media stories appear in correct hierarchical order
5.3	Verify existing Use Cases stories (Business Affiliates, List Views, Items ITM-0001/0002/0004) still render correctly — no regressions from sidebar reorder	fe	5.1	Pending	Existing stories appear in sidebar, play functions pass
5.4	Verify all new stories appear at correct sidebar positions matching the specification tree	fe	5.2	Pending	Every scenario folder is foldable, stories nest correctly
5.5	Wave gate: lint, tsc, build-storybook, test, VRT	fe	5.1–5.4	Pending	All checks pass
5.6	Quality review — sidebar structure matches specification tree	qr	5.5	Pending	Every story appears at the correct sidebar position

Internal Dependency Graph

5.1 (top-level reorder) ──► 5.2 (Entity Media sort config) ──► 5.6 (verify existing)
                                                                       │
5.3 (GEN::MEDIA titles) ──────────────────────────────────────────────►│
5.4 (REF::ITM titles) ────────────────────────────────────────────────►│
5.5 (MDX titles) ─────────────────────────────────────────────────────►│
                                                                       ▼
                                                               5.7 (wave gate)
                                                                       │
                                                                       ▼
                                                               5.8 (quality review)

Tasks 5.3, 5.4, 5.5 are independent of 5.1/5.2 and can run in parallel.

Exit Criteria

#	Criterion	Verification Command	Expected Output
1	Top-level sidebar order correct	Inspect preview.ts storySort.order[0..6]	Docs, Visual Elements, Components, Use Cases, Canary Refactor, Dev Witness, Archive
2	Entity Media stories hierarchical	Grep story titles for scenario grouping pattern	All match {UC}/{Scenario}/{Story}
3	Lint passes	npm run lint --prefix <ux-prototype>	Exit 0
4	TypeScript compiles	npx tsc --noEmit --project <ux-prototype>	Exit 0
5	Storybook builds	npm run build-storybook --prefix <ux-prototype>	Exit 0
6	Unit tests pass	npm run test --prefix <ux-prototype>	Exit 0
7	VRT baselines current	npx playwright test --project=vrt --prefix <ux-prototype>	Exit 0
8	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
9	Post-rebase checks pass (lint, tsc, build, test, VRT)	Re-run criteria 3–7 after rebase	All pass

Agent Prompt Templates

Front-End Engineer — fe-sidebar-cleanup

Reorganize the Storybook sidebar for the ux-prototype repository. Working directory: <worktree-path>.

Two changes:

1. Top-level reorder in .storybook/preview.ts storySort.order: Current: Docs, Components, Visual Elements, Dev Witness, Canary Refactor, Use Cases, Archive. Target: Docs, Visual Elements, Components, Use Cases, Canary Refactor, Dev Witness, Archive.

2. Hierarchical Use Cases sidebar — add Entity Media section config with scenario-level nesting. Update all new story title paths from {UC}/{Story} to {UC}/{Scenario}/{Story}. Update MDX <Meta title> accordingly.

Do NOT change existing story titles for Business Affiliates, List Views, or existing Item stories (ITM-0001, ITM-0002, ITM-0004) — only the new image stories created in Runs 1–4.

Quality Reviewer — qr-sidebar-cleanup

Verify the complete Storybook sidebar structure matches the specification tree in index.md. Check every story appears at the correct position. Verify existing stories are not affected by the reorder.

Handoff

Artifacts Consumed (from previous runs)

Artifact	Source Run	Path
All story and MDX files	Runs 1–4	src/use-cases/general-behaviors/entity-media/, src/use-cases/reference/items/

Artifacts Produced (final)

Artifact	Consumer	Path
Organized sidebar config	PR review, stakeholders	.storybook/preview.ts
Hierarchical story titles	PR review, stakeholders	All *.stories.tsx title fields