@saulwade/swl-ses 2.3.0 → 2.4.1

package/reglas/usar-context7.md

@@ -1,226 +1,226 @@
-# Regla: Consultar Context7 antes de generar código con dependencias externas
-
-Esta regla es OBLIGATORIA para todo agente o skill del sistema SWL que
-genere código que use librerías, frameworks, SDKs o APIs externas. La regla
-se carga automáticamente para los agentes de stack (`backend-*-swl`,
-`frontend-*-swl`, `mobile-*-swl`, `implementador-swl`, `llm-apps-swl`,
-`pagos-swl`, `datos-swl`) y para skills de implementación.
-
----
-
-## Por qué existe esta regla
-
-El conocimiento del modelo sobre librerías de terceros tiene fecha de
-corte. Una librería que en el corte estaba en la versión X y era la
-recomendación, hoy puede estar:
-
-- En una versión Y mayor con cambios incompatibles
-- Deprecada y reemplazada por otra librería
-- Con vulnerabilidades conocidas que requieren un parche
-- Renombrada o migrada a otra organización
-
-Generar código sin verificar la versión actual genera tres clases de
-defectos en producción:
-
-1. **Imports a APIs deprecadas** que arrastran warnings o se eliminan
-   en próximas versiones (ejemplo histórico: `@xenova/transformers`
-   migrado a `@huggingface/transformers`).
-2. **Dependencias transitivas obsoletas** que el usuario ve como
-   warnings al instalar (ejemplo: `prebuild-install@7.1.3` arrastrada
-   por una librería que el sistema eligió sin verificar la salud).
-3. **Vulnerabilidades CVE conocidas** que están parchadas en versiones
-   más nuevas que el modelo no conoce.
-
-Context7 (MCP `mcp__claude_ai_Context7__query-docs` y
-`mcp__claude_ai_Context7__resolve-library-id`) provee documentación
-actualizada de librerías y frameworks. Su uso es la primera línea de
-defensa contra estos tres problemas.
-
----
-
-## Cuándo consultar Context7 (OBLIGATORIO)
-
-Antes de:
-
-1. **Agregar una nueva dependencia** a `package.json`, `requirements.txt`,
-   `pom.xml`, `Cargo.toml`, `go.mod`, `composer.json`, `Package.swift` o
-   equivalente.
-2. **Generar código que importe o use una librería externa** que no
-   estaba ya en uso en el proyecto, aunque la librería ya esté
-   instalada.
-3. **Actualizar la versión** de una dependencia existente.
-4. **Migrar de una librería a otra** alternativa (ej.
-   `axios` → `fetch`, `moment` → `date-fns`, `jest` → `vitest`).
-5. **Resolver un warning de deprecación** de una dependencia
-   transitiva.
-6. **Implementar un patrón nuevo** del framework (ej. Server Actions
-   en Next.js, Signals en Angular, Suspense en React) — la API
-   correcta cambia rápido.
-
-NO es necesario consultar Context7 cuando:
-
-- La librería es interna al proyecto SWL (`scripts/lib/*`,
-  `hooks/lib/*`).
-- Es la biblioteca estándar del lenguaje (Node `fs`, Python `os`).
-- Es código que no usa dependencias externas (algoritmos, lógica de
-  negocio sin librerías de terceros).
-- El cambio es trivial (renombrar variable, formatear).
-
----
-
-## Cómo consultar Context7
-
-El MCP de Context7 expone dos herramientas principales:
-
-```
-mcp__claude_ai_Context7__resolve-library-id(libraryName)
-  → Resuelve un nombre de librería (ej. "react", "next.js") al ID
-    canónico que Context7 usa internamente.
-
-mcp__claude_ai_Context7__query-docs(library, topic, version?)
-  → Devuelve documentación actualizada de la librería sobre el
-    topic específico. Acepta versión opcional.
-```
-
-Flujo típico:
-
-1. Resolver el ID de la librería:
-   ```
-   const id = mcp__claude_ai_Context7__resolve-library-id({
-     libraryName: "next.js"
-   });
-   ```
-
-2. Consultar el tema específico:
-   ```
-   const docs = mcp__claude_ai_Context7__query-docs({
-     library: id,
-     topic: "Server Actions",
-     version: "16"
-   });
-   ```
-
-3. Verificar:
-   - ¿La librería sigue siendo la recomendada o está deprecada?
-   - ¿Hay una alternativa migrada que deberíamos usar?
-   - ¿La API que voy a generar es la actual o cambió?
-   - ¿La versión que recomienda Context7 coincide con la del
-     `package.json` del proyecto?
-
----
-
-## Reglas estrictas
-
-### NUNCA agregar dependencia sin verificar
-
-Antes de escribir `npm install <paquete>`, `pip install <paquete>`,
-`go get <paquete>` o equivalente:
-
-- Consultar Context7 para confirmar que la librería sigue activa.
-- Confirmar la versión más reciente compatible con el resto del
-  stack del proyecto.
-- Si Context7 reporta deprecación, **NO la uses**. Buscar la
-  alternativa migrada.
-
-### NUNCA generar código con API obsoleta
-
-Si el usuario pide implementar X usando librería Y:
-
-- Consultar Context7 sobre cómo se hace X en la versión actual de Y.
-- Si la API que aparece en el contexto del modelo difiere de la que
-  Context7 reporta como actual, **usar la de Context7**.
-- Documentar en un comentario corto la versión consultada y la
-  fecha si la API es notable.
-
-### NUNCA copiar ejemplos de la web sin verificar versión
-
-Stack Overflow, blogs y tutoriales tienen alta probabilidad de
-mostrar código deprecado. Si el agente consulta una web (vía
-WebSearch o WebFetch) y obtiene un ejemplo, ese ejemplo debe
-validarse contra Context7 antes de incorporarlo.
-
----
-
-## Excepción: Context7 no responde o no tiene la librería
-
-Si Context7 no tiene documentación disponible para una librería
-específica:
-
-1. **Documentar en el código** que Context7 no respondió y la API se
-   tomó de la fuente oficial (npm registry, docs del repo).
-2. **Verificar al menos**: la librería existe, no está deprecada en
-   npm/PyPI, su última publicación es reciente (≤ 12 meses).
-3. **NO bloquear** el flujo del usuario por este caso — proceder con
-   diligencia razonable.
-
----
-
-## Auditoría retroactiva
-
-Esta regla aplica también al código existente del proyecto SWL:
-
-- Si durante un refactor se detecta una dependencia que arrastra
-  warnings de deprecación, abrir un ticket para auditarla con
-  Context7 y migrar si hay alternativa actual.
-- El comando `/swl:auditar-deps` (cuando esté disponible) debe
-  cruzar las dependencias del proyecto contra Context7 para
-  detectar deprecaciones silenciosas.
-
----
-
-## Aplicabilidad por agente
-
-| Agente | Aplica | Cuándo |
-|---|---|---|
-| `backend-python-swl` | SÍ | Al generar código FastAPI/Django/SQLAlchemy |
-| `backend-node-swl` | SÍ | Al generar código Express/Fastify/NestJS |
-| `backend-java-swl` | SÍ | Al generar código Spring Boot/JPA |
-| `backend-go-swl` | SÍ | Al generar código Go con frameworks |
-| `backend-rust-swl` | SÍ | Al generar código Axum/Actix |
-| `backend-csharp-swl` | SÍ | Al generar código ASP.NET Core |
-| `frontend-react-swl` | SÍ | Al generar código React/Next.js |
-| `frontend-angular-swl` | SÍ | Al generar código Angular |
-| `frontend-css-swl` | SÍ | Al usar PostCSS/Tailwind plugins |
-| `frontend-tailwind-swl` | SÍ | Al usar Tailwind v4+ APIs |
-| `frontend-swl` | SÍ | Al usar Vue/Svelte/Lit |
-| `mobile-android-swl` | SÍ | Al usar Jetpack Compose libs |
-| `mobile-ios-swl` | SÍ | Al usar SwiftUI/Combine |
-| `mobile-cross-swl` | SÍ | Al usar React Native/Flutter |
-| `implementador-swl` | SÍ | Generalista — siempre |
-| `llm-apps-swl` | SÍ | LangChain, OpenAI SDK, Anthropic SDK |
-| `pagos-swl` | SÍ | Stripe SDK actualizado |
-| `datos-swl` | SÍ | ORMs y drivers de BD |
-| `arquitecto-swl` | RECOMENDADO | Al evaluar tradeoffs entre librerías |
-| `revisor-codigo-swl` | RECOMENDADO | Al detectar deps deprecadas en review |
-| `revisor-seguridad-swl` | OBLIGATORIO | Al verificar CVEs de dependencias |
-| Resto de agentes | NO | No generan código con dependencias externas |
-
----
-
-## Checklist de consulta Context7
-
-Antes de marcar una tarea como completa:
-
-- [ ] ¿Las dependencias agregadas/usadas se verificaron contra Context7?
-- [ ] ¿La versión usada está alineada con la que Context7 reporta como actual?
-- [ ] ¿No hay imports de APIs deprecadas según Context7?
-- [ ] ¿Las dependencias transitivas conocidas no son warnings de
-      deprecación al instalar?
-- [ ] Si Context7 no tenía la librería, ¿se documentó el motivo?
-
----
-
-## Origen de esta regla
-
-Esta regla se formalizó tras observar en la primera instalación pública
-de `@saulwade/swl-ses@1.0.0` (2026-04-30) un warning de
-`prebuild-install@7.1.3 deprecated` arrastrado por
-`@xenova/transformers` que estaba en `optionalDependencies`. La
-dependencia se eligió en una iteración anterior sin verificar Context7;
-la migración oficial era `@huggingface/transformers`. El warning se vio
-en cada `npm install` del paquete distribuido. Resuelto en v1.0.1
-eliminando la dependencia opcional y elevando esta regla a obligatoria
-para que no se repita.
-
-Memoria asociada: `feedback_usar_context7.md` (preferencia previa del
-usuario, formalizada como regla).
+# Regla: Consultar Context7 antes de generar código con dependencias externas
+
+Esta regla es OBLIGATORIA para todo agente o skill del sistema SWL que
+genere código que use librerías, frameworks, SDKs o APIs externas. La regla
+se carga automáticamente para los agentes de stack (`backend-*-swl`,
+`frontend-*-swl`, `mobile-*-swl`, `implementador-swl`, `llm-apps-swl`,
+`pagos-swl`, `datos-swl`) y para skills de implementación.
+
+---
+
+## Por qué existe esta regla
+
+El conocimiento del modelo sobre librerías de terceros tiene fecha de
+corte. Una librería que en el corte estaba en la versión X y era la
+recomendación, hoy puede estar:
+
+- En una versión Y mayor con cambios incompatibles
+- Deprecada y reemplazada por otra librería
+- Con vulnerabilidades conocidas que requieren un parche
+- Renombrada o migrada a otra organización
+
+Generar código sin verificar la versión actual genera tres clases de
+defectos en producción:
+
+1. **Imports a APIs deprecadas** que arrastran warnings o se eliminan
+   en próximas versiones (ejemplo histórico: `@xenova/transformers`
+   migrado a `@huggingface/transformers`).
+2. **Dependencias transitivas obsoletas** que el usuario ve como
+   warnings al instalar (ejemplo: `prebuild-install@7.1.3` arrastrada
+   por una librería que el sistema eligió sin verificar la salud).
+3. **Vulnerabilidades CVE conocidas** que están parchadas en versiones
+   más nuevas que el modelo no conoce.
+
+Context7 (MCP `mcp__claude_ai_Context7__query-docs` y
+`mcp__claude_ai_Context7__resolve-library-id`) provee documentación
+actualizada de librerías y frameworks. Su uso es la primera línea de
+defensa contra estos tres problemas.
+
+---
+
+## Cuándo consultar Context7 (OBLIGATORIO)
+
+Antes de:
+
+1. **Agregar una nueva dependencia** a `package.json`, `requirements.txt`,
+   `pom.xml`, `Cargo.toml`, `go.mod`, `composer.json`, `Package.swift` o
+   equivalente.
+2. **Generar código que importe o use una librería externa** que no
+   estaba ya en uso en el proyecto, aunque la librería ya esté
+   instalada.
+3. **Actualizar la versión** de una dependencia existente.
+4. **Migrar de una librería a otra** alternativa (ej.
+   `axios` → `fetch`, `moment` → `date-fns`, `jest` → `vitest`).
+5. **Resolver un warning de deprecación** de una dependencia
+   transitiva.
+6. **Implementar un patrón nuevo** del framework (ej. Server Actions
+   en Next.js, Signals en Angular, Suspense en React) — la API
+   correcta cambia rápido.
+
+NO es necesario consultar Context7 cuando:
+
+- La librería es interna al proyecto SWL (`scripts/lib/*`,
+  `hooks/lib/*`).
+- Es la biblioteca estándar del lenguaje (Node `fs`, Python `os`).
+- Es código que no usa dependencias externas (algoritmos, lógica de
+  negocio sin librerías de terceros).
+- El cambio es trivial (renombrar variable, formatear).
+
+---
+
+## Cómo consultar Context7
+
+El MCP de Context7 expone dos herramientas principales:
+
+```
+mcp__claude_ai_Context7__resolve-library-id(libraryName)
+  → Resuelve un nombre de librería (ej. "react", "next.js") al ID
+    canónico que Context7 usa internamente.
+
+mcp__claude_ai_Context7__query-docs(library, topic, version?)
+  → Devuelve documentación actualizada de la librería sobre el
+    topic específico. Acepta versión opcional.
+```
+
+Flujo típico:
+
+1. Resolver el ID de la librería:
+   ```
+   const id = mcp__claude_ai_Context7__resolve-library-id({
+     libraryName: "next.js"
+   });
+   ```
+
+2. Consultar el tema específico:
+   ```
+   const docs = mcp__claude_ai_Context7__query-docs({
+     library: id,
+     topic: "Server Actions",
+     version: "16"
+   });
+   ```
+
+3. Verificar:
+   - ¿La librería sigue siendo la recomendada o está deprecada?
+   - ¿Hay una alternativa migrada que deberíamos usar?
+   - ¿La API que voy a generar es la actual o cambió?
+   - ¿La versión que recomienda Context7 coincide con la del
+     `package.json` del proyecto?
+
+---
+
+## Reglas estrictas
+
+### NUNCA agregar dependencia sin verificar
+
+Antes de escribir `npm install <paquete>`, `pip install <paquete>`,
+`go get <paquete>` o equivalente:
+
+- Consultar Context7 para confirmar que la librería sigue activa.
+- Confirmar la versión más reciente compatible con el resto del
+  stack del proyecto.
+- Si Context7 reporta deprecación, **NO la uses**. Buscar la
+  alternativa migrada.
+
+### NUNCA generar código con API obsoleta
+
+Si el usuario pide implementar X usando librería Y:
+
+- Consultar Context7 sobre cómo se hace X en la versión actual de Y.
+- Si la API que aparece en el contexto del modelo difiere de la que
+  Context7 reporta como actual, **usar la de Context7**.
+- Documentar en un comentario corto la versión consultada y la
+  fecha si la API es notable.
+
+### NUNCA copiar ejemplos de la web sin verificar versión
+
+Stack Overflow, blogs y tutoriales tienen alta probabilidad de
+mostrar código deprecado. Si el agente consulta una web (vía
+WebSearch o WebFetch) y obtiene un ejemplo, ese ejemplo debe
+validarse contra Context7 antes de incorporarlo.
+
+---
+
+## Excepción: Context7 no responde o no tiene la librería
+
+Si Context7 no tiene documentación disponible para una librería
+específica:
+
+1. **Documentar en el código** que Context7 no respondió y la API se
+   tomó de la fuente oficial (npm registry, docs del repo).
+2. **Verificar al menos**: la librería existe, no está deprecada en
+   npm/PyPI, su última publicación es reciente (≤ 12 meses).
+3. **NO bloquear** el flujo del usuario por este caso — proceder con
+   diligencia razonable.
+
+---
+
+## Auditoría retroactiva
+
+Esta regla aplica también al código existente del proyecto SWL:
+
+- Si durante un refactor se detecta una dependencia que arrastra
+  warnings de deprecación, abrir un ticket para auditarla con
+  Context7 y migrar si hay alternativa actual.
+- El comando `/swl:auditar-deps` (cuando esté disponible) debe
+  cruzar las dependencias del proyecto contra Context7 para
+  detectar deprecaciones silenciosas.
+
+---
+
+## Aplicabilidad por agente
+
+| Agente | Aplica | Cuándo |
+|---|---|---|
+| `backend-python-swl` | SÍ | Al generar código FastAPI/Django/SQLAlchemy |
+| `backend-node-swl` | SÍ | Al generar código Express/Fastify/NestJS |
+| `backend-java-swl` | SÍ | Al generar código Spring Boot/JPA |
+| `backend-go-swl` | SÍ | Al generar código Go con frameworks |
+| `backend-rust-swl` | SÍ | Al generar código Axum/Actix |
+| `backend-csharp-swl` | SÍ | Al generar código ASP.NET Core |
+| `frontend-react-swl` | SÍ | Al generar código React/Next.js |
+| `frontend-angular-swl` | SÍ | Al generar código Angular |
+| `frontend-css-swl` | SÍ | Al usar PostCSS/Tailwind plugins |
+| `frontend-tailwind-swl` | SÍ | Al usar Tailwind v4+ APIs |
+| `frontend-swl` | SÍ | Al usar Vue/Svelte/Lit |
+| `mobile-android-swl` | SÍ | Al usar Jetpack Compose libs |
+| `mobile-ios-swl` | SÍ | Al usar SwiftUI/Combine |
+| `mobile-cross-swl` | SÍ | Al usar React Native/Flutter |
+| `implementador-swl` | SÍ | Generalista — siempre |
+| `llm-apps-swl` | SÍ | LangChain, OpenAI SDK, Anthropic SDK |
+| `pagos-swl` | SÍ | Stripe SDK actualizado |
+| `datos-swl` | SÍ | ORMs y drivers de BD |
+| `arquitecto-swl` | RECOMENDADO | Al evaluar tradeoffs entre librerías |
+| `revisor-codigo-swl` | RECOMENDADO | Al detectar deps deprecadas en review |
+| `revisor-seguridad-swl` | OBLIGATORIO | Al verificar CVEs de dependencias |
+| Resto de agentes | NO | No generan código con dependencias externas |
+
+---
+
+## Checklist de consulta Context7
+
+Antes de marcar una tarea como completa:
+
+- [ ] ¿Las dependencias agregadas/usadas se verificaron contra Context7?
+- [ ] ¿La versión usada está alineada con la que Context7 reporta como actual?
+- [ ] ¿No hay imports de APIs deprecadas según Context7?
+- [ ] ¿Las dependencias transitivas conocidas no son warnings de
+      deprecación al instalar?
+- [ ] Si Context7 no tenía la librería, ¿se documentó el motivo?
+
+---
+
+## Origen de esta regla
+
+Esta regla se formalizó tras observar en la primera instalación pública
+de `@saulwade/swl-ses@1.0.0` (2026-04-30) un warning de
+`prebuild-install@7.1.3 deprecated` arrastrado por
+`@xenova/transformers` que estaba en `optionalDependencies`. La
+dependencia se eligió en una iteración anterior sin verificar Context7;
+la migración oficial era `@huggingface/transformers`. El warning se vio
+en cada `npm install` del paquete distribuido. Resuelto en v1.0.1
+eliminando la dependencia opcional y elevando esta regla a obligatoria
+para que no se repita.
+
+Memoria asociada: `feedback_usar_context7.md` (preferencia previa del
+usuario, formalizada como regla).