@saulwade/swl-ses 2.6.0 → 2.8.0

package/comandos/swl/claudemd.md

@@ -1,234 +1,234 @@
----
-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
-npx -y @saulwade/swl-ses@latest audit-claudemd            # output legible
-npx -y @saulwade/swl-ses@latest audit-claudemd --json     # output JSON estructurado
-npx -y @saulwade/swl-ses@latest audit-claudemd --strict   # exit 1 si WARN (modo check)
-```
-
-El subcomando `audit-claudemd` del CLI funciona con cualquier modo de instalación
-(global vía `npm i -g`, npx puntual o local dev) porque resuelve el script via
-el paquete npm, no via path relativo al CWD. Es independiente del proyecto desde
-donde se invoque.
-
-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 **Reglas obligatorias** que **DEBE** incluir como primera línea
-  bajo el encabezado:
-  ```markdown
-  ## Reglas obligatorias
-
-  Aplica la regla global `usar-sistema-swl.md` (matriz operacional del sistema
-  SWL), auto-cargada desde `.claude/rules/`. NO duplicar su contenido aquí.
-  ```
-  Esta mención es obligatoria — recuerda la matriz operacional de uso del
-  sistema SWL. NO usar `@reglas/usar-sistema-swl.md`: la regla se auto-carga
-  desde `.claude/rules/` y un `@reglas/...` se rompe en proyectos downstream
-  (ahí no existe `reglas/`). Las demás reglas globales (`seguridad.md`,
-  `arquitectura.md`, etc.) también se auto-cargan desde `.claude/rules/` — NO
-  referenciarlas con `@reglas/...`; mencionarlas por nombre si hace falta.
-- Sección **Reglas de máxima prioridad** con sub-sección obligatoria
-  **Cuatro principios de implementación (Karpathy)**:
-  ```markdown
-  ### Cuatro principios de implementación (Karpathy)
-  Antes de implementar, refactorizar o corregir bugs: (1) **pensar antes de codificar** (no asumir en silencio), (2) **simplicidad primero** (sin abstracciones especulativas), (3) **cambios quirúrgicos** (leer archivo completo antes de editar, no refactor de oportunidad), (4) **ejecución orientada a metas** (criterios verificables, test que reproduce bugs antes del fix). Detalle + 9 ejemplos MAL→BIEN: `Skill("prevencion-sobreingenieria")` + `recursos/EXAMPLES.md`.
-  ```
-  Esta sub-sección es estándar SWL y cubre los gaps cognitivos más
-  frecuentes del agente sin agregar reglas específicas del proyecto.
-- 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. Si detecta que el CLAUDE.md
-existente NO menciona la regla global `usar-sistema-swl` o NO menciona los cuatro
-principios Karpathy (o `prevencion-sobreingenieria`), emitir hallazgo WARN
-recomendando agregarlo manualmente.
-
-### Validación síncrona post-generación
-
-Tras `init-project` generar el archivo nuevo, ejecutar inmediatamente
-`audit` sobre el resultado:
-
-```bash
-swl-ses audit-claudemd --json
-# Fallback si el script no está en el proyecto destino (instalación global vía npm):
-npx -y @saulwade/swl-ses@latest audit-claudemd --json
-```
-
-Veredicto esperado: `OK` (el template debe respetar el contrato por
-construcción). Cualquier WARN/ERROR es bug del template — reportar al
-usuario y abrir issue para corrección. Este check es parte del contrato
-cruzado con `/swl:aprender` documentado en `@docs/contrato-aprender-claudemd.md`.
-
-### audit — checks específicos sobre Karpathy
-
-El subcomando `audit` verifica además de las dimensiones estándar:
-
-- ¿El CLAUDE.md menciona los cuatro principios Karpathy (texto literal
-  "Karpathy" o nombres de los 4 principios) o referencia
-  `prevencion-sobreingenieria` con `Skill(...)` o `@reglas/`?
-
-Si NO los menciona y el archivo tiene >50 líneas: emitir hallazgo WARN
-recomendando agregar la sub-sección compacta (4 líneas) como guía de
-implementación. NO emite WARN para CLAUDE.md mínimos (<50 LOC) ni para
-archivos `~/.claude/CLAUDE.md` user-level (esos siguen otro contrato).
-
-### audit — checks específicos sobre duplicación de reglas globales
-
-El subcomando `audit` también detecta (dimensión 7) si CLAUDE.md duplica
-reglas que ya viven en `~/.claude/rules/` y se cargan globalmente.
-Consume el catálogo declarativo
-`scripts/lib/reglas-globales-conocidas.json` que cataloga 6 reglas
-conocidas:
-
-- `brevedad-output.md` § Idioma obligatorio: español de México
-- `brevedad-output.md` § Brevedad y eficiencia de output
-- `git-coauthor.md` § Sin co-autores en commits
-- `arreglar-al-detectar.md` § Detectar → Informar → Arreglar
-- `debatir-antes-de-aceptar.md`
-- `usar-context7.md`
-
-Si detecta duplicación: emite hallazgo `duplicacion-reglas-globales`
-severidad WARN con línea aproximada y remediación específica. NO bloquea
-el comando — sirve como nudge para limpiar el CLAUDE.md.
-
-NO aplica a `~/.claude/CLAUDE.md` user-level (ahí sí pueden declararse
-preferencias personales que parafrasean reglas globales).
-
-Aplica regla `reglas/sin-duplicacion-reglas-globales.md`.
-
-### refactor — propuestas para duplicaciones de reglas globales
-
-Cuando `audit` detecta duplicaciones, el subcomando `refactor` propone
-el reemplazo concreto usando `construirSugerenciaRefactor()` del
-detector. Cada propuesta incluye:
-
-- **Bloque a eliminar** (línea aproximada en CLAUDE.md)
-- **Regla global afectada** (archivo + sección canónica)
-- **Reemplazo sugerido** (3 opciones):
-  1. Eliminar el bloque — la regla global YA aplica automáticamente
-  2. Reescribir como matiz local en ≤3 líneas referenciando la regla
-  3. Documentar override explícito con justificación
-
-El refactor SOLO imprime el diff propuesto. El usuario decide aplicar.
-
-## 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
+---
+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
+npx -y @saulwade/swl-ses@latest audit-claudemd            # output legible
+npx -y @saulwade/swl-ses@latest audit-claudemd --json     # output JSON estructurado
+npx -y @saulwade/swl-ses@latest audit-claudemd --strict   # exit 1 si WARN (modo check)
+```
+
+El subcomando `audit-claudemd` del CLI funciona con cualquier modo de instalación
+(global vía `npm i -g`, npx puntual o local dev) porque resuelve el script via
+el paquete npm, no via path relativo al CWD. Es independiente del proyecto desde
+donde se invoque.
+
+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 **Reglas obligatorias** que **DEBE** incluir como primera línea
+  bajo el encabezado:
+  ```markdown
+  ## Reglas obligatorias
+
+  Aplica la regla global `usar-sistema-swl.md` (matriz operacional del sistema
+  SWL), auto-cargada desde `.claude/rules/`. NO duplicar su contenido aquí.
+  ```
+  Esta mención es obligatoria — recuerda la matriz operacional de uso del
+  sistema SWL. NO usar `@reglas/usar-sistema-swl.md`: la regla se auto-carga
+  desde `.claude/rules/` y un `@reglas/...` se rompe en proyectos downstream
+  (ahí no existe `reglas/`). Las demás reglas globales (`seguridad.md`,
+  `arquitectura.md`, etc.) también se auto-cargan desde `.claude/rules/` — NO
+  referenciarlas con `@reglas/...`; mencionarlas por nombre si hace falta.
+- Sección **Reglas de máxima prioridad** con sub-sección obligatoria
+  **Cuatro principios de implementación (Karpathy)**:
+  ```markdown
+  ### Cuatro principios de implementación (Karpathy)
+  Antes de implementar, refactorizar o corregir bugs: (1) **pensar antes de codificar** (no asumir en silencio), (2) **simplicidad primero** (sin abstracciones especulativas), (3) **cambios quirúrgicos** (leer archivo completo antes de editar, no refactor de oportunidad), (4) **ejecución orientada a metas** (criterios verificables, test que reproduce bugs antes del fix). Detalle + 9 ejemplos MAL→BIEN: `Skill("prevencion-sobreingenieria")` + `recursos/EXAMPLES.md`.
+  ```
+  Esta sub-sección es estándar SWL y cubre los gaps cognitivos más
+  frecuentes del agente sin agregar reglas específicas del proyecto.
+- 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. Si detecta que el CLAUDE.md
+existente NO menciona la regla global `usar-sistema-swl` o NO menciona los cuatro
+principios Karpathy (o `prevencion-sobreingenieria`), emitir hallazgo WARN
+recomendando agregarlo manualmente.
+
+### Validación síncrona post-generación
+
+Tras `init-project` generar el archivo nuevo, ejecutar inmediatamente
+`audit` sobre el resultado:
+
+```bash
+swl-ses audit-claudemd --json
+# Fallback si el script no está en el proyecto destino (instalación global vía npm):
+npx -y @saulwade/swl-ses@latest audit-claudemd --json
+```
+
+Veredicto esperado: `OK` (el template debe respetar el contrato por
+construcción). Cualquier WARN/ERROR es bug del template — reportar al
+usuario y abrir issue para corrección. Este check es parte del contrato
+cruzado con `/swl:aprender` documentado en `@docs/contrato-aprender-claudemd.md`.
+
+### audit — checks específicos sobre Karpathy
+
+El subcomando `audit` verifica además de las dimensiones estándar:
+
+- ¿El CLAUDE.md menciona los cuatro principios Karpathy (texto literal
+  "Karpathy" o nombres de los 4 principios) o referencia
+  `prevencion-sobreingenieria` con `Skill(...)` o `@reglas/`?
+
+Si NO los menciona y el archivo tiene >50 líneas: emitir hallazgo WARN
+recomendando agregar la sub-sección compacta (4 líneas) como guía de
+implementación. NO emite WARN para CLAUDE.md mínimos (<50 LOC) ni para
+archivos `~/.claude/CLAUDE.md` user-level (esos siguen otro contrato).
+
+### audit — checks específicos sobre duplicación de reglas globales
+
+El subcomando `audit` también detecta (dimensión 7) si CLAUDE.md duplica
+reglas que ya viven en `~/.claude/rules/` y se cargan globalmente.
+Consume el catálogo declarativo
+`scripts/lib/reglas-globales-conocidas.json` que cataloga 6 reglas
+conocidas:
+
+- `brevedad-output.md` § Idioma obligatorio: español de México
+- `brevedad-output.md` § Brevedad y eficiencia de output
+- `git-coauthor.md` § Sin co-autores en commits
+- `arreglar-al-detectar.md` § Detectar → Informar → Arreglar
+- `debatir-antes-de-aceptar.md`
+- `usar-context7.md`
+
+Si detecta duplicación: emite hallazgo `duplicacion-reglas-globales`
+severidad WARN con línea aproximada y remediación específica. NO bloquea
+el comando — sirve como nudge para limpiar el CLAUDE.md.
+
+NO aplica a `~/.claude/CLAUDE.md` user-level (ahí sí pueden declararse
+preferencias personales que parafrasean reglas globales).
+
+Aplica regla `reglas/sin-duplicacion-reglas-globales.md`.
+
+### refactor — propuestas para duplicaciones de reglas globales
+
+Cuando `audit` detecta duplicaciones, el subcomando `refactor` propone
+el reemplazo concreto usando `construirSugerenciaRefactor()` del
+detector. Cada propuesta incluye:
+
+- **Bloque a eliminar** (línea aproximada en CLAUDE.md)
+- **Regla global afectada** (archivo + sección canónica)
+- **Reemplazo sugerido** (3 opciones):
+  1. Eliminar el bloque — la regla global YA aplica automáticamente
+  2. Reescribir como matiz local en ≤3 líneas referenciando la regla
+  3. Documentar override explícito con justificación
+
+El refactor SOLO imprime el diff propuesto. El usuario decide aplicar.
+
+## 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