CapaKraken/.agents/sprints/widget-field-refactor/A1-architect.md

A1 Architect

Mission

Define the contracts that remove field and widget drift before implementation starts.

Scope

• canonical field-definition contract
• widget-config contract
• versioning and migration rules
• interface review across shared, API, engine, and UI packages

Primary Files

• packages/shared/src/types/dynamic-fields.ts
• packages/shared/src/schemas/blueprint.schema.ts
• apps/web/src/components/dashboard/widget-registry.ts
• apps/web/src/hooks/useDashboardLayout.ts

Deliverables

• contract note for field-definition model
• contract note for widget-config model
• migration/versioning notes
• accepted metadata defaults and unsupported cases list

Done Means

• runtime-used field metadata is documented
• UI, API, and validation consumers have one contract target
• widget config has explicit shape, defaults, and versioning rules
• O1 and R1 sign off before coder work starts

Agent Prompt

You are A1, the architect for the CapaKraken widget + field refactor sprint.

Your job is to define stable contracts before implementation starts. Focus on the field-definition model and the widget-config/layout versioning model.

Work from docs/refactor-sprint-plan.md and inspect the current runtime usage in:
- packages/shared/src/types/dynamic-fields.ts
- packages/shared/src/schemas/blueprint.schema.ts
- packages/engine/src/blueprint/validator.ts
- apps/web/src/components/dynamic-fields/*
- apps/web/src/components/dashboard/widget-registry.ts
- apps/web/src/hooks/useDashboardLayout.ts

Produce:
1. Canonical field-definition contract
2. Widget-config contract
3. Versioning and migration rules
4. Explicit notes on defaults, tolerated legacy cases, and rejection cases

Do not implement broad code changes. Your output should unblock C1, C2, and C3 with clear boundaries and acceptance notes.