@saulwade/swl-ses 1.2.1 → 1.3.0

package/comandos/swl/claudemd.md

@@ -0,0 +1,136 @@
+---
+name: swl:claudemd
+description: Audita, refactoriza, valida o inicializa archivos CLAUDE.md según best practices Anthropic (ADR-0016). Subcomandos audit (analiza calidad), refactor (sugiere extracciones), check (verifica secciones canónicas), init-user (crea ~/.claude/CLAUDE.md template), init-project (genera CLAUDE.md raíz del proyecto).
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+---
+
+# /swl:claudemd — Tratamiento profesional de CLAUDE.md
+
+Comando para auditar, refactorizar y mantener `CLAUDE.md` siguiendo las
+cinco recomendaciones del video oficial Anthropic *"The CLAUDE.md file"*:
+
+1. **Compacto** — empieza sin uno, agrega solo lo que tengas que corregir
+2. **Stack arriba** — lenguaje, framework, ORM, BD
+3. **Commands** — cómo correr dev, tests, lint, build
+4. **Code style** — convenciones de indentación, exports, nombrado
+5. **Conventions** — dónde van las cosas, qué patrones preferir
+
+**Carga**: `Skill("swl-claudemd")` — contiene la lógica de auditoría, las
+secciones canónicas, los umbrales de inflación y los templates de
+generación. Delega análisis y criterios al skill.
+
+## Subcomandos
+
+| Subcomando | Propósito |
+|---|---|
+| `/swl:claudemd audit` | Audita el CLAUDE.md actual (líneas, bullets gigantes, secciones canónicas, @references, placeholders) |
+| `/swl:claudemd check` | Como audit pero exit 1 si hay WARN — útil en pre-commit/CI |
+| `/swl:claudemd refactor` | Sugiere extracciones a archivos `@`-referenciados (no modifica, solo propone diff) |
+| `/swl:claudemd init-user` | Crea `~/.claude/CLAUDE.md` con template de preferencias personales si no existe |
+| `/swl:claudemd init-project` | Genera CLAUDE.md raíz del proyecto detectando el stack actual |
+
+Sin subcomando: equivale a `audit`.
+
+## Cuándo usar
+
+- Después de modificar manualmente CLAUDE.md (verifica calidad)
+- Al inicio de un proyecto que no tenía CLAUDE.md (init-project)
+- Al cambiar de máquina y querer transportar preferencias (init-user)
+- En pre-commit hook si el proyecto trackea CLAUDE.md (check)
+- Cuando el hook `claudemd-bloat-detector` emite nudge
+
+## Ejecución de cada subcomando
+
+### audit / check
+
+```bash
+node scripts/auditar-claudemd.js                # output legible
+node scripts/auditar-claudemd.js --json         # output JSON estructurado
+node scripts/auditar-claudemd.js --strict       # exit 1 si WARN (modo check)
+```
+
+El veredicto puede ser:
+
+- **OK** — cumple best practices, sin hallazgos
+- **WARN** — tiene oportunidades de mejora (líneas excesivas, bullets
+  gigantes, secciones ausentes, sin @references)
+- **ERROR** — no existe, tiene placeholders sin reemplazar, faltan
+  secciones críticas
+
+### refactor
+
+Lee el CLAUDE.md actual, identifica candidatos a extracción (bullets
+monolíticos, secciones largas, contenido duplicable a `@references`) y
+imprime el diff propuesto. **NO modifica el archivo** — el usuario
+revisa y aplica manualmente o con `git apply`.
+
+Patrones de extracción típicos:
+
+| Si el bullet/sección contiene… | Mover a… |
+|---|---|
+| Variables de entorno opt-in | `docs/variables-entorno.md` |
+| Reglas de gobernanza extensas | `docs/gobernanza.md` |
+| Catálogo de comandos completo | `COMANDOS.md` (referenciar) |
+| Mapa de propagación detallado | `docs/mapa-propagacion.md` |
+| Convenciones de cada capa | `docs/convenciones-{capa}.md` |
+
+### init-user
+
+Verifica si existe `~/.claude/CLAUDE.md` (en Windows:
+`%USERPROFILE%\.claude\CLAUDE.md`). Si no existe, genera template
+mínimo:
+
+```markdown
+# CLAUDE.md (preferencias personales transversales)
+
+> Este archivo aplica a TODOS mis proyectos. Las reglas específicas de
+> proyecto van en el CLAUDE.md de la raíz del proyecto, no aquí.
+
+## Mi rol y stack preferido
+
+- Rol: [ej. ingeniero senior backend]
+- Stack preferido: [ej. Python + FastAPI, TypeScript + Next.js]
+- Herramientas habituales: [ej. Neovim, ripgrep, fd, gh CLI]
+
+## Estilo de comunicación
+
+- Idioma: español
+- Formato preferido para respuestas: [breve / detallado / con tablas]
+- Cuándo prefiero ver alternativas vs. una sola recomendación
+
+## Patrones que aplico siempre
+
+- [ej. "Antes de implementar, mostrar el plan"]
+- [ej. "Tests para todo código nuevo, sin excepción"]
+- [ej. "Commits atómicos en español, formato conventional"]
+```
+
+Si ya existe, NO lo sobreescribe — sugiere añadir secciones faltantes.
+
+### init-project
+
+Detecta el stack del proyecto actual con `scripts/lib/detectar-stack-detallado.js`
+y genera `./CLAUDE.md` mínimo con:
+
+- Sección **Stack** poblada (lenguaje, framework, ORM, package manager)
+- Sección **Comandos** poblada (npm scripts detectados o comandos típicos)
+- Sección **Code style** vacía con placeholders
+- Sección **Conventions** vacía con placeholders
+- Sección **@references** apuntando a `.planning/PROYECTO.md`,
+  `README.md`, etc. si existen
+
+Si CLAUDE.md ya existe, **NO lo sobreescribe**. Sugiere correr
+`/swl:claudemd refactor` para mejorar el actual.
+
+## Variables de entorno
+
+Ver `@docs/variables-entorno.md` sección "Calidad de CLAUDE.md":
+
+- `SWL_CLAUDEMD_BLOAT` (on/off) — activa hook `claudemd-bloat-detector`
+- `SWL_CLAUDEMD_MAX_LINES` (default 200) — umbral de líneas totales
+- `SWL_CLAUDEMD_MAX_BULLET_CHARS` (default 1000) — umbral de bullet/párrafo
+
+## Exit codes
+
+- `0` — OK o WARN (consultivo)
+- `1` — ERROR o `--strict` + WARN

package/comandos/swl/salud.md

@@ -286,6 +286,35 @@ Si `SWL_AUDIT_AGENTES` no está definida, este paso se omite — los reportes
 son opt-in por diseño (CLAUDE.md: "Variables de entorno opt-in para
 integraciones enterprise").
 
+## Paso 5f — Calidad de CLAUDE.md (ADR-0016)
+
+Auditoría determinista del archivo `CLAUDE.md` raíz del proyecto según best
+practices Anthropic ("The CLAUDE.md file"): líneas totales, bullets
+monolíticos, secciones canónicas (Stack/Comandos/Code style/Conventions),
+uso de `@references`, placeholders sin reemplazar.
+
+```bash
+node scripts/auditar-claudemd.js --json
+```
+
+Veredictos posibles:
+
+| Veredicto | Significado | Score impact |
+|---|---|---|
+| `OK` | Cumple best practices, sin hallazgos | +1 |
+| `WARN` | Oportunidades de mejora (líneas excesivas, bullets gigantes, secciones ausentes, sin @references) | -0.5 |
+| `ERROR` | No existe, placeholders sin reemplazar, secciones críticas ausentes | -1 |
+
+Si veredicto != OK, el reporte sugiere ejecutar `/swl:claudemd refactor`
+para identificar candidatos a extracción a archivos `@`-referenciados.
+
+Variables de entorno: `SWL_CLAUDEMD_MAX_LINES` (default 200) y
+`SWL_CLAUDEMD_MAX_BULLET_CHARS` (default 1000) ajustan los umbrales.
+Documentación completa en `@docs/variables-entorno.md`.
+
+Este paso siempre se ejecuta (no es opt-in) — la calidad de CLAUDE.md
+es métrica continua del sistema.
+
 ## Paso 5e — Verificación de drift de skills (skills-lock)
 
 Si existe `manifiestos/skills-lock.json`, comparar el hash actual de cada

package/habilidades/fastapi-experto/SKILL.md

@@ -5,12 +5,12 @@ description: >
   testing con httpx. Incluye el anti-patrón crítico MissingGreenlet (lazy loading
   en async). Cargar cuando se implementen endpoints FastAPI, schemas Pydantic v2,
   queries SQLAlchemy async, WebSockets, SSE o tests de integración con httpx.
-version: "1.1.2"
+version: "1.2.0"
 evolved: true
-evolved-from: "1.1.1"
-evolved-at: "2026-05-04"
+evolved-from: "1.1.2"
+evolved-at: "2026-05-10"
 evolved-by: "aprender"
-evolved-note: "Fix lógica del gotcha endswith asyncpg: el formato 'INSERT oid N' tiene 3 partes (no 2), len(partes) == 2 fallaba para INSERT. Solución correcta: int(partes[-1]) — siempre el count, sea con o sin oid."
+evolved-note: "2 reglas nuevas en sesión SIGM Opción B: response_model=dict obsoleto vs Envelope[T] tipado, RETURNING * sin soporte de JOINs (refactor a 2 queries con _SQL_X_ENRIQUECIDA)"
 herramientasPermitidas: [Read]
 exclusiones:
   - "No cargar para proyectos Django o Flask — los patrones de ORM sync, Class-Based Views y middleware difieren fundamentalmente; cargar `django-experto` o el skill del framework correspondiente."
@@ -219,6 +219,8 @@ class Factura(Base):
 - **`return result or {}` después de UPDATE/INSERT enmascara errores de BD silenciosamente**: patrón típico `result = await repo.actualizar_estatus(...); return result or {}` devuelve `{}` al cliente cuando el UPDATE no encontró la fila (race condition, RLS, FK violado). El cliente recibe HTTP 200 con body vacío en lugar del 404/500 esperado, los bugs quedan invisibles en monitoring. Causa: `or {}` trata `None` como "datos no disponibles" cuando en realidad significa "el UPDATE falló post-INSERT". Solución: explicit None check con raise — usar `if result is None: raise HTTPException(404, "Recurso no encontrado")` cuando el ID viene del cliente, o `raise HTTPException(500, "Error interno...")` cuando es un invariante post-INSERT (la fila acaba de crearse, debe existir).
 - **`detail=str(exc)` en HTTPException — solo aceptable cuando la excepción es de DOMINIO con mensaje diseñado para usuario**: las excepciones de capa externa (MinIO/S3, BD driver, HTTP client de un PSP, parser PDF) tienen mensajes que pueden contener bucket/host/paths/credenciales parciales/stack traces. Pasar `str(exc)` directo al `detail` los expone al cliente. Causa: tratar todas las excepciones igual sin distinguir dominio (controlado) de capa externa (no controlado). Solución: dos patrones distintos. Para excepciones de dominio (`MIMENoPermitidoError("MIME 'X' no permitido")`, `EmailDuplicadoError`): `except DominioError as exc: raise HTTPException(422, detail=str(exc))` OK. Para capa externa (`ErrorEvidencia`, `boto3.ClientError`, `httpx.RequestError`): `except CapaExternaError as exc: logger.exception("contexto"); raise HTTPException(502, detail="Error genérico al cliente")`. La diferencia es que el mensaje de DominioError fue diseñado para el usuario; el de CapaExternaError no.
 - **Vocabulario interno (nombres de funciones PL/pgSQL, schemas, tablas, "RLS", "transaccional") en `detail` al cliente fuga arquitectura**: detail genérico al cliente y detail con detalles de infraestructura para diagnóstico **no son lo mismo**. Patrones de fuga típicos: `detail=f"fn_evaluar_X no retornó resultado"` (revela nombre de función PL/pgSQL), `detail="Posible inconsistencia transaccional o RLS"` (revela motor + capa de seguridad), `detail=f"Recurso {id} no encontrado en activacion tras INSERT"` (revela UUID interno y secuencia de operaciones). Causa: el desarrollador escribe el mensaje pensando en debug, no en exposición. Solución: detail al cliente = mensaje genérico orientado al recurso ("Error interno al activar el recurso. Contacte al administrador."); detalles internos solo en `logger.error("contexto detallado %s %s", uuid, programa_id, ...)` con format strings estructurados (NO concatenación con `+`). Aplica a todos los HTTPException 500/503; el 404/422 puede ser más específico si el mensaje es del dominio.
+- **`response_model=dict` produce `{[key:string]:unknown}` en `openapi-typescript` — tipos inútiles para frontend**: declarar endpoints con `response_model=dict` (placeholder) hace que el codegen `openapi-typescript` genere responses tipados como objeto vacío. El frontend lee campos via `.id`, `.monto` con type assertions implícitas → mismatches silenciosos en runtime cuando los nombres del backend cambian. Causa: FastAPI sin schema concreto no documenta el shape en `/openapi.json`. Fix: SIEMPRE declarar `response_model=EnvelopeResponse[Schema]`, `EnvelopePaginatedResponse[Schema]`, `EnvelopeOffsetResponse[Schema]` o `EnvelopeResponse[MensajeResponse]` con un schema Pydantic concreto. Genéricos `EnvelopeResponse[T] / EnvelopePaginatedResponse[T] / EnvelopeOffsetResponse[T] / MensajeResponse` deben vivir en `app/common/response.py` (Pydantic v2 + Generic[T]). Excepción única documentable: `StreamingResponse` (PDF/CSV) puede usar `response_model=dict` con comentario explicativo. Caso real: 155 endpoints SIGM refactorizados (2026-05-10) tras descubrir que el codegen producía tipos vacíos por `response_model=dict` heredado.
+- **Pydantic + PostgreSQL `RETURNING *` no soporta JOINs en INSERT/UPDATE — refactor a 2 queries**: para mutaciones que devuelven un schema enriquecido con JOINs (ej: `cajero_nombre` desde `usuario.usuario`, `clave_catastral` desde `cuenta_predial`), `INSERT/UPDATE ... RETURNING *` no permite agregar JOINs. Causa: PostgreSQL `RETURNING` solo accede a las columnas de la tabla afectada. Fix: refactorizar a 2 queries: (1) `INSERT/UPDATE ... RETURNING id`; (2) `SELECT ... FROM tabla LEFT JOIN ... WHERE id = $1`. Costo: 1 round-trip extra (sub-1ms en LAN). Beneficio: el método siempre devuelve el shape enriquecido, mappers consistentes entre `crear`, `obtener` y `listar`. Patrón DRY: extraer la query SELECT a constante de clase (`_SQL_X_ENRIQUECIDA`) para reusar entre métodos. Caso: `crear_solicitud_descuento`, `autorizar_descuento`, `obtener_solicitud_descuento` y `listar_solicitudes_pendientes` comparten `_SQL_SOLICITUD_ENRIQUECIDA` con LEFT JOIN a `cuenta_predial` + `usuario` (cajero/supervisor).
 
 ## Referencias especializadas
 

package/habilidades/nextjs-experto/SKILL.md

@@ -4,7 +4,12 @@ description: >
   Next.js App Router: Server Components, Client Components, Server Actions,
   streaming con Suspense, ISR, route handlers y middleware. Cargar cuando se
   implementen páginas Next.js, data fetching, mutaciones o rutas de API.
-version: "1.0.0"
+version: "1.1.0"
+evolved: true
+evolved-from: "1.0.0"
+evolved-at: "2026-05-10"
+evolved-by: "aprender"
+evolved-note: "3 gotchas operativos confirmados en sesión SIGM Opción B: useSearchParams Suspense bailout, cache .next stale, brace-expansion override CVE-2025-5889"
 herramientasPermitidas: [Read]
 exclusiones:
   - "No cargar para proyectos Next.js con Pages Router (pages/index.tsx) — el modelo de getServerSideProps y getStaticProps es diferente al App Router; este skill solo cubre App Router."
@@ -316,6 +321,12 @@ export default function Reloj() {
 
 **Variables de entorno sin `NEXT_PUBLIC_` no disponibles en el cliente en runtime**: `process.env.MI_VAR` en un Client Component retorna `undefined` en el browser aunque esté definida en `.env.local`. Causa: Next.js solo serializa al bundle del cliente las variables con prefijo `NEXT_PUBLIC_`. Fix: renombrar a `NEXT_PUBLIC_MI_VAR` si debe estar en el cliente, o leerla en un Server Component/Action y pasarla como prop.
 
+**`useSearchParams()` requiere `<Suspense>` boundary durante prerender estático**: build de producción falla con `⨯ useSearchParams() should be wrapped in a suspense boundary at page "/X". Read more: https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout`. Causa: el prerender estático no puede ejecutar el hook → CSR bailout → build aborta. Fix: en `page.tsx` envolver el componente que usa `useSearchParams()` en `<Suspense fallback={null}>` (o un esqueleto). El shell se prerenderiza vacío; el componente hidrata en cliente con los search params disponibles. Mismo patrón aplica a `useRouter()` y `usePathname()` cuando se usan en componentes prerenderizados. Caso real: SIGM agregó `useSearchParams()` a `useLoginForm.ts` para honrar `?siguiente=`; tsc + vitest pasaban pero `npm run build` falló hasta envolver `<LoginForm />` en `<Suspense>`.
+
+**Cache `.next/` puede ocultar errores TypeScript reales tras refactor de tipos masivo**: `npx tsc --noEmit` local pasa pero CI falla con errores TS2724/TS2305 sobre tipos eliminados. Causa: `.next/types/*.d.ts` y `tsconfig.tsbuildinfo` cachean los types del estado anterior; CI clona limpio y ve los errores reales. Fix: cuando se modifican imports/exports masivos en `lib/*/tipos.ts` (refactor de tipos, eliminación de interfaces, codegen openapi-typescript), borrar cache antes de validar local: `cd frontend && rm -rf .next && npx tsc --noEmit`. Si CI falla con TSC y local pasa: 90% de las veces es cache stale.
+
+**Override de `brace-expansion@^5` rompe minimatch (eslint depende)**: `npm install` aplica el override pero `eslint . --ext .ts,.tsx` falla con `TypeError: expand is not a function` en `@eslint/config-array → minimatch → brace-expansion`. Causa: brace-expansion v3+ cambió la API (de export default `expand` function a export con shape distinto); minimatch espera la API v2. Fix: para CVE-2025-5889 (ReDoS), usar `"brace-expansion": "^2.0.2"` (parcheado desde 2.0.2 — NO requiere v5). Validación pre-override: `npm ls brace-expansion` para revisar consumidores conocidos antes de bumpear major. Mismo patrón aplicable a otros overrides de transitives — validar cadena de consumers antes de bumpear major.
+
 ## Checklist de verificación
 
 - [ ] "use client" solo en componentes con hooks, eventos o browser APIs

package/habilidades/nuevo-proyecto/SKILL.md

@@ -176,7 +176,85 @@ Una vez obtenidas las respuestas, crea la carpeta `.planning/` y los tres docume
 
 ---
 
-## Fase 3 — Checklist de arranque
+## Fase 3 — Generar CLAUDE.md raíz del proyecto
+
+Antes de cerrar la sesión de inicialización, **genera un `CLAUDE.md` mínimo en
+la raíz del proyecto recién creado**. Es el onboarding script que Claude leerá
+en cada sesión futura sobre este proyecto.
+
+> Sigue las best practices del video oficial Anthropic
+> ("The CLAUDE.md file"): empieza compacto, deja que el archivo crezca con
+> correcciones explícitas. Las cinco secciones canónicas son:
+> Stack / Comandos / Code style / Conventions / @references.
+
+### Plantilla mínima: `./CLAUDE.md` del proyecto
+
+Usa los datos del Bloque B (stack) y del Bloque C (equipo, repo) del cuestionario.
+
+```markdown
+# CLAUDE.md — [Nombre del Proyecto]
+
+## Stack
+
+- **Lenguaje**: [del Bloque B5 / B6]
+- **Framework principal**: [si aplica]
+- **Base de datos**: [del Bloque B7]
+- **Infraestructura**: [del Bloque B6]
+
+## Comandos del proyecto
+
+| Comando | Propósito |
+|---------|-----------|
+| `[npm run dev / poetry run / etc.]` | Servidor de desarrollo |
+| `[npm test / pytest / cargo test]` | Tests |
+| `[npm run build / ...]` | Build |
+| `[npm run lint / ruff / clippy]` | Lint |
+
+## Code style
+
+- [Convención de indentación si difiere del default del lenguaje]
+- [Preferencia de exports / módulos si aplica]
+- [Naming si difiere del idiomático del lenguaje]
+
+## Conventions
+
+- [Convención de organización: dónde van los endpoints / componentes / utils]
+- [Patrones a preferir: ej. "preferir async sobre callbacks"]
+- [Restricciones del Bloque B8 si son operativas]
+
+## @references
+
+- `@.planning/PROYECTO.md` — visión, objetivos del MVP, criterios de éxito
+- `@.planning/REQUISITOS.md` — requerimientos funcionales y no funcionales
+- `@.planning/HOJA-RUTA.md` — fases planeadas
+
+## Cómo evolucionar este archivo
+
+1. Empieza mínimo. No adelantes reglas.
+2. Cuando corrijas a Claude, pídele explícitamente: *"guarda esto en CLAUDE.md"*.
+3. Para preferencias personales (no del proyecto), usa `~/.claude/CLAUDE.md`.
+4. Si crece demasiado, ejecuta `/swl:claudemd refactor` para extraer secciones.
+```
+
+### Reglas de generación
+
+- **Llenar TODOS los placeholders `[...]` con los datos reales del cuestionario**.
+  Si falta un dato (ej. el usuario no especificó comandos), dejar el bullet con
+  un comentario `<!-- pendiente: confirmar con el equipo -->` en lugar de
+  eliminar el bullet o dejarlo vacío.
+- **Mantener el archivo bajo 80 líneas inicialmente**. El video oficial
+  recomienda explícitamente "empezar sin uno y construir desde ahí" — la
+  primera versión debe ser un esqueleto, no una enciclopedia.
+- **NO incluir reglas que aún no han sido violadas**. Por ejemplo, no
+  agregar "no usar `eval()`" si Claude nunca lo usó en este proyecto. Esa
+  regla puede vivir como global del usuario o agregarse cuando aparezca el
+  primer caso.
+- **NO duplicar información que ya está en `.planning/PROYECTO.md`**. Usar
+  `@.planning/PROYECTO.md` como referencia.
+
+---
+
+## Fase 4 — Checklist de arranque
 
 Antes de cerrar la sesión de inicialización, verifica:
 
@@ -185,10 +263,12 @@ Antes de cerrar la sesión de inicialización, verifica:
 - [ ] El HOJA-RUTA.md tiene fases con duración estimada
 - [ ] Las restricciones "no negociables" están identificadas y documentadas
 - [ ] Se registró quién tomó cada decisión de stack (para futura referencia)
+- [ ] CLAUDE.md raíz generado con secciones canónicas pobladas (Stack, Comandos, @references)
+- [ ] CLAUDE.md raíz validado con `/swl:claudemd audit` (sin warnings)
 
 ## Gotchas / Errores comunes no obvios
 
-- **PROYECTO.md generado con `[TBD]` en restricciones no negociables**: el agente deja campos sin resolver para no bloquear al usuario, pero las restricciones vacías generan retrabajos costosos cuando se descubren tardíamente. Causa: el checklist de cierre de la Fase 3 no se aplicó rigurosamente. Solución: no cerrar la sesión de inicialización hasta que no quede ningún `[TBD]` en el bloque de restricciones — si el usuario no puede responder, registrar la restricción como "pendiente" en la sección `## Decisiones pendientes` con ticket asignado.
+- **PROYECTO.md generado con `[TBD]` en restricciones no negociables**: el agente deja campos sin resolver para no bloquear al usuario, pero las restricciones vacías generan retrabajos costosos cuando se descubren tardíamente. Causa: el checklist de cierre de la Fase 4 no se aplicó rigurosamente. Solución: no cerrar la sesión de inicialización hasta que no quede ningún `[TBD]` en el bloque de restricciones — si el usuario no puede responder, registrar la restricción como "pendiente" en la sección `## Decisiones pendientes` con ticket asignado.
 - **Fase 1 de HOJA-RUTA.md sin duración estimada**: el usuario acepta el documento sin notar que las fases no tienen estimaciones. Causa: el agente genera el template sin poblar las duraciones. Solución: antes de entregar HOJA-RUTA.md, pedir al usuario una estimación rough (días, semanas) para cada fase — sin eso el roadmap es decorativo.
 - **Stack seleccionado sin verificar restricciones del Bloque B**: el agente sugiere un stack "moderno" que viola una restricción de licencia OSS o de plataforma mandatoria del equipo. Causa: el Bloque B se procesó en orden pero las respuestas no se cruzaron con las sugerencias del Bloque A. Solución: al proponer stack, citar explícitamente cada restricción del Bloque B y confirmar que ninguna es violada.
 - **No preguntar por sistemas legados cuando el usuario menciona "reemplazar"**: el agente omite la pregunta 4 del Bloque A asumiendo que el proyecto es greenfield. Causa: mala clasificación del proyecto como nuevo cuando el usuario usó la palabra "reemplazar". Solución: si el usuario menciona "reemplazar", "migrar" o "integrar con" en la descripción, la pregunta 4 es obligatoria, no opcional.

package/habilidades/react-experto/SKILL.md

@@ -1,7 +1,12 @@
 ---
 name: react-experto
 description: React + Next.js mejores prácticas modernas. Cubre Server Components vs Client Components, data fetching patterns (RSC, React Query, SWR, Server Actions), state management (useState, Zustand, Jotai), performance (memo, lazy, Suspense, streaming) y Next.js App Router patterns.
-version: "1.0.0"
+version: "1.1.0"
+evolved: true
+evolved-from: "1.0.0"
+evolved-at: "2026-05-10"
+evolved-by: "aprender"
+evolved-note: "Patrón useSyncExternalStore para hidratación cliente-only confirmado en sesión SIGM (evita la regla nueva react-hooks/set-state-in-effect)"
 herramientasPermitidas: [Read]
 exclusiones:
   - "No cargar para optimización de rendimiento React (memo, useMemo, useCallback, virtualización, code splitting) — para rendimiento cargar `react-optimizacion`."
@@ -207,3 +212,13 @@ Para ejemplos completos de React Query (mutations + invalidacion), Server Action
 **Server Action que actualiza datos sin `revalidatePath` o `revalidateTag` muestra datos obsoletos**: después de un Server Action exitoso (crear/actualizar/eliminar), el cliente sigue viendo el caché anterior del RSC. Causa: Next.js cachea agresivamente los datos del servidor; los Server Actions no invalidan el caché automáticamente. Fix: llamar `revalidatePath('/ruta/afectada')` o `revalidateTag('tag-del-dato')` al final del Server Action antes de `redirect()` o `return`.
 
 **`useState` con objeto como valor inicial no se actualiza con shallow comparison en re-renders del padre**: `useState({ nombre: '', email: '' })` inicializa el estado una sola vez — si el componente padre pasa nuevos valores como prop para reinicializar el formulario, el estado no se actualiza. Causa: `useState` solo usa el valor inicial en el primer render. Fix: usar `key` en el componente para forzar remonte cuando cambien los datos base, o usar `useEffect` con las props como dependencias para sincronizar explícitamente.
+
+**Patrón `useState + useEffect(() => setState(true), [])` para detectar cliente dispara la regla `react-hooks/set-state-in-effect` en eslint-plugin-react-hooks v7+**: build CI falla con `Calling setState synchronously within an effect body causes cascading renders`. Causa: la regla nueva (Next.js 16+) detecta el patrón clásico de "mounted flag" para hidratación segura como anti-patrón de performance. Fix idiomático React 19: usar `useSyncExternalStore`:
+```tsx
+const mounted = useSyncExternalStore(
+  () => () => {},        // subscribe — no-op (la 'store' no cambia tras hidratación)
+  () => true,            // getSnapshot — cliente siempre montado
+  () => false,           // getServerSnapshot — SSR siempre 'no montado'
+)
+```
+Equivalente funcional al patrón mounted flag, sin disparar la regla. Type-safe, lint-compliant. Usar en Header/Sidebar/cualquier componente que lea localStorage o `window` y necesite render distinto en SSR vs cliente.

package/habilidades/swl-claudemd/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: swl-claudemd
+description: Tratamiento profesional de CLAUDE.md según best practices Anthropic (ADR-0016). Cubre auditoría (líneas totales, bullets gigantes, secciones canónicas, @references, placeholders), refactor (extracción a archivos referenciados con @), generación de templates (init-user para preferencias personales transversales en ~/.claude/CLAUDE.md, init-project para CLAUDE.md raíz del proyecto detectando stack). Cargar cuando se invoque /swl:claudemd o cuando el hook claudemd-bloat-detector sugiera intervención.
+version: "1.0.0"
+herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
+exclusiones:
+  - "No cargar para editar reglas globales en ~/.claude/rules/ — usar Edit directo."
+  - "No cargar para crear ADRs — usar habilidades/doc-coauthoring o Write directo."
+  - "No cargar para validar otros archivos (.md de docs, READMEs) — solo CLAUDE.md tiene contrato canónico."
+  - "No cargar para generar el bloque del installer en CLAUDE.md de proyectos destino — eso lo hace scripts/lib/transformadores/claude.js."
+evolvable: true
+---
+
+# Habilidad: Tratamiento profesional de CLAUDE.md
+
+## Propósito
+
+Aplicar las cinco recomendaciones del video oficial Anthropic
+*"The CLAUDE.md file"* (`temp/YouTube · O0FGCxkHM-U.md`) como mecanismo
+verificable y mantenible:
+
+1. **Compacto** — empieza sin uno, agrega solo lo que tengas que corregir
+2. **Stack arriba** — lenguaje, framework, ORM, BD
+3. **Commands** — cómo correr dev, tests, lint, build
+4. **Code style** — convenciones de indentación, exports, nombrado
+5. **Conventions** — dónde van las cosas, qué patrones preferir
+
+Más dos prácticas auxiliares del video:
+
+- **`@filepath`** para referenciar docs en lugar de duplicar contenido
+- **"Ask Claude to save to memory"** — el archivo crece con correcciones
+  explícitas, no por adelantar reglas hipotéticas
+
+## Cuándo cargar
+
+- El usuario invoca `/swl:claudemd [audit|check|refactor|init-user|init-project]`
+- El hook `claudemd-bloat-detector` emite nudge sugiriendo `/swl:claudemd refactor`
+- El usuario pregunta "¿está bien mi CLAUDE.md?" o "¿cómo mejoro mi CLAUDE.md?"
+- Se está generando un proyecto nuevo y se necesita CLAUDE.md raíz
+- Se está cambiando de máquina y se necesita transportar `~/.claude/CLAUDE.md`
+
+## Cuándo NO cargar
+
+- El usuario quiere editar `~/.claude/rules/*.md` (reglas globales) — usar Edit directo
+- El usuario quiere validar otros `.md` (READMEs, docs/) — no aplica el contrato canónico de CLAUDE.md
+- El usuario quiere generar el bloque del installer — eso lo hace `scripts/lib/transformadores/claude.js`
+- El usuario quiere crear un ADR — usar `Skill("doc-coauthoring")` o Write directo
+
+---
+
+## Subcomando: audit
+
+Ejecuta el auditor determinista:
+
+```bash
+node scripts/auditar-claudemd.js
+node scripts/auditar-claudemd.js --json    # para parsing
+node scripts/auditar-claudemd.js --strict  # exit 1 si WARN
+```
+
+El auditor verifica seis dimensiones:
+
+| Dimensión | Regla | Severidad |
+|---|---|---|
+| Existencia | Archivo presente en `./CLAUDE.md` o `./.claude/CLAUDE.md` | ERROR si ausente |
+| Tamaño total | Líneas ≤ `SWL_CLAUDEMD_MAX_LINES` (default 200) | WARN |
+| Bullets monolíticos | Cada bullet/párrafo ≤ `SWL_CLAUDEMD_MAX_BULLET_CHARS` (default 1000). Tablas y bloques de código se ignoran | WARN |
+| Secciones canónicas | Stack, Comandos, Code style, Conventions presentes | WARN |
+| @references | Archivos >80 líneas usan al menos un `@docs/...md` | WARN |
+| Placeholders | `[TBD]`, `[TODO]`, `[COMPLETAR]` | ERROR |
+
+Veredicto final: ERROR → WARN → OK (el más severo gana).
+
+### Cómo interpretar los resultados
+
+- **OK**: el archivo cumple. No hay acción requerida.
+- **WARN líneas**: el archivo creció demasiado. Ejecuta `refactor` para
+  identificar candidatos a extracción.
+- **WARN bullet gigante**: un bullet/párrafo es ilegible. Convertirlo a
+  tabla, lista jerárquica, o extraer su contenido a archivo separado.
+- **WARN secciones ausentes**: las secciones canónicas Anthropic no
+  están. Si el archivo es proyecto greenfield, agregarlas. Si es CLAUDE.md
+  de overview/meta-sistema, considerar si aplica el contrato.
+- **WARN sin @references**: el archivo es grande pero no enlaza nada
+  externo. Identificar contenido duplicable a `@docs/`, `@.planning/`, etc.
+- **ERROR placeholders**: bloqueador. Resolver antes de commitear.
+
+---
+
+## Subcomando: refactor
+
+**No modifica archivos** — propone diff. El usuario decide aplicar.
+
+### Algoritmo
+
+1. Lee `CLAUDE.md` actual.
+2. Para cada bullet/párrafo > `MAX_BULLET_CHARS`:
+   - Si contiene **una sola lista de items homogéneos** → propone tabla
+   - Si contiene **definiciones técnicas extensas** → propone extracción a `docs/[tema].md`
+   - Si contiene **enumeración de variables/configuración** → propone extracción a `docs/variables-[scope].md`
+3. Para cada sección > 50 líneas:
+   - Identifica el "tema" del header
+   - Propone `docs/[tema-kebab].md` y reemplazo en CLAUDE.md por:
+     `Para detalles ver @docs/[tema].md`
+4. Imprime diff propuesto en formato unified.
+
+### Patrones de extracción típicos
+
+| Si la sección/bullet contiene… | Mover a… |
+|---|---|
+| Variables de entorno opt-in | `docs/variables-entorno.md` |
+| Reglas de gobernanza extensas | `docs/gobernanza.md` |
+| Catálogo completo de comandos | `COMANDOS.md` (referenciar) |
+| Mapa de propagación detallado | `docs/mapa-propagacion.md` |
+| Convenciones por capa | `docs/convenciones-{capa}.md` |
+| Lista de dependencias / stack histórico | `docs/stack-historico.md` |
+| Decisiones puntuales antiguas | ADR en `.planning/adrs/` |
+
+### Anti-patrones de refactor
+
+- **NO extraer reglas de máxima prioridad** — esas DEBEN estar en CLAUDE.md raíz
+- **NO extraer la sección Stack** — es la primera info que Claude necesita
+- **NO extraer la sección Commands** — son acción inmediata, deben estar visibles
+- **NO crear más de 3 archivos `@`-referenciados nuevos en un solo refactor** — fragmentar demasiado dispersa el contexto
+
+---
+
+## Subcomando: init-user
+
+Genera `~/.claude/CLAUDE.md` (en Windows: `%USERPROFILE%\.claude\CLAUDE.md`)
+con template de preferencias personales si NO existe. Si existe, sugiere
+secciones faltantes pero NO sobreescribe.
+
+### Pasos
+
+1. Detectar la ruta:
+   - Linux/macOS: `$HOME/.claude/CLAUDE.md`
+   - Windows: `$env:USERPROFILE/.claude/CLAUDE.md` (en PowerShell)
+2. Si existe → leer, identificar secciones faltantes, sugerir patches
+3. Si no existe → crear directorio `~/.claude/` si falta, escribir template
+
+### Template
+
+Ver template completo en el comando `/swl:claudemd` sección `init-user`.
+
+Las secciones canónicas para user-level son DISTINTAS de project-level:
+
+| Sección | Project-level | User-level |
+|---|---|---|
+| Stack | Sí — del proyecto | No (varía por proyecto) |
+| Comandos | Sí — del proyecto | No |
+| Code style | Sí — convenciones del equipo | Sí — preferencias personales (indent, naming favorito) |
+| Conventions | Sí — del proyecto | No |
+| Mi rol y stack preferido | No | Sí |
+| Estilo de comunicación | No | Sí |
+| Patrones que aplico siempre | No | Sí — meta-preferencias cross-project |
+
+---
+
+## Subcomando: init-project
+
+Genera `./CLAUDE.md` raíz del proyecto detectando stack actual.
+
+### Pasos
+
+1. Verificar que `./CLAUDE.md` NO exista. Si existe → mensaje "ya existe,
+   considera `/swl:claudemd refactor`" y salir sin tocar.
+2. Ejecutar `detectarStackDetallado(process.cwd())` (de
+   `scripts/lib/detectar-stack-detallado.js`).
+3. Generar archivo con secciones pobladas:
+   - **Stack**: lenguaje + framework + ORM + package manager detectados
+   - **Comandos**: npm scripts detectados o comandos típicos por lenguaje
+   - **Code style**: placeholders explícitos (`<!-- pendiente: definir convención de X -->`)
+   - **Conventions**: placeholders explícitos
+   - **@references**: enlazar a `.planning/PROYECTO.md`, `README.md`,
+     `CONTRIBUTING.md` solo si existen
+4. Imprimir mensaje con próximo paso: "ejecuta `/swl:claudemd audit`
+   para verificar".
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Marcar tablas como bullets gigantes**: el detector debe excluir
+  líneas que empiezan con `|` (tablas Markdown). Sin ese filtro genera
+  falsos positivos en cualquier CLAUDE.md con tablas. Implementado en
+  `scripts/auditar-claudemd.js` función `detectarBulletsGigantes`.
+- **Marcar bloques de código como bullets gigantes**: igual que tablas
+  — el detector entra en modo "code fence" al ver ` ``` ` y no cuenta
+  esas líneas. Sin ese filtro un script Bash de 50 líneas en CLAUDE.md
+  rompe la auditoría.
+- **`refactor` que termina escribiendo el archivo**: el subcomando
+  refactor SOLO debe imprimir diff. Si modifica el archivo viola el
+  principio "el usuario decide". Cualquier modificación destructiva debe
+  ser explícita y confirmada por el usuario.
+- **`init-project` sobreescribiendo CLAUDE.md existente**: el usuario
+  puede tener un CLAUDE.md curado con valor irrecuperable. NUNCA
+  sobreescribir — sugerir refactor.
+- **Templates con `[TBD]` que después fallan auditoría**: los templates
+  generados por `init-user` y `init-project` usan `<!-- pendiente: ... -->`
+  HTML comments en lugar de `[TBD]` para que el auditor no los marque
+  como ERROR placeholders. Comments HTML son ignorados por el regex.
+- **Aplicar el contrato canónico a CLAUDE.md de subdirectorios**: si el
+  proyecto adopta jerarquía (ADR-0007), los CLAUDE.md de subdirectorios
+  pueden NO tener todas las secciones canónicas (porque heredan del root).
+  Por ahora el auditor aplica el contrato uniforme; si el ADR-0007 se
+  acepta, el auditor debe distinguir root vs subdirectorio.
+
+## Señales de alerta
+
+Detente y escala si:
+
+- El usuario pide `init-project` en un directorio que ya tiene CLAUDE.md
+  con >100 líneas de contenido custom (riesgo: pérdida de información)
+- `audit` reporta WARN líneas pero el contenido es legítimamente
+  necesario (ej. listas grandes de comandos sin posibilidad de extracción
+  útil) — sugerir ajustar `SWL_CLAUDEMD_MAX_LINES`, no extraer por extraer
+- El usuario pide `refactor` y propone extracciones que dispersarían
+  contexto crítico (ej. mover "Reglas de máxima prioridad") — rechazar
+  con explicación del anti-patrón