@saulwade/swl-ses 1.2.2 → 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/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/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

package/hooks/claudemd-bloat-detector.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: claudemd-bloat-detector.js
+ * Tipo: PostToolUse  (aplica a: Write, Edit, MultiEdit)
+ *
+ * Ejecuta `scripts/auditar-claudemd.js` contra archivos `CLAUDE.md`
+ * recién modificados y emite un nudge a `.planning/evolucion/nudges.jsonl`
+ * si el veredicto es WARN o ERROR.
+ *
+ * Aplica ADR-0016 (best practices Anthropic "The CLAUDE.md file"):
+ * detecta inflación (líneas excesivas, bullets monolíticos, secciones
+ * canónicas ausentes, ausencia de @references) y sugiere intervención
+ * con `/swl:claudemd refactor`.
+ *
+ * Opt-out: SWL_CLAUDEMD_BLOAT=0 desactiva completamente el hook.
+ *
+ * Comportamiento:
+ *   - Nunca bloquea operaciones (exit code 0 siempre)
+ *   - Solo emite nudge cuando veredicto != OK — ruido mínimo
+ *   - Solo se dispara con archivos cuyo basename sea exactamente CLAUDE.md
+ *   - Respeta exclusiones: temp/, node_modules/, respositorios-git/
+ *
+ * Formato del nudge:
+ *   {
+ *     id: string,
+ *     kind: "claudemd-bloat",
+ *     target: "documentador-swl",
+ *     source: "hooks/claudemd-bloat-detector.js",
+ *     message: "...",
+ *     data: { archivo, veredicto, lineas, hallazgos_count },
+ *     ts: ISO,
+ *     accionado: false
+ *   }
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// ─── Opt-out global ───────────────────────────────────────────────────────
+if (process.env.SWL_CLAUDEMD_BLOAT === '0') {
+  process.exit(0);
+}
+
+let hookInput = '';
+try {
+  hookInput = fs.readFileSync(0, 'utf-8');
+} catch (_) {
+  process.exit(0);
+}
+
+let evento;
+try {
+  evento = JSON.parse(hookInput);
+} catch (_) {
+  process.exit(0);
+}
+
+const toolName = evento?.tool_name;
+const toolInput = evento?.tool_input;
+
+if (!toolName || !['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
+  process.exit(0);
+}
+
+const filePath = toolInput?.file_path;
+if (!filePath) {
+  process.exit(0);
+}
+
+// Solo CLAUDE.md (basename exacto, case-sensitive)
+const basename = path.basename(filePath);
+if (basename !== 'CLAUDE.md') {
+  process.exit(0);
+}
+
+const pathNormalized = filePath.replace(/\\/g, '/');
+const RUTAS_EXCLUIDAS = [
+  '/temp/',
+  '/node_modules/',
+  '/respositorios-git/',
+  '/.planning/',
+];
+if (RUTAS_EXCLUIDAS.some((excluida) => pathNormalized.includes(excluida))) {
+  process.exit(0);
+}
+
+// El archivo debe existir
+if (!fs.existsSync(filePath)) {
+  process.exit(0);
+}
+
+// ─── Ejecutar auditor (módulo, no subproceso) ─────────────────────────────
+const CWD = process.cwd();
+const auditorPath = path.join(CWD, 'scripts', 'auditar-claudemd.js');
+if (!fs.existsSync(auditorPath)) {
+  // No hay auditor instalado en este destino; salir silenciosamente
+  process.exit(0);
+}
+
+let resultado;
+try {
+  const { auditar } = require(auditorPath);
+  resultado = auditar(filePath);
+} catch (_) {
+  // Cualquier error del auditor: salir silenciosamente, no romper el hook
+  process.exit(0);
+}
+
+// Solo emitir nudge si veredicto != OK
+if (!resultado || resultado.veredicto === 'OK') {
+  process.exit(0);
+}
+
+// ─── Construir nudge ──────────────────────────────────────────────────────
+const rutaRelativa = path.relative(CWD, filePath).replace(/\\/g, '/');
+const topHallazgos = (resultado.hallazgos || [])
+  .slice(0, 3)
+  .map((h) => `  - [${h.severidad}] ${h.mensaje}`)
+  .join('\n');
+
+const nudge = {
+  id: crypto.randomBytes(8).toString('hex'),
+  kind: 'claudemd-bloat',
+  target: 'documentador-swl',
+  source: 'hooks/claudemd-bloat-detector.js',
+  message:
+    `[claudemd] ${rutaRelativa} veredicto: ${resultado.veredicto} ` +
+    `(${resultado.hallazgos.length} hallazgos)\n` +
+    topHallazgos + '\n' +
+    `  Ejecutar \`/swl:claudemd audit\` para detalle, ` +
+    `\`/swl:claudemd refactor\` para sugerencias de extracción.`,
+  data: {
+    archivo: rutaRelativa,
+    veredicto: resultado.veredicto,
+    lineas: resultado.metricas?.lineas,
+    secciones_ausentes: resultado.metricas?.secciones_ausentes || [],
+    tiene_at_references: resultado.metricas?.tiene_at_references,
+    hallazgos_count: resultado.hallazgos.length,
+  },
+  ts: new Date().toISOString(),
+  accionado: false,
+  accionado_ts: null,
+  accionado_por: null,
+};
+
+// ─── Persistir a nudges.jsonl ─────────────────────────────────────────────
+try {
+  const nudgesPath = path.join(CWD, '.planning', 'evolucion', 'nudges.jsonl');
+  const nudgesDir = path.dirname(nudgesPath);
+  if (!fs.existsSync(nudgesDir)) {
+    fs.mkdirSync(nudgesDir, { recursive: true });
+  }
+  fs.appendFileSync(nudgesPath, JSON.stringify(nudge) + '\n', 'utf-8');
+} catch (_) {
+  // No fallar el hook por error de escritura
+}
+
+process.exit(0);

package/manifiestos/hooks-config.json

@@ -347,6 +347,15 @@
       "maxConsecutiveFailures": 5,
       "degradeOnFailure": "skip"
     },
+    "claudemd-bloat-detector.js": {
+      "event": "PostToolUse",
+      "matcher": "Write|Edit|MultiEdit",
+      "description": "Ejecuta scripts/auditar-claudemd.js contra archivos CLAUDE.md recién modificados (basename exacto, no cualquier .md). Emite nudge a .planning/evolucion/nudges.jsonl si veredicto != OK (líneas excesivas, bullets gigantes, secciones canónicas ausentes, sin @references, placeholders). Aplica ADR-0016 (best practices Anthropic 'The CLAUDE.md file'). No bloquea. Excluye temp/, node_modules/, respositorios-git/, .planning/. Opt-out: SWL_CLAUDEMD_BLOAT=0.",
+      "blocking": false,
+      "async": true,
+      "maxConsecutiveFailures": 5,
+      "degradeOnFailure": "skip"
+    },
     "notificacion-telegram.js": {
       "event": "Stop",
       "matcher": "",