zugzbot 1.0.39 → 1.0.41

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

@@ -3,7 +3,7 @@ description: Implementa código ajustándose estrictamente a los contratos en sp
 mode: subagent
 hidden: true
 steps: 10
-model: deepseek/deepseek-v4-flash
+model: google/gemini-3.5-flash
 temperature: 0.35
 frequency_penalty: 0.5
 presence_penalty: 0.2

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

@@ -2,7 +2,7 @@
 description: Limpia Docker y realiza el despliegue local del sistema
 mode: subagent
 hidden: true
-model: deepseek/deepseek-v4-flash
+model: google/gemini-3.5-flash
 temperature: 0.1
 tools:
   write: true

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

@@ -1,7 +1,7 @@
 ---
 description: Coordinador principal del flujo SDD y del stack cerrado
 mode: primary
-model: deepseek/deepseek-v4-flash
+model: google/gemini-3.5-flash
 temperature: 0.1
 tools:
   write: false

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

@@ -2,7 +2,7 @@
 description: Realiza una auditoría/revisión de código contra el contrato y el linter
 mode: subagent
 hidden: false
-model: deepseek/deepseek-v4-flash
+model: google/gemini-3.5-flash
 temperature: 0.1
 tools:
   write: false

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

@@ -2,7 +2,7 @@
 description: Redacta y valida contratos OpenAPI e interfaces en specs/
 mode: subagent
 hidden: true
-model: deepseek/deepseek-v4-flash
+model: google/gemini-3.5-flash
 temperature: 0.1
 tools:
   write: true

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

@@ -3,7 +3,7 @@ description: Diseña y corre pruebas unitarias, integración y visuales (Playwri
 mode: subagent
 hidden: true
 steps: 15
-model: deepseek/deepseek-v4-flash
+model: google/gemini-3.5-flash
 temperature: 0.35
 frequency_penalty: 0.5
 presence_penalty: 0.2

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

@@ -22,11 +22,13 @@ Cuando el estado del sistema tiene `loopMode === true` (activado mediante el com
 - **Specs Incrementales**: Si la petición es grande, el orquestador debe dividirla secuencialmente en contratos incrementales. Completa un spec por completo (F0->F4) y arranca el siguiente de inmediato de forma autónoma hasta finalizar todo el plan.
 - **Rollback de Emergencia**: Si una misma fase falla de forma continua (más de 2 rollbacks), desactiva `loopMode` usando `sdd_set_phase` y solicita asistencia humana en el chat.
 
-## 3. Uso Mandatorio de Bloques Prehechos de Shadcn UI (dashboard, sidebar, login, etc.)
+## 3. Uso Mandatorio de Bloques Prehechos de Shadcn UI - Estrategia "Block-First" (MANDATORIO)
 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.
+- **Inyección Zero-Touch y Migración Física en Fase A**: El Coder (F2) **debe** instalar el bloque usando `npx shadcn@latest add <block-name>`. Los archivos se descargarán en `src/components/blocks/<block-name>/`. Queda **estrictamente prohibido** importar el `page.tsx` del bloque como un simple componente hijo (ej: `return <BlockPage />` desde la raíz de la app), ya que esto rompe el router, layouts y metadata de Next.js. El Coder debe **copiar íntegramente el contenido del código** de `src/components/blocks/<block-name>/page.tsx` hacia el `page.tsx` de la ruta destino, y **reescribir todos los imports relativos** de componentes y datos locales (ej. `./components/...` o `./data.json`) para usar aliases absolutos que apunten a la ruta física descargada por Shadcn (ej. `@/components/blocks/<block-name>/components/...` o `@/components/blocks/<block-name>/data.json`). El archivo de datos locales `data.json` debe preservarse e importarse para garantizar un renderizado visual clonado perfecto.
+- **Sustitución Atómica de Datos en Fase B**: Una vez que el bloque compila e interactúa en el navegador de manera idéntica al demo con los datos de ejemplo, el Coder procederá de forma exclusiva a sustituir los datos mock por lógica y fetchings de datos dinámicos del backend, manteniendo intactos los contenedores estructurales del bloque (grids de diseño, paddings y contenedores flex) sin alteración alguna para evitar aberraciones visuales.
+- **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 +44,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 +59,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

@@ -72,14 +72,34 @@ 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. **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.
+### 3.1 Componer, no reinventar - Estrategia "Block-First" con Inyección Zero-Touch (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.
 
-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.
+Para garantizar interfaces de usuario premium y visualmente idénticas a los demos oficiales de Shadcn, se debe seguir de manera mandatoria la **Metodología de Arquitectura Block-First**:
+
+1. **El Bloque es el Esqueleto Absoluto (Fase A - Inyección Pura y Migración Física)**:
+   - El Coder (F2) **debe** instalar el bloque de Shadcn correspondiente mediante la CLI (`npx shadcn@latest add <block-name>`).
+   - El bloque se descargará en `src/components/blocks/<block-name>/`. El Coder tiene **estrictamente prohibido** importar el `page.tsx` del bloque como un simple componente hijo (ej: `return <BlockPage />` desde la raíz de la app), ya que esto rompe la estructura del router de Next.js, layouts y metadata.
+   - **Acción Obligatoria**: El Coder debe **copiar el contenido íntegro del código** de `src/components/blocks/<block-name>/page.tsx` hacia el `page.tsx` de tu ruta destino (por ejemplo, `src/app/page.tsx` o `src/app/dashboard/page.tsx`).
+   - **Corrección de Imports de forma Manual**: Al mover el código de la ruta de componentes al App Router de Next.js, los imports relativos en ese archivo se romperán. El Coder tiene la obligación de **reescribir todos los imports relativos de componentes e información locales** (ej. `./components/app-sidebar` o `./data.json`) para usar aliases absolutos que apunten a la ubicación física descargada por Shadcn (ej. `@/components/blocks/<block-name>/components/app-sidebar` o `@/components/blocks/<block-name>/data.json`).
+   - **Preservación de Datos Mock/Dummy**: El archivo de datos del bloque (por ejemplo, `data.json` o constantes internas) **debe ser preservado e importado de manera intacta** durante esta Fase A para garantizar que la vista renderice con datos idénticos al demo original en el navegador.
+   - **Meta**: Al terminar la Fase A, la aplicación debe renderizarse de manera *pixel-perfect* (idéntica) al demo oficial de Shadcn en local, sin un solo error de compilación o de imports rotos.
+
+2. **Sustitución de Datos Atómica (Fase B - Conexión de Lógica)**:
+   - Una vez comprobado que el esqueleto visual se muestra perfecto y sin aberraciones de flexbox o alineación, el Coder procederá a sustituir de manera quirúrgica y atómica los datos dummy o locales por la lógica de negocio real (estados de React, fetchings de API del backend).
+   - El Coder **no debe modificar las clases contenedoras estructurales** (`SidebarProvider`, `SidebarInset`, grids de diseño principales, anchos o paddings del bloque) para evitar corrupciones visuales en pantallas grandes o pequeñas.
+
+3. **Prevención de Parpadeos (Flicker) de Sidebar y Providers**:
+   - Si el bloque utiliza providers globales como `<SidebarProvider>`, el Coder debe extraer la barra lateral (`AppSidebar`) y sus providers principales hacia `src/app/layout.tsx` (o un layout del Route Group respectivo) en lugar de dejarlos redundantes en el `page.tsx` de cada ruta, permitiendo un ruteo libre de parpadeos desagradables y garantizando consistencia.
+
+4. **Catálogo de Bloques a Explorar**:
+   - **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.
+
+**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:
@@ -109,25 +129,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"),