@saulwade/swl-ses 1.2.2 → 1.3.1

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/nextjs-experto/SKILL.md

@@ -4,12 +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.1.0"
+version: "1.1.1"
 evolved: true
-evolved-from: "1.0.0"
-evolved-at: "2026-05-10"
+evolved-from: "1.1.0"
+evolved-at: "2026-05-11"
 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"
+evolved-note: "L-108 SIGM Opción C: cache .next/ confirmado x2 (Opción B + Opción C) — patrón consolidado para refactors de tipos masivos. Sin cambios en otros gotchas."
 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."
@@ -323,7 +323,7 @@ export default function Reloj() {
 
 **`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.
+**Cache `.next/` puede ocultar errores TypeScript reales tras refactor de tipos masivo** [CONFIRMADO x2 — Opción B 2026-05-10, Opción C 2026-05-11]: `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. Reforzado masivamente en F2/F3 de SIGM Opción C — 6+ archivos generados con tipos backend-first detectaron diff que el cache local ocultaba.
 
 **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.
 

package/habilidades/nextjs-testing/SKILL.md

@@ -4,7 +4,12 @@ description: >
   Testing Next.js con Vitest, React Testing Library, Playwright y MSW.
   Cubre Server Components, Server Actions, page objects E2E y mocking de API.
   Cargar cuando se escriban tests de componentes, integración o E2E en Next.js.
-version: "1.0.0"
+version: "1.0.1"
+evolved: true
+evolved-from: "1.0.0"
+evolved-at: "2026-05-11"
+evolved-by: "aprender"
+evolved-note: "L-106 SIGM Opción C: gotcha getByText vs getAllByText/getByRole para textos duplicados legítimos (subtotal+total, heading+botón) - confirmado x2 en F1.1 y F1.2"
 herramientasPermitidas: [Read]
 exclusiones:
   - "No cargar para tests React puros fuera del contexto de Next.js (Vite, CRA, Remix) — los mocks del router de Next.js y los Server Components son específicos del framework."
@@ -311,6 +316,26 @@ Preferir assertions específicas sobre el contenido crítico.
 
 **`userEvent.setup()` debe llamarse fuera del `it()` o re-instanciarse por test**: compartir una instancia de `userEvent` entre tests causa que el estado del puntero/teclado se acumule entre tests, causando comportamiento impredecible. Causa: `userEvent.setup()` crea un estado de dispositivo virtual que persiste. Fix: llamar `const user = userEvent.setup()` dentro de cada `it()` o en `beforeEach`, no al nivel de `describe`.
 
+**`getByText` falla con "found multiple elements" cuando el mismo texto aparece en varios nodos legítimos** [CONFIRMADO x2 en SIGM Opción C, F1.1 y F1.2]: en componentes con resumen + total, o heading + botón con texto similar, el monto `$5,000.00` o la palabra "Forma de pago" aparece en 2+ elementos del DOM. `getByText` lanza error. Fix por precisión semántica, en orden de preferencia:
+
+```tsx
+// ❌ Falla cuando hay duplicación legítima
+expect(screen.getByText('$5,000.00')).toBeInTheDocument()
+
+// ✅ Opción 1 — usar getByRole con accessibility name (más precisa)
+expect(screen.getByRole('heading', { name: /forma de pago/i })).toBeInTheDocument()
+expect(screen.getByRole('button', { name: /agregar forma de pago/i })).toBeInTheDocument()
+
+// ✅ Opción 2 — getAllByText cuando todas las apariciones son válidas
+const montos = screen.getAllByText('$5,000.00')
+expect(montos).toHaveLength(2)  // subtotal + total
+
+// ✅ Opción 3 — within() para scope al contenedor
+const total = within(screen.getByTestId('seccion-total')).getByText('$5,000.00')
+```
+
+Regla práctica: si el texto aparece duplicado, casi siempre la intención del test es verificar UNO de los dos elementos por su rol semántico (`heading` vs `button` vs `cell`). `getByRole` con `name` lo resuelve sin recurrir a `data-testid`.
+
 ## Checklist de verificación
 
 - [ ] Vitest/Jest configurado con next/jest transform o plugin react

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/planear-fase/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: planear-fase
 description: Crea el PLAN.md ejecutable para una fase de desarrollo. Descompone la fase en tareas atómicas con dependencias explícitas, las agrupa en oleadas de ejecución paralela cuando es posible, y aplica verificación goal-backward para garantizar que el plan completo satisface los criterios de éxito definidos en CONTEXTO.md.
-version: "1.1.0"
+version: "1.2.0"
 evolved: true
-evolved-from: "1.0.0"
-evolved-at: "2026-05-09"
+evolved-from: "1.1.0"
+evolved-at: "2026-05-10"
 evolved-by: "aprender"
-evolved-note: "Sección nueva 'Convivencia con placeholders previos del roadmap' — anti-patrón confirmado en auditoría SIGM 2026-05-09 (3 placeholders PLAN-fase-3/4/5.md desactualizados coexistiendo con 0N-PLAN.md reales)"
+evolved-note: "Sección nueva 'Estimación de commits — bloques funcionales, no archivos' — anti-patrón confirmado en sesión ADR-0016 (estimación 12 commits resultó 7 reales, 1.7× sobreestimación por contar archivos en vez de bloques funcionales)"
 herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
 exclusiones:
   - "No cargar si no existe CONTEXTO.md para la fase — ejecutar `discutir-fase` primero."
@@ -75,6 +75,26 @@ Agrupa tareas sin dependencias mutuas en la misma oleada. Las tareas de una
 oleada pueden ejecutarse en paralelo (o en secuencia rápida si el contexto lo
 requiere).
 
+### 5. Estimación de commits — bloques funcionales, no archivos
+
+Al estimar la cantidad de commits que requerirá una fase, contar **bloques
+funcionales atómicos** (1 bloque = 1 commit), no archivos modificados. Un
+refactor que toca 25 archivos pero implementa 7 bloques funcionales coherentes
+genera 7 commits, no 25.
+
+**Heurística**:
+
+- Cada Bn (B1, B2, B3...) del plan = 1 commit atómico (incluye código + tests + manifests asociados)
+- Modificaciones cross-archivo en el MISMO bloque funcional van al MISMO commit
+- Tests del bloque van CON el bloque, no en commit separado (excepto TDD estricto)
+- Bump de versión + docs + CHANGELOG = 1 commit final aparte (B-final)
+
+**Anti-patrón observado** (sesión 2026-05-10, ADR-0016): estimación inicial
+"~12 commits, ~25 archivos" para Opción C completa. Resultado real: 7 commits,
+25 archivos (1.7× sobreestimación de commits). La cuenta de archivos fue
+correcta; la de commits estaba inflada por contar "1 archivo nuevo = 1 commit"
+en vez de "1 bloque funcional = 1 commit".
+
 ---
 
 ## Algoritmo de construcción del plan

package/habilidades/react-experto/SKILL.md

@@ -1,12 +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.1.0"
+version: "1.1.1"
 evolved: true
-evolved-from: "1.0.0"
-evolved-at: "2026-05-10"
+evolved-from: "1.1.0"
+evolved-at: "2026-05-11"
 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)"
+evolved-note: "L-105 SIGM: setState dentro de useEffect bloqueado por react-hooks/set-state-in-effect (eslint-plugin-react-hooks v7+) - 3 patrones de reemplazo (lazy init, useMemo, useSyncExternalStore) confirmados x3 en F1.2/F1.3/F3"
 herramientasPermitidas: [Read]
 exclusiones:
   - "No cargar para optimización de rendimiento React (memo, useMemo, useCallback, virtualización, code splitting) — para rendimiento cargar `react-optimizacion`."
@@ -222,3 +222,24 @@ const mounted = useSyncExternalStore(
 )
 ```
 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.
+
+**`setState` dentro de `useEffect` por cualquier razón dispara la misma regla — 3 patrones idiomáticos para reemplazarlo** [CONFIRMADO x3 en SIGM Opción C, F1.2/F1.3/F3]: la regla `react-hooks/set-state-in-effect` no solo afecta al patrón mounted flag — bloquea cualquier `setX(...)` síncrono dentro del cuerpo de un `useEffect`. Patrones de reemplazo según el caso:
+
+```tsx
+// ❌ Anti-patrón (la regla lo bloquea)
+const [value, setValue] = useState(null)
+useEffect(() => {
+  setValue(cargarDesdeStorage())
+}, [])
+
+// ✅ Caso 1 — lazy initialization (estado inicial computado una sola vez)
+const [value, setValue] = useState(() => cargarDesdeStorage())
+
+// ✅ Caso 2 — valor derivado de props o estado
+const value = useMemo(() => calcular(prop1, prop2), [prop1, prop2])
+
+// ✅ Caso 3 — detección cliente vs SSR
+const isClient = useSyncExternalStore(() => () => {}, () => true, () => false)
+```
+
+Regla práctica: si el `setState` solo se ejecuta una vez al montar, casi siempre puede reescribirse como `useState(() => init())` o `useMemo(...)`. Solo dejar `setState` dentro de `useEffect` cuando responde a un evento externo asíncrono (fetch, subscription) — en ese caso, mover la lógica a un handler dedicado y aplicar `// eslint-disable-next-line react-hooks/set-state-in-effect` con comentario justificando.

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