Skip to content
Arda Platform Documentation

Choreography: Callil Consolidation

Execution Sequence

Section titled “Execution Sequence”
OrderRunDirectoryTriggerEstimated Duration
1Run 0: Branch Setuprun-0-branch-setup/Manual5 min
2Run 1: Foundationrun-1-foundation/After Run 0 exit gate passes45-60 min
3Run 2: Visual Foundationrun-2-visual-foundation/After Run 1 exit gate passes20-30 min
4Run 3: Organism Portrun-3-organism-port/After Run 2 exit gate passes45-60 min
5Run 4: Cell Editor Upgraderun-4-cell-editor-upgrade/After Run 3 exit gate passes30-45 min
6Run 5: Entity-data-grid Evolutionrun-5-entity-grid-evolution/After Run 4 exit gate passes90-120 min
7Run 6: Item-grid Integrationrun-6-item-grid-integration/After Run 5 exit gate passes45-60 min
8Run 7: Package APIrun-7-package-api/After Run 6 exit gate passes20-30 min
9Run 8: Acceptancerun-8-acceptance/After Run 7 exit gate passes60-90 min
10Run 9: canary-refactor Adaptationrun-9-canary-refactor/After Run 8 exit gate passes30-45 min

All runs are sequential. Each depends on the prior run’s exit gate passing.

Artifact Dependency Map

Section titled “Artifact Dependency Map”
ArtifactProduced ByConsumed ByPathFormat
Branch jmpicnic/component-consolidationRun 0All subsequent runsux-prototype repoGit branch
Baseline green statusRun 0Run 1 (entry criterion)run-0-branch-setup/validate-exit.sh outputScript pass
src/styles/tokens.css (Arda orange)Run 1Run 2, Run 3 (theme tokens)ux-prototype/src/styles/tokens.cssCSS
src/styles/globals.css (refactored)Run 1Run 2, Run 3 (global styles)ux-prototype/src/styles/globals.cssCSS
src/components/canary/primitives/Run 1Run 3 (organism imports)ux-prototype/src/components/canary/primitives/TSX
src/components/canary/atoms/ (expanded)Run 1Run 3, Run 4 (organism/editor imports)ux-prototype/src/components/canary/atoms/TSX
src/types/canary/hooks/use-mobile.tsRun 1Run 3 (sidebar organism)ux-prototype/src/types/canary/hooks/use-mobile.tsTS
Canonical cn import pathRun 1All subsequent runs@/types/canary/utils across 38+ filesTS imports
Primitives import check storyRun 1Run 2 (Storybook verification)ux-prototype/src/components/canary/primitives/primitives.stories.tsxTSX
DataGrid molecule with themeQuartzRun 2Run 3 (organism grid rendering), Run 5 (entity-data-grid base)ux-prototype/src/components/canary/molecules/data-grid/data-grid.tsxTSX
ThemedGrid storyRun 2Run 3, Run 8 (visual reference)ux-prototype/src/components/canary/molecules/data-grid/TSX
VRT baselines (grid)Run 2Run 6 (regression comparison)ux-prototype/__screenshots__/PNG
Sidebar, app-header, item-details, item-grid organismsRun 3Run 4, Run 5, Run 6, Run 8ux-prototype/src/components/canary/organisms/TSX
Supporting molecules (sidebar, item-grid, item-details, overflow-toolbar)Run 3Run 4, Run 5, Run 6ux-prototype/src/components/canary/molecules/TSX
atoms/grid/select/ (SelectCellEditor)Run 4Run 5 (entity-data-grid editing), Run 6 (item-grid refactor)ux-prototype/src/components/canary/atoms/grid/select/TSX
Entity-data-grid with auto-publish, actions, search, pagination, toolbarRun 5Run 6 (item-grid base)ux-prototype/src/components/canary/organisms/shared/entity-data-grid/TSX
10+ new stories with play functionsRun 5Run 8 (acceptance reference)ux-prototype/src/components/canary/organisms/shared/entity-data-grid/TSX
Refactored item-grid using entity-data-gridRun 6Run 7 (barrel exports), Run 8 (composition stories)ux-prototype/src/components/canary/organisms/item-grid/TSX
Updated src/canary.ts barrelRun 7Run 8 (library build verification), Run 9 (canary-refactor imports)ux-prototype/src/canary.tsTS
Updated package.jsonRun 7Run 8 (build verification)ux-prototype/package.jsonJSON
Library build (dist/)Run 7Run 8 (entry criterion)ux-prototype/dist/JS/TS
Composition stories (items, suppliers, list views)Run 8Run 9 (visual reference)ux-prototype/src/use-cases/TSX
VRT baselines (complete set)Run 8Run 9 (regression baseline)ux-prototype/__screenshots__/PNG
MDX documentationRun 8Run 9 (reference)ux-prototype/src/components/canary/MDX
Adapted canary-refactor storiesRun 9Final deliverableux-prototype/src/canary-refactor/TSX

Hand-Off Protocol

Section titled “Hand-Off Protocol”

All hand-offs are filesystem-only — no in-memory state is shared between runs. Each run works on the same branch (jmpicnic/component-consolidation) in the ux-prototype repository. State is transmitted via committed files on the branch.

General Protocol (Between Any Run N and Run N+1)

Section titled “General Protocol (Between Any Run N and Run N+1)”
  1. Run N completes all tasks and commits results to jmpicnic/component-consolidation.
  2. Run N’s validate-exit.sh passes (all entry and exit criteria verified).
  3. The project manager reviews the exit gate output.
  4. Run N+1 is launched. Its entry criteria reference Run N’s committed artifacts.
  5. Run N+1’s validate-exit.sh entry section verifies prerequisites before work begins.

Between Run 0 and Run 1

Section titled “Between Run 0 and Run 1”
  1. Run 0 creates branch jmpicnic/component-consolidation off HEAD of jmpicnic/list-view-management-620.
  2. Baseline verification passes: npm ci && npm run lint && npx tsc --noEmit && npm run test.
  3. Run 1 begins with the clean branch as its working state.

Between Run 1 and Run 2

Section titled “Between Run 1 and Run 2”
  1. Run 1 commits all foundation work (styles, primitives, atoms, hooks, import rewrites).
  2. Full verification gate passes: lint + tsc + test + build-storybook.
  3. No references to @/components/ui/* or @/utils remain (except vendored code).
  4. Run 2 begins with the themed DataGrid work.

Between Run 2 and Run 3

Section titled “Between Run 2 and Run 3”
  1. Run 2 commits the themeQuartz DataGrid migration and regenerated VRT baselines.
  2. All grid stories render with the Arda-themed appearance.
  3. Run 3 begins porting organisms that depend on the themed DataGrid.

Between Run 3 and Run 4

Section titled “Between Run 3 and Run 4”
  1. Run 3 commits all ported organisms, molecules, and assets with rewritten imports.
  2. All organism stories render in Storybook.
  3. Run 4 begins with the SelectCellEditor upgrade, which depends on the ported item-grid molecule.

Between Run 4 and Run 5

Section titled “Between Run 4 and Run 5”
  1. Run 4 commits the promoted SelectCellEditor atom and deleted/replaced EnumCellEditor.
  2. All grid stories with enum columns still work.
  3. Run 5 begins entity-data-grid evolution using the new SelectCellEditor.

Between Run 5 and Run 6

Section titled “Between Run 5 and Run 6”
  1. Run 5 commits all 5 sub-runs (auto-publish, actions, search, pagination, toolbar).
  2. Entity-data-grid API supports all capabilities needed for item-grid integration.
  3. Run 6 begins refactoring item-grid to delegate to entity-data-grid.

Between Run 6 and Run 7

Section titled “Between Run 6 and Run 7”
  1. Run 6 commits the refactored item-grid.
  2. Item-grid stories are visually equivalent to pre-refactor.
  3. Run 7 begins package API cleanup (barrel exports, dependencies, orphan deletion).

Between Run 7 and Run 8

Section titled “Between Run 7 and Run 8”
  1. Run 7 commits updated barrel exports, package.json, and deleted orphan files.
  2. Library build succeeds (npm run build:lib).
  3. Run 8 begins acceptance work (composition stories, VRT, documentation).

Between Run 8 and Run 9

Section titled “Between Run 8 and Run 9”
  1. Run 8 commits composition stories, VRT baselines, and MDX documentation.
  2. All play functions pass; Storybook build succeeds.
  3. Run 9 begins adapting canary-refactor stories to use consolidated components.

Recovery Procedures

Section titled “Recovery Procedures”

Run N fails mid-execution

Section titled “Run N fails mid-execution”
  1. Identify which task failed by checking the task list status in the project plan.
  2. The branch should have commits from completed tasks (each task commits independently).
  3. Fix the failing task and re-run its intermediate gate.
  4. Resume from the failed task forward; do not re-run completed tasks.
  5. If the failure corrupted committed state, use git log to identify the last good commit and git reset --hard <sha> to that point before retrying.

Run N exit gate fails

Section titled “Run N exit gate fails”
  1. Run validate-exit.sh to identify which specific criteria failed.
  2. For build/lint/test failures: fix the code on the branch, re-run the failing checks.
  3. For missing-file criteria (e.g., expected directory does not exist): the task that produces that artifact was not completed — re-run that task.
  4. For import-path criteria (e.g., stale @/utils references found): use grep -r to locate remaining references and fix them.
  5. Re-run validate-exit.sh until all criteria pass.

Run N+1 entry criteria fail

Section titled “Run N+1 entry criteria fail”
  1. The entry criteria check artifacts from Run N. If they fail, Run N did not complete correctly.
  2. Return to Run N and re-run its exit gate to diagnose.
  3. Fix any issues in Run N, re-commit, and re-validate.
  4. Then re-attempt Run N+1 launch.

Storybook build fails after file moves

Section titled “Storybook build fails after file moves”

This is the most likely failure mode in Runs 1 and 3 (large file moves with import rewrites).

  1. Run npm run build-storybook 2>&1 | head -50 to identify the first error.
  2. Common causes: missing import (file not copied), wrong import path (rewrite missed), circular dependency (barrel re-export loop).
  3. Fix the identified file, re-run npx tsc --noEmit to verify, then re-run npm run build-storybook.

VRT baseline mismatch after theme change (Run 2)

Section titled “VRT baseline mismatch after theme change (Run 2)”
  1. This is expected — Run 2 changes the grid theme, so all grid VRT baselines will diff.
  2. Visually review the diffs using Playwright MCP screenshots.
  3. If the new appearance matches the Arda design tokens, regenerate baselines: npx playwright test --project=vrt --update-snapshots.
  4. If the appearance is wrong, fix the theme token mapping and re-run.

VRT diffs the agent cannot assess

Section titled “VRT diffs the agent cannot assess”

When a VRT diff is ambiguous — the agent cannot confidently determine whether the visual change is acceptable or a regression — the agent must stop and consult the user before regenerating baselines.

Procedure:

  1. Do NOT regenerate baselines automatically.
  2. Copy the diff images (expected, actual, diff) to the run’s implementation output directory: implementation/<run-dir>/vrt-review/.
  3. Notify the user with:
    • Which story/stories have ambiguous diffs
    • File paths to the expected, actual, and diff screenshots so the user can open them side-by-side
    • [Playwright MCP] Offer to navigate to the affected story in Storybook so the user can inspect it live in the browser
  4. Wait for the user to respond with “accept” (regenerate baselines) or “reject” (fix the code).

This applies to all runs that involve VRT, not just Run 2.

Launch Commands

Section titled “Launch Commands”
RunCommand
0/launch-team callil-consolidation/plan/run-0-branch-setup
1/launch-team callil-consolidation/plan/run-1-foundation
2/launch-team callil-consolidation/plan/run-2-visual-foundation
3/launch-team callil-consolidation/plan/run-3-organism-port
4/launch-team callil-consolidation/plan/run-4-cell-editor-upgrade
5/launch-team callil-consolidation/plan/run-5-entity-grid-evolution
6/launch-team callil-consolidation/plan/run-6-item-grid-integration
7/launch-team callil-consolidation/plan/run-7-package-api
8/launch-team callil-consolidation/plan/run-8-acceptance
9/launch-team callil-consolidation/plan/run-9-canary-refactor

Note: All launch commands reference plan directories relative to the documentation/src/content/docs/roadmap/backlog/requested/ base. The team lead reads project-plan.md from the specified directory.

Copyright: © Arda Systems 2025-2026, All rights reserved