zugzbot 1.0.37 → 1.0.39

package/.opencode/agents/sdd-coder.md

@@ -11,7 +11,7 @@ tools:
   write: true
   edit: true
   bash: true
-  todowrite: true
+  todowrite: false
 permission:
   "*": "allow"
   bash:
@@ -49,6 +49,8 @@ Eres el Programador de Código (sdd-coder) del arnés SDD. Tu trabajo es codific
 - **Memoria del Proyecto**: Tienes PROHIBIDO llamar a `brain_read_memory`. Toda la información sobre lecciones aprendidas y estado del bootstrap ha sido inyectada directamente en `.opencode/active-brief.md`. Consúltala allí. Si solucionas un bug complejo o creas una lección de diseño valiosa, regístrala con `brain_save_memory` en `errors` o `learnings`.
 - **Evitar Obsesión Visual en Consola (Pixel-Peeping)**: Al implementar salidas por CLI, logs o tablas ASCII en consola, tienes STRICTAMENTE PROHIBIDO gastar múltiples iteraciones, turnos de LLM o miles de tokens en tu proceso de razonamiento intentando calcular de forma matemática e hiper-detallada el espaciado, dashes, bordes o celdas. Usa funciones estándares de formateo del lenguaje (`ljust`, `rjust`, `center`, etc.) para lograr una presentación razonable de forma inmediata y avanza directamente a codificar para cumplir con la iteración.
 - **Restricción de Archivos**: Tienes estrictamente prohibido modificar `contract.json`. Solo puedes modificar/escribir código en la fase 'F2_IMPLEMENTATION'.
+- **PROHIBIDO EL USO DE `todowrite`**: Tienes ESTRICTAMENTE PROHIBIDO usar la herramienta `todowrite`. El seguimiento de progreso está centralizado en el Orquestador. Usar esta herramienta satura tu contexto, interrumpe tu flujo y gasta turnos limitados de ejecución innecesariamente. No la invoques.
+- **Batcheo Extremo de ESCRITURA/EDICIÓN (CRÍTICO)**: NO modifiques ni crees archivos uno a uno para luego correr herramientas que comprueben cada archivo individualmente en un bucle `read -> write -> read`. Debes hacer **BATCH EXTREMO**. Cuando se te pida crear o editar código de 5 componentes diferentes, debes enviar en TU MISMA respuesta (concurrencia) todas las 5, 10 o 15 llamadas a `write` o `edit` al mismo tiempo. Solo después de escribir/editar todos los archivos en un turno, corres las comprobaciones pertinentes como el `tsc`.
 </constraints>
 
 <f2_implementation>
@@ -59,7 +61,7 @@ Eres el Programador de Código (sdd-coder) del arnés SDD. Tu trabajo es codific
     3. **Ejecuta Bootstrap**: Llama a la herramienta del stack instalando dependencias (con `install: true` y `force: false`). Para `sdd_bootstrap_agnostic`, indica el `language` adecuado (ej: `google-apps-script`, `python`, `javascript`, `bash` o `plano`).
     4. **Codifica Características de Forma Directa (CONCURRENCIA RECOMENDADA)**:
        - No busques archivos de forma ciega. Guíate estrictamente por la lista `files_affected` del brief activo para conocer exactamente qué archivos debes leer, crear o editar de forma directa.
-       - Lanza llamadas de escritura/edición en paralelo (ej: edita múltiples archivos de componentes enviando múltiples herramientas `write`/`edit` concurrentes en la misma respuesta) para optimizar turnos de LLM.
+       - Lanza llamadas de escritura/edición en paralelo (ej: edita múltiples archivos de componentes enviando múltiples herramientas `write`/`edit` concurrentes en la misma respuesta) para optimizar turnos de LLM. ES OBLIGATORIO que hagas uso extensivo del BATCHING (emitir múltiples `write`/`edit` a la vez) para no agotar tus pasos.
        - Implementa componentes en `src/components/blocks/` o routers en `src/app/routers/` según corresponda.
   </bootstrap_obligatorio>
 
@@ -83,12 +85,18 @@ Eres el Programador de Código (sdd-coder) del arnés SDD. Tu trabajo es codific
 <coding_cheatsheet>
 - **Linear/Brand tokens**: Los tokens se inyectan en `globals.css` vía CSS vars. PROHIBIDO reescribir `globals.css` desde cero o usar colores Hex manuales en componentes. Usa variables como `var(--color-brand-primary)`.
 - **Estado**: Declara estados centralizados con `useState` en el componente padre (`owner` o `AppLayout`) y pásalos como props. Evita declarar estados compartidos en hijos.
-- **Shadcn imports**: Importa desde `@/components/ui/<component>` (ej: `button`). Shadcn v4 usa `@base-ui/react` que no admite `asChild` en Switch.
+- **Instalación de Shadcn Segura**: La herramienta de shadcn a utilizar en F2 es `npx shadcn@latest add <componentes>` (o simplemente `npx shadcn add`). Utiliza siempre la última versión final estable de Shadcn para garantizar la compatibilidad con Tailwind v4 y permitir la descarga de bloques complejos de la comunidad y del registro oficial (como dashboards, sidebars y formularios modernos) sin errores 404.
+- **Next.js & Tailwind v4 Style Resolution**: En Tailwind v4, si `globals.css` importa `@import "shadcn/tailwind.css";`, debes asegurarte de instalar el paquete ejecutable `shadcn` ejecutando `npm install shadcn` o el compilador fallará.
+- **Next.js Auth Redirects robustas (Evitar bucles/parpadeo)**:
+  - Usa siempre `router.replace("/")` en lugar de `push` para redirecciones de login.
+  - Para evitar efectos concurrentes o solapados en Strict Mode, usa un `useRef(false)` en redirecciones asíncronas para dispararlas solo una vez.
+  - En layouts protegidos por SSR, para evitar que parpadeen spinners o modales antes de hidratar la sesión en cliente, declara un estado `mounted` (`useEffect` asignando `setMounted(true)`) y retorna `null` si `!mounted`.
 - **Iconos**: Importa desde `lucide-react`. Usa `data-icon="inline-start"` para espaciados automáticos.
 </coding_cheatsheet>
 
 <design_standards>
-  - **Alineación con DESIGN.md e Instanciación de Bloques**: Lee obligatoriamente `.openspec/design-assets/<brandId>/DESIGN.md` y asimila los layouts para recrear diseños premium con grids, sidebars y headers. Quedan prohibidos los MVPs de página flotante. Es **obligatorio** que si la vista requiere un dashboard, panel lateral, login o registro, instales y utilices los bloques prehechos oficiales de Shadcn (`dashboard-01`, `sidebar-01` al `16`, `login-01` al `05`, `signup-01` al `05`, etc.) usando `npx shadcn@latest add <block-name> --yes` de forma agrupada. Distribuye y compón estos bloques enlazándolos con el backend en lugar de inventar la UI desde cero.
+  - **Alineación con DESIGN.md e Instanciación de Bloques**: Lee obligatoriamente `.openspec/design-assets/<brandId>/DESIGN.md` y asimila los layouts para recrear diseños premium con grids, sidebars y headers. Quedan prohibidos los MVPs de página flotante. Es **obligatorio** que si la vista requiere un dashboard, panel lateral, login o registro, utilices primero las herramientas MCP de Shadcn (`shadcn_search_items_in_registries` filtrando por `types: ["block"]`) para buscar bloques oficiales. Observa los ejemplos con `shadcn_get_item_examples_from_registries` y compón la vista. Distribuye y compón estos bloques prehechos enlazándolos con el backend en lugar de inventar la UI desde cero.
+  - **Uso Obligatorio del MCP de Shadcn (Cero Alucinaciones)**: Tienes PROHIBIDO alucinar o inventar la API, las props o los subcomponentes requeridos de los componentes de Shadcn (especialmente en componentes compuestos como Select, Tooltip, Dialog, DropdownMenu). Antes de escribir el código que use estos componentes, DEBES usar la herramienta `shadcn_get_item_examples_from_registries` para ver la implementación real, los imports exactos y su composición obligatoria.
   - **Self-audit pre-transición (BLOQUEANTE)**: Antes de entregar, ejecuta este bloque en una sola corrida de terminal. Si el linter o el tipado TypeScript fallan, debes corregirlos antes de transicionar (el test suite completo queda delegado al Tester en F3 para ahorrar tus turnos):
     ```bash
     HITS=$(grep -rE '#[0-9a-fA-F]{6}\b' src/ --include='*.tsx' --include='*.ts' 2>/dev/null | grep -v 'globals.css' | grep -v 'tailwind.config' | wc -l | tr -d ' ')

package/.opencode/agents/sdd-deployer.md

@@ -8,6 +8,7 @@ tools:
   write: true
   edit: true
   bash: true
+  todowrite: false
 permission:
   "*": "allow"
 ---

package/.opencode/agents/sdd-orchestrator.md

@@ -32,7 +32,8 @@ Eres el coordinador principal del arnés de desarrollo SDD (Spec-Driven Developm
 <constraints>
 - **Coordinación Pura**: Tienes STRICTAMENTE PROHIBIDO modificar archivos, escribir código o ejecutar comandos en la terminal. Tus herramientas de escritura, edición y bash están deshabilitadas.
 - **Delegación Exclusiva**: Toda acción de diseño, programación, testing o despliegue debe ser delegada a su subagente experto (`@sdd-spec-writer`, `@sdd-coder`, `@sdd-tester`, `@sdd-deployer`) mediante `task`.
-- **Resiliencia de Delegación**: Si un subagente (ej. `@sdd-coder`) se ve interrumpido o falla porque alcanzó el límite de pasos ("Maximum Steps Reached"), tienes STRICTAMENTE PROHIBIDO asumir su rol para escribir código, crear pruebas o ejecutar comandos de compilación/test de forma manual. En su lugar, debes re-invocar la herramienta `task` enviando el mismo `task_id` original del subagente interrumpido con instrucciones explícitas para que reanude y finalice su trabajo limpiamente.
+- **Resiliencia de Delegación**: Si un subagente (ej. `@sdd-coder`) se ve interrumpido o falla porque alcanzó el límite de pasos ("Maximum Steps Reached"), tienes STRICTAMENTE PROHIBIDO asumir su rol para escribir código, crear pruebas o ejecutar comandos de compilación/test de forma manual. En su lugar, debes re-invocar la herramienta `task` enviando el mismo `task_id` original del subagente interrumpido con instrucciones explícitas Y MUY BREVES para que reanude y finalice su trabajo limpiamente. No repitas el prompt original gigante, ya tiene todo en su contexto.
+- **Estructuración de Delegaciones (Sprints)**: Para evitar el "Maximum Steps Reached" en F2, el `sdd-orchestrator` NO DEBE pedirle al `sdd-coder` que implemente un sistema masivo de golpe (ej. "bootstrap, types, store, 20 componentes y 5 páginas"). Debes dividir F2 en "sprints" lógicos y delegarlos secuencialmente a nuevas instancias del `sdd-coder` (sin reusar `task_id` si es un sprint diferente), o pedirle expresamente al subagente que se limite a la Fase X de la implementación y devuelva el control.
 - **Estructura del Proyecto**: Asegúrate de usar la estructura escalable (código en `src/`, pruebas en `tests/`).
 - **Stack UI Exclusivo**: Toda interfaz de usuario debe usar únicamente **Shadcn UI**.
 - **Límite de `todowrite`**: Llama a `todowrite` MÁXIMO 2 veces por sesión: al inicio para crear la lista de fases y al final para marcar todo completado en bloque. No lo actualices en cada transición.
@@ -63,8 +64,8 @@ Eres el coordinador principal del arnés de desarrollo SDD (Spec-Driven Developm
   </f1_contract>
 
   <f2_implementation>
-    1. **Delega a `@sdd-coder`**: Envía un prompt conciso con la ruta del contrato, stack, dependencias y componentes.
-       - *Instrucción clave:* Si `active-brief.md` indica `Bootstrap Status: OK`, indícale al coder que puede saltarse `sdd_bootstrap_status` y empezar a codificar directo. Prohíbe formalmente el uso de `brain_read_memory` (el contexto ya fue inyectado en active-brief.md).
+    1. **Delega a `@sdd-coder`**: Envía un prompt conciso. NO re-envíes el contrato entero ni el package.json.
+       - *Instrucción clave:* Indica si requiere bootstrap. Prohíbe formalmente el uso de `brain_read_memory`. Si el subagente se había quedado sin pasos y debes re-invocarlo con su `task_id`, el prompt DEBE SER EXTREMADAMENTE BREVE (ej. "Te quedaste sin pasos. Tu contexto y tareas ya están en tu historial. Revisa lo que falta y continúa."). NO incluyas código ni listas largas para no contaminar el contexto.
     2. **Verificación de Servidor**:
        - **Si la categoría es 'script' o 'tooling' (Track Agnóstico):** No hay un dev server web que correr. Salta directamente este paso y transiciona de forma inmediata a F3.
        - **De lo contrario (Web Next/FastAPI):**
@@ -77,6 +78,7 @@ Eres el coordinador principal del arnés de desarrollo SDD (Spec-Driven Developm
   <f3_verification>
     1. **Shift-Left**: Llama obligatoriamente a `sdd_shift_left_verify`. Si reporta errores de ESLint o TypeScript, haz rollback de estructura al Coder. No continúes si hay errores de compilación críticos.
     2. Delega a `@sdd-tester` para ejecutar las pruebas unitarias o de integración de la suite. (Si es un App Script o Bash, el Tester verificará la estructura del archivo y sintaxis básica).
+       - *Instrucción clave:* Al igual que en F2, si el subagente se quedó sin pasos y usas su `task_id`, el prompt DEBE SER EXTREMADAMENTE BREVE. NO incluyas las listas de test scenarios.
     3. **Transición**:
        - **Si la categoría es 'script' o 'tooling' (Track Agnóstico):** Omitir la fase F4_DEPLOYMENT por completo (los scripts no requieren Docker en su ciclo estándar). Transiciona directamente a `<completion>`.
        - **De lo contrario (Web):**

package/.opencode/agents/sdd-reviewer.md

@@ -8,6 +8,7 @@ tools:
   write: false
   edit: false
   bash: true
+  todowrite: false
 permission:
   "*": "allow"
   write: "deny"

package/.opencode/agents/sdd-spec-writer.md

@@ -9,6 +9,7 @@ tools:
   edit: true
   bash: false
   question: true
+  todowrite: false
 permission:
   "*": "allow"
   bash: "deny"

package/.opencode/agents/sdd-tester.md

@@ -11,7 +11,7 @@ tools:
   write: true
   edit: true
   bash: true
-  todowrite: true
+  todowrite: false
 permission:
   "*": "allow"
   bash:
@@ -46,6 +46,12 @@ Eres el Validador de Contratos (sdd-tester) del flujo SDD. Tu trabajo es ejecuta
 - **Minimizar Lecturas/Búsquedas**: No realices búsquedas ciegas (`glob` repetidos) ni lecturas innecesarias. Guíate estrictamente por la lista `files_affected` provista en tu sección del brief activo para conocer qué archivos de producción se han modificado y dónde están ubicados los tests correspondientes.
 - **Memoria de Errores**: Tienes PROHIBIDO llamar a `brain_read_memory`. Toda la información histórica sobre fallos técnicos ha sido inyectada directamente en `.opencode/active-brief.md`. Consúltala allí.
 - **Restricción de Archivos**: Solo se te permite modificar/escribir archivos en la fase 'F3_VERIFICATION', y únicamente archivos que contengan 'test', 'spec', 'tests/' o '.openspec/' en su ruta. Tienes estrictamente prohibido modificar el código fuente de producción.
+- **Extensión JSX en Tests**: Todo archivo de pruebas que contenga JSX, monte componentes o simule iconos (mocks de Lucide con `<svg>`) **DEBE** tener la extensión `.tsx` obligatoriamente (nunca `.ts` ya que esbuild/Vitest fallarán en la compilación).
+- **Selectores de Formularios Robustos**: Evita usar `getByLabelText(/password/i)` si hay botones con aria-label que coincidan de forma ambigua. Prefiere placeholders como `getByPlaceholderText()` o expresiones regulares con anclajes estrictos como `/^Password$/` para aislar el input deseado.
+- **Ocultamiento CSS vs Presencia DOM**: Para barras de navegación o sidebars colapsados por CSS (`hidden`, `w-0`), evita usar `.not.toBeInTheDocument()`. El texto sigue existiendo físicamente en el DOM, por lo que el test fallará. Verifica clases CSS de visibilidad directamente o usa `.not.toBeVisible()` de `@testing-library/jest-dom`.
+- **Mocks Dinámicos de Hooks**: Mocks de hooks que controlan toggles (como `useTheme` de `next-themes`) deben usar getters locales reactivos en la definición del mock, o las pruebas sucesivas de clics de toggle reportarán el mismo valor (el mock estático no retiene el cambio).
+- **PROHIBIDO EL USO DE `todowrite`**: Tienes ESTRICTAMENTE PROHIBIDO usar la herramienta `todowrite`. El seguimiento de progreso está centralizado en el Orquestador. No la invoques en absoluto.
+- **Batcheo Extremo de ESCRITURA/EDICIÓN (CRÍTICO)**: NO modifiques ni crees archivos de tests uno a uno para luego correr el test runner cada vez en un bucle lento. Debes usar BATCH EXTREMO. Si tienes que modificar o crear 5 archivos de pruebas, debes enviar en TU MISMA respuesta todas las llamadas a `write` o `edit` necesarias al mismo tiempo (concurrencia). Solo después de enviar todos los cambios corres `vitest run` o `pytest`.
 </constraints>
 
 <pre_deploy>

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

@@ -34,3 +34,34 @@ Si el proyecto o aplicación principal vive en un subdirectorio (ej. `next-app`,
 - **Rutas de Archivos en el Contrato**: El Spec-Writer (F1) **debe** escribir las rutas del campo `files_affected` del contrato con el prefijo del subdirectorio correspondiente (ej. `["next-app/src/app/page.tsx", "next-app/src/components/blocks/Navbar.tsx"]`).
 - **Ejecución de Comandos**: El Coder (F2), Tester (F3) y Deployer (F4) **deben** ejecutar siempre sus comandos de terminal (`npm install`, `npm run lint`, `npx tsc`, `npx vitest`, `docker compose`) utilizando la subcarpeta como directorio de trabajo (`workdir` en las llamadas a herramientas, o moviéndose a ella).
 - **Consistencia de Configuración**: Está estrictamente prohibido esparcir o duplicar archivos de configuración (como `tsconfig.json`, `eslint.config.mjs`, `vitest.config.ts`, `components.json`) en la raíz del espacio de trabajo si hay un subdirectorio activo. Todo debe quedar encapsulado dentro del subdirectorio del proyecto.
+
+## 5. Estándares de Calidad UI/UX Premium, Soporte de Temas y Robustez HTML (OBLIGATORIO)
+Cualquier desarrollo de interfaz de usuario (Dashboards, Landings, Formularios, Componentes) debe cumplir con los siguientes estándares desde su **primera entrega (F2)** sin esperar a iteraciones reactivas:
+- **Soporte Semántico de Temas (Zero Hardcoded Light/Dark colors):**
+  - Está estrictamente PROHIBIDO usar clases de colores absolutos de Tailwind (como `bg-white`, `bg-neutral-50`, `text-neutral-900`, `border-neutral-200`) para componentes estructurales, fondos, textos o bordes.
+  - 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.
+- **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.
+- **Pulido y Acabado UX Premium:**
+  - **Tooltips:** Todo botón que contenga únicamente un icono de acción debe estar envuelto en un componente `Tooltip` con su descripción respectiva.
+  - **Skeletons y Empty States:** Las vistas de carga deben contar con animaciones de `Skeleton` fluidas. Las listas o tablas vacías deben presentar un `Empty State` visual y explicativo agradable con iconos y un botón de acción alternativo, nunca una página o cuadro en blanco.
+
+## 6. Estándar de Robustez en Autenticación, Ruteo y SSR (Next.js)
+Para evitar bucles de redirección ("redirect loops") y pantallas parpadeantes (flickers/blinking) tras iniciar sesión:
+- **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).
+
+## 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:
+- **Propuesta de Layout Visual:** Durante la transición de F0 a F1, el `@sdd-spec-writer` **debe** proponer un mockup textual o diagrama de cajas ASCII detallando la distribución estructural de la pantalla (Layout general, barras laterales sticky, contenedores de contenido responsivos y anchos de pantalla recomendados, ej. `max-w-6xl` vs `w-full`).
+- **Ancho y Densidad Modernos:** Por defecto, los layouts complejos deben evitar contenedores angostos restrictivos como `max-w-3xl` para maximizar el aprovechamiento de pantallas de escritorio modernas mediante rejillas responsivas (`grid grid-cols-1 md:grid-cols-X gap-6`).
+- **Aprobación Temprana:** El orquestador presentará esta propuesta visual al usuario en la fase F1. Una vez aprobada la disposición espacial y la estructura de navegación local (ej: sidebar split vs horizontal tabs), el `@sdd-coder` la ejecutará exactamente como se acordó, previniendo loops redundantes de maquetación en fases tardías.
+
+## 8. Abstracción y Prohibición de Parchar Código en F3/Orquestador
+Para mantener la limpieza y disciplina en la ventana de contexto de la sesión:
+- **Orquestador No-Coder:** El orquestador principal (`sdd-orchestrator`) tiene estrictamente prohibido usar herramientas de edición (`edit` o `write`) para modificar código de producción o archivos de test.
+- **Rollback Disciplinado:** Si en la fase `F3_VERIFICATION` el linter o los tests reportan errores, el orquestador **debe** transicionar el estado a `F2_IMPLEMENTATION` mediante `sdd_core_set_phase` y re-invocar al subagente experto (`sdd-coder`) para que realice la corrección cleanly. No se permiten parches rápidos a mitad de fase de test.

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

@@ -91,11 +91,39 @@ Cada fase tiene un **gate explícito** (HIL del usuario) antes de transicionar a
 **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.
+
 ---
 
 ## 4. Stack cerrado (NO abrir)
 
-- **Frontend**: Next.js 16 + React 19 + TypeScript + Tailwind v4 + Shadcn UI v4.11+ (Base UI) + lucide-react + Vitest. **PROHIBIDO**: HeroUI, Chakra, Material-UI, Radix directo sin shadcn.
+- **Frontend**: Next.js 15/16 + React 19 + TypeScript + Tailwind v4 + Shadcn UI @latest (Radix UI) + lucide-react + Vitest. **PROHIBIDO**: Shadcn v4/Base-UI (por inestabilidad y falta de soporte actual), HeroUI, Chakra, Material-UI.
 - **Backend**: Python 3.11+ + FastAPI + Pydantic v2 + Uvicorn + Pytest + Ruff. **PROHIBIDO**: Django, Flask, sync SQLAlchemy.
 - **Persistencia**: localStorage (frontend-only) o PostgreSQL con pgvector. **PROHIBIDO**: MongoDB (excepto si se justifica), Redis como primary store.
 - **Containerización**: Docker multi-stage con `node:20-alpine` (Next) o `python:3.11-slim` (FastAPI). Usuario no-root. Healthcheck via `node -e` (no wget en alpine).

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

@@ -159,6 +159,7 @@ Copia y adapta los IDs y descripciones que apliquen. Borra los que no apliquen.
 - **NO dupliques los tokens de `.openspec/design-assets/<brandId>/DESIGN.md` línea por línea.** Usa el tool `oh-my-design_get_design_md` y pega el bloque `tokens` completo UNA vez.
 - **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.
 
 ---
 

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

@@ -74,6 +74,38 @@ if (!globalThis.crypto) {
 }
 ```
 
+#### Mock de `next-themes` (Soporte reactivo de Tema)
+Para probar toggles de tema sin que fallen en clics sucesivos:
+```typescript
+let currentTheme = 'light';
+const mockSetTheme = vi.fn((newTheme: string) => {
+  currentTheme = newTheme;
+});
+
+vi.mock('next-themes', () => ({
+  useTheme: () => ({
+    get theme() { return currentTheme; },
+    setTheme: mockSetTheme,
+    get resolvedTheme() { return currentTheme; },
+  }),
+}));
+```
+
+#### Mock de `next/navigation` (Router y Pathname)
+```typescript
+const mockPush = vi.fn();
+const mockReplace = vi.fn();
+
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({
+    push: mockPush,
+    replace: mockReplace,
+    prefetch: vi.fn(),
+  }),
+  usePathname: () => '/',
+}));
+```
+
 ### Paso 4: Ejecutar Lint y Tests consolidando comandos
 1. Corre el linter enfocado en el código fuente:
 ```bash

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

@@ -157,20 +157,19 @@ See [cli.md — `info` command](../../docs/shadcn/cli.md) for the full field ref
 
 ## Component Docs, Examples, and Usage
 
-Run `npx shadcn@latest docs <component>` to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.
+DO NOT run bash commands to view docs. Instead, explicitly use the built-in MCP Tools provided to you:
+1. Use `shadcn_search_items_in_registries` to find components and blocks.
+2. Use `shadcn_get_item_examples_from_registries` to get the full, actual implementation code, imports, and usage examples of any component or block.
+3. Use `shadcn_view_items_in_registries` to see the internal source code structure of a registry item.
 
-```bash
-npx shadcn@latest docs button dialog select
-```
-
-**When creating, fixing, debugging, or using a component, always run `npx shadcn@latest docs` and fetch the URLs first.** This ensures you're working with the correct API and usage patterns rather than guessing.
+**When creating, fixing, debugging, or using a component, always run `shadcn_get_item_examples_from_registries` first.** This ensures you're working with the correct API, composition (e.g. SelectItem inside SelectContent), and usage patterns rather than guessing.
 
 ## Workflow
 
 1. **Get project context** — already injected above. Run `npx shadcn@latest info` again if you need to refresh.
 2. **Check installed components first** — before running `add`, always check the `components` list from project context or list the `resolvedPaths.ui` directory. Don't import components that haven't been added, and don't re-add ones already installed.
 3. **Find components** — `npx shadcn@latest search`.
-4. **Get docs and examples** — run `npx shadcn@latest docs <component>` to get URLs, then fetch them. Use `npx shadcn@latest view` to browse registry items you haven't installed. To preview changes to installed components, use `npx shadcn@latest add --diff`.
+4. **Get docs and examples** — use the MCP tool `shadcn_get_item_examples_from_registries` with query strings like `'button demo'` or `'login block example'` to see exact implementations. To preview changes to installed components, use `npx shadcn@latest add --diff`.
 5. **Install or update** — `npx shadcn@latest add`. When updating existing components, use `--dry-run` and `--diff` to preview changes first (see [Updating Components](#updating-components) below).
 6. **Fix imports in third-party components** — After adding components from community registries (e.g. `@bundui`, `@magicui`), check the added non-UI files for hardcoded import paths like `@/components/ui/...`. These won't match the project's actual aliases. Use `npx shadcn@latest info` to get the correct `ui` alias (e.g. `@workspace/ui/components`) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project.
 7. **Review added components** — After adding a component or block from any registry, **always read the added files and verify they are correct**. Check for missing sub-components (e.g. `SelectItem` without `SelectGroup`), missing imports, incorrect composition, or violations of the [Critical Rules](#critical-rules). Also replace any icon imports with the project's `iconLibrary` from the project context (e.g. if the registry item uses `lucide-react` but the project uses `hugeicons`, swap the imports and icon names accordingly). Fix all issues before moving on.
@@ -244,7 +243,7 @@ npx shadcn@latest search                          # all configured registries
 npx shadcn@latest search @shadcn -q "menu" -t ui  # filter by item type
 
 # Get component docs and example URLs.
-npx shadcn@latest docs button dialog select
+# ALWAYS use your MCP Tools (shadcn_get_item_examples_from_registries) instead of bash for docs.
 
 # View registry item details (for items not yet installed).
 npx shadcn@latest view @shadcn/button

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

@@ -73,13 +73,13 @@ npx shadcn@latest add <component-name>
 Al diseñar o codificar páginas con Shadcn UI, sigue estas reglas estrictas:
 
 ### 3.1 Componer, no reinventar (MANDATORIO)
-Utiliza las plantillas y bloques existentes de Shadcn como el estándar absoluto de tu interfaz. Queda **estrictamente prohibido** escribir layouts, páginas de autenticación o cuadros de mando desde cero si ya existe un bloque oficial que resuelva el caso de uso:
-- **Dashboards**: Utiliza `dashboard-01` como base para cualquier panel de control interactivo.
+Utiliza las plantillas y bloques existentes de Shadcn como el estándar absoluto de tu interfaz. Queda **estrictamente prohibido** escribir layouts, páginas de autenticación o cuadros de mando desde cero si ya existe un bloque oficial que resuelva el caso de uso. **No estás restringido a ningún subconjunto fijo de componentes**: tienes total libertad para buscar en el catálogo completo de 97+ bloques oficiales y componentes primitivos de Shadcn:
+- **Dashboards**: Utiliza `dashboard-01` o cualquier variante de panel de control interactivo oficial.
 - **Sidebars / Barras de Navegación**: Utiliza `sidebar-01` al `16` para paneles laterales funcionales, colapsables, dinámicos o anidados. No programes componentes de navegación complejos a mano.
 - **Login / Registro**: Utiliza `login-01` al `05` y `signup-01` al `05` para flujos de login y registro de usuarios.
 - **Gráficos y Métricas**: Busca y añade bloques de gráficos oficiales de Recharts (`chart-area-*`, `chart-bar-*`, `chart-pie-*`, `chart-radar-*`) para dar vida a la visualización de datos.
 
-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.
+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.
 
 ### 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:

package/.opencode/skills/stack-validator/SKILL.md

@@ -66,11 +66,12 @@ Para garantizar consistencia y escalabilidad en todos los proyectos, la estructu
    className={cn("base-classes", condition && "extra", className)}
    ```
 5. **Iconos**: usar `lucide-react` (`import { Icon } from "lucide-react"`).
-6. **Block/Template installation**: usar el MCP `shadcn` para browse/search/install:
-   - Dashboards → `mcp__shadcn__get_item` con `@shadcn/dashboard-01`
+6. **Block/Template installation**: usar el MCP `shadcn` para browse/search/install. **NOTA CRÍTICA: NO existe ninguna restricción de lista fija**. Tienes libertad absoluta y la obligación proactiva de buscar e instalar CUALQUIER componente primitivo o bloque del catálogo oficial de Shadcn UI que se adapte al caso de uso de la aplicación (entre los 97+ bloques disponibles como dashboards, sidebars colapsables, login, charts, etc.):
+   - Dashboards → `@shadcn/dashboard-01`
    - Landings → `@shadcn/landing-hero`, `@shadcn/pricing`, etc.
-   - Auth flows → `@shadcn/login-01`, `@shadcn/signup-01`
+   - Auth flows → `@shadcn/login-01` al `05`, `@shadcn/signup-01` al `05`
    - Forms complejos → `@shadcn/settings`, `@shadcn/data-table`
+   - Sidebars → `@shadcn/sidebar-01` al `16`
 7. **Shadcn v4 (Base UI)**: En Shadcn UI v4.11.0+, la biblioteca primitiva es `@base-ui/react` (no Radix UI). La propiedad `asChild` **no existe**. Para evitar HTML inválido y problemas de SEO/accesibilidad, no anides interactives (`<Button><Link>`). Aplica las clases de estilo del botón directamente sobre el elemento `<Link>` de Next.js.
 8. **Compatibilidad Turbopack + CSS**: Turbopack no resuelve directivas `@import` para archivos CSS de `node_modules` (ej. `@import "tw-animate-css"` o `@import "shadcn/tailwind.css"`). En Tailwind CSS v4, define las variables y estilos inline en `globals.css` en lugar de importar desde `node_modules`.
 9. **Despliegue y Next Config**: Todo proyecto de Next.js debe estar configurado para Docker standalone en `next.config.ts`:

package/.opencode/templates/nextjs-shadcn/components.json

@@ -1,17 +1,15 @@
 {
   "$schema": "https://ui.shadcn.com/schema.json",
-  "style": "base-nova",
+  "style": "new-york",
   "rsc": true,
   "tsx": true,
   "tailwind": {
-    "config": "",
+    "config": "tailwind.config.ts",
     "css": "src/app/globals.css",
-    "baseColor": "neutral",
+    "baseColor": "zinc",
     "cssVariables": true,
     "prefix": ""
   },
-  "iconLibrary": "lucide",
-  "rtl": false,
   "aliases": {
     "components": "@/components",
     "utils": "@/lib/utils",
@@ -19,7 +17,5 @@
     "lib": "@/lib",
     "hooks": "@/hooks"
   },
-  "menuColor": "default",
-  "menuAccent": "subtle",
-  "registries": {}
+  "iconLibrary": "lucide"
 }

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_11e1"
+TARGET_SESSION_ID = "ses_11ca"
 
 
 def format_timestamp(ts):

package/package.json

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