siesa-agents 2.1.89 → 2.1.91

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/steps/step-02b-kit-warmup.md

@@ -0,0 +1,96 @@
+---
+name: 'step-02b-kit-warmup'
+description: 'Kit Warm-up: instala/usa el paquete REAL de siesa-ui-kit en una mini app, verifica con build+render, y produce kit-grounding.md (fuente de verdad anti-alucinación) ANTES de diseñar'
+
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals'
+thisStepFile: '{workflow_path}/steps/step-02b-kit-warmup.md'
+nextStepFile: '{workflow_path}/steps/step-03-scenarios.md'
+
+# Outputs
+kit_playground: '{design_artifacts}/_kit-playground'
+kit_grounding: '{design_artifacts}/_kit-playground/kit-grounding.md'
+
+# References
+siesa_uikit_catalog_url: 'https://siesa-ui-kit.pages.dev/llms.txt'
+componentMappingData: '{workflow_path}/data/component-mapping.csv'
+base_ux_spec: '{project-root}/_siesa-agents/resources/ux-ui/ux-design-specification.md'
+---
+
+# Step 2b: Kit Warm-up — Grounding del UI kit REAL (anti-alucinación)
+
+## STEP GOAL
+
+Antes de mapear objetos a componentes y renderizar, el agente debe **tocar el kit real**: instalarlo, compilarlo y renderizarlo. El resultado es `kit-grounding.md` — la **fuente de verdad** (nombres, props, contratos reales) que consumen step-04 (specs) y step-05 (prototype). Esto evita alucinaciones como suponer componentes/props que el catálogo `llms.txt` lista pero el paquete no expone (p. ej. `LayoutContent` vs el real `ContentLayout`, o `Dashboard`/`StatCard` inexistentes).
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read this entire file first.
+- 🔴 La verdad la da el **paquete instalado**, NO el catálogo. Si `kit-grounding.md` y `llms.txt` discrepan, **gana el grounding**.
+- 🧪 No se considera "verificado" hasta que el playground **compile** (build exit 0) o renderice.
+- 🇪🇸 Texto de UI siempre en español.
+- ✅ Speak in `{communication_language}`.
+
+## EXECUTION SEQUENCE
+
+### 1. Detect existing grounding (skip if fresh)
+
+If `{kit_grounding}` already exists AND records the same `siesa_uikit_package` version resolved in step-01:
+- Inform the user it's current and **skip to section 6** (no reinstall).
+Otherwise continue.
+
+### 2. Clone BaseFrontend (the harness) — per workflow_ext §3A
+
+El harness del frontend ES un clon del repo base oficial `{frontend_base_repo}` (Vite 6 + React 19 + TS + Tailwind v4 + `siesa-ui-kit@^1.0.109` con todos los peers ya instalados, TanStack Router, Clean Architecture por módulos, capa mock y shell `LayoutBase`). NO scaffoldees a mano.
+
+```bash
+git clone --depth 1 https://github.com/SiesaTeams/BaseFrontend {kit_playground}
+rm -rf {kit_playground}/.git    # no anidar .git dentro del repo SIESA
+cd {kit_playground} && npm install
+```
+
+- Si `{kit_playground}` ya existe con un clon válido (tiene `package.json` con dependencia `siesa-ui-kit`), reutilízalo — no re-clones.
+- El `.gitignore` del base solo trae `node_modules/`; añade `dist/` para no versionar el build de verificación.
+- Si NO hay red/acceso al repo o al registro npm → ve a la sección 5 (grounding degradado) y avisa al usuario.
+- El paquete queda **fijado por el `package.json` del base** (`siesa-ui-kit@^1.0.109`); no hay que resolver el nombre a mano. CSS ya se importa en `src/main.tsx` (`import 'siesa-ui-kit/styles.css'`).
+
+### 3. Verify the real package builds (the grounding act)
+
+1. `npm run build` en `{kit_playground}` debe salir **exit 0** (compila los imports/exports reales del kit contra los módulos de ejemplo `agentes`/`colaboradores`). Un import roto es en sí un hallazgo.
+2. Opcional: `npm run dev` (puerto 3010) + screenshot para confirmar el render visual del shell `LayoutBase` + `MasterCrud`.
+3. Extrae los **exports y prop types reales** desde el paquete instalado: `{kit_playground}/node_modules/siesa-ui-kit/dist/index.d.ts` y `dist/components/**/*.types.d.ts`.
+4. Documenta los contratos que el base **ya usa** como referencia verificada: `LayoutBase` (props del shell + `navigationItems`), `MasterCrud` (array `fields` con `accessorKey`/`header`/`type`/`config` + `service`/`schema`), y el patrón de 4 capas de un módulo (`src/modules/agentes/`).
+
+### 5. Write `kit-grounding.md`
+
+Write `{kit_grounding}` with, at minimum:
+- **Install**: package name + version + peer deps + transitive deps + CSS import + order gotchas.
+- **Real component inventory** (verified export names).
+- **Real prop signatures** for the components in scope (e.g. `Button.type` not `variant`, `Badge.label`, `DescriptionList` = one `term`/`details` per row, `Table` data-driven, server-driven `LookupField`/`ContactManager`).
+- **Hallucinations caught**: a table of "assumed name → real name / does-not-exist" (this is the anti-hallucination payload).
+
+**Degraded mode** (no install possible): still write `kit-grounding.md` from `{siesa_uikit_catalog_url}` + `{componentMappingData}`, clearly flagged `⚠️ NO VERIFICADO EN RUNTIME — derivado del catálogo`. Never silently skip the file.
+
+### 6. Spec Sync gate (HALT)
+
+Present a concise summary of the grounding (package/version, components verified, hallucinations caught) and ask:
+
+```
+🧪 Kit Warm-up listo. Grounding en _kit-playground/kit-grounding.md
+- Paquete: {nombre}@{versión} ({verificado por build/render | degradado})
+- Componentes verificados: {n}   - Correcciones detectadas: {n}
+
+[C] Continuar a generar escenarios (step-04/05 usarán el grounding)
+[S] Sincronizar el spec ahora (aplicar correcciones a ux-design-specification.md)
+[E] Editar el grounding antes de continuar
+```
+
+If `[S]`: apply the name/contract corrections to the project `ux-design-specification.md` (add/refresh a "Kit Grounding — Spec Sync" section). Then return to this menu.
+
+On `[C]`: update `_progress/00-design-log.md` ("Phase 3 — generar escenarios; grounding listo") and load + execute `{nextStepFile}`.
+
+---
+
+## 🚨 SUCCESS / FAILURE
+
+✅ Paquete real resuelto; playground compila/renderiza; `kit-grounding.md` escrito con nombres/props reales y alucinaciones detectadas; gate de Spec Sync presentado.
+❌ Saltar el grounding y diseñar contra el catálogo; omitir `kit-grounding.md`; declarar "verificado" sin build/render; escribir UI de ejemplo en inglés.

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/steps/step-03-scenarios.md

@@ -0,0 +1,102 @@
+---
+name: 'step-03-scenarios'
+description: 'Deriva escenarios UX y páginas desde las épicas/historias usando los scripts scaffold de WDS'
+
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals'
+thisStepFile: '{workflow_path}/steps/step-03-scenarios.md'
+nextStepFile: '{workflow_path}/steps/step-04-specs.md'
+
+wds_scripts: '{project-root}/_siesa-agents/wds/scripts'
+init_scenario: '{wds_scripts}/wds-init-scenario.js'
+init_page: '{wds_scripts}/wds-init-page.js'
+nav: '{wds_scripts}/wds-nav.js'
+---
+
+# Step 3: Escenarios y Páginas (Phase 3 WDS)
+
+## STEP GOAL
+
+Convertir cada épica/historia del alcance en la estructura de escenarios y páginas de WDS, usando EXCLUSIVAMENTE los scripts scaffold (nunca markdown a mano). Salida bajo `{design_artifacts}/C-UX-Scenarios/`.
+
+## MANDATORY EXECUTION RULES
+
+- 🧩 NEVER write the scenario/page markdown by hand — use the scripts
+- 📖 Read this entire file first
+- ✅ Speak in `{communication_language}`
+
+## MAPPING MODEL
+
+```
+Épica            → Escenario WDS   (un flujo de usuario)
+Historia         → Página WDS      (una pantalla del flujo)
+Criterio (AC)    → Success Criteria de la página
+Orden de historias → numeración de páginas (01, 02, ...)
+```
+
+## EXECUTION SEQUENCE
+
+### 1. Plan the Scenarios (HALT for confirmation)
+
+From the in-scope epics, propose the scenario/page breakdown:
+
+```
+Propuesta de escenarios:
+1. "01 <Épica A>"  → páginas: 01 <Historia> · 02 <Historia> · ...
+2. "02 <Épica B>"  → páginas: ...
+
+[C] Confirmar y generar la estructura
+[E] Ajustar el desglose
+```
+
+HALT. Group stories that clearly belong to the same flow; split very large epics into multiple scenarios if needed. Keep page count realistic for a proposal.
+
+### 2. Create Each Scenario
+
+For each confirmed scenario:
+
+```bash
+node {init_scenario} \
+  --scenario "NN <Nombre del escenario>" \
+  --description "<flujo en una frase, en español>" \
+  --output {design_artifacts}
+```
+
+### 3. Create Each Page
+
+For each story/screen in the scenario:
+
+```bash
+node {init_page} \
+  --page "NN <Nombre de la página>" \
+  --scenario "NN <Nombre del escenario>" \
+  --platform "Web" \
+  --visibility "<Public|Authenticated>" \
+  --output {design_artifacts}
+```
+
+Choose `--platform` from the architecture (default "Web"; "Mobile web" if the PRD targets mobile). Choose `--visibility` from whether the story is pre/post login.
+
+### 4. Wire Navigation
+
+After all pages of a scenario exist:
+
+```bash
+node {nav} --scenario "NN <Nombre del escenario>" --output {design_artifacts}
+```
+
+Or, once everything is created: `node {nav} --all --output {design_artifacts}`.
+
+### 5. Record Source Traceability
+
+For each created page, note in memory (used in step-04 and step-06) the originating `[Source: <Épica> / <Historia> / FR-x]` so every spec and proposal traces back to planning.
+
+### 6. Update Log & Proceed
+
+Update `{design_artifacts}/_progress/00-design-log.md` "Current" to "Phase 4 — poblar page-specs". Load and execute `{nextStepFile}`.
+
+---
+
+## 🚨 SUCCESS / FAILURE
+
+✅ Cada escenario y página creados vía scripts; navegación cableada; trazabilidad a épicas/historias registrada.
+❌ Escribir specs a mano; páginas sin orden numérico; perder el vínculo con las historias de origen.

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/steps/step-04-specs.md

@@ -0,0 +1,97 @@
+---
+name: 'step-04-specs'
+description: 'Puebla cada page-spec con objetos mapeados a componentes siesa-ui-kit y spacing, en español, y valida estructuralmente'
+
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals'
+thisStepFile: '{workflow_path}/steps/step-04-specs.md'
+nextStepFile: '{workflow_path}/steps/step-05-prototype.md'
+
+wds_scripts: '{project-root}/_siesa-agents/wds/scripts'
+add_object: '{wds_scripts}/wds-add-object.js'
+add_spacing: '{wds_scripts}/wds-add-spacing.js'
+validate: '{wds_scripts}/wds-validate.js'
+
+componentMappingData: '{workflow_path}/data/component-mapping.csv'
+siesa_uikit_catalog_url: 'https://siesa-ui-kit.pages.dev/llms.txt'
+kit_grounding: '{design_artifacts}/_kit-playground/kit-grounding.md'
+freya_spec_quality: '{project-root}/_siesa-agents/wds/data/agent-guides/freya/specification-quality.md'
+freya_design_system: '{project-root}/_siesa-agents/wds/data/agent-guides/freya/design-system.md'
+---
+
+# Step 4: Page Specs con siesa-ui-kit (Phase 4 WDS)
+
+## STEP GOAL
+
+Rellenar cada página con sus objetos UI (mapeados a componentes **siesa-ui-kit**), spacing y tipografía, con todo el texto en **español**, y dejar las specs validando sin errores.
+
+## MANDATORY EXECUTION RULES
+
+- 🧩 NEVER edit the page markdown by hand — use `wds-add-object.js` / `wds-add-spacing.js`
+- 🧪 **GROUNDING FIRST**: load `{kit_grounding}` (de step-02b) and treat it as the **authoritative source** for component names and props. If `{kit_grounding}` and the catalog (`llms.txt`) disagree, **el grounding gana** (usa el nombre/contrato real, p. ej. `ContentLayout` no `LayoutContent`; no inventes `Dashboard`/`StatCard`). If `{kit_grounding}` is missing, go back and run step-02b.
+- 🔴 siesa-ui-kit FIRST: cada objeto se mapea a un componente del catálogo antes de considerar algo custom
+- 🇪🇸 Texto de UI en español → va en `--se`; referencia en inglés → `--en`
+- 📖 Read this entire file first; load `{freya_spec_quality}` and `{freya_design_system}`
+- ✅ Speak in `{communication_language}`
+
+## EXECUTION SEQUENCE
+
+### 1. Load Grounding + Catalog (grounding wins)
+
+1. **FIRST** load `{kit_grounding}` (real package truth from step-02b): exact export names, prop signatures, and the "hallucinations caught" table. This is authoritative.
+2. Then load the catalog (`{siesa_uikit_catalog_url}`) and `{componentMappingData}` as a secondary reference. When they conflict with the grounding, **use the grounding** (real names/props).
+3. Prefer **view-level** components when a whole page matches — but use the **real export names from the grounding** (e.g. `ContentLayout`, `MasterCrud`, `MasterPatternView`, `ListView`, `LoginView`; note there is no `Dashboard`/`StatCard` export — compose with `Card`).
+
+### 2. For Each Page — Define Objects
+
+Walk the page's originating story + acceptance criteria. For each UI element, decide the section (e.g. "Encabezado", "Formulario", "Acciones") and the siesa-ui-kit component, then append:
+
+```bash
+node {add_object} \
+  --page "{design_artifacts}/C-UX-Scenarios/<scenario-slug>/<page-slug>/<page-slug>.md" \
+  --section "<Sección>" \
+  --object "<Nombre del objeto>" \
+  --component "<Componente siesa-ui-kit>" \
+  --se "<Texto en ESPAÑOL>" \
+  --en "<English reference>" \
+  --behavior "<comportamiento, ej. onClick: enviar formulario>"
+```
+
+**Component Decision Protocol** (per workflow_ext.md §3) — **automático, sin preguntar**: si la necesidad NO está en siesa-ui-kit, **busca el componente en shadcn** (registro MCP de shadcn). Si existe en shadcn, úsalo. Si tampoco está en shadcn, **el agente crea el componente** (componiendo primitivos + tokens de marca). Registra la decisión (`kit` / `shadcn` / `custom`) en el design log.
+
+For `MasterCrud`-shaped pages (listados con CRUD), consult the `MasterCrud` skill for the contract and capture its key props as object behaviors.
+
+### 3. For Each Page — Define Spacing
+
+Add the spacing decisions that shape the layout rhythm:
+
+```bash
+node {add_spacing} \
+  --page "{design_artifacts}/C-UX-Scenarios/<scenario-slug>/<page-slug>/<page-slug>.md" \
+  --direction <v|h> --type <space|separator|line> --size <zero|sm|md|lg|xl|2xl|3xl|flex> \
+  --reason "<por qué, en español>"
+```
+
+### 4. Add Source Traceability
+
+In each page's "Reference Materials" / "Overview", add the `[Source: <Épica>/<Historia>/FR-x]` line recorded in step-03, and set Success Criteria from the story's acceptance criteria.
+
+### 5. Validate
+
+Run validation and fix every error before proceeding:
+
+```bash
+node {validate} --all --output {design_artifacts}
+```
+
+Common fixes: missing SE/EN content, Object IDs not kebab-case or wrong page prefix, missing sketches folder, wrong nav row count. Re-run until 0 errors.
+
+### 6. Update Log & Proceed
+
+Update the design log "Current" to "Phase 4 — render de prototipos". Load and execute `{nextStepFile}`.
+
+---
+
+## 🚨 SUCCESS / FAILURE
+
+✅ Todos los objetos mapeados a siesa-ui-kit, texto en español, `wds-validate.js --all` con 0 errores, trazabilidad presente.
+❌ Componentes custom sin pasar por el protocolo; UI en inglés; specs que no validan; objetos sin componente asignado.

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/steps/step-05-prototype.md

@@ -0,0 +1,102 @@
+---
+name: 'step-05-prototype'
+description: 'Fase de prototipado: construye UNA app integrada navegable con los componentes reales de siesa-ui-kit y la verifica en navegador'
+
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals'
+thisStepFile: '{workflow_path}/steps/step-05-prototype.md'
+nextStepFile: '{workflow_path}/steps/step-06-handoff.md'
+
+freya_agentic: '{project-root}/_siesa-agents/wds/data/agent-guides/freya/agentic-development.md'
+base_ux_spec: '{project-root}/_siesa-agents/resources/ux-ui/ux-design-specification.md'
+siesa_uikit_catalog_url: 'https://siesa-ui-kit.pages.dev/llms.txt'
+kit_grounding: '{design_artifacts}/_kit-playground/kit-grounding.md'
+kit_playground: '{design_artifacts}/_kit-playground'
+---
+
+# Step 5: Prototipos Renderizados (Visual Design)
+
+## STEP GOAL
+
+Producir prototipos **navegables y visibles** de las páginas especificadas, fieles a siesa-ui-kit, y verificarlos en navegador. Este es el entregable que el diseñador "ve".
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read this entire file first; load `{freya_agentic}` (design loop + verificación Puppeteer de Freya)
+- 🧬 Trabaja **DENTRO del clon de BaseFrontend** en `{kit_playground}` (de step-02b), per workflow_ext §3A. Ya trae el paquete real, todos los peers, el shell `LayoutBase`, routing, capa mock y los módulos de ejemplo `agentes`/`colaboradores` que vas a **reemplazar**.
+- 🧪 Load `{kit_grounding}` (de step-02b) y úsalo para imports/props reales. Importa siempre desde `siesa-ui-kit` (nunca asumas `@siesa/ui-kit`).
+- 🎨 Implementa contra los Object IDs de las page-specs — la spec es la fuente de verdad
+- 🇪🇸 Todo el texto visible en español; 🔴 siesa-ui-kit primero; ⚙️ Vite (BaseFrontend), nunca Next.js
+- ✅ Speak in `{communication_language}`
+
+## ENTREGABLE: LA APP CLONADA (BaseFrontend) INTEGRADA
+
+El entregable es **la app de BaseFrontend clonada en `{kit_playground}`**, con sus módulos de ejemplo reemplazados por los módulos del dominio del alcance, navegable de punta a punta con `npm run dev` (standalone, puerto 3010). NO un prototipo aislado por épica. Respeta las **convenciones del base** (no las reescribas):
+
+1. **Shell = ya está** en `src/routes/_app.tsx` → `LayoutBase` de siesa-ui-kit con `navigationItems` de `src/config/navigation.tsx` + `<Outlet/>`. La épica de shell (nav/rail/404) **es este layout**; ajústalo (productName, logo, ítems), no lo reconstruyas.
+2. **Un módulo por dominio**, NO por página-spec, bajo `src/modules/<dominio>/` con las 4 capas del patrón `agentes`/`colaboradores`:
+   - `domain/<x>.types.ts` — entidad + DTOs
+   - `application/schemas/<x>.schema.ts` (Zod) + `application/hooks/` (useQuery/useMutation)
+   - `infrastructure/api/<x>.api.ts` (mock → Axios) + `infrastructure/service/<x>.service.ts` (`CrudService<T>`)
+   - `presentation/pages/<X>Page.tsx`
+   Agrupa épicas relacionadas en el mismo módulo:
+   - Épicas de "listado + CRUD de una entidad" → un `MasterCrud` dirigido por `fields` (copia el patrón de `AgentesPage.tsx`): cada campo `{accessorKey, header, type, config:{required, showInList, searchable, cardPosition,…}}`.
+   - Épicas de "relación/asociación" NO son un módulo aparte: **se integran dentro de los módulos que relacionan** (panel de asociados + "Asociar/Reasignar" dentro del módulo correspondiente).
+   - Épica de dashboard/inicio → página de tarjetas (`Card`) con totales **calculados del estado real** (lee los stores mock).
+   - Épica de administración/catálogos → su módulo (`MasterCrud` o `GenericEntities`/`GenericEntityModal`).
+3. **Estado compartido = la capa mock** (`src/lib/mock/<x>.mock.ts`): una BD en memoria por entidad que los servicios leen/escriben. Los flujos se conectan DE VERDAD sobre estos stores:
+   - Eliminar una entidad padre → sus hijos quedan huérfanos y aparecen así en el otro módulo.
+   - Asociar/reasignar/crear/editar → se refleja al instante en todos los módulos afectados (invalida las queries de TanStack Query).
+   - Enlaces cruzados navegables ("Ver cliente" desde un contacto → `navigate({ to: '/clientes', search:{ id } })`).
+4. **Rutas + nav**: por cada módulo, crea `src/routes/_app/<modulo>.tsx` (`createFileRoute` → tu `Page`) y añade su ítem a `src/config/navigation.tsx` (con su permiso en `permissions.ts`). `routeTree.gen.ts` lo regenera el plugin de Vite al levantar `dev` — no lo edites.
+5. **Providers ya cableados**: `App.tsx` monta `QueryClientProvider` (`config/query-client.ts`) y el toaster. No los re-declares.
+6. Borra o vacía los módulos/rutas/nav de ejemplo (`agentes`, `colaboradores`) que no correspondan al proyecto.
+
+**Nunca** generes HTML+CSS que finja usar el kit (`<div class="rail" title="NavigationRail">`, `/* siesa-ui-kit Button */`) — se importan los componentes reales, siempre.
+
+**Gotchas reales (el base ya resuelve varios):**
+- **`QueryClientProvider` ya provisto** por `App.tsx`/`config/query-client.ts` → `GenericEntityModal`/`ContactManager` funcionan sin envolver nada extra.
+- **`LayoutBase` ya maneja logos/usuario** vía props en `_app.tsx` (`productName`, `siesaLogoPath`, `userDropdown`). Ajusta esas props, no toques Navbar/rail a mano.
+- **`MasterCrud`** es data-driven por `fields` + `service` + `schema` (ver `AgentesPage.tsx`). Para el contrato completo consulta el skill `MasterCrud`.
+- **`ContentLayout`** = master-detail `{children, factBox, factBoxOpen, onFactBoxClose}` (main + FactBox), no un header de título.
+- **`LookupField`** es server-driven: `fetcher` mock que devuelva `{ data, page, pageSize }` (records con `Id` PascalCase). No es un `<Select>`.
+- **`Button`** variante = `type` (`default|outline|plain`), no `variant`. **`Badge`** texto en `label`. **`Input`** trae `label`/`errorMessage`. **Toast** = `sonner`.
+
+## DESIGN LOOP (per page) — Freya's pattern
+
+For each page, follow the inline-testing split from `{freya_agentic}`:
+
+1. **Implement** the section from the spec (objects, spacing, Spanish text).
+2. **Verify en navegador** (agent-checkable, measurable). Levanta el harness (`cd {kit_playground} && npm run dev`, puerto **3010**) y captura cada módulo/estado (navega por el rail; abre detalle/form/diálogos). BaseFrontend usa **rutas de historial**, captura por ruta (`/clientes`, `/contactos`, …), no por hash.
+   - 🔴 **Si hay diseño de referencia (`{design_artifacts}/_design-ref/`, de step-01/workflow_ext §3C): compara tu screenshot LADO A LADO contra el de referencia — solo pasa si coinciden layout, colores, espaciado, tipografía y componentes.** No declares fidelidad contra una descripción textual ni contra tu modelo mental. Si el diseño usa tokens `var(--…)`, confirma que su bloque `:root` está importado en el harness (`src/styles/tokens.css` desde `src/index.css`) o los componentes custom saldrán sin estilo. Si el default de un componente de vista del kit (`MasterCrud`/`LayoutBase`) no se parece al diseño, compón la presentación a medida para igualarlo (importando primitivos del kit).
+   - Text content matches the spec (Spanish strings)
+   - Colors / key dimensions match tokens
+   - Interactive states (hover/focus/disabled, empty/error) render
+   - Navigation links work
+   **Captura de screenshots:** si no hay Puppeteer/Playwright instalado, usa **Chrome headless** directamente (suele estar disponible en Windows):
+   `chrome --headless=new --disable-gpu --hide-scrollbars --window-size=1440,900 --virtual-time-budget=4000 --screenshot=<out.png> "http://localhost:3010/<ruta>"`.
+   Guárdalos en `{design_artifacts}/C-UX-Scenarios/<scenario>/<page>/sketches/<page-slug>-real.png`. Nota: cada invocación de Chrome tarda ~7–10s; captura en lotes pequeños y mata procesos chrome colgados entre lotes.
+3. **Fix** measurable issues before presenting.
+4. **Present** to the user for qualitative feedback (feel, jerarquía visual, claridad). Iterate per their notes.
+
+## EXECUTION SEQUENCE
+
+1. **Construye los módulos dentro del clon** (`{kit_playground}/src/modules/<dominio>/`, 4 capas cada uno) + sus rutas (`src/routes/_app/<modulo>.tsx`) + ítems de nav (`config/navigation.tsx`), y ajusta el shell (`_app.tsx`). Reemplaza los módulos de ejemplo. Estado compartido en la capa mock; flujos cruzados de verdad (ver arquitectura arriba). Muestra progreso por módulo.
+2. **Verifica** con `cd {kit_playground} && npm run build` (exit 0) y `npm run dev` (puerto 3010), y **guarda un screenshot por página-spec** en su `sketches/<page-slug>-real.png` (satisface la validación WDS); captura los módulos/estados navegando por rutas reales, no pantallas aisladas.
+3. **Empaqueta la app como UN HTML autocontenido → `{design_artifacts}/propuesta-app.html`.** 🔴 Este ES el entregable estático para el diseñador. **NO** generes una galería de screenshots (`propuestas-visuales.html`): el entregable es la **app real funcional** en un solo archivo que abre por doble clic (`file://`), no imágenes. Los screenshots del paso 2 son solo para tu verificación interna. La app clonada es un SPA de Vite; para que funcione por `file://` se compila con JS+CSS inline y **hash routing**:
+   a. Instala el plugin en el clon: `cd {kit_playground} && npm i -D vite-plugin-singlefile`.
+   b. Crea `{kit_playground}/vite.config.singlefile.ts`: `base: './'`, `define: { 'import.meta.env.VITE_SINGLEFILE': JSON.stringify('true') }`, plugins `[TanStackRouterVite({...}), tailwindcss(), react(), viteSingleFile()]`, `resolve.alias` igual al base, `build: { outDir: 'dist-single', assetsInlineLimit: 100000000, chunkSizeWarningLimit: 100000 }`. Añade `dist-single/` al `.gitignore`.
+   c. En `src/App.tsx` usa **hash routing SOLO bajo el flag** (la app web normal se queda con history routing): `import { createHashHistory } from '@tanstack/react-router'` → `const isSingleFile = Boolean((import.meta.env as Record<string, unknown>).VITE_SINGLEFILE)` → `createRouter({ routeTree, ...(isSingleFile ? { history: createHashHistory() } : {}) })`. Sin hash, la ruta inicial `file://…` no matchea y sale 404.
+   d. **Importa los assets (logos/imágenes) vía Vite** (`import logo from '@/assets/logo.png'` y pásalo como prop), NO por ruta pública (`/logo.png`): solo los importados se inlinan como data-URI y cargan por `file://`. Copia a `src/assets/` cualquier logo que hoy viva en `public/`.
+   e. Compila y copia: `npx vite build --config vite.config.singlefile.ts` y luego `cp {kit_playground}/dist-single/index.html {design_artifacts}/propuesta-app.html`.
+   f. **Verifica** abriendo `file:///.../propuesta-app.html` (screenshot headless): deben verse el shell + logo, y una **ruta profunda por hash** (`propuesta-app.html#/<ruta>`, ej. `#/clientes/1`).
+   - La versión interactiva/viva sigue siendo `cd {kit_playground} && npm run dev` (:3010).
+   - Si existen `{design_artifacts}/C-UX-Scenarios/<escenario>/prototype.html`, reescríbelos como una nota breve que apunta a `propuesta-app.html` y a `npm run dev`.
+4. Update `{design_artifacts}/_progress/00-design-log.md` with what was rendered and any open design questions.
+5. Load and execute `{nextStepFile}`.
+
+---
+
+## 🚨 SUCCESS / FAILURE
+
+✅ App **clonada de BaseFrontend** con módulos del dominio (4 capas), shell `LayoutBase`, estado compartido en la capa mock y flujos conectados; `npm run build` exit 0 y `npm run dev` levanta en :3010; **`propuesta-app.html`** = la app real en UN HTML autocontenido que abre por `file://` (single-file + hash routing), verificada por screenshot; texto en español; **si había diseño de referencia, cada página verificada lado a lado contra él y coincidiendo**.
+❌ Scaffoldear un frontend a mano en vez de clonar BaseFrontend; entregar pantallas sueltas por épica; **entregar una galería de screenshots (`propuestas-visuales.html`) en vez de la app real**; HTML que finja usar el kit; usar Next.js; saltar la verificación en navegador; **declarar fidelidad sin comparar lado a lado contra el diseño de referencia renderizado** (o diseñar contra una descripción textual); **dejar sin importar los tokens `var(--…)` del diseño de referencia** (componentes custom sin estilo); replicar solo la pantalla inicial cuando la referencia tiene más pantallas.

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/steps/step-06-handoff.md

@@ -0,0 +1,96 @@
+---
+name: 'step-06-handoff'
+description: 'Empaqueta las propuestas visuales para los diseñadores (índice + app autocontenida en UN HTML + trazabilidad) y commitea la fase'
+
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals'
+thisStepFile: '{workflow_path}/steps/step-06-handoff.md'
+
+proposalIndexTemplate: '{workflow_path}/templates/proposal-index.md'
+# Entregable consolidado = la app real en UN HTML autocontenido (propuesta-app.html),
+# generada en step-05 §3 (vite-plugin-singlefile + hash routing). NO una galería de screenshots.
+wds_validate: '{project-root}/_siesa-agents/wds/scripts/wds-validate.js'
+phase2: '{project-root}/_siesa-agents/scripts/phases/phase2.js'
+---
+
+# Step 6: Empaquetado, Handoff y Commit
+
+## STEP GOAL
+
+Dejar las propuestas visuales listas para el equipo de diseño: un índice navegable con trazabilidad (`proposal-index.md`), la **app real compilada en UN HTML autocontenido** (`propuesta-app.html`, generada en step-05 §3), validación final, y el commit de fase. 🔴 El visor consolidado es la app funcional, NO una galería de screenshots.
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read this entire file first
+- ✅ Speak in `{communication_language}`
+
+## EXECUTION SEQUENCE
+
+### 1. Final Validation
+
+```bash
+node {wds_validate} --all --output {design_artifacts}
+```
+
+Must be 0 errors. Fix any remaining before continuing.
+
+### 2. Build the Proposal Index
+
+Using `{proposalIndexTemplate}`, create `{design_artifacts}/proposal-index.md` with:
+- Instrucción destacada para abrir la **app clonada de BaseFrontend** interactiva: `cd {design_artifacts}/_kit-playground && npm run dev` (puerto 3010), y enlace a la **app autocontenida** `propuesta-app.html` (un solo HTML, doble clic, sin servidor) para revisión rápida.
+- Por escenario/página: ruta del **módulo/página** correspondiente en la app (`/clientes`, `/contactos`, …) y su screenshot, no un HTML por épica.
+- Nombre de la página + enlace a su page-spec
+- Miniatura/enlace al screenshot real (`sketches/<page>-real.png`)
+- Componentes siesa-ui-kit usados
+- Trazabilidad `[Source: <Épica>/<Historia>/FR-x]`
+- Preguntas de diseño abiertas (del design log)
+
+This index is the single entry point a designer opens.
+
+### 2b. Consolidated viewers
+
+Dos formas de ver las propuestas (ambas son **la app real**, no screenshots):
+
+1. **App interactiva** = el clon de BaseFrontend en `{design_artifacts}/_kit-playground` → `npm run dev` (puerto 3010). Navegable de punta a punta por el rail (`LayoutBase`), con estado compartido y flujos conectados. Es la fuente viva.
+2. **`{design_artifacts}/propuesta-app.html`** — **la app compilada en UN HTML autocontenido** (JS+CSS inline + hash routing), generada en step-05 §3. Abre por doble clic, sin servidor: es la MISMA app funcional (navegación, CRUD, asociación en memoria) empaquetada para compartir/revisar sin instalar nada. 🔴 NO es una galería de imágenes.
+
+Ambos complementan al `proposal-index.md` (el índice con specs/trazabilidad).
+
+### 3. Present to Designer (HALT)
+
+```
+🎨 Propuestas visuales listas.
+- Escenarios: {n}   - Páginas: {n}
+- App interactiva (clon BaseFrontend): cd {design_artifacts}/_kit-playground && npm run dev  (:3010)
+- Índice: {design_artifacts}/proposal-index.md
+- App autocontenida (un HTML, doble clic): {design_artifacts}/propuesta-app.html
+
+¿Cómo seguimos?
+[D] Entregar al diseño (solo commitear) — recomendado
+[I] Iterar sobre alguna página antes de cerrar
+```
+
+HALT and wait.
+
+### 4. Update State
+
+Mark phases 3–4 complete in `{design_artifacts}/_progress/wds-project-outline.yaml` and update `_progress/00-design-log.md`.
+
+### 5. Phase Commit (per workflow_ext.md §5)
+
+```bash
+git status --short
+git diff --stat
+node {phase2} --commit "[Phase 2 - Planning] add WDS visual proposals for {project_name}"
+```
+
+Confirm:
+> `✅ Propuestas visuales WDS committeadas en la rama Phase 2 (planning).`
+
+**This is the LAST action. Do not continue after the commit.**
+
+---
+
+## 🚨 SUCCESS / FAILURE
+
+✅ Validación 0 errores; proposal-index.md con trazabilidad; **`propuesta-app.html` generada (la app real en un solo HTML autocontenido)**; estado WDS actualizado; commit de fase hecho.
+❌ Entregar sin índice; índice sin trazabilidad; **entregar una galería de screenshots en vez de la app autocontenida `propuesta-app.html`**; olvidar el commit de fase.

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/templates/product-brief-bridge.md

@@ -0,0 +1,68 @@
+---
+type: wds-product-brief
+status: bridged-from-planning
+source: siesa-planning-bridge
+generated_date: ""
+source_files: []
+stepsCompleted: []
+---
+
+# Product Brief — {{project_name}}
+
+> Documento generado por el workflow `wds-visual-proposals` a partir de los artefactos de planning existentes. Es el prerequisito de Fase 1 que Freya (WDS) valida antes de diseñar. Cada sección referencia su fuente con `[Source: ...]`.
+
+## 1. Vision (WHY)
+
+{{vision}}
+
+[Source: {{prd_source}}]
+
+## 2. Golden Circle
+
+- **WHY** — {{why}}
+- **HOW** — {{how}}
+- **WHAT** — {{what}}
+
+## 3. Target Users
+
+{{target_users}}
+
+[Source: {{prd_users_source}}]
+
+## 4. Business Goals & KPIs
+
+| Objetivo | Métrica / KPI |
+|---|---|
+| {{goal_1}} | {{kpi_1}} |
+
+[Source: {{prd_goals_source}}]
+
+## 5. Scope & Constraints
+
+- **En alcance:** {{in_scope}}
+- **Fuera de alcance:** {{out_of_scope}}
+- **Restricciones técnicas:** {{tech_constraints}}
+
+[Source: {{architecture_source}}]
+
+## 6. Content Language & Tone
+
+- **Idioma de UI:** Español (obligatorio)
+- **Tono:** {{tone}}
+
+## 7. Visual Direction (resumen)
+
+- **Color primario:** `#0e79fd` (siesa-ui-kit) {{color_overrides}}
+- **Tipografía:** Inter
+- **Sistema de componentes:** siesa-ui-kit primero
+- Detalle completo en `A-Product-Brief/visual-direction.md`
+
+[Source: ux-design-specification.md]
+
+## 8. Asunciones a confirmar
+
+{{assumptions}}
+
+---
+
+_Provenance: este brief NO contiene contenido inventado; deriva de los archivos listados en `source_files`._

package/siesa-agents/bmm/workflows/3-solutioning/wds-visual-proposals/templates/proposal-index.md

@@ -0,0 +1,46 @@
+---
+type: wds-proposal-index
+project: "{{project_name}}"
+generated_date: ""
+siesa_uikit_package: ""
+---
+
+# Propuestas Visuales — {{project_name}}
+
+> Punto de entrada para el equipo de diseño. Cada página enlaza su especificación WDS, su ruta en la app y su screenshot, con trazabilidad al planning de origen.
+
+**App interactiva (clon BaseFrontend):** `cd _kit-playground && npm run dev` (:3010)  ·  **App autocontenida (un HTML, doble clic):** [`propuesta-app.html`](propuesta-app.html)  ·  **Paquete siesa-ui-kit:** {{siesa_uikit_package}}
+
+---
+
+## Resumen
+
+| Escenario | Páginas | Origen (Épica) |
+|---|---|---|
+| {{scenario_1}} | {{scenario_1_pages}} | {{scenario_1_epic}} |
+
+---
+
+## Detalle por escenario
+
+### {{scenario_1}}
+
+[Source: {{scenario_1_epic}}]
+
+| # | Página | Spec | Prototipo | Screenshot | Componentes siesa-ui-kit | Origen |
+|---|---|---|---|---|---|---|
+| 01 | {{page_name}} | [spec]({{page_spec_path}}) | [ver]({{page_prototype_path}}) | ![]({{page_screenshot_path}}) | {{page_components}} | [Source: {{page_source}}] |
+
+---
+
+## Preguntas de diseño abiertas
+
+{{open_questions}}
+
+---
+
+## Cómo revisar
+
+1. Corre `cd _kit-playground && npm run dev` (:3010) y navega por el rail entre módulos, o abre `propuesta-app.html` (doble clic) — la app real en un solo HTML autocontenido.
+2. Compara contra la page-spec (texto en español, componentes siesa-ui-kit).
+3. Deja feedback cualitativo; el workflow puede iterar página por página (`/wds-visual-proposals` → reanudar → iterar).