Run 9: canary-refactor Adaptation — Project Plan

Overview

Adapt existing src/canary-refactor/ stories to use the consolidated canary components instead of their current mix of inline implementations and branch-specific APIs. This run serves as an integration test for the consolidated library: divergences found during adaptation drive fixes back into the component library.

Repository: ux-prototype at /Users/jmp/code/arda/ux-prototype/ Branch: jmpicnic/component-consolidation Worktree (read-only reference): /Users/jmp/code/arda/callil-consolidation-worktree/

Entry Criteria

#	Criterion	Verification
E1	Run 8 exit gate passed	`plan/run-8-acceptance/validate-exit.sh` returns 0
E2	All composition stories render and pass	`npm run test:storybook` green
E3	MDX documentation complete	Primitives, atoms, molecules, organisms all documented
E4	Branch clean, all Run 8 commits pushed	`git status` clean
E5	Baseline tests pass	`npm run lint && npx tsc --noEmit && npm run test` all green

Artifact Specifications

Artifact	Location	Description
Adapted ItemsPage	`src/canary-refactor/components/ItemsPage.tsx`	Uses consolidated canary organisms
Adapted stories	`src/canary-refactor/reference/items/*.stories.tsx`	Stories using consolidated components
Component fix list	Run 9 commit messages	Fixes to the component library discovered during adaptation

Background

src/canary-refactor/ contains copies of selected dev-witness stories ported to use canary components. Both branches modified these files independently:

File	Main Clone State	Worktree State
`components/ItemsPage.tsx`	Large monolithic page	Reduced, delegates to callil organisms
`components/ItemDetailsPanel.tsx`	Present	Deleted (absorbed into item-details organism)
`components/ItemTableAGGrid.tsx`	Not present	Added (extracted grid logic)
`components/columnPresets.tsx`	Not present	Added (extracted column definitions)
`components/ItemDetailPage.tsx`	Present	Modified
`reference/items/item-detail.stories.tsx`	Present	Modified
`reference/items/items-grid.stories.tsx`	Present	Modified

Neither version survives as-is. Both were written against their branch’s component APIs, which changed during Runs 1-8.

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
9.1	Assess canary-refactor stories	front-end-engineer	E1-E5	Pending	Written inventory of all files in `src/canary-refactor/`. For each file: current state (which branch version is present), which consolidated components it should use, what changes are needed. Categorize as: (a) uses consolidated components already, (b) needs adaptation, (c) should be deleted (superseded).
9.2	Determine ItemDetailsPanel.tsx disposition	front-end-engineer	9.1	Pending	Decision documented: was ItemDetailsPanel’s functionality absorbed into the `item-details` organism (from Run 3), or does it need to be recreated against the consolidated API? If absorbed, delete the file. If needed, adapt it to import from `@/components/canary/organisms/item-details`.
9.3	Determine ItemTableAGGrid.tsx and columnPresets.tsx disposition	front-end-engineer	9.1	Pending	Decision documented: are these files superseded by the consolidated item-grid organism (which uses entity-data-grid as of Run 6), or do the canary-refactor stories need their own grid wrapper? If superseded, delete and replace usages with item-grid imports. If needed, adapt to use consolidated components.
9.4	Adapt all canary-refactor stories to use consolidated canary components	front-end-engineer	9.2, 9.3	Pending	All files in `src/canary-refactor/` import from `@/components/canary/` paths (organisms, molecules, atoms). No imports from `@/components/ui/`, no inline component implementations that duplicate what the canary library provides. `npx tsc --noEmit` passes. Stories render in Storybook.
9.5	Fix component issues discovered during adaptation	front-end-engineer	9.4	Pending	Any gaps, API mismatches, or missing capabilities discovered while adapting canary-refactor stories are fixed in the component library (not worked around in canary-refactor). Each fix committed separately with a descriptive message. If a fix is too large for this run, it is documented as a follow-up issue. Affected Run 1-8 tests re-verified after each fix.
9.6	Visual comparison against dev-witness originals	front-end-engineer	9.4, 9.5	Pending	Navigate to each canary-refactor story and the corresponding dev-witness story in Storybook. Visual comparison confirms the canary-refactor version is recognizably similar to the dev-witness version. Discrepancies documented and justified (expected differences from component tree change vs bugs).
9.7	Playwright MCP verification	front-end-engineer	9.6	Pending	Use Playwright MCP to navigate through canary-refactor stories: items grid (search, click row, drawer), item detail page. Screenshot and compare against dev-witness equivalents. All interaction flows work (no broken callbacks, no missing data, no layout regressions).

Dependency Graph

E1-E5 (entry criteria)
  |
  v
9.1 Assess canary-refactor stories
  |
  +-------+
  |       |
  v       v
9.2     9.3
  |       |
  +---+---+
      |
      v
    9.4 Adapt all stories
      |
      v
    9.5 Fix component issues (feedback loop)
      |
      v
    9.6 Visual comparison
      |
      v
    9.7 Playwright MCP verification

Parallelization: Tasks 9.2 and 9.3 can run in parallel (they assess different files). All other tasks are sequential, as each depends on the prior task’s output.

Feedback loop: Task 9.5 may require iterating back to the component library. If fixes are needed, the agent should:

Make the fix in the component source (e.g., src/components/canary/organisms/)
Verify the fix does not break existing tests (npm run test)
Commit the fix separately
Continue adapting canary-refactor stories

Single agent: All tasks assigned to one front-end-engineer. The canary-refactor directory is small (6 files) and tightly coupled.

Exit Criteria

#	Criterion	Verification
X1	`npm run lint` passes	CI gate
X2	`npx tsc --noEmit` passes	CI gate
X3	`npm run test` passes	CI gate
X4	`npm run build-storybook` passes	CI gate
X5	canary-refactor stories render in Storybook	Manual or `npm run test:storybook`
X6	canary-refactor stories visually equivalent to dev-witness	Playwright MCP comparison documented
X7	No imports from `@/components/ui/` in canary-refactor	grep verification
X8	All component fixes committed separately	`git log` shows distinct fix commits
X9	All discovered issues resolved or tracked	No open issues remaining without documentation
X10	All Run 9 commits on `jmpicnic/component-consolidation`	`git log`

Agent Prompt Templates

front-end-engineer (all tasks)

You are adapting canary-refactor stories to use the consolidated canary component library.

Working directory: /Users/jmp/code/arda/ux-prototype/
Branch: jmpicnic/component-consolidation
Read-only reference: /Users/jmp/code/arda/callil-consolidation-worktree/

Key files:
- canary-refactor: src/canary-refactor/
  - components/ItemsPage.tsx
  - components/ItemDetailsPanel.tsx (may not exist)
  - components/ItemTableAGGrid.tsx
  - components/columnPresets.tsx
  - components/ItemDetailPage.tsx
  - reference/items/items-grid.stories.tsx
  - reference/items/item-detail.stories.tsx

Consolidated components (use these):
- src/components/canary/organisms/item-grid/ (ItemGrid via entity-data-grid)
- src/components/canary/organisms/item-details/ (ArdaItemDetails)
- src/components/canary/organisms/app-header/ (ArdaAppHeader)
- src/components/canary/organisms/sidebar/ (ArdaSidebar)
- src/components/canary/organisms/shared/entity-data-grid/ (createEntityDataGrid)

Dev-witness (visual comparison targets):
- src/dev-witness/ (original vendored pages)

Analysis:
- /Users/jmp/code/arda/documentation/src/content/docs/roadmap/backlog/requested/callil-consolidation/analysis/canary-refactor.md

Start with task 9.1: inventory all canary-refactor files, understand what each
does, and determine what consolidated components should replace inline code.

IMPORTANT: This is a feedback loop. If you discover that a consolidated component
is missing a capability needed by canary-refactor, fix the component FIRST
(in src/components/canary/), verify tests pass, commit the fix, then continue
adaptation. Do not work around component gaps in canary-refactor code.

Implementation Output

At run completion, write the following to implementation/run-9-canary-refactor/:

Artifact	File	Description
Run summary	`summary.md`	What was done, decisions made during implementation, deviations from plan
Byproducts log	`byproducts.md`	Discovered issues, TODOs, observations for later runs
Validation output	`validation-output.txt`	Stdout from `validate-exit.sh` execution
Session log	`session-log.md`	Agent session IDs, timestamps, notable events

Path: documentation/src/content/docs/roadmap/backlog/requested/callil-consolidation/implementation/run-9-canary-refactor/

Handoff

Project Completion

Run 9 is the final run of the Callil Consolidation project. Upon completion:

The consolidated canary component library is proven across three validation layers:
1. Unit tests (Runs 1-7): every component has tests
2. Composition stories (Run 8): use-case-mapped stories prove page-level equivalence
3. canary-refactor (Run 9): existing validation harness adapted to consolidated components
Branch jmpicnic/component-consolidation is ready for PR review against jmpicnic/list-view-management-620

Follow-up items to capture

Any component gaps documented in Run 9 task 9.5 that were deferred as too large
CHANGELOG update (deferred per cross-cutting decision: evaluate against main CHANGELOG)
PR creation and review process