zugzbot 1.0.39 → 1.0.40

package/.opencode/rules/sdd-global.md

@@ -25,8 +25,9 @@ Cuando el estado del sistema tiene `loopMode === true` (activado mediante el com
 ## 3. Uso Mandatorio de Bloques Prehechos de Shadcn UI (dashboard, sidebar, login, etc.)
 Para optimizar el tiempo de desarrollo, garantizar una experiencia visual premium y evitar la invención de layouts o formularios comunes desde cero:
 - **Prioridad de Bloques**: Al diseñar cualquier interfaz de usuario (Layouts, Dashboards, Paneles de Control, Vistas de Configuración, Páginas de Autenticación, Tablas de Datos, Gráficos), los agentes **deben** buscar y utilizar de forma prioritaria los bloques prehechos del registro oficial `@shadcn` (como `dashboard-01`, `sidebar-01` al `16`, `login-01` al `05`, `signup-01` al `05`).
-- **Búsqueda Proactiva**: El Spec-Writer **debe** consultar el registro utilizando las herramientas del MCP `shadcn` (`shadcn_search_items_in_registries`, `shadcn_list_items_in_registries`) al redactar el contrato (F1) para identificar qué bloques se ajustan a la necesidad, y declararlos en `frontend.components` y `files_affected` de `contract.json`.
-- **Implementación por Distribución y Composición**: El Coder (F2) **debe** instalar estos bloques usando `npx shadcn@latest add <block-name>` (ej: `dashboard-01`, `login-03`) en su proyecto, integrando y distribuyendo los elementos con el estado y lógica del backend, sin rediseñar o codificar layouts que ya existen de forma oficial.
+- **Búsqueda Proactiva**: El Spec-Writer **debe** consultar el registro utilizando las herramientas del MCP `shadcn` (`shadcn_search_items_in_registries`, `shadcn_list_items_in_registries`) al redactar el contrato (F1) para identificar qué bloques se ajustan a la necesidad, y declararlos en `frontend.components` y `files_affected` de `contract.json`. Además, el Spec-Writer **debe** invocar `shadcn_view_items_in_registries` sobre los bloques complejos seleccionados para inspeccionar por adelantado sus archivos, rutas y dependencias inyectadas por defecto, anticipando cualquier colisión de ruteo y documentándolo con precisión en el contrato.
+- **Implementación por Distribución y Composición**: El Coder (F2) **debe** instalar estos bloques usando `npx shadcn@latest add <block-name>` (ej: `dashboard-01`, `login-03`) en su proyecto, integrando y distribuyendo los elementos con el estado y lógica del backend, sin rediseñar o codificar layouts que ya existen de forma oficial. El Coder puede usar `shadcn_get_item_examples_from_registries` para ver ejemplos de implementación realistas y aplicarlos limpiamente a la primera, reduciendo el desvío visual.
+- **Resolución Activa de Conflictos de Ruteo por Inyección de Bloques**: Si la CLI de Shadcn inyecta automáticamente una estructura de rutas (ej: `src/app/dashboard/page.tsx`) que compite con las rutas del contrato (como un route group `(dashboard)` o una ruta raíz), el Coder **debe** borrar o refactorizar de inmediato el código inyectado por defecto para evitar bucles de redirección infinitos o colisiones en el router.
 
 ## 4. Soporte para Subdirectorios, Monorepos (targetDir) y Estándar Corporativo `src/`
 Si el proyecto o aplicación principal vive en un subdirectorio (ej. `next-app`, `frontend`, `backend`), se deben seguir estas directivas estrictas para mantener la consistencia y el "estándar corporativo con carpeta `src/`":
@@ -42,6 +43,9 @@ Cualquier desarrollo de interfaz de usuario (Dashboards, Landings, Formularios,
   - Se deben mapear obligatoriamente a variables semánticas de Shadcn/Tailwind que soporten modo claro/oscuro dinámico por defecto (ej. `bg-background`, `bg-muted/50`, `bg-accent`, `text-foreground`, `text-muted-foreground`, `border-border`).
 - **Gráficos Dinámicos y Reactivos (SVG/Recharts Theme Sync):**
   - Cualquier componente de gráficos (como Recharts o visores vectoriales SVG) que use atributos de pintado inline (`stroke`, `fill`, `color`) debe resolver sus colores mediante un custom hook o variables dinámicas que consuman el estado del tema actual (`useTheme` de `next-themes` u homólogo), previniendo que líneas o textos queden invisibles en modo oscuro.
+  - Está estrictamente prohibido usar variables CSS puras directamente en `stroke` o `fill` de SVG si estas no son resueltas de forma dinámica. Si es necesario, utiliza una paleta de colores hexadecimales fija de alto contraste y compatible con ambos modos claro y oscuro (ej: `#0072f5` para líneas y barras, o una paleta de sectores sólida para PieCharts) que garantice legibilidad 100% en fondos claros y oscuros, manteniendo solo los ejes y rejillas de fondo (grids) referenciando variables semánticas.
+- **Evitar Solapamiento de Sidebar (Sidebar Overlap Prevention):**
+  - Al implementar barras laterales colapsables de Shadcn (`Sidebar`), el Coder debe asegurarse de que el contenedor del contenido principal use de forma robusta `<SidebarInset>` o una estructura flexbox flexible (ej: `flex flex-1 flex-col`) que responda al estado del sidebar. Está estrictamente prohibido usar posicionamiento fijo o absoluto en el sidebar sin un espaciador o contenedor dinámico que evite que el sidebar se sobreponga al contenido en pantallas anchas.
 - **Robustez HTML y Regla de No-Nesting en Triggers:**
   - Al utilizar componentes contenedores de Radix/Shadcn UI (como `TooltipTrigger`, `DropdownMenuTrigger`, `DialogTrigger`, `SheetTrigger`), está estrictamente PROHIBIDO anidar un elemento interactivo nativo (como `<button>` o `<a>`) directamente dentro de otro trigger que ya renderice un botón por defecto.
   - Para evitar la hidratación rota y HTML inválido, se debe usar siempre el prop `asChild` en el trigger de Radix o delegar los props correctamente usando las directivas del componente de base.
@@ -54,6 +58,8 @@ Para evitar bucles de redirección ("redirect loops") y pantallas parpadeantes (
 - **Evitar Race Conditions en Redirecciones:** En el formulario de login, usa siempre `router.replace("/")` en lugar de `push` tras un login exitoso para evitar empujar estados duplicados al historial.
 - **Evitar useEffects Cruzados Activos:** Si usas un guard de redirección en `LoginPage` o similar para usuarios ya autenticados, utiliza un `useRef(false)` para controlar que la redirección asíncrona solo se dispare una vez y no se encadene con re-renderizados concurrentes de React.
 - **Evitar Flash de Carga SSR en Layouts:** Para layouts o guards protegidos, nunca asumas estados por defecto que pinten elementos cargando (spinners) durante el servidor. Comprueba si el componente está montado (`mounted === true`) antes de evaluar la sesión en el cliente y renderizar el contenido. Retorna `null` antes de montar para evitar desajustes de hidratación (hydration mismatch).
+- **Eliminación Obligatoria de Placeholders de Página Raíz:**
+  - El Coder debe asegurar que la página de entrada de la aplicación (`src/app/page.tsx` o similar) no se quede con el texto placeholder por defecto. Debe ser reemplazada por el componente principal especificado o contener una redirección limpia (`redirect("/dashboard")`) hacia la vista principal protegida o pública definida por el contrato.
 
 ## 7. Mockups Visuales y Validación Temprana de Layout (F0/F1)
 Para optimizar el diseño, evitar cambios de arquitectura estructurales a mitad del desarrollo (como rediseñar pestañas a layouts de sidebar lateral) y garantizar alineación inmediata con las expectativas del usuario:

package/.opencode/skills/docker-templates/SKILL.md

@@ -63,6 +63,13 @@ ENV HOSTNAME="0.0.0.0"
 CMD ["node", "server.js"]
 ```
 
+#### 🛠️ **Manejo de Conflictos de Dependencias y Sincronización de Lockfile**
+En proyectos donde las dependencias cambian con frecuencia por la adición automática de componentes de Shadcn, es muy común que el comando estricto `npm ci --frozen-lockfile` falle dentro de Docker con errores de desincronización de lockfile (ej: `Invalid: lock file's picomatch... does not satisfy`).
+
+Para solucionar esto de manera robusta:
+1. **Solución Local Primaria**: El Coder debe añadir de manera explícita la dependencia par conflictiva en su `package.json` (ej: `"picomatch": "^4.0.4"`) y ejecutar `npm install` localmente para regenerar y sincronizar un `package-lock.json` limpio antes de intentar compilar el contenedor.
+2. **Estrategia Fallback en Dockerfile**: Si la sincronización del lockfile sigue presentando conflictos intermitentes e inestabilidad insalvable, el Deployer tiene autorización para modificar el paso de instalación del Dockerfile de un estricto `npm ci` a un dinámico `npm install --no-audit --no-fund` para permitir que el motor de resolución de Node resuelva las dependencias pares de forma adaptativa.
+
 #### **.dockerignore**
 ```ignore
 node_modules

package/.opencode/skills/sdd-methodology/SKILL.md

@@ -41,83 +41,47 @@ Cada fase tiene un **gate explícito** (HIL del usuario) antes de transicionar a
 
 ---
 
-## 3. Trampas conocidas (EVITAR siempre)
+## 3. Trampas del Flujo Maestro (EVITAR siempre)
 
 ### Trampa 1: Listar marcas de diseño una por una
-**NO HAGAS**: 4 llamadas a `oh-my-design_list_references` con `category: "saas"`, "fintech", "ecommerce", "consumer" solo para mostrar opciones.
-**HAZ**: 1 llamada a `sdd_list_design_recommendations({ use_case: "all", max_per_category: 3 })`. Si el usuario quiere "Personalizar", ahí sí usa `oh-my-design_search_by_vibe`.
+**NO HAGAS**: Hacer múltiples llamadas a `oh-my-design_list_references` para mostrar opciones al usuario en F0.
+**HAZ**: Haz una única llamada consolidada a `sdd_list_design_recommendations({ use_case: "all", max_per_category: 3 })`.
 
 ### Trampa 2: Crear la carpeta del spec en 2 steps
-**NO HAGAS**: `sdd_create_spec_folder("mi-spec")` + `sdd_set_phase("F1_CONTRACT", ...)` en 2 calls (race condition de timestamp, observado en sesión 137a).
-**HAZ**: 1 sola call: `sdd_set_phase({ phase: "F1_CONTRACT", spec_name: "mi-spec" })`. Devuelve `activeContract` listo.
+**NO HAGAS**: Llamar a `sdd_create_spec_folder("mi-spec")` y luego a `sdd_set_phase("F1_CONTRACT", ...)` por separado (causa race conditions en el timestamp).
+**HAZ**: Transiciona en un solo paso: `sdd_set_phase({ phase: "F1_CONTRACT", spec_name: "mi-spec" })`.
 
-### Trampa 3: Reescribir `globals.css` desde cero
-**NO HAGAS**: Sobrescribir `src/app/globals.css` quitando las variables shadcn (`--color-border: var(--border)`, etc.) al aplicar tokens de marca. Build falla con `Cannot apply unknown utility class 'border-border'` (observado en sesión 137a).
-**HAZ**: Usar `sdd_apply_brand_tokens` que inyecta en un bloque `@theme inline` aparte, preservando las variables shadcn.
+### Trampa 3: Cargar `next-devtools` MCP en sesión normal
+**NO HAGAS**: Activar `next-devtools` por defecto. Inyecta miles de palabras de instrucciones redundantes al contexto, desperdiciando tokens de razonamiento.
+**HAZ**: Mantenerlo deshabilitado en `opencode.json` y activarlo únicamente bajo demanda si se depura un error muy específico del runtime de Next.js.
 
-### Trampa 4: Cargar `next-devtools` MCP en sesión normal
-**NO HAGAS**: Dejar `next-devtools` habilitado. Su tool `init` inyecta 1000+ palabras de "FORGET ALL PRIOR KNOWLEDGE" (~8K tokens de reasoning desperdiciado — el coder tuvo el mayor consumo de tokens de la sesión 137a por esta razón).
-**HAZ**: Está deshabilitado por defecto en `opencode.json`. Solo activarlo on-demand si un subagente reporta un error específico de Next 16.
+### Trampa 4: Escribir el contrato desde cero en F1
+**NO HAGAS**: Redactar cientos de líneas de `contract.json` de forma manual.
+**HAZ**: Cargar la skill `sdd-quickstart` y rellenar los huecos `{{...}}` de su plantilla preconfigurada.
 
-### Trampa 5: Escribir el contrato desde cero
-**NO HAGAS**: Redactar 600+ líneas de `contract.json` en cada sesión. Riesgo alto de inconsistencia.
-**HAZ**: Cargar la skill `sdd-quickstart` y usar la plantilla pre-rellenada. Solo rellenar `{{...}}`.
+### Trampa 5: Permitir que el Coder escriba los tests en F2
+**NO HAGAS**: Desarrollar la lógica y luego redactar las pruebas (causa bucles redundantes entre Coder y Tester).
+**HAZ**: Que el Spec-Writer declare las aserciones en el contrato en F1. El Coder solo implementa el código de negocio necesario para que pasen.
 
-### Trampa 6: Tests en F2
-**NO HAGAS**: Que el coder escriba los tests después de implementar (loop Coder → Tester → Coder, observado en sesión 137a).
-**HAZ**: Que el spec-writer (en F1) cree los tests con assertions reales basadas en `test_scenarios`. El coder solo implementa el código de producción para hacerlos pasar.
+### Trampa 6: Exceso de actualizaciones de TODOs con `todowrite`
+**NO HAGAS**: Llamar a `todowrite` para actualizar el estado del arnés tras cada pequeño cambio o fase.
+**HAZ**: Inicializar la lista al inicio, marcar `in_progress` al arrancar una fase, y marcar los TODOs completados en bloque al final.
 
-### Trampa 7: 5+ llamadas a `todowrite` durante la sesión
-**NO HAGAS**: Actualizar la lista de TODOs cada vez que cambias de fase (observado 5 veces en sesión 137a).
-**HAZ**: Crear la lista al inicio. Marcar `in_progress` solo cuando arrancas la fase. Marcar `completed` **en bloque** al final.
+### Trampa 7: Cargar skills duplicadas en subagentes
+**NO HAGAS**: Cargar skills generales (como `sdd-methodology`) de manera redundante en subagentes especializados (como `@sdd-deployer` o `@sdd-tester`) que ya la tienen incorporada en su prompt base.
+**HAZ**: Limitar la carga de skills estrictamente a tareas que requieran sus plantillas específicas.
 
-### Trampa 8: `lint: false` en el orquestador
-**NO HAGAS**: Dejar que el tester descubra imports no usados en tests.
-**HAZ**: El self-audit del coder (F2) y el auto-lint gate de `sdd_set_phase("F3_VERIFICATION")` ya lo previenen. El orquestador debe **reportar el `lintWarning`** al usuario antes de delegar al tester.
+### Trampa 8: Invocar Playwright en modo Console
+**NO HAGAS**: Abrir navegadores o tomar snapshots si `verificationMode` es `"console"`.
+**HAZ**: Confiar plenamente en Vitest/Pytest y curls rápidos desde la terminal.
 
-### Trampa 9: Cargar skills duplicadas
-**NO HAGAS**: Cargar skills de forma genérica en subagentes si su contenido ya está integrado en su prompt de identidad (ej. cargar `sdd-methodology` en `@sdd-deployer` o `@sdd-tester`). Esto duplica los tokens de input consumidos.
-**HAZ**: Limitar la carga de skills a los casos proactivos indicados o cuando se requieran plantillas/recursos específicos de la skill (ej. `sdd-quickstart` en `@sdd-spec-writer`).
+### Trampa 9: Orquestador usurpador (Ruptura de Abstracción)
+**NO HAGAS**: Editar código de producción o escribir/ejecutar tests directamente desde el orquestador si un subagente falla o se queda sin pasos.
+**HAZ**: Re-invocar al subagente experto (`sdd-coder` o `sdd-tester`) mediante la herramienta `task` pasándole el `task_id` original para que continúe limpiamente.
 
-### Trampa 10: Playwright en modo Console
-**NO HAGAS**: Invocar herramientas de Playwright (`playwright_browser_navigate`, `playwright_browser_snapshot`, etc.) si `verificationMode` está configurado en `"console"`. Esto consume tiempo y reasoning innecesarios.
-**HAZ**: En modo `console`, confía en pruebas unitarias/integración (Vitest) y verificaciones directas con curls/logs. No abras navegadores.
-
-### Trampa 11: Orquestador usurpador (Ruptura de Abstracción)
-**NO HAGAS**: Permitir que el Orquestador principal (`sdd-orchestrator`) tome el rol de escribir el código de producción o escribir/ejecutar tests directamente si un subagent (ej. `@sdd-coder`) falla o alcanza el límite de pasos ("Maximum Steps Reached"). Esto ensucia la ventana de contexto principal de la sesión.
-**HAZ**: Re-invoca al mismo subagente usando la herramienta `task`, pasando el `task_id` original del subagente interrumpido e instruyéndole: "Te quedaste sin pasos. Continúa y finaliza los archivos pendientes".
-
-### Trampa 12: Obsesión por alineación de consola (Pixel-Peeping)
-**NO HAGAS**: Gastar múltiples iteraciones o miles de tokens en el razonamiento de `@sdd-coder` tratando de lograr una alineación perfecta de columnas con espacios exactos en salidas CLI o tablas ASCII.
-**HAZ**: Usa funciones estándar de formateo de strings de tu lenguaje (como `ljust()`, `rjust()` o `center()` en Python; o formateadores sencillos en JS/TS) para lograr una presentación razonable de forma inmediata y avanzar directamente a la creación de pruebas.
-
-### Trampa 13: Omitir la disposición espacial y propuesta de Layout en F1
-**NO HAGAS**: Redactar el contrato en F1 listando únicamente archivos de forma abstracta sin definir o validar la geometría estructural y distribución de la UI (ej. si se requieren Sidebars locales de navegación vs pestañas horizontales planas), asumiendo anchos angostos y estáticos (como `max-w-3xl`) o rompiendo el soporte de modo oscuro con colores absolutos (`bg-white`).
-**HAZ**: El spec-writer debe proponer proactivamente en F1 un bosquejo textual o diagrama ASCII de la interfaz y validar con el usuario un layout responsivo amplio (`max-w-6xl` o superior). Además, el coder debe implementar soporte semántico dinámico de temas de entrada (sin colores duros) y sincronizar colores SVG/gráficos dinámicamente con el tema actual.
-
-### Trampa 14: Guardar archivos de tests que contienen JSX con extensión `.ts` en vez de `.tsx`
-**NO HAGAS**: Usar la extensión `.ts` para archivos de tests que mockean iconos de lucide o renderizan primitivas de HTML o JSX (esbuild/Vitest fallarán en la compilación con errores como `Expected ">" but found "data"`).
-**HAZ**: Toda suite de pruebas unitarias o de integración que monte componentes o contenga JSX debe grabarse con la extensión `.tsx` obligatoriamente.
-
-### Trampa 15: Selectores de Testing Library ambiguos para campos comunes
-**NO HAGAS**: Usar queries amplias y con insensibilidad a mayúsculas como `screen.getByLabelText(/password/i)` si hay botones como "Show password" con `aria-label` que repiten la palabra clave. Esto lanzará un error de "Found multiple elements".
-**HAZ**: Usa selectores de coincidencia exacta como `screen.getByLabelText(/^Password$/)` o busca mediante `screen.getByPlaceholderText(...)` para aislar de forma unívoca el input deseado.
-
-### Trampa 16: Probar la ausencia de elementos ocultos por CSS con `not.toBeInTheDocument()`
-**NO HAGAS**: Tratar de validar que un menú, etiqueta de barra lateral colapsada o modal ya no es visible utilizando `expect(queryByText("...")).not.toBeInTheDocument()`. Al ocultar layouts mediante clases CSS de ancho cero (`w-0`), opacidad (`opacity-0`) o display (`hidden`), los elementos siguen existiendo físicamente en el DOM de pruebas.
-**HAZ**: Verifica las clases CSS de visibilidad directamente (ej. `expect(sidebarEl.className).toContain("w-16")`) o usa `.not.toBeVisible()` de `@testing-library/jest-dom`.
-
-### Trampa 17: Mocks estáticos para toggles y hooks con estado
-**NO HAGAS**: Mockear hooks que controlan transiciones (como `useTheme` de `next-themes`) con retornos fijos y estáticos, ej. `vi.mock('next-themes', () => ({ useTheme: () => ({ theme: 'light', setTheme: vi.fn() }) }))`. El segundo clic en el toggle intentará pasar de 'light' a 'dark' pero fallará porque el estado simulado sigue en 'light' (llamando a setTheme('dark') por segunda vez).
-**HAZ**: Define variables mutables a nivel de archivo dentro de la suite de mocks y usa getters en la definición del mock para reflejar los cambios en caliente.
-
-### Trampa 18: Fallos en resolución de `@import "shadcn/tailwind.css"` en Tailwind v4 con Next.js 16/Shadcn
-**NO HAGAS**: Importar `@import "shadcn/tailwind.css"` en `globals.css` sin comprobar si el paquete npm `shadcn` está instalado en la máquina, provocando fallos fatales de compilación durante el comando `next build`.
-**HAZ**: El coder siempre debe instalar explícitamente el paquete base ejecutable y estilizado `npm install shadcn` en proyectos Next + Tailwind v4.
-
-### Trampa 19: Bucle infinito y parpadeo de pantalla (Flicker) tras el inicio de sesión
-**NO HAGAS**: Usar redirecciones cruzadas en `useEffect` con `router.push()` tanto en el formulario de login como en la propia página de login, o renderizar spinners por defecto antes de verificar la sesión en el cliente, causando que el router encadene múltiples repeticiones de renderizado y la pantalla parpadee.
-**HAZ**: Usa `router.replace()` para evitar ensuciar el historial. Proporciona siempre una bandera de montaje (`mounted === true`) y retorna `null` para evitar desajustes de hidratación (hydration mismatch). Protege las redirecciones del login mediante una referencia `useRef(false)` para controlar que no se solapen redirecciones de estado concurrentes de React.
+### Trampa 10: Obsesión por alineación exacta en consola (Pixel-Peeping)
+**NO HAGAS**: Consumir iteraciones intentando alinear espacios exactos en salidas CLI o tablas ASCII.
+**HAZ**: Usar funciones estándar de formateo de strings de tu lenguaje (`ljust()`, `rjust()`) y priorizar la lógica de negocio y las pruebas.
 
 ---
 

package/.opencode/skills/sdd-quickstart/SKILL.md

@@ -160,6 +160,7 @@ Copia y adapta los IDs y descripciones que apliquen. Borra los que no apliquen.
 - **NO escribas más de 5-6 `test_scenarios`** para modo `console`. Más de eso no acelera la entrega, solo retrasa F2.
 - **NO incluyas escenarios `visual` o `e2e` si `verificationMode` es `console`.** El tester los rechazará.
 - **NO omitas la disposición espacial y propuesta de Layout**: El spec-writer DEBE proponer un bosquejo textual o diagrama ASCII de la disposición espacial de la UI en F1 (ej. layouts con sidebar lateral para configuración o paneles complejos en lugar de simples pestañas tradicionales planas) y acordar anchos de pantalla generosos (`max-w-6xl` o superior, evitando el limitante `max-w-3xl`) con el usuario antes de transicionar a F2. Esto previene reestructuraciones estéticas costosas y asegura entregas de alta gama a la primera.
+- **NO omitas la página raíz (`src/app/page.tsx`) en el mapeo de archivos afectados**: El spec-writer DEBE asegurar que `src/app/page.tsx` quede registrado explícitamente y que el contrato aclare si la ruta raíz `/` servirá el contenido principal de la aplicación, o si simplemente ejecutará una redirección limpia (`redirect("/dashboard")`) hacia el panel principal. Esto evita que el Coder conserve el placeholder por defecto de bootstrap y cause inconsistencias visuales o de navegación.
 
 ---
 

package/.opencode/skills/sdd-tester-quickstart/SKILL.md

@@ -19,12 +19,14 @@ Esta habilidad proporciona un **flujo de trabajo estructurado en 4 pasos** para
 - En el **Paso 3**, no aplican los mocks de React, Lucide ni `crypto.randomUUID` en JS. Si necesitas mockear en Python, usa `unittest.mock` (como `patch` o `MagicMock`).
 - En el **Paso 4**, ejecuta `ruff check src/` o similar para linting, y `python -m pytest tests/ -v` para ejecutar toda la suite de pruebas de una sola llamada consolidada.
 
-### Paso 1: Leer solo lo indispensable (Máximo 3 reads)
+### Paso 1: Leer solo lo indispensable (Máximo 3 reads) y asegurar entorno
 1. **Contrato**: Lee únicamente `contract.json` para extraer los `test_scenarios` y el `verificationMode`.
 2. **Setup**: Lee `src/test/setup.ts` o `vitest.config.ts` para confirmar si ya hay polyfills.
 3. **Breve examen**: Lee el componente principal (`AppLayout` o similar) para confirmar el `stateFlow`. 
 *NO uses `glob` ciegos para buscar archivos del proyecto.*
 
+**VERIFICACIÓN CLAVE DE DEPENDENCIAS**: Asegúrate de que `package.json` tenga instaladas las devDependencies necesarias para pruebas de React: `happy-dom`, `@testing-library/jest-dom` y `@testing-library/dom`. Si no están presentes, instálalas en un solo comando unificado: `npm install --save-dev happy-dom @testing-library/jest-dom @testing-library/dom`.
+
 ### Paso 2: Autogenerar plantillas de tests (BLOQUEANTE)
 Antes de escribir cualquier test a mano, **DEBES** ejecutar:
 ```bash
@@ -35,17 +37,24 @@ Esto creará automáticamente las plantillas correspondientes en base a los `tes
 ### Paso 3: Completar aserciones usando Mocks Estandarizados (Evitar fallos de librerías)
 Completa los tests importando los componentes reales. Si Vitest o happy-dom fallan por dependencias externas de Shadcn UI o Lucide, aplica estos mocks centralizados:
 
-#### Mock de Lucide Icons (si fallan por SVG/React)
+#### Mock Dinámico de Lucide Icons (Recomendado para evitar fallos de iconos faltantes)
+Para evitar que tests fallen porque falta mockear un icono específico (ej. `PanelLeft`, `Search`, etc.), usa un Proxy que mockea dinámicamente CUALQUIER icono exportado por `lucide-react`:
 ```typescript
-vi.mock('lucide-react', () => ({
-  Sun: () => <div data-testid="icon-sun" />,
-  Moon: () => <div data-testid="icon-moon" />,
-  Plus: () => <div data-testid="icon-plus" />,
-  Trash2: () => <div data-testid="icon-trash" />,
-  History: () => <div data-testid="icon-history" />,
-  Clock: () => <div data-testid="icon-clock" />,
-  Calculator: () => <div data-testid="icon-calculator" />
-}));
+vi.mock('lucide-react', () => {
+  return new Proxy(
+    {},
+    {
+      get: (target, prop) => {
+        // Retorna un componente funcional con el testid del icono solicitado
+        const IconComponent = (props: any) => (
+          <span data-testid={`icon-${String(prop).toLowerCase()}`} {...props} />
+        );
+        IconComponent.displayName = String(prop);
+        return IconComponent;
+      },
+    }
+  );
+});
 ```
 
 #### Mock de Base UI / Shadcn Radix Primitives
@@ -123,3 +132,24 @@ npx vitest run
 1. **PROHIBIDO Playwright en modo Console**: Si `verificationMode === "console"`, no instancies ni corras ningún test de Playwright, ni navegues con tools de Playwright. Solo corre tests de Vitest.
 2. **PROHIBIDO modificar código de features para "hacer pasar" el test**: Si el código tiene un bug, haz rollback a `F2_IMPLEMENTATION` reportando el error exacto al coder. No parches la lógica del negocio en F3.
 3. **Consolidación**: No corras `vitest` archivo por archivo. Corre la suite completa en una sola llamada a `bash`.
+4. **REGLA DE ORO DE ASERCIONES DE TEXTO (Acentos y Encoding)**: Para evitar fallos tontos de aserción por diferencias de codificación en caracteres con tildes (ej: `ó` vs `\u00f3`, `ñ` vs `\u00f1`), usa siempre expresiones regulares insensibles a mayúsculas y comodines (ej: `screen.getByText(/Inicia sesi.n/i)` o `screen.getByText(/contrase.a/i)`). Nunca utilices comparaciones estrictas de cadenas de texto acentuadas.
+
+---
+
+## ⚠️ Trampas Comunes de Pruebas (Testing Gotchas)
+
+### 1. Extensión incorrecta en archivos de pruebas con JSX
+* **No hagas**: Usar la extensión `.ts` para archivos de tests que renderizan primitivas de HTML o JSX o que mockean componentes de interfaz (causa fallos de compilación inmediatos en Vitest).
+* **Haz**: Toda suite de pruebas que monte componentes o contenga JSX debe grabarse con la extensión `.tsx` obligatoriamente.
+
+### 2. Selectores ambiguos para campos interactivos comunes
+* **No hagas**: Usar queries genéricas e insensibles como `screen.getByLabelText(/password/i)` si existen múltiples elementos en el DOM que contengan esa palabra (ej: botones de "Show password"). Esto lanzará un error de "Found multiple elements".
+* **Haz**: Usa selectores de coincidencia exacta como `screen.getByLabelText(/^Password$/)` o busca mediante placeholders específicos (`screen.getByPlaceholderText(...)`).
+
+### 3. Validar ausencia de elementos ocultos por CSS con `not.toBeInTheDocument()`
+* **No hagas**: Tratar de validar que un menú o modal colapsado/oculto ya no es visible utilizando `expect(queryByText("...")).not.toBeInTheDocument()`. Si el elemento simplemente se oculta con clases de CSS (como `hidden`, `w-0` u `opacity-0`), el nodo sigue existiendo físicamente en el DOM.
+* **Haz**: Verifica la visibilidad real usando `.not.toBeVisible()` de `@testing-library/jest-dom`, o comprueba directamente las clases CSS de colapso.
+
+### 4. Mocks estáticos de hooks con estado
+* **No hagas**: Mockear hooks que controlan toggles (como `useTheme` de `next-themes`) usando un retorno fijo estático. Al simular el clic en el botón de toggle, el test fallará o entrará en bucles porque el valor del estado simulado permanece congelado.
+* **Haz**: Declara variables mutables locales a nivel de archivo de pruebas y usa getters dinámicos en la definición del mock de Vitest para simular los cambios de estado correctamente.

package/.opencode/skills/shadcn-templates/SKILL.md

@@ -81,6 +81,9 @@ Utiliza las plantillas y bloques existentes de Shadcn como el estándar absoluto
 
 Busca layouts de dashboards o formularios complejos en el registro mediante el MCP `shadcn` antes de escribir cualquier código personalizado. Una vez agregado el bloque, distribuye y adapta sus elementos con el estado y la lógica de tu aplicación. Te motivamos a explorar todo el ecosistema de bloques pre-creados por Shadcn para armar una UI robusta y moderna.
 
+**REGLA CRÍTICA DE RUTAS DUPLICADAS POR SHADCN CLI**:
+Al agregar un bloque interactivo complejo (como `dashboard-01`), el CLI de Shadcn puede inyectar automáticamente archivos en directorios fijos (como `src/app/dashboard/page.tsx`). El Coder **debe** verificar inmediatamente si existe una colisión con la estructura de rutas establecida por el contrato (`contract.json`) —por ejemplo, si el contrato establece un Route Group `src/app/(dashboard)/page.tsx` que sirve en la raíz `/`—. Si ocurre esto, el Coder tiene la obligación de **borrar, mover o refactorizar de inmediato el archivo inyectado automáticamente** para eliminar la duplicidad de rutas, evitando así bucles infinitos de redirección o errores fatales de compilación del router de Next.js.
+
 ### 3.2 Form Layouts (FieldGroup + Field)
 Para estructurar campos de formularios, no uses `div`s arbitrarios con clases de espaciado complejas. Usa las composiciones semánticas oficiales de Shadcn:
 ```tsx
@@ -109,25 +112,19 @@ Para estructurar campos de formularios, no uses `div`s arbitrarios con clases de
 ### 3.4 Sin Placeholders en Producción
 Los datos dummy y placeholders deben reemplazarse inmediatamente por estados y hooks reales en el frontend que llamen a las APIs del backend (ej. estados de carga, manejo de errores de llamada, y datos dinámicos).
 
-### 3.5 Estética de Diseño Premium y Layouts (OBLIGATORIO)
-Queda **estrictamente prohibido** generar interfaces visualmente planas, vacías o que parezcan un "mínimo producto viable" básico (por ejemplo, una sola caja minimalista en el centro de un fondo blanco plano con un botón gris). 
-
-El diseño debe ser profesional y generar impacto visual instantáneo. Sigue estas directrices:
-- **Estructura de Layout Completa**: Toda herramienta, calculadora o pantalla debe estar contenida en un layout profesional. Usa barras de navegación superiores (`Header`), paneles laterales colapsables (`Sidebar`), menús de usuario con avatares, y una barra de estado o pie de página.
-- **Grids de KPIs y Métricas**: Añade tarjetas estadísticas en la parte superior de la página para resumir datos clave (ej. número de cálculos realizados, tiempo de respuesta promedio, tasa de éxito) utilizando iconos, números destacados y pequeños indicadores porcentuales.
-- **Gráficos e Historiales**: Si hay tablas o historiales, hazlos interactivos. Usa bordes redondeados (`rounded-xl`), sombras suaves, efectos de hover en las filas y, de ser posible, integra gráficos modernos (ej. utilizando `@/components/ui/chart` o Recharts) para representar tendencias.
-- **Colores Semánticos y Gradientes**: Utiliza gradientes sutiles y la paleta de colores HSL/OKLCH del tema en lugar de colores puros. Asegúrate de que el botón de cambiar tema (Modo Claro/Oscuro) esté visible en la barra de navegación y funcione de manera impecable.
-- **Estados Dinámicos y Micro-animaciones**: Añade pequeños efectos de transición y hover (`transition-all duration-200`) en botones, inputs y tarjetas para que la interfaz se sienta "viva" y responda a las acciones del usuario.
+### 3.5 Reglas de Diseño y Estándares de Calidad (Consolidadas)
+* **Estándar Semántico**: Consulta y aplica estrictamente la **Sección 5 de `.opencode/rules/sdd-global.md`** para la prevención de colores fijos (hardcoded light/dark), sincronización de temas en gráficos Recharts, prevención de solapamientos del sidebar (Sidebar Overlap) y la regla de no anidamiento en triggers de Radix.
+* **Componentes de Calidad**: Toda interfaz debe estar pulida con skeletons de carga fluidos, empty states agradables con iconos ilustrativos, y tooltips descriptivos para cualquier botón basado únicamente en iconos.
 
 ---
 
 ## 4. Flujo de Trabajo en SDD
 
 ### Fase F1 (Spec-Driven Contract)
-El `@sdd-spec-writer` utiliza el MCP `shadcn` (`mcp__shadcn__search_items`, `mcp__shadcn__get_item`) para documentar en el contrato (`contract.json`) qué componentes y bloques se usarán para la UI y verificar sus APIs/propiedades expuestas.
+El `@sdd-spec-writer` utiliza de manera proactiva el MCP `shadcn` (`shadcn_search_items_in_registries`, `shadcn_list_items_in_registries`) para encontrar bloques. **Es obligatorio** usar la herramienta `shadcn_view_items_in_registries` para inspeccionar el contenido completo, la estructura de archivos y las dependencias del bloque seleccionado antes de cerrar el contrato. Esto le permite al Spec-Writer mapear con exactitud los archivos que se generarán en `files_affected` y documentar explícitamente cualquier potencial colisión de ruteo en el `contract.json`.
 
 ### Fase F2 (Implementation)
-El `@sdd-coder` utiliza el template base `nextjs-shadcn` y ejecuta `npx shadcn@latest add` para instalar los componentes requeridos para la interfaz. Implementa las vistas componiendo dichos bloques y vinculando el estado con el backend.
+El `@sdd-coder` utiliza el template base `nextjs-shadcn`. Si el contrato no detalla todos los sub-componentes o el Coder necesita verificar el comportamiento de un bloque antes de acoplarlo con el backend, debe ejecutar `shadcn_get_item_examples_from_registries` para ver ejemplos funcionales del componente real. Tras ejecutar la instalación con `npx shadcn@latest add`, el Coder debe contrastar los archivos inyectados con el mapa del contrato y limpiar de inmediato cualquier archivo redundante (como una página de inicio duplicada) que no coincida con el router oficial.
 
 ### Fase F3 (Verification)
 El `@sdd-tester` ejecuta las pruebas según el modo de verificación especificado en el contrato (`settings.verificationMode`):

package/.opencode/tools/brain.ts

@@ -75,7 +75,7 @@ const writeBrainFile = (filePath: string, title: string, sections: Record<string
 }
 
 export const save_memory = tool({
-  description: "Guarda un aprendizaje, decisión de diseño, ruta concreta, resolución de error o memoria del proyecto en el archivo .openspec/brain.md. Es acumulativo y añade una marca de tiempo.",
+  description: "Guarda una memoria o aprendizaje clave en .openspec/brain.md de forma acumulativa.",
   args: {
     category: tool.schema.string().describe("Categoría o sección donde clasificar la memoria (ej: 'design', 'learnings', 'routing', 'errors')"),
     content: tool.schema.string().describe("El contenido o aprendizaje exacto que se desea guardar. Se recomienda ser conciso y claro.")
@@ -115,7 +115,7 @@ export const save_memory = tool({
 })
 
 export const read_memory = tool({
-  description: "Recupera la memoria y los aprendizajes del proyecto del archivo .openspec/brain.md. Si se especifica una categoría, solo lee esa sección para optimizar tokens y contexto. Si no se especifica, lista las categorías disponibles.",
+  description: "Recupera la memoria y los aprendizajes del proyecto de .openspec/brain.md.",
   args: {
     category: tool.schema.string().optional().describe("La categoría específica a leer (ej: 'design', 'learnings', 'routing', 'errors'). Si no se provee, se listarán las categorías disponibles.")
   },

package/.opencode/tools/sdd_bootstrap.ts

@@ -101,7 +101,7 @@ function detectPythonPackageManager(root: string): "uv" | "pip" {
 
 // Tool: sdd_bootstrap_status
 export const bootstrap_status = tool({
-  description: "Reporta el estado de bootstrap del proyecto (qué plantilla se usó, cuándo, qué componentes shadcn están instalados, versión de Node y package manager). Si el proyecto no está bootstrapped, retorna NOT_BOOTSTRAPPED. Útil para que el coder verifique antes de empezar a codear.",
+  description: "Reporta el estado de bootstrap del proyecto.",
   args: {},
   async execute(args, context) {
     const root = getRoot(context)
@@ -143,7 +143,7 @@ export const bootstrap_status = tool({
 
 // Tool: sdd_bootstrap_nextjs_shadcn
 export const bootstrap_nextjs_shadcn = tool({
-  description: "Inicializa un proyecto Next.js 16 + Shadcn UI + Tailwind v4 + Vitest a partir de la plantilla canónica en .opencode/templates/nextjs-shadcn/. Es IDEMPOTENTE: si el proyecto ya está inicializado y no se pasa force=true, no toca nada. Copia archivo-por-archivo (sin pisar los existentes), mergea package.json, y opcionalmente instala dependencias y shadcn components.",
+  description: "Inicializa un proyecto Next.js 16 + Shadcn UI + Tailwind v4 + Vitest.",
   args: {
     targetDir: tool.schema.string().default(".").describe("Subdirectorio donde se inicializará el proyecto Next.js (ej: 'next-app' o '.')."),
     components: tool.schema.array(tool.schema.string()).default([]).describe("Lista de shadcn components a instalar (ej: ['button','input','table']). Vacío = no instalar shadcn components."),
@@ -353,7 +353,7 @@ export const bootstrap_nextjs_shadcn = tool({
 
 // Tool: sdd_bootstrap_fastapi
 export const bootstrap_fastapi = tool({
-  description: "Inicializa un proyecto FastAPI + Pydantic + Uvicorn + Pytest + Ruff a partir de la plantilla canónica en .opencode/templates/fastapi-sdd/. Es IDEMPOTENTE: si el proyecto ya está inicializado y no se pasa force=true, no toca nada. Copia archivo-por-archivo (sin pisar los existentes), opcionalmente instala dependencias con uv (fallback pip).",
+  description: "Inicializa un proyecto FastAPI + Pydantic + Uvicorn + Pytest + Ruff.",
   args: {
     targetDir: tool.schema.string().default(".").describe("Subdirectorio donde se inicializará el proyecto FastAPI (ej: 'backend' o '.')."),
     extras: tool.schema.array(tool.schema.string()).default([]).describe("Lista de paquetes Python adicionales a instalar (ej: ['sqlalchemy','pydantic-settings','pytest-asyncio']). Vacío = no instalar extras extra."),
@@ -543,7 +543,7 @@ export const bootstrap_fastapi = tool({
 
 // Tool: sdd_bootstrap_agnostic
 export const bootstrap_agnostic = tool({
-  description: "Inicializa un proyecto de tipo script, tooling o agnóstico de forma idempotente (crea un package.json básico, requirements.txt, o estructura plana de archivos según sea necesario). Evita la sobrecarga de frameworks pesados.",
+  description: "Inicializa un proyecto de tipo script, tooling o agnóstico de forma idempotente.",
   args: {
     language: tool.schema.enum(["javascript", "python", "bash", "google-apps-script", "plano"]).default("plano").describe("El lenguaje o entorno para inicializar"),
     install: tool.schema.boolean().default(true).describe("Si true, ejecuta npm init -y o uv init de forma básica si aplica.")

package/.opencode/tools/sdd_core.ts

@@ -248,7 +248,7 @@ const getPidFilePath = (root: string) => {
 
 // Tool: sdd_set_phase (file sdd_core.ts, export set_phase -> sdd_set_phase)
 export const set_phase = tool({
-  description: "Establece la fase activa del ciclo de desarrollo SDD (F0_DETECT, F1_CONTRACT, F2_IMPLEMENTATION, F3_VERIFICATION, F4_DEPLOYMENT). Si phase=F1_CONTRACT y se pasa spec_name, crea la carpeta del spec atómicamente y devuelve la ruta absoluta. Si phase=F3_VERIFICATION, ejecuta auto-lint (no bloqueante, solo informativo) y aborta si hay errores de lint.",
+  description: "Establece la fase activa del ciclo de desarrollo SDD.",
   args: {
     phase: tool.schema.enum(["F0_DETECT", "F1_CONTRACT", "F2_IMPLEMENTATION", "F3_VERIFICATION", "F4_DEPLOYMENT"]).describe("La fase a establecer"),
     activeContract: tool.schema.string().optional().describe("La ruta o nombre del archivo de contrato JSON activo (.openspec/specs/XXXX_TIMESTAMP_NAME/contract.json)"),
@@ -431,7 +431,7 @@ export const set_phase = tool({
 
 // Tool: sdd_get_state (file sdd_core.ts, export get_state -> sdd_get_state)
 export const get_state = tool({
-  description: "Obtiene el estado de desarrollo actual (fase activa, contrato seleccionado, stack validado)",
+  description: "Obtiene el estado de desarrollo actual.",
   args: {},
   async execute(args, context) {
     const filePath = getStateFilePath(context)
@@ -442,7 +442,7 @@ export const get_state = tool({
 
 // Tool: sdd_get_initial_session_data
 export const get_initial_session_data = tool({
-  description: "Obtiene atómicamente todos los datos de inicio de sesión: el estado actual del arnés, las memorias históricas clave del Brain ('learnings', 'design', 'routing'), y la lista curada de recomendaciones de diseño de Oh My Design. Reemplaza las llamadas secuenciales a sdd_get_state, brain_read_memory y sdd_list_design_recommendations.",
+  description: "Obtiene de forma atómica el estado actual, memorias del Brain y recomendaciones Oh My Design.",
   args: {},
   async execute(args, context) {
     const root = getRoot(context)
@@ -498,7 +498,7 @@ export const get_initial_session_data = tool({
 
 // Tool: sdd_save_active_brief
 export const save_active_brief = tool({
-  description: "Guarda un resumen breve y estructurado del spec o contrato activo en .openspec/active-brief.md para que sirva de anclaje de contexto de sistema (System State Anchoring) para el subagente sdd-coder o sdd-tester.",
+  description: "Guarda un resumen del spec activo en .openspec/active-brief.md como anclaje de contexto.",
   args: {
     brief: tool.schema.string().describe("Contenido en formato Markdown con el resumen del spec activo, componentes, diseño y dependencias.")
   },
@@ -558,7 +558,7 @@ export const save_active_brief = tool({
 
 // Tool: sdd_create_spec_folder (file sdd_core.ts, export create_spec_folder -> sdd_create_spec_folder)
 export const create_spec_folder = tool({
-  description: "Crea una nueva carpeta ordenada para la especificación del cambio (formato: yyyy-mm-dd__hh-mm-ss_nombre)",
+  description: "Crea una nueva carpeta ordenada para la especificación del cambio.",
   args: {
     name: tool.schema.string().describe("Nombre del cambio en minúsculas y separado por guiones (ej. sumar-endpoint)")
   },
@@ -593,7 +593,7 @@ export const create_spec_folder = tool({
 
 // Tool: sdd_validate_contract
 export const validate_contract = tool({
-  description: "Valida de forma estricta el archivo contract.json contra el contract-schema.json oficial para detectar errores de tipos, alucinaciones o campos faltantes antes de avanzar.",
+  description: "Valida contract.json contra el contract-schema.json oficial.",
   args: {
     contractPath: tool.schema.string().describe("Ruta relativa al contract.json (ej. '.openspec/specs/XXXX/contract.json')")
   },

package/.opencode/tools/sdd_design.ts

@@ -41,7 +41,7 @@ export const RECOMMENDED_BRANDS: Record<string, { id: string; name: string; cate
 
 // Tool: sdd_select_design
 export const select_design = tool({
-  description: "Copia fielmente el archivo DESIGN.md y sus ejemplos y recursos interactivos asociados desde el catálogo original de oh-my-design a la carpeta .openspec/ del proyecto.",
+  description: "Copia fielmente el archivo DESIGN.md y ejemplos de la marca a .openspec/",
   args: {
     brandId: tool.schema.string().describe("ID exacto del diseño en oh-my-design (ej: 'linear.app', 'vercel', 'stripe')")
   },
@@ -128,7 +128,7 @@ async function selectDesignHelper(brandId: string, context: any) {
 
 // Tool: sdd_list_design_recommendations
 export const list_design_recommendations = tool({
-  description: "Devuelve una lista curada y corta de marcas de diseño recomendadas (con assets HTML+CSS interactivos), filtrada por categoría de uso. Reemplaza 3-4 llamadas a oh-my-design_list_references en F0.",
+  description: "Devuelve una lista curada de marcas de diseño recomendadas.",
   args: {
     use_case: tool.schema.enum(["saas", "fintech", "ecommerce", "consumer", "all"]).default("all").describe("Categoría del proyecto para filtrar marcas relevantes"),
     max_per_category: tool.schema.number().default(3).describe("Máximo de marcas a devolver por categoría"),
@@ -162,7 +162,7 @@ export const list_design_recommendations = tool({
 
 // Tool: sdd_apply_brand_tokens
 export const apply_brand_tokens = tool({
-  description: "Inyecta tokens de diseño de marca (colores, tipografía, radius) en src/app/globals.css preservando las variables shadcn (--color-border, --color-background, etc.). Usar en F2 cuando se necesite aplicar el tema de marca.",
+  description: "Inyecta tokens de diseño de marca en src/app/globals.css.",
   args: {
     tokens: tool.schema.string().describe("JSON stringificado con {colors: {...}, typography: {...}, radius: {...}} extraído de contract.json design.tokens"),
   },
@@ -232,7 +232,7 @@ ${brandVarLines.join("\n")}
 
 // Tool: sdd_validate_lucide_icons_batch
 export const validate_lucide_icons_batch = tool({
-  description: "Valida un lote de nombres de iconos de Lucide React de forma rápida e idempotente. Si node_modules/lucide-react existe, verifica contra los exports reales; de lo contrario, valida contra un listado estático de los iconos más comunes.",
+  description: "Valida un lote de nombres de iconos de Lucide React de forma rápida.",
   args: {
     icons: tool.schema.array(tool.schema.string()).describe("Lista de nombres de iconos a validar (ej: ['Sun', 'Moon', 'Plus'])"),
   },

package/.opencode/tools/sdd_docker.ts

@@ -34,7 +34,7 @@ const getTargetDir = (root: string): string => {
 
 // Tool: sdd_clean_docker_environment
 export const clean_docker_environment = tool({
-  description: "Asegura que Docker esté abierto y realiza una limpieza total y agresiva: detiene y elimina TODOS los contenedores (activos o inactivos), remueve TODAS las imágenes, volúmenes y redes para garantizar un lienzo en blanco absoluto antes de desplegar.",
+  description: "Asegura que Docker esté abierto y realiza una limpieza total y agresiva.",
   args: {},
   async execute(args, context) {
     const results: Record<string, string> = {}
@@ -114,7 +114,7 @@ export const clean_docker_environment = tool({
 
 // Tool: sdd_generate_dockerfile
 export const generate_dockerfile = tool({
-  description: "Genera Dockerfile multi-stage, .dockerignore y docker-compose.yml optimizados a partir del stack del proyecto (nextjs|fastapi|agnostic). Detecta package manager desde package.json.",
+  description: "Genera Dockerfile, .dockerignore y docker-compose.yml optimizados para el stack.",
   args: {
     stack: tool.schema.enum(["nextjs", "fastapi", "agnostic"]).describe("Stack del proyecto"),
     port: tool.schema.number().default(3000).describe("Puerto de la aplicación"),

package/.opencode/tools/sdd_network.ts

@@ -39,7 +39,7 @@ const getPidFilePath = (root: string) => {
 
 // Tool: sdd_free_port
 export const free_port = tool({
-  description: "Busca y termina de manera forzada cualquier proceso que esté escuchando en un puerto específico",
+  description: "Libera un puerto específico de forma forzada.",
   args: {
     port: tool.schema.number().describe("El puerto a liberar (ej. 3000 o 8000)")
   },
@@ -69,7 +69,7 @@ export const free_port = tool({
 
 // Tool: sdd_start_server
 export const start_server = tool({
-  description: "Inicia un servidor de desarrollo o producción en segundo plano y registra su PID para limpieza posterior",
+  description: "Inicia un servidor en segundo plano y registra su PID.",
   args: {
     command: tool.schema.string().describe("Comando para iniciar el servidor (ej. 'yarn dev' o 'npm run dev')"),
     port: tool.schema.number().optional().default(3000).describe("Puerto esperado del servidor (default: 3000)"),
@@ -132,7 +132,7 @@ export const start_server = tool({
 
 // Tool: sdd_stop_server
 export const stop_server = tool({
-  description: "Detiene el servidor en segundo plano usando el PID registrado",
+  description: "Detiene el servidor en segundo plano registrado.",
   args: {},
   async execute(args, context) {
     const root = getRoot(context)

package/.opencode/tools/sdd_status.ts

@@ -10,7 +10,7 @@ const getRoot = (context: any) => {
 };
 
 export default tool({
-  description: "Obtiene de forma nativa y unificada el estado del ciclo SDD (.openspec/sdd_state.json) junto con un resumen de las categorías de memoria del cerebro (Brain). Evita llamadas lentas de consola y es multiplataforma.",
+  description: "Obtiene el estado unificado del ciclo SDD y un resumen de las categorías del Brain.",
   args: {},
   async execute(args, context) {
     const root = getRoot(context)

package/.opencode/tools/sdd_testing.ts

@@ -71,7 +71,7 @@ const parseSemanticErrors = (rawOutput: string, type: "eslint" | "tsc"): any[] =
 
 // Tool: sdd_quick_lint
 export const quick_lint = tool({
-  description: "Ejecuta el linter del proyecto (eslint) restringido a src/. Devuelve exit code y warnings. Usado como gate automático antes de transicionar a F3.",
+  description: "Ejecuta el linter del proyecto (eslint) restringido a src/.",
   args: {},
   async execute(args, context) {
     const root = getRoot(context)
@@ -140,7 +140,7 @@ export const quick_lint = tool({
 
 // Tool: sdd_shift_left_verify
 export const shift_left_verify = tool({
-  description: "Ejecuta validaciones estáticas Shift-Left completas en el proyecto: ejecuta el compilador de TypeScript (tsc) y el linter (eslint) de manera combinada. Limpia y parsea semánticamente los stack traces y logs de error crudos, devolviendo un JSON limpio y estructurado de errores que el LLM puede digerir y solucionar de inmediato sin perder atención.",
+  description: "Ejecuta validaciones estáticas Shift-Left completas (tsc + eslint) combinadas.",
   args: {},
   async execute(args, context) {
     const root = getRoot(context)
@@ -323,7 +323,7 @@ export const shift_left_verify = tool({
 
 // Tool: sdd_generate_tests
 export const generate_tests = tool({
-  description: "Autogenera plantillas de pruebas unitarias/integración en el directorio corporativo de pruebas a partir de los escenarios de prueba descritos en el contrato activo de sdd_state.json. No pisa archivos de pruebas existentes.",
+  description: "Autogenera plantillas de pruebas a partir de los escenarios del contrato activo.",
   args: {},
   async execute(args, context) {
     const root = getRoot(context)
@@ -442,7 +442,7 @@ export const generate_tests = tool({
 
 // Tool: sdd_save_playwright_artifacts
 export const save_playwright_artifacts = tool({
-  description: "Promueve y archiva los artefactos de captura visual/videos (.openspec/.playwright/) generados por Playwright a la carpeta del spec/contrato activo de forma ordenada, evitando ensuciar la raíz.",
+  description: "Promueve y archiva los artefactos de Playwright a la carpeta del contrato activo.",
   args: {
     callId: tool.schema.string().optional().describe("ID de llamada de Playwright MCP específica. Si no se pasa, toma la última ejecución de forma automática."),
     move: tool.schema.boolean().default(false).describe("Si true, mueve los archivos en lugar de copiarlos.")

package/.utils/export_opencode_session.py

@@ -9,7 +9,7 @@ DB_PATH = "/Users/wavesbyte/.local/share/opencode/opencode.db"
 
 # Escribe aquí el ID de la sesión que deseas exportar (ejemplo: "ses_1234...")
 # Si se deja vacío, el script requerirá el ID como argumento al ejecutarlo
-TARGET_SESSION_ID = "ses_11ca"
+TARGET_SESSION_ID = "ses_11a7"
 
 
 def format_timestamp(ts):

package/opencode.json

@@ -43,7 +43,7 @@
         "./.opencode/oh-my-design/packages/mcp/dist/index.mjs"
       ],
       "enabled": true,
-      "purpose": "MCP oficial de Oh My Design para buscar, consultar y aplicar temas de diseño (Toss, Stripe, Supabase, etc.)."
+      "purpose": "Busca, consulta y aplica temas de diseño (Toss, Stripe, Supabase, etc.)."
     },
     "shadcn": {
       "type": "local",
@@ -54,7 +54,7 @@
         "mcp"
       ],
       "enabled": true,
-      "purpose": "Librería UI objetivo. Usar para browse/search/install de componentes y blocks (dashboards, landings, auth, forms)."
+      "purpose": "Usa para browse/search/install de componentes y blocks oficiales de Shadcn UI."
     },
     "context7": {
       "type": "local",
@@ -76,7 +76,7 @@
         "--isolated"
       ],
       "enabled": true,
-      "purpose": "Playwright MCP. Artefactos (screenshots, traces, videos, downloads) van a .openspec/.playwright/<call-id>/. Para evidencia por sesión SDD, promueve los artefactos relevantes a .openspec/specs/<activeContract>/playwright/ con .opencode/tools/save-playwright-artifacts.sh. --isolated evita ensuciar el perfil del browser en disco."
+      "purpose": "Ejecuta pruebas de regresión visual y capturas de pantalla de Playwright."
     },
     "next-devtools": {
       "type": "local",
@@ -89,7 +89,7 @@
       "environment": {
         "NEXT_TELEMETRY_DISABLED": "1"
       },
-      "purpose": "Toolchain oficial Vercel para Next.js 16. Provee init, nextjs_docs, nextjs_index/nextjs_call (errores, logs, rutas, Server Actions en runtime), browser_eval, upgrade_nextjs_16 y enable_cache_components. Complementa context7 (docs genérico) con docs y runtime específicos de Next 16 (dev server expone /_next/mcp). Telemetría desactivada explícitamente. **DESHABILITADO por defecto** — solo activar on-demand cuando un subagente reporte un error específico de Next 16 que requiera docs oficiales. La razón: el tool `init` inyecta 1000+ palabras de 'FORGET ALL PRIOR KNOWLEDGE' en el contexto del coder (~8K tokens de reasoning desperdiciado en sesiones normales)."
+      "purpose": "Toolchain oficial para depurar Next.js 16 (deshabilitado por defecto)."
     },
     "lucide-icons": {
       "type": "local",
@@ -100,7 +100,7 @@
         "--stdio"
       ],
       "enabled": true,
-      "purpose": "Permite buscar, filtrar y obtener ejemplos de uso JSX de más de 1,500 iconos de Lucide React de forma exacta mediante herramientas del MCP."
+      "purpose": "Busca y obtiene ejemplos de uso de iconos de Lucide React."
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zugzbot",
-  "version": "1.0.39",
+  "version": "1.0.40",
   "description": "Fácil instalador del arnés SDD de Zugzbot para proyectos OpenCode",
   "type": "module",
   "bin": {