@saulwade/swl-ses 2.0.0 → 2.2.0

package/comandos/swl/claudemd.md

@@ -1,234 +1,239 @@
----
-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"]
-evolved: true
-evolved-from: "1.6.9"
-evolved-at: "2026-05-22"
-evolved-by: "aprender"
-evolved-note: "Audit dimensión 7 — duplicación de reglas globales (cataloga 6 reglas de ~/.claude/rules/ que NO deben duplicarse inline). Refactor propone reemplazo canónico. Aplica regla nueva sin-duplicacion-reglas-globales.md."
----
-
-# /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
-
-  @reglas/usar-sistema-swl.md
-  ```
-  Esta referencia es obligatoria — fuerza que el agente cargue la matriz
-  operacional de uso del sistema SWL al inicio de cada sesión. Si el proyecto
-  tiene otras reglas locales (`@reglas/seguridad.md`, `@reglas/arquitectura.md`,
-  etc.), agregarlas debajo.
-- 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 incluye `@reglas/usar-sistema-swl.md` 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
-node scripts/auditar-claudemd.js --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"]
+evolved: true
+evolved-from: "1.6.9"
+evolved-at: "2026-05-22"
+evolved-by: "aprender"
+evolved-note: "Audit dimensión 7 — duplicación de reglas globales (cataloga 6 reglas de ~/.claude/rules/ que NO deben duplicarse inline). Refactor propone reemplazo canónico. Aplica regla nueva sin-duplicacion-reglas-globales.md."
+---
+
+# /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

package/comandos/swl/compactar.md

@@ -269,10 +269,37 @@ Archivos actualizados:
 - .planning/COMPACTACION.md (creado/actualizado)
 - .planning/ESTADO.md (referencia agregada)
 
-El contexto está listo para continuar con sesión fresca.
-Próximo comando: [comando exacto]
+El estado está a salvo en disco. IMPORTANTE: este comando NO compacta la
+ventana de contexto — eso es una operación del harness que el agente no
+puede ejecutar. Para compactar de verdad, AHORA ejecuta TÚ una de estas:
+
+  /compact          ← built-in de Claude Code: trunca la ventana usando
+                       el estado ya persistido (recomendado para seguir
+                       en la misma sesión)
+  /clear o sesión nueva ← arranque limpio; pega la instrucción de arranque
+                       del Paso 7
+
+Próximo comando de trabajo (tras compactar): [comando exacto]
 ```
 
+## Paso 9 — Por qué este comando NO compacta la ventana (límite del harness)
+
+La compactación REAL del contexto (truncar la conversación) es una operación
+exclusiva del harness de Claude Code: el `/compact` built-in o el auto-compact.
+Un comando `/swl:*` corre DENTRO de la conversación y el modelo no tiene
+ninguna herramienta para truncar su propia ventana — por diseño.
+
+División de responsabilidades:
+
+| Mitad | Quién | Qué hace |
+|-------|-------|----------|
+| `/swl:compactar` | el agente | Persiste el estado a disco (COMPACTACION.md + ESTADO.md) para que NADA se pierda al truncar |
+| `/compact` | el usuario (harness) | Trunca la ventana de verdad. Sin la mitad anterior, perdería las decisiones no escritas |
+
+El error a prevenir: ejecutar `/compact` SIN haber corrido `/swl:compactar`
+antes (estado solo en la memoria de la conversación → se pierde). El orden
+correcto siempre es: `/swl:compactar` → `/compact`.
+
 ## Reglas de comportamiento
 
 - El COMPACTACION.md debe reemplazar la necesidad de releer toda la conversación. Si alguien lo lee, debe poder continuar el trabajo.

package/comandos/swl/configurar-ci.md

@@ -59,16 +59,14 @@ Si el usuario omite `init` e invoca con flags directos, respetar esos flags sin
 
 ### Paso 3 — Copiar workflows
 
-Invocar `scripts/lib/configurar-ci.js` con las opciones seleccionadas:
+Invocar el subcomando del CLI (resuelve cross-scope; ver
+`docs/invocacion-cli-cross-scope.md`). Imprime el resultado como JSON
+(`copiados`, `existentes`, `error`):
 
-```javascript
-const { init } = require('./scripts/lib/configurar-ci');
-const resultado = init({
-  withSecurity: true,
-  withCi: true,
-  withReleasePlease: false,
-  // dryRun: true,  // con --dry-run
-});
+```bash
+swl-ses configurar-ci init
+# flags: --no-security  --no-ci  --with-release-please  --dry-run  --force
+# fallback: npx -y @saulwade/swl-ses@latest configurar-ci init
 ```
 
 Si hay archivos existentes en `resultado.existentes`, preguntar:
@@ -78,7 +76,7 @@ Los siguientes workflows ya existen en .github/workflows/:
 ¿Sobreescribir? (s/N)
 ```
 
-Si el usuario dice que sí, volver a llamar `init` con `force: true`.
+Si el usuario dice que sí, volver a llamar el subcomando con `--force`.
 
 ### Paso 4 — Configurar CLAUDE_API_KEY (solo si se instaló swl-security.yml)
 
@@ -152,14 +150,15 @@ Próximos pasos:
 
 ## /swl:configurar-ci status
 
-Muestra el estado actual de los workflows SWL en el proyecto.
+Muestra el estado actual de los workflows SWL en el proyecto. Subcomando del CLI
+(salida JSON con `instalados`, `faltantes`, `secretsFaltantes`):
 
-```javascript
-const { status } = require('./scripts/lib/configurar-ci');
-const resultado = status();
+```bash
+swl-ses configurar-ci status
+# fallback: npx -y @saulwade/swl-ses@latest configurar-ci status
 ```
 
-Formato de salida:
+Formato de salida (presentar al usuario a partir del JSON):
 
 ```
 Workflows SWL en .github/workflows/:
@@ -187,11 +186,13 @@ gh secret list 2>/dev/null | grep CLAUDE_API_KEY
 
 Elimina los workflows gestionados por swl-ses. No toca branch protection ni otros workflows.
 
-```javascript
-const { uninstall } = require('./scripts/lib/configurar-ci');
+Subcomando del CLI (salida JSON). Primero listar qué se eliminaría (sin
+confirmar), luego repetir con `--confirmar`:
 
-// Primero listar qué se eliminaría (sin confirmar)
-const plan = uninstall({ confirmar: false });
+```bash
+swl-ses configurar-ci uninstall            # plan (confirmar: false)
+swl-ses configurar-ci uninstall --confirmar  # ejecuta la eliminación
+# fallback: npx -y @saulwade/swl-ses@latest configurar-ci uninstall [--confirmar]
 ```
 
 Mostrar:

package/comandos/swl/cron.md

@@ -160,21 +160,19 @@ deliverResult(job, result, process.cwd());
 
 ## Parser de lenguaje natural programático (experimental)
 
-El módulo `scripts/lib/schedule-parser.js` proporciona parseo programático de
-frases en inglés a expresiones cron, disponible para scripts y extensiones del
-comando. No requiere dependencias externas.
+El subcomando `swl-ses schedule-parse` parsea frases en inglés a expresiones
+cron (resuelve cross-scope; ver `docs/invocacion-cli-cross-scope.md`). No
+requiere dependencias externas.
 
-Uso desde Node.js:
-```javascript
-const { parseNaturalSchedule, isCronDue } = require('./scripts/lib/schedule-parser');
-
-// "every morning at 9am" → { cron: '0 9 * * *', descripcion: 'Diariamente a las 9:00 AM' }
-const resultado = parseNaturalSchedule('every morning at 9am');
-
-// Verificar si una expresión cron debe ejecutarse ahora
-const pendiente = isCronDue('0 9 * * *', Date.now(), ultimaEjecucionMs);
+```bash
+# "every morning at 9am" → { "cron": "0 9 * * *", "descripcion": "Diariamente a las 9 AM" }
+swl-ses schedule-parse "every morning at 9am"
+# fallback: npx -y @saulwade/swl-ses@latest schedule-parse "every morning at 9am"
 ```
 
+La verificación de si un cron debe ejecutarse ahora (`isCronDue`) la usa el
+motor de scheduling internamente; no se expone como subcomando.
+
 Frases reconocidas:
 - `"hourly"` → `0 * * * *`
 - `"daily"` / `"every day"` → `0 9 * * *`