Callil Consolidation — Decision Log

All decisions made during the callil consolidation analysis and planning session on 2026-03-19.

Branch and Method

#	Decision	Value	Rationale	Source
D-01	Target branch	jmpicnic/component-consolidation off HEAD of jmpicnic/list-view-management-620	Fresh branch for consolidation work, preserving both source branches	analysis/index.md
D-02	Integration method	Manual file-by-file (no git merge)	Two architects worked independently; semantic reconciliation needed per file	analysis/index.md
D-03	Overlap resolution	Case-by-case semantic analysis	No blanket “one side wins” rule; each overlapping file evaluated individually	analysis/index.md
D-04	Pre-push gate	npm run lint, npx tsc --noEmit, npm run test must pass	Mandatory local validation before any push to origin	analysis/index.md
D-05	CHANGELOG version	Deferred — evaluate against main CHANGELOG after completion	Version depends on what’s on main when consolidation completes	analysis/index.md

Canonical Paths and Utilities

#	Decision	Value	Rationale	Source
D-06	cn() utility path	@/types/canary/utils (NOT @/utils)	Canonical location for all utilities is under src/types/canary	analysis/index.md
D-07	cn() import rewrite	38+ files from @/utils → @/types/canary/utils	Worktree moved cn to @/utils; must be reverted to canonical path	analysis/index.md
D-08	use-mobile.ts hook	src/types/canary/hooks/use-mobile.ts	Hooks go under the canary types namespace	analysis/index.md

Component Organization

#	Decision	Value	Rationale	Source
D-09	Stock shadcn/ui components	src/components/canary/primitives/ (peer of atoms/)	Clear vendor boundary; regenerable via CLI; no stories needed; natural dependency direction atoms→primitives	analysis/primitives.md
D-10	Custom shadcn-derived components	src/components/canary/atoms/ (first-class, with stories/tests)	Avatar, badge, button, card, dialog, input-group contain meaningful custom logic	analysis/primitives.md
D-11	Primitives not exported	Internal use only, not in canary.ts barrel	Primitives are building blocks for atoms, not public API	analysis/primitives.md
D-12	Primitives count	13 files (sonner.tsx excluded)	sonner.tsx dropped per D-18	analysis/primitives.md

Barrel Exports

#	Decision	Value	Rationale	Source
D-13	canary.ts	Union of both branches minus ArdaDetailField, plus all worktree additions	Worktree is a superset; DetailField replaced by ReadOnlyField	analysis/index.md
D-14	extras.ts	Identical in both branches, no changes	No divergence	analysis/index.md
D-15	index.ts	Identical in both branches, no changes	No divergence	analysis/index.md
D-16	ArdaDetailField	Drop from exports and delete underlying files	Replaced by ReadOnlyField from callil branch	analysis/index.md
D-17	ArdaBadge collision	Acceptable — canary and extras have different import paths	Canary version is canonical long-term; extras version must not be used outside **/extras/** paths	analysis/index.md

Styles and Tokens

#	Decision	Value	Rationale	Source
D-18	globals.css	Worktree version replaces main clone (Arda orange palette)	Main clone has default shadcn blue-slate; worktree has correct Arda branding	analysis/styles.md
D-19	tokens.css	Kept as separate file, updated to Arda orange	Lightweight published entrypoint for external consumers preserved	analysis/styles.md
D-20	globals.css ↔ tokens.css	globals.css imports tokens.css (no duplicate values)	Single source of truth for token values; eliminates drift	analysis/styles.md
D-21	Legacy sidebar CSS	Dropped	Canary sidebar organism replaces .sidebar-menu-button-hover, [data-active='true'] etc.	analysis/styles.md
D-22	sonner.tsx file	Dropped (dead code)	Nobody imports it; it’s the only consumer of next-themes	analysis/styles.md
D-23	next-themes package	Dropped	Next.js-specific, doesn’t belong in Vite/Storybook project; sole consumer (sonner.tsx) is dead code	analysis/styles.md

Dependencies

#	Decision	Value	Rationale	Source
D-24	radix-ui	Keep as production dependency (bundled)	Used by 13 primitives; replaces @radix-ui/react-tooltip	analysis/dependencies.md
D-25	@radix-ui/react-tooltip	Remove	Superseded by radix-ui unified package	analysis/dependencies.md
D-26	@reduxjs/toolkit, react-redux, redux-persist	Keep as devDependencies	Required by Storybook decorator for Dev Witness stories; not in published entry points	analysis/dependencies.md
D-27	sonner (npm package)	Keep as devDependency	Used directly by use-case stories and canary-refactor; not in published entry points	analysis/dependencies.md
D-28	react-icons	Drop	One icon in transitional code; lucide-react is canonical	analysis/dependencies.md
D-29	shadcn CLI	Drop	Scaffolding tool; use npx shadcn@latest on demand	analysis/dependencies.md
D-30	pako, qr-scanner, react-dropzone	Drop	Zero usages in worktree	analysis/dependencies.md
D-31	@storybook/addon-links	Conditionally keep	Drop if no linkTo usage confirmed	analysis/dependencies.md

Grid Integration

#	Decision	Value	Rationale	Source
D-32	Auto-publish lifecycle	Promote into entity-data-grid; row-auto-publish is the only mode	No need for cell-granular onEntityUpdated — replaced entirely	analysis/grid-integration.md
D-33	Select vs Enum editor	Callil’s SelectCellEditor replaces jmpicnic’s EnumCellEditor	Custom listbox with keyboard nav, checkmark, ARIA roles superior to native <select> wrapper	analysis/grid-integration.md
D-34	SelectCellEditor convention	Both direct component and createSelectCellEditor factory	Consistent with existing canary cell editor pattern	analysis/grid-integration.md
D-35	Pagination approach	Both server-driven and client-side via StaticConfig (design-time)	Different use cases need different modes; mutually exclusive at design time	analysis/grid-integration.md
D-36	Actions column	Item-grid’s actionsColumn ColDef pattern as InitConfig (mount-time)	Full ColDef flexibility; mount-time for future user/tenant configurability	analysis/grid-integration.md
D-37	AG Grid theme	Item-grid’s themeQuartz with design-system token mapping	DataGrid molecule’s 'legacy' string retrofitted to Arda tokens	analysis/grid-integration.md
D-38	Entity-data-grid-shim	Deprecated but kept in place	Migration aid for ArdaGrid-based dev-witness pages; new code must use entity-data-grid directly	analysis/grid-integration.md

Run 5 Implementation Details

#	Decision	Value	Rationale	Source
D-39	useDirtyTracking removal	Remove — useRowAutoPublish subsumes all functionality	No external consumers beyond entity-data-grid	plan/run-5
D-40	Search implementation	Client-side rowData filtering	Gives control over field selection and filtered count display; server-side via Query DSL is future enhancement (#824)	plan/run-5
D-41	Toolbar layout	Same row as search bar, toolbar right-aligned with ml-auto	Matches item-grid’s existing layout	plan/run-5

canary-refactor

#	Decision	Value	Rationale	Source
D-42	canary-refactor/ role	Validation harness adapted after consolidation, not during	Neither branch’s version is canonical; adaptation is a follow-on task	analysis/canary-refactor.md

Conventions

#	Decision	Value	Rationale	Source
D-43	Play function step DSL	All new play functions must use step() from Storybook context	Named collapsible steps in interactions panel; integrates with test runner	analysis/test-coverage.md
D-44	VRT ambiguous diffs	Agent stops and consults user with screenshot paths and Playwright MCP offer	Prevents auto-regenerating baselines when visual correctness is uncertain	plan/choreography.md
D-45	Implementation output	Each run writes summary, byproducts, validation output, session log to implementation/<run-dir>/	Traceability and knowledge capture per run	plan/run-*/project-plan.md

External Tickets

#	Ticket	Description	Created From
T-01	#824	Entity-data-grid: server-side search via Query DSL	D-40 (client-side search decision; server-side is future enhancement)