Callil Branch Merge: Project Plan

Context

• Analysis — branch comparison, overlap assessment, decisions (Rounds 1-2)
• Migration Candidates — per-story DSL framework assessment
• Requirements — functional requirements (REQ-SB-001 through REQ-VRT-001)
• Verification — traceability matrix and gate checks

Project Type

Modification — changes to existing Storybook configuration, CI, and story files.

Scope

Incorporate unique contributions from the callil/storybook-ia-refactor branch into jmpicnic/list-view-management-620. The work covers two areas:

1. Storybook infrastructure simplification — remove subpath deployment, adopt CSS @import layer(), remove unused addon, simplify sidebar sort
2. DSL framework adoption — convert 2 BA use-case stories to use the existing createUseCaseStories<T>() framework

Worktree Strategy

Single directory — no worktrees needed. The work is sequential and single-agent.

Branch setup:

• Base branch: jmpicnic/list-view-management-620
• Working branch: jmpicnic/callil-merge-storybook-ia
• Create via: git -C /Users/jmp/code/arda/ux-prototype worktree add <path> -b jmpicnic/callil-merge-storybook-ia jmpicnic/list-view-management-620
• Working directory: worktree at ux-prototype-callil-merge/ (sibling of ux-prototype/)

Cleanup: Remove worktree after merge to the base branch.

Quality Guidelines

• All import paths must follow the conventions established in jmpicnic/list-view-management-620 (e.g., @/types/canary/utils for cn, @/components/canary/atoms/shared/formatters for formatters)
• No imports from @/lib/ (deleted in the preparation cleanup)
• BA use-case stories and shared infrastructure must be preserved — do NOT delete
• DSL conversions must use createUseCaseStories<T>() from @/use-cases/framework

Tasks

Phase 1: Setup and VRT Baseline

T1 — Create Branch and Capture VRT Baselines

1. Create the worktree and branch from jmpicnic/list-view-management-620
2. Run npm install
3. Build Storybook: npm run build-storybook
4. Capture VRT baselines: npm run test:vrt:update
5. Verify VRT passes: npm run test:vrt:ci

STOP — Verify baselines are clean before proceeding.

Covers: REQ-VRT-001

Phase 2: Storybook Configuration Simplification

T2 — Remove Subpath Deployment Support

1. In .storybook/main.ts:
   • Remove the STORYBOOK_BASE env variable handling (lines 36-41)
   • Remove the fix-mocker-entry-base-path plugin (lines 100-117)
2. In .storybook/preview.ts:
   • Simplify MSW initialization: replace the serviceWorker.url override with plain initialize({ onUnhandledRequest: 'bypass' })
3. In .github/workflows/ci.yml:
   • Remove the subpath deployment test job
4. In .github/workflows/deploy-pages.yml:
   • Remove STORYBOOK_BASE: /ux-prototype/ env variable
5. In playwright.config.ts:
   • Remove the subpath-deployment project definition
6. Delete tests/smoke/subpath-deployment.spec.ts
7. Delete tests/smoke/subpath-server.mjs

Covers: REQ-SB-001

Verify: npm run lint + npm run build:lib + npm run test

T3 — Adopt CSS @import layer() and Remove Vite Plugin

1. In src/styles/ag-theme-arda.css:
   • Change @import 'ag-grid-community/styles/ag-grid.css'; to @import 'ag-grid-community/styles/ag-grid.css' layer(base);
   • Same for ag-theme-alpine.css
   • Remove the 6-line comment block explaining the old Rollup workaround
2. In src/styles/canary/ag-theme-arda.css:
   • Apply the same @import layer(base) changes
3. In .storybook/main.ts:
   • Remove the wrap-ag-grid-css-in-layer plugin (lines 84-98)

Verify: npm run lint + npm run build:lib + npm run test. Then build Storybook (npm run build-storybook) and run VRT (npm run test:vrt:ci). If VRT fails on AG Grid styling, revert to the Vite plugin approach and document the failure.

Covers: REQ-SB-002

T4 — Remove @storybook/addon-links

1. In .storybook/main.ts: remove '@storybook/addon-links' from the addons array
2. Run npm uninstall @storybook/addon-links

Covers: REQ-SB-003

Verify: npm run lint + npm run build:lib + npm run test

T5 — Simplify Storybook Sidebar Sort

1. In .storybook/preview.ts: replace the 44-line nested BA hierarchy in storySort with a simplified version that preserves ordering for retained stories. Use the pattern from Callil’s branch as reference but keep BA entries since stories are retained.

Covers: REQ-SB-004

Verify: npm run lint + npm run build:lib + npm run test

STOP — Run full gates including Storybook: npm run build-storybook + npm run test:vrt:ci. Commit Phase 2.

Phase 3: DSL Framework Adoption

T6 — Adopt Create Supplier Happy Path DSL Rewrite

1. Read Callil’s rewritten create-supplier/happy-path.stories.tsx from the worktree at /Users/jmp/code/arda/ux-prototype-storybook-ia-refactor
2. Replace the current src/use-cases/reference/business-affiliates/create-supplier/happy-path.stories.tsx with Callil’s version
3. Adjust import paths to match branch conventions:
   • Verify @/use-cases/framework imports resolve correctly (framework is already on main)
   • Verify @/components/extras/ imports are valid (extras components are retained)
   • Verify @/types/extras type imports
4. Update create-supplier/create-supplier.mdx if Callil’s version has relevant changes
5. The creatable-suppliers-page.tsx is no longer imported by the DSL version — verify no other file references it before deleting. If other files reference it, keep it.

Covers: REQ-DSL-001

Verify: npm run lint + npm run build:lib + npm run test

T7 — Convert Edit Supplier Happy Path to DSL

1. Read the current src/use-cases/reference/business-affiliates/edit-supplier/happy-path.stories.tsx (351 lines)
2. Rewrite using createUseCaseStories<T>() following the patterns in:
   • Callil’s create-supplier rewrite (T6 output)
   • src/use-cases/reference/items/add-supply/happy-path.stories.tsx (existing reference)
3. Define GuideEntry[] array mapping the existing step descriptions
4. Define Scene<T>[] snapshots matching the existing custom scene navigator data
5. Create a Wizard component using useWizard() that renders the edit supplier form
6. Define the play callback for the Automated variant
7. Remove custom guide panel, step indicator, story control bar, and scene navigator code

Covers: REQ-DSL-002

Verify: npm run lint + npm run build:lib + npm run test

STOP — Run full gates including Storybook: npm run build-storybook + npm run test:vrt:ci. Visually verify both converted stories render correctly. Commit Phase 3.

Phase 3b: DSL Framework Workflow Documentation

T8 — Create Use Case Framework Workflow Guide

Create src/docs/workflows/use-case-framework.mdx — a practical workflow guide for creating and converting use-case stories using the DSL framework.

The existing src/docs/storybook-structure/use-cases.mdx covers the conceptual model (what use cases are, artifact types, story modes) and includes a detailed API reference for the framework. The new workflow doc should be a complementary step-by-step recipe focused on:

1. When to use the framework — decision criteria (wizard-like multi-step flows: yes; grid observation, single-step views, error-variant stories: no). Reference the assessment in Migration Candidates.
2. Creating a new use-case story from scratch — condensed recipe (define FormData, INITIAL, SAMPLE, guides, scenes, Wizard component, play function, export via createUseCaseStories). Reference the full API in storybook-structure/use-cases.mdx.
3. Converting an existing story to the framework — step-by-step migration pattern:
   • Identify the existing story’s interaction pattern and variants
   • Map custom scene/step navigation to Scene<T>[] snapshots
   • Replace custom guide panels with GuideEntry[]
   • Replace custom chrome (step indicators, control bars) with UseCaseShell
   • Replace custom wizard state with useWizard()
   • Rewrite the play function using PlayContext (goToScene, delay)
   • Remove dead custom infrastructure code
4. Worked example — before/after comparison using the edit-supplier happy-path conversion (T7 output) as the concrete example.
5. Common pitfalls — meta must be a static object literal (not from createUseCaseStories), delayMs tuning, goToScene must match play function steps.

Cross-linking and doc review:

In addition to creating the new workflow guide, review and update existing documentation to capture conventions and practices introduced by the list-view and callil branches:

• src/docs/workflows/creating-stories.mdx — add a section or link pointing to the framework guide for use-case stories
• src/docs/storybook-structure/use-cases.mdx — add a link to the workflow guide in the “Creating a Use Case” section (e.g., “For a step-by-step workflow guide, see Use Case Framework Workflow”)
• src/docs/workflows/canary-components/how-to-extract-and-publish.mdx — review and update to reflect:
  • The canary grid component library (DataGrid, cell atoms, entity data grid factory)
  • The cn utility location (@/types/canary/utils)
  • The canary formatters location (@/components/canary/atoms/shared/formatters)
  • The ESLint canary-to-extras boundary rule
  • The canary barrel export pattern (canary.ts)
• src/docs/components/guidelines.mdx — review for any references that need updating given the new canary component structure (atoms/grid, molecules/data-grid, organisms/entity-data-grid)

Verify: npm run build-storybook (MDX compiles without errors). Visually check the docs render in Storybook sidebar under Docs/Workflows and Docs/Components.

Covers: REQ-DSL-003

Phase 4: Rebase, Review, and Merge

T9 — Rebase onto Base Branch

The base branch (jmpicnic/list-view-management-620) may have received additional commits during this work. Before merging back:

1. Fetch latest: git -C <worktree> fetch origin
2. Rebase onto the base branch: git -C <worktree> rebase jmpicnic/list-view-management-620
3. Resolve any conflicts. Likely conflict areas:
   • .storybook/main.ts — if the base branch modified Storybook config
   • .storybook/preview.ts — if the base branch modified sidebar sort
   • src/styles/ag-theme-arda.css or src/styles/canary/ag-theme-arda.css — if the base branch modified AG Grid CSS
4. After resolving conflicts, re-run all gates:
   • npm run lint
   • npm run build:lib
   • npm run test
   • npm run build-storybook
   • npm run test:vrt:ci

T10 — User Review

STOP — Present the branch for review before merging. The review should cover:

1. Storybook visual inspection — start Storybook dev server (npm run storybook) and verify:
   • BA use-case stories still render and function correctly
   • Converted DSL stories (create-supplier, edit-supplier) produce correct Interactive, Stepwise, and Automated variants
   • AG Grid styling is correct (no regressions from CSS layer change)
   • Sidebar ordering is correct after simplification
2. Documentation review — verify the new workflow guide and updated docs are accurate
3. Code review — scan changed files for import path correctness and convention adherence

Provide a summary of all changes for the reviewer, including:

• Commit list with descriptions
• List of files added, modified, and deleted
• Before/after screenshots of converted stories (if captured during T6/T7)

T11 — Merge to Base Branch and Cleanup

After review approval:

1. Merge into the base branch: git -C /Users/jmp/code/arda/ux-prototype merge jmpicnic/callil-merge-storybook-ia
2. Remove the Callil reference worktree: git -C /Users/jmp/code/arda/ux-prototype worktree remove /Users/jmp/code/arda/ux-prototype-storybook-ia-refactor
3. Remove the project worktree after merge is confirmed clean

Covers: REQ-VRT-001

Acceptance Criteria

• Subpath deployment infrastructure fully removed (REQ-SB-001)
• AG Grid CSS uses @import layer(base) syntax; Vite plugin removed (REQ-SB-002)
• @storybook/addon-links removed from config and dependencies (REQ-SB-003)
• Storybook sidebar sort simplified for BA section (REQ-SB-004)
• create-supplier/happy-path.stories.tsx uses createUseCaseStories<T>() (REQ-DSL-001)
• edit-supplier/happy-path.stories.tsx uses createUseCaseStories<T>() (REQ-DSL-002)
• DSL framework workflow guide and doc updates complete (REQ-DSL-003)
• All BA use-case stories and shared infrastructure retained
• All import paths follow jmpicnic/list-view-management-620 conventions
• Rebased onto latest base branch with no conflicts (or conflicts resolved)
• User review approved
• All gates pass: lint, build:lib, test, build-storybook, VRT (REQ-VRT-001)
• Worktrees cleaned up

Open Questions and Decisions

All questions resolved in Analysis Rounds 1-2. No remaining open questions.

#	Question	Options	Recommendation	Decision
—	All resolved	See Analysis OQ-1 through OQ-8	—	—